Shelve Integration

Shelve is a secrets management platform for development teams. This integration fetches your secrets at build time and injects them into runtime config.

Prerequisites

Before configuring the module, you need a Shelve account with secrets configured.

1. Create a Shelve Account

Sign up at app.shelve.cloud or your self-hosted instance. After signing up, create a team to organize your projects.

2. Create a Project and Add Secrets

Create a project in the Shelve web UI and add your secrets. You can also use the CLI to push an existing .env file:

pnpm add -D @shelve/cli
shelve login
SHELVE_PROJECT=my-app SHELVE_TEAM_SLUG=my-team shelve push

3. Generate an API Token

Navigate to User Tokens and create a new token. Save this token securely — you'll need it for authentication.

Module Configuration

Configure Shelve directly in your nuxt.config:

import * as v from 'valibot'

export default defineNuxtConfig({
  modules: ['nuxt-safe-runtime-config'],
  safeRuntimeConfig: {
    $schema: v.object({
      databaseUrl: v.pipe(v.string(), v.url()),
      authSecret: v.pipe(v.string(), v.minLength(32)),
      public: v.object({
        apiBase: v.pipe(v.string(), v.url()),
      }),
    }),
    shelve: {
      project: 'my-project',
      slug: 'my-team',
    },
  },
})

For local development, run shelve login to authenticate. For CI/CD, set the SHELVE_TOKEN environment variable.

Setup Wizard

On module install (interactive terminals only), the setup wizard can bootstrap schema + Shelve configuration.

Before mutating anything, it shows the planned actions and asks for final confirmation:

• install validation dependencies (if needed)
• write ~/.shelve token (if newly entered)
• update nuxt.config

In CI and non-interactive terminals, the wizard is skipped automatically.

How It Works

1. The module reads your Shelve configuration from nuxt.config
2. Fetches secrets from the Shelve API using your token
3. Transforms variable names to match runtime config structure
4. Merges secrets into runtimeConfig (secrets take priority)
5. Your schema validates the complete merged config

Configuration Options

Authentication

The module requires a valid token to fetch secrets.

Local Development

Run shelve login to store your token in ~/.shelve. The module reads this file automatically.

CI/CD and Production

Set the SHELVE_TOKEN environment variable:

export SHELVE_TOKEN=your-token-here

Variable Transformation

Shelve variables use SCREAMING_SNAKE_CASE. The module transforms them to match Nuxt's runtime config structure:

SHELVE                          → runtimeConfig
─────────────────────────────────────────────────
DATABASE_URL                    → databaseUrl
AUTH_SECRET                     → authSecret
NUXT_PUBLIC_API_BASE            → public.apiBase
NUXT_PUBLIC_FEATURE_FLAGS       → public.featureFlags

Transformation rules:

• NUXT_PUBLIC_* variables become public.* properties
• SCREAMING_SNAKE_CASE converts to camelCase
• Common prefixes group into nested objects

Runtime Fetch

By default, secrets are fetched once at build time and baked into the server bundle. For secrets that must be fresh on each deployment, enable runtime fetch:

safeRuntimeConfig: {
  shelve: {
    project: 'my-project',
    slug: 'my-team',
    fetchAtBuild: false,
    fetchAtRuntime: true,
  },
}

Environment Detection

The module auto-detects which environment to fetch secrets from:

1. shelve.environment option in nuxt.config
2. SHELVE_ENV environment variable
3. 'development' when nuxt.options.dev is true, otherwise 'production'

Self-Hosted Instances

For self-hosted Shelve deployments, configure the URL:

safeRuntimeConfig: {
  shelve: {
    project: 'my-project',
    slug: 'my-team',
    url: 'https://shelve.your-company.com',
  },
}

Or set the SHELVE_URL environment variable.

Environment Variables

You can override any configuration using environment variables:

Resolution priority (high to low):