tessl/npm-nuxt--schema

Nuxt types and default configuration providing comprehensive TypeScript types, schema definitions, and configuration system for the Nuxt framework.

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview

Eval results

Files

Runtime Configuration

Name: tessl/npm-nuxt--schema
Author: tessl

The runtime configuration system in @nuxt/schema provides type-safe configuration management with environment variable support, public/private separation, and runtime override capabilities.

Core Runtime Types

RuntimeConfig Interface

The main runtime configuration interface with server and client separation.

interface RuntimeConfig extends RuntimeConfigNamespace {
  app: NitroRuntimeConfigApp
  /** Server-only configuration */
  nitro?: NitroRuntimeConfig['nitro']
  /** Public configuration (exposed to client) */
  public: PublicRuntimeConfig
}

type RuntimeConfigNamespace = Record<string, unknown>

interface PublicRuntimeConfig extends RuntimeConfigNamespace {
  [key: string]: any
}

Runtime Value Types

Type-safe runtime values with environment variable messaging.

type RuntimeValue<T, B extends string> = T & { [message]?: B }

type UpperSnakeCase<S extends string> = Uppercase<SnakeCase<S>>

type Overrideable<T extends Record<string, any>, Path extends string = ''> = {
  [K in keyof T]?: K extends string
    ? unknown extends T[K]
      ? unknown
      : T[K] extends Record<string, unknown>
        ? RuntimeValue<Overrideable<T[K], `${Path}_${UpperSnakeCase<K>}`>, `You can override this value at runtime with NUXT${Path}_${UpperSnakeCase<K>}`>
        : RuntimeValue<T[K], `You can override this value at runtime with NUXT${Path}_${UpperSnakeCase<K>}`>
    : K extends number
      ? T[K]
      : never
}

Configuration Setup

Basic Runtime Configuration

// nuxt.config.ts
export default defineNuxtConfig({
  runtimeConfig: {
    // Private keys (server-only, not exposed to client)
    apiSecret: 'default-secret',
    databaseUrl: 'postgresql://localhost:5432/mydb',
    stripeSecretKey: '',
    
    // Public keys (exposed to client and server)
    public: {
      apiBase: '/api/v1',
      appName: 'My Nuxt App',
      version: '1.0.0',
      googleAnalyticsId: '',
      baseUrl: 'http://localhost:3000'
    }
  }
});

Environment Variable Mapping

Runtime config values are automatically overridden by environment variables:

# Environment variables override runtime config
NUXT_API_SECRET=my-production-secret
NUXT_DATABASE_URL=postgresql://prod:5432/myapp
NUXT_PUBLIC_API_BASE=https://api.myapp.com
NUXT_PUBLIC_GOOGLE_ANALYTICS_ID=GA-XXXXXXX

// The above environment variables will override:
const config = {
  runtimeConfig: {
    apiSecret: 'my-production-secret',      // from NUXT_API_SECRET
    databaseUrl: 'postgresql://prod:5432/myapp', // from NUXT_DATABASE_URL
    public: {
      apiBase: 'https://api.myapp.com',     // from NUXT_PUBLIC_API_BASE
      googleAnalyticsId: 'GA-XXXXXXX'      // from NUXT_PUBLIC_GOOGLE_ANALYTICS_ID
    }
  }
};

Usage Patterns

Accessing Runtime Config

// In pages, components, plugins, or middleware
export default defineNuxtPlugin(() => {
  const config = useRuntimeConfig();
  
  // Access public config (available everywhere)
  console.log(config.public.apiBase);     // '/api/v1'
  console.log(config.public.appName);     // 'My Nuxt App'
  
  // Access private config (server-only)
  if (process.server) {
    console.log(config.apiSecret);        // 'default-secret'
    console.log(config.databaseUrl);      // 'postgresql://localhost:5432/mydb'
  }
});

Server-Side Usage

// server/api/users.ts
export default defineEventHandler(async (event) => {
  const config = useRuntimeConfig();
  
  // Private config available on server
  const apiSecret = config.apiSecret;
  const databaseUrl = config.databaseUrl;
  
  // Use private config for server operations
  const database = await connectToDatabase(databaseUrl);
  
  return {
    users: await database.users.findMany(),
    // Public config can be sent to client
    apiVersion: config.public.version
  };
});

Client-Side Usage

// composables/useApi.ts
export const useApi = () => {
  const config = useRuntimeConfig();
  
  const apiBase = config.public.apiBase;
  
  const get = async <T>(endpoint: string): Promise<T> => {
    const response = await $fetch<T>(`${apiBase}${endpoint}`);
    return response;
  };
  
  const post = async <T>(endpoint: string, data: any): Promise<T> => {
    return $fetch<T>(`${apiBase}${endpoint}`, {
      method: 'POST',
      body: data
    });
  };
  
  return { get, post };
};

Advanced Configuration Patterns

Nested Configuration

export default defineNuxtConfig({
  runtimeConfig: {
    // Nested server configuration
    database: {
      host: 'localhost',
      port: 5432,
      name: 'myapp',
      credentials: {
        username: 'user',
        password: 'password'
      }
    },
    
    // Service configurations
    services: {
      redis: {
        url: 'redis://localhost:6379',
        maxRetries: 3
      },
      email: {
        provider: 'smtp',
        host: 'smtp.gmail.com',
        port: 587,
        secure: false
      }
    },
    
    public: {
      // Nested public configuration
      features: {
        analytics: true,
        darkMode: true,
        notifications: false
      },
      
      ui: {
        theme: 'default',
        locale: 'en',
        currency: 'USD'
      }
    }
  }
});

Environment variables for nested config:

# Nested server config
NUXT_DATABASE_HOST=production-db.com
NUXT_DATABASE_PORT=5432
NUXT_DATABASE_CREDENTIALS_USERNAME=prod_user
NUXT_DATABASE_CREDENTIALS_PASSWORD=prod_password

# Nested public config
NUXT_PUBLIC_FEATURES_ANALYTICS=false
NUXT_PUBLIC_UI_THEME=dark
NUXT_PUBLIC_UI_LOCALE=fr

Type-Safe Runtime Config

// types/runtime-config.d.ts
declare module 'nuxt/schema' {
  interface RuntimeConfig {
    apiSecret: string
    databaseUrl: string
    stripeSecretKey: string
    
    database: {
      host: string
      port: number
      name: string
      credentials: {
        username: string
        password: string
      }
    }
  }
  
  interface PublicRuntimeConfig {
    apiBase: string
    appName: string
    version: string
    googleAnalyticsId: string
    
    features: {
      analytics: boolean
      darkMode: boolean
      notifications: boolean
    }
    
    ui: {
      theme: 'default' | 'dark' | 'light'
      locale: string
      currency: string
    }
  }
}

Dynamic Configuration

// nuxt.config.ts
export default defineNuxtConfig({
  runtimeConfig: {
    // Computed values
    apiSecret: process.env.NODE_ENV === 'production' 
      ? process.env.PROD_API_SECRET 
      : 'dev-secret',
    
    // Conditional configuration
    databaseUrl: process.env.DATABASE_URL || (() => {
      const isDev = process.env.NODE_ENV === 'development';
      return isDev 
        ? 'postgresql://localhost:5432/dev_db'
        : 'postgresql://localhost:5432/test_db';
    })(),
    
    public: {
      // Environment-based public config
      apiBase: process.env.NODE_ENV === 'production'
        ? 'https://api.myapp.com'
        : '/api',
      
      // Feature flags
      features: {
        betaFeatures: process.env.ENABLE_BETA === 'true',
        debugMode: process.env.NODE_ENV === 'development'
      }
    }
  }
});

Runtime Config Utilities

Configuration Validation

// utils/validate-config.ts
import type { RuntimeConfig } from '@nuxt/schema';

export function validateRuntimeConfig(config: RuntimeConfig) {
  const errors: string[] = [];
  
  // Validate required server config
  if (!config.apiSecret) {
    errors.push('API secret is required');
  }
  
  if (!config.databaseUrl) {
    errors.push('Database URL is required');
  }
  
  // Validate public config
  if (!config.public.apiBase) {
    errors.push('API base URL is required');
  }
  
  if (errors.length > 0) {
    throw new Error(`Runtime config validation failed:\n${errors.join('\n')}`);
  }
}

// In a plugin
export default defineNuxtPlugin(() => {
  const config = useRuntimeConfig();
  
  if (process.server) {
    validateRuntimeConfig(config);
  }
});

Configuration Helpers

// composables/useConfig.ts
export const useAppConfig = () => {
  const config = useRuntimeConfig();
  
  return {
    // Typed getters
    get apiBase() { return config.public.apiBase; },
    get appName() { return config.public.appName; },
    get version() { return config.public.version; },
    
    // Feature flags
    isFeatureEnabled: (feature: keyof typeof config.public.features) => {
      return config.public.features[feature] === true;
    },
    
    // Environment helpers
    get isDevelopment() {
      return config.public.features?.debugMode === true;
    },
    
    get isProduction() {
      return !this.isDevelopment;
    }
  };
};

Module Integration

// In a Nuxt module
export default defineNuxtModule({
  setup(options, nuxt) {
    // Add module-specific runtime config
    nuxt.options.runtimeConfig.myModule = {
      apiKey: options.apiKey || '',
      timeout: options.timeout || 5000
    };
    
    nuxt.options.runtimeConfig.public.myModule = {
      enabled: options.enabled !== false,
      version: '1.0.0'
    };
    
    // Validate configuration
    nuxt.hook('ready', () => {
      const config = nuxt.options.runtimeConfig;
      if (!config.myModule?.apiKey) {
        throw new Error('MyModule: API key is required');
      }
    });
  }
});

The runtime configuration system provides a powerful and type-safe way to manage application settings with clear separation between server and client configuration, automatic environment variable mapping, and full TypeScript support.

Install with Tessl CLI