@veestackio/config

Centralized configuration management for VeeStack with environment validation.

Overview

This package provides:

• Environment Schema - Zod-based environment variable validation
• Configuration Loading - Load and merge environment variables
• Environment Guards - Validate production/development URL consistency
• Type-Safe Config - TypeScript types for all configuration values

Used by CLI, Frontend, and Edge Functions to ensure consistent configuration.

Installation

# In a VeeStack monorepo package
pnpm add @veestackio/config

# From npm (when published)
npm install @veestackio/config

Usage

Basic Usage

import { configEnv, loadEnv, validateEnvironment } from '@veestackio/config';

// configEnv is pre-loaded and validated
console.log(configEnv.VEESTACK_API_URL);
console.log(configEnv.NODE_ENV);

Manual Loading

import { loadEnv, validateEnvironment } from '@veestackio/config';

// Load environment
const { env, usedDotenvFallbackKeys } = loadEnv();

// Validate
const guard = validateEnvironment(env);

if (!guard.ok) {
  console.error('Environment errors:', guard.errors);
  process.exit(1);
}

if (guard.warnings.length > 0) {
  console.warn('Environment warnings:', guard.warnings);
}

Custom Dotenv Path

import { loadEnv } from '@veestackio/config';

const { env } = loadEnv({ dotenvPath: '/path/to/.env' });

API Reference

Environment Schema

All environment variables are validated using Zod:

import { envSchema, type VeeStackEnv } from '@veestackio/config';

// Schema definition
const envSchema = z.object({
  NODE_ENV: z.enum(['development', 'production', 'test']).default('production'),
  VEESTACK_API_URL: z.string().url(),
  VEESTACK_WEB_URL: z.string().url(),
  ACCESS_TOKEN_TTL: z
    .string()
    .regex(/^\d+(ms|s|m|d)$/)
    .default('15m'),
  REFRESH_TOKEN_TTL: z
    .string()
    .regex(/^\d+(ms|s|m|d)$/)
    .default('30d'),
  LOG_LEVEL: z.enum(['debug', 'info', 'warn', 'error']).default('info'),
});

Environment Variables

| Variable | Required | Default | Description | | ------------------- | -------- | ------------ | ---------------------- | | NODE_ENV | No | production | Environment mode | | VEESTACK_API_URL | Yes* | Auto | API base URL | | VEESTACK_WEB_URL | Yes* | Auto | Web dashboard URL | | ACCESS_TOKEN_TTL | No | 15m | Access token lifetime | | REFRESH_TOKEN_TTL | No | 30d | Refresh token lifetime | | LOG_LEVEL | No | info | Logging level |

*Required in production, auto-populated in development.

Development Defaults:

• VEESTACK_API_URL: http://localhost:3000
• VEESTACK_WEB_URL: http://localhost:3000

Production Defaults:

• VEESTACK_API_URL: https://www.veestack.com/api
• VEESTACK_WEB_URL: https://www.veestack.com

Duration Format

Time durations use the format: <number><unit>

| Unit | Meaning | Example | | ---- | ------------ | --------------- | | ms | Milliseconds | 5000ms | | s | Seconds | 900s (15 min) | | m | Minutes | 15m | | h | Hours | 24h | | d | Days | 30d |

Type: VeeStackEnv

interface VeeStackEnv {
  NODE_ENV: 'development' | 'production' | 'test';
  VEESTACK_API_URL: string;
  VEESTACK_WEB_URL: string;
  ACCESS_TOKEN_TTL: string;
  REFRESH_TOKEN_TTL: string;
  LOG_LEVEL: 'debug' | 'info' | 'warn' | 'error';
}

Environment Guards

The guard system validates URL consistency between development and production.

Validation Rules

| Rule | Error | Description | | ---------------- | ---------- | ----------------------------------------- | | Dev + Prod URL | ❌ Error | Cannot use production URLs in development | | Prod + Localhost | ❌ Error | Cannot use localhost in production | | Different Hosts | ⚠️ Warning | API and WEB hosts differ |

GuardResult

interface GuardResult {
  ok: boolean; // All checks passed
  errors: string[]; // Fatal errors
  warnings: string[]; // Non-fatal warnings
}

Example Guard Output

import { loadEnv, validateEnvironment } from '@veestackio/config';

const { env } = loadEnv();
const guard = validateEnvironment(env);

// Mismatch example
// guard.ok = false
// guard.errors = [
//   'Mismatch: NODE_ENV=development cannot use production API URL...'
// ]

Integration

With CLI

// apps/cli/src/index.ts
import { configEnv } from '@veestackio/config';

const apiUrl = configEnv.VEESTACK_API_URL;
const isDev = configEnv.NODE_ENV === 'development';

With Frontend

// apps/frontend/src/lib/api.ts
import { configEnv } from '@veestackio/config';

export const API_BASE_URL = configEnv.VEESTACK_API_URL;

With Edge Functions

// supabase/functions/analyze/index.ts
import { loadEnv } from '@veestackio/config';

const { env } = loadEnv();
const logLevel = env.LOG_LEVEL;

Environment Files

.env.example

# Environment
NODE_ENV=development

# URLs (auto-set if not provided)
VEESTACK_API_URL=http://localhost:3000
VEESTACK_WEB_URL=http://localhost:3000

# Token TTL
ACCESS_TOKEN_TTL=15m
REFRESH_TOKEN_TTL=30d

# Logging
LOG_LEVEL=info

Loading Order

1. process.env (already set variables)
2. .env file (fallback only, doesn't overwrite)
3. Default values (environment-specific)

Error Handling

import { loadEnv } from '@veestackio/config';

try {
  const { env } = loadEnv();
} catch (error) {
  // Invalid environment variables
  console.error('Failed to load configuration:', error);
  process.exit(1);
}

Common Errors:

• Invalid URL format
• Invalid duration format
• Missing required variables in production

Debugging

Use --debug flag to see warnings:

node my-script.js --debug

Output:

⚠️ Environment warnings:
- Heads-up: API host (localhost:3000) != WEB host (localhost:3001). Ensure this is intentional.

Best Practices

1. Always use configEnv for pre-validated config
2. Check guard.ok before starting application
3. Set explicit URLs in production
4. Use duration constants for token TTL

Related

• @veestackio/utils - Uses config for RBAC limits
• CLI Documentation
• Environment Setup Guide