Black Friday: 50% off all products for the first 50 customers. Only 10 left. Use code
40/50 claimed
See pricing →
November 16, 2026

Nuxt Runtime Config and Env Variables Explained

Nuxt runtime config explained: private vs public keys, how NUXT_ env variables override them, why .env is ignored in production, when to use app.config.
Nuxt
Configuration
Deployment
Vue

Nuxt runtime config is where a Nuxt app keeps the values that change between environments: API keys, a database URL, the public site address. You declare the keys once in nuxt.config.ts, and environment variables fill them in when the server starts, so one build can run in staging and production with different settings. The rules are short but strict: the variable names must follow a pattern, .env files are only read at certain times, and anything in the public part ends up in the browser. This post covers all of it, plus app.config and when to use it instead. It follows the Nuxt 4 docs.

What Nuxt runtime config is for

There are three places a Nuxt value can come from, and they answer different questions:

runtimeConfigapp.config.tsprocess.env in nuxt.config.ts
Set whenServer start (from env variables)Build timeBuild time
Env variables override itYes, NUXT_* onesNoIt is the env variable
Reaches the browserOnly the public partAll of it (bundled)Only if you pass it on
Can hold functions, Maps, SetsNo (it's serialized)Yes—
Hot reload in devNoYesNo
ForSecrets, URLs, anything per environmentTheme, site name, feature labelsConfiguring Nuxt and modules

The short version: if a value changes between environments or is secret, it goes in runtimeConfig. If it's fixed for a build and safe to show, app.config.ts.

Private and public keys

Declare every key in nuxt.config.ts, with a default:

// nuxt.config.ts
export default defineNuxtConfig({
  runtimeConfig: {
    databaseUrl: '',
    stripe: {
      secretKey: '',
      webhookSecret: '',
    },
    public: {
      siteUrl: 'http://localhost:3000',
      stripePublishableKey: '',
    },
  },
})

Top-level keys are private: they exist only on the server. Keys under public are available on the server and in the browser, because Nuxt adds them to every page payload.

That second part is the one to be careful with. A secret that ends up under public is readable by every visitor, in the page source. The Stripe publishable key is meant to be public; the secret key never is. The same goes for passing a private value into a page some other way, like returning it from a composable or putting it in useState: the Nuxt docs warn against exposing secrets to the client through any route.

Reading runtime config

In components, composables and plugins, call useRuntimeConfig():

<script setup lang="ts">
const config = useRuntimeConfig()

const canonical = `${config.public.siteUrl}/pricing`
</script>

In the browser, only public (and Nuxt's own app key) is there. On the server, the whole object is available but read-only. In the client, public is writable and reactive, though changing it only affects that visitor's page. Templates can also read $config.public.siteUrl directly.

In server routes, pass the event:

// server/api/checkout.post.ts
export default defineEventHandler(async (event) => {
  const { stripe } = useRuntimeConfig(event)

  return $fetch('https://api.stripe.com/v1/checkout/sessions', {
    method: 'POST',
    headers: { Authorization: `Bearer ${stripe.secretKey}` },
    body: new URLSearchParams({ mode: 'payment' /* ... */ }),
  })
})

The event argument is optional, but the Nuxt docs recommend it, because it applies the environment overrides at runtime. Server code lives in server/ and never ships to the browser; the Nuxt 4 folder structure post explains which folders end up where.

Nuxt env variables: the NUXT_ prefix

An environment variable overrides a runtime config key only if its name matches the key's path:

  1. Start with NUXT_, and NUXT_PUBLIC_ for keys under public.
  2. Turn each level of nesting into an underscore.
  3. Turn camelCase into SCREAMING_SNAKE_CASE.

For the config above:

NUXT_DATABASE_URL=libsql://prod.example.com
NUXT_STRIPE_SECRET_KEY=sk_live_...
NUXT_STRIPE_WEBHOOK_SECRET=whsec_...
NUXT_PUBLIC_SITE_URL=https://www.example.com
NUXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_live_...

Two rules follow from this:

  • The key must be declared. NUXT_ANALYTICS_ID does nothing unless runtimeConfig has an analyticsId key. That's on purpose: only variables you declared reach your code.
  • Other names don't work at runtime. A default like apiKey: process.env.MY_API_KEY is read once, when Nuxt builds, and frozen into the output. In production, setting MY_API_KEY on the server changes nothing. The Nuxt docs say plainly that runtime config won't pick up variables that don't start with NUXT_ in production. Leave the default empty and set NUXT_API_KEY instead.

Values are parsed, not taken as strings

Nuxt converts env values to JavaScript types: true becomes a boolean and 4848 a number. That catches values that only look like numbers. The docs' example is 4848e0, which becomes the number 4848. To keep a string, wrap it in literal double quotes inside the value: NUXT_MY_VAR='"4848e0"'. Check that your hosting dashboard doesn't strip them.

.env in development, build and production

This is where most "it works locally" bugs come from.

  • nuxt dev, nuxt build and nuxt generate read .env from the project root. Changing .env in development restarts Nuxt. To use another file, pass --dotenv .env.local.
  • nuxt preview reads .env too, so local production previews behave like development here.
  • A built server doesn't read .env. When you run node .output/server/index.mjs or deploy to a host, set the variables in the environment: the host's dashboard, the container config or the shell.
NUXT_DATABASE_URL=libsql://prod.example.com node .output/server/index.mjs

And .env belongs in .gitignore. Commit a .env.example with the variable names and empty values instead, so a new developer knows what to set.

Static sites can't change at runtime

With nuxt generate, pages are rendered at build time, and the runtime config values are baked into them. There's no server to start later, so setting env variables after the build does nothing. Set them in the build environment instead.

When to use app.config instead

app.config.ts lives in app/ and holds public values that are fixed at build time:

// app/app.config.ts
export default defineAppConfig({
  siteName: 'Acme',
  theme: {
    dark: false,
    radius: 'md',
  },
})

Read it with useAppConfig(). Unlike runtime config, it supports non-primitive values, has full type inference, and updates without a restart in development. Environment variables can't override it.

Good fits: the site name, theme settings, labels, a list of social links. If you find yourself wanting a different app.config value per environment, it belongs in runtimeConfig.

Typing and environment overrides

Nuxt generates types for runtimeConfig from your defaults, which is one more reason to give every key a default of the right type ('' for strings, 0 for numbers). If you need more precise types, augment the interfaces:

// shared/types/runtime-config.d.ts
declare module 'nuxt/schema' {
  interface RuntimeConfig {
    databaseUrl: string
  }
  interface PublicRuntimeConfig {
    siteUrl: string
  }
}
export {}

nuxt.config.ts also accepts $production, $development and $env: { staging: { ... } } blocks, selected with nuxt build --envName staging. These are build-time switches for Nuxt's own configuration (route rules, modules, devtools). They're not a replacement for env variables: changing a secret should never need a rebuild.

The app secret

Nuxt reserves keys starting with app. appSecret is a private root secret for modules and server features that sign or encrypt data. Set it with NUXT_APP_SECRET in every deployed environment, without declaring it. In development Nuxt generates one if it's missing, but builds never do. Keep it stable across deployments: changing it invalidates whatever was signed with it, like sessions.

Common questions about Nuxt runtime config

Why is my runtime config value empty in production? Usually one of three things: the variable lacks the NUXT_ prefix, its name doesn't match the key's path, or the server is expected to read a .env file it never opens.

Can I use process.env in my components? Don't. It's not available in the browser, and on the server it skips the declared-key rule. Read useRuntimeConfig() instead.

What's the difference between NUXT_ and NUXT_PUBLIC_? NUXT_PUBLIC_* fills keys under runtimeConfig.public, which reach the browser. NUXT_* fills private, server-only keys.

Can runtime config hold an object or array? Plain objects and arrays, yes; nested keys map to underscores. Functions, Maps and Sets don't survive serialization; put that logic in a plugin.

Next step

With the configuration sorted, the rest of an app is screens. The QuasarUI Templates are four complete Quasar admin dashboards with light and dark mode, each with dashboard, reports, task management and kanban pages, delivered as a private GitHub repo. Open the live previews before you start building your own.