# Shelve Integration

> 

[Shelve](https://shelve.cloud) is a secrets management platform. This integration fetches your secrets and injects them into runtime config.

## Setup

1. Install and configure Shelve CLI:

```bash
npx shelve@latest init
```

1. Enable in your config:

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  safeRuntimeConfig: {
    $schema: runtimeConfigSchema,
    shelve: true, // auto-detect from shelve.json
  },
})
```

## How It Works

<steps level="4">

#### Module reads your `shelve.json` configuration

#### Fetches secrets from Shelve API at build time

#### Merges secrets into `runtimeConfig`

#### Your schema validates the merged config

</steps>

Secrets from Shelve override values in `runtimeConfig`.

## Configuration

### Auto Mode (default)

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

### Explicit Configuration

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

## Options

<table>
<thead>
  <tr>
    <th>
      Option
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Default
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        enabled
      </code>
    </td>
    
    <td>
      <code>
        boolean | 'auto'
      </code>
    </td>
    
    <td>
      <code>
        'auto'
      </code>
    </td>
    
    <td>
      Enable integration
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        project
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      from shelve.json
    </td>
    
    <td>
      Project name
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        slug
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      from shelve.json
    </td>
    
    <td>
      Team slug
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        environment
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      auto-detected
    </td>
    
    <td>
      Environment name
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        url
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      <code>
        https://app.shelve.cloud
      </code>
    </td>
    
    <td>
      API URL
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        fetchAtBuild
      </code>
    </td>
    
    <td>
      <code>
        boolean
      </code>
    </td>
    
    <td>
      <code>
        true
      </code>
    </td>
    
    <td>
      Fetch during build
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        fetchAtRuntime
      </code>
    </td>
    
    <td>
      <code>
        boolean
      </code>
    </td>
    
    <td>
      <code>
        false
      </code>
    </td>
    
    <td>
      Fetch on cold start
    </td>
  </tr>
</tbody>
</table>

## Variable Transformation

Shelve variables are automatically transformed to match runtime config structure:

```text
# 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:

```ts
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:

<steps level="4">

#### `shelve.environment` option

#### `SHELVE_ENV` environment variable

#### `shelve.json` defaultEnv

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

</steps>
