nuxt-safe-runtime-config logonuxt-safe-runtime-config

Shelve Integration

Shelve is a secrets management platform. This integration fetches your secrets and injects them into runtime config.

Setup

  1. Install and configure Shelve CLI:
npx shelve@latest init
  1. Enable in your config:
nuxt.config.ts
export default defineNuxtConfig({
  safeRuntimeConfig: {
    $schema: runtimeConfigSchema,
    shelve: true, // auto-detect from shelve.json
  },
})

How It Works

Module reads your shelve.json configuration

Fetches secrets from Shelve API at build time

Merges secrets into runtimeConfig

Your schema validates the merged config

Secrets from Shelve override values in runtimeConfig.

Configuration

Auto Mode (default)

safeRuntimeConfig: {
  shelve: true, // uses shelve.json settings
}

Explicit Configuration

safeRuntimeConfig: {
  shelve: {
    project: 'my-project',
    slug: 'my-team',
    environment: 'production',
    url: 'https://app.shelve.cloud', // default
  },
}

Options

OptionTypeDefaultDescription
enabledboolean | 'auto''auto'Enable integration
projectstringfrom shelve.jsonProject name
slugstringfrom shelve.jsonTeam slug
environmentstringauto-detectedEnvironment name
urlstringhttps://app.shelve.cloudAPI URL
fetchAtBuildbooleantrueFetch during build
fetchAtRuntimebooleanfalseFetch on cold start

Variable Transformation

Shelve variables are automatically transformed to match runtime config structure:

# Shelve variables
DATABASE_URL=postgres://...
NUXT_PUBLIC_API_BASE=https://api.example.com
AUTH_SECRET=my-secret

# Becomes runtimeConfig
{
  databaseUrl: 'postgres://...',
  public: {
    apiBase: 'https://api.example.com'
  },
  authSecret: 'my-secret'
}

Transformation rules:

  • NUXT_PUBLIC_* becomes public.*
  • SCREAMING_CASE becomes camelCase
  • Grouped by common prefixes

Runtime Fetch

For secrets that should be fetched fresh on each cold start:

safeRuntimeConfig: {
  shelve: {
    fetchAtBuild: false,    // skip build-time fetch
    fetchAtRuntime: true,   // fetch on server start
  },
}

Requires SHELVE_TOKEN environment variable at runtime.

Environment Detection

Environment is auto-detected in this order:

shelve.environment option

SHELVE_ENV environment variable

shelve.json defaultEnv

'development' if nuxt.options.dev, else 'production'

Integrations

ESLint Integration