Skip to main content

​
Overview

The @aixyz/config package handles loading and validating your aixyz.config.ts configuration file. It uses Zod schemas to ensure type safety and provides clear error messages for invalid configurations.

​
API

​
getAixyzConfig()

Returns the full configuration object for build-time use. This includes all fields needed by the build pipeline, CLI, and plugins. 
import { getAixyzConfig } from "@aixyz/config";

const config = getAixyzConfig();

​
getAixyzConfigRuntime()

Returns a subset of the configuration that is safe for inclusion in runtime bundles. 
import { getAixyzConfigRuntime } from "@aixyz/config";

const runtimeConfig = getAixyzConfigRuntime();
At build time, the AixyzConfigPlugin replaces imports from aixyz/config with the resolved runtime config, so the config file is not required at runtime.

​
Types

import type { AixyzConfig, Network } from "@aixyz/config";
  • AixyzConfig — the full config type for aixyz.config.ts
  • Network — CAIP-2 network identifier type (e.g., "eip155:8453")

​
Environment File Loading

Environment variables are loaded in the following order (later files take precedence):
  1. .env
  2. .env.local
  3. .env.$(NODE_ENV) — e.g., .env.production
  4. .env.$(NODE_ENV).local — e.g., .env.production.local
This matches the loading order used by Next.js.

​
URL Auto-Detection

If url is not set in config, it is resolved from environment variables:
  1. https://${VERCEL_PROJECT_PRODUCTION_URL} (Vercel production)
  2. https://${VERCEL_URL} (Vercel preview)
  3. http://localhost:3000 (fallback)

​
Zod Validation

All configuration fields are validated against Zod schemas at load time. If your config is invalid, you get a descriptive error with the exact field and expected type.

​
Usage in Build Plugins

The AixyzConfigPlugin (part of @aixyz/cli) calls getAixyzConfig() during the build to resolve the full config, then materializes the runtime-safe subset into the bundle. This means:
  • import config from "aixyz/config" works at runtime without the config file
  • Environment variables are baked in at build time
  • The config file itself is not included in the output bundle

Configuration Guide

How to write your aixyz.config.ts file.

CLI Package

Build pipeline that consumes this config.