---
title: "Configuration and secrets"
description: "Read API keys and settings through Nuxt's runtimeConfig and set them with wervt env."
canonical_url: "https://docs.dev.lightdrop.cloud/guides/configuration"
---
# Configuration and secrets

> Read API keys and settings through Nuxt's runtimeConfig and set them with wervt env.

An app reads its configuration (API keys, feature switches, URLs of other services) through Nuxt's
`runtimeConfig`. Declare each key with a default in `nuxt.config.ts`, then set the real value per
app with `wervt env`. No rebuild or redeploy is needed.

- The defaults give the keys their types, so there is no `env.d.ts` to write.
- Keys outside `public` exist only on the server and never reach the browser.
- The same names work locally in `.env`, on wervt with `wervt env`, and in CI.

## Declare the keys

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  modules: ['@wervt/nuxt'],
  runtimeConfig: {
    weatherApiKey: '',
    public: { mapStyle: 'light' },
  },
  compatibilityDate: '2026-10-01',
})
```

New apps from `create-wervt` start with an `exampleSecret` key and the route
`server/api/example-secret.get.ts` that reads it. Replace both with your own.

## Read them

On the server, `useRuntimeConfig()` from `nuxt/server` returns every key:

```ts [server/api/weather.get.ts]
import { createError, defineEventHandler, useRuntimeConfig } from 'nuxt/server'

export default defineEventHandler(async () => {
  const { weatherApiKey } = useRuntimeConfig()
  if (!weatherApiKey) throw createError({ status: 500, message: 'NUXT_WEATHER_API_KEY is not set' })
  return $fetch('https://api.example.com/today', { query: { key: weatherApiKey } })
})
```

In Vue components, `useRuntimeConfig()` returns only the `public` keys:

```vue [app.vue]
<script setup lang="ts">
const { mapStyle } = useRuntimeConfig().public
</script>
```

## Set the values

Each key has an environment variable: `NUXT_` followed by the key path in SCREAMING_SNAKE_CASE.

<table>
<thead>
  <tr>
    <th>
      Key in <code>
        runtimeConfig
      </code>
    </th>
    
    <th>
      Variable
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        weatherApiKey
      </code>
    </td>
    
    <td>
      <code>
        NUXT_WEATHER_API_KEY
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        public.mapStyle
      </code>
    </td>
    
    <td>
      <code>
        NUXT_PUBLIC_MAP_STYLE
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        stripe.secretKey
      </code>
    </td>
    
    <td>
      <code>
        NUXT_STRIPE_SECRET_KEY
      </code>
    </td>
  </tr>
</tbody>
</table>

```bash
wervt env my-app --set NUXT_WEATHER_API_KEY=… --set NUXT_PUBLIC_MAP_STYLE=dark
wervt env my-app                                 # lists the keys, never the values
wervt env my-app --unset NUXT_PUBLIC_MAP_STYLE   # back to the default from nuxt.config.ts
```

The runtime passes the variables to the app's isolate when it starts, and Nuxt applies them to
`runtimeConfig` there, not at build time. A change starts a fresh isolate on the next request, so
it applies without a deploy. The same build can run with different values, and nothing secret ends
up in the build output.

Only keys declared in `runtimeConfig` can be set this way. A `NUXT_*` variable without a matching
key is ignored, so add the key to `nuxt.config.ts` (and deploy) first.

Values are write-only: nobody can read them back through the CLI or the dashboard. Names starting
with `WERVT_` and `DATABASE_URL` are reserved for the runtime.

## Locally

`nuxt dev` reads the same variables from the app's `.env`, which `create-wervt` already ignores
in git:

```bash [.env]
NUXT_WEATHER_API_KEY=…
```

## `process.env`

Variables set with `wervt env` are in `process.env` as well, and `@wervt/nuxt` types it for server
code. It still works for code that expects it (a library reading `process.env`), but use
`runtimeConfig` for the app's own settings: it is typed by the defaults, keeps private keys out of
the client, and works the same in `nuxt dev` and in the isolate.


## Sitemap

See the full [sitemap](https://docs.dev.lightdrop.cloud/sitemap.md) for all pages.
