Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/dvlkit/nuxe/llms.txt

Use this file to discover all available pages before exploring further.

Runtime config lets you inject values into your app at server startup time, without a rebuild. You define default values in nuxe.config.ts, and any of those values can be overridden by NUXE_* environment variables when the server starts. Nuxe automatically generates TypeScript types for your config so that useRuntimeConfig() is fully typed throughout your project.

​
Defining runtime config

Declare defaults under runtimeConfig in nuxe.config.ts. Top-level keys are server-only. Keys nested under public are also sent to the client.
nuxe.config.ts
import { defineConfig } from '@dvlkit/nuxe/config'

export default defineConfig({
  runtimeConfig: {
    dbUrl: 'postgres://localhost/mydb',  // server-only
    public: {
      apiBase: '/api',                   // client + server
    },
  },
})
Never place secrets or private credentials under runtimeConfig.public. The entire public object is serialized and sent to the browser. Only top-level (non-public) keys stay on the server.

​
Reading runtime config

Call useRuntimeConfig() inside any Vue <script setup>, composable, or plugin. It returns a typed RuntimeConfig object whose shape is derived from your nuxe.config.ts. The RuntimeConfig type is defined as: 
interface RuntimeConfig {
  public: Record<string, unknown>
  [key: string]: unknown
}
Once Nuxe generates types from your config (see Type generation below), useRuntimeConfig() is narrowed to the exact shape of your declared keys. 
<script setup lang="ts">
const config = useRuntimeConfig()
console.log(config.public.apiBase)
</script>
useRuntimeConfig() uses Vue’s inject internally. It is safe to call anywhere that has an active injection context (setup functions, plugins, composables called from setup). Outside of a Vue context it returns an empty config ({ public: {} }).

​
Client vs. server availability

On the server, useRuntimeConfig() returns the full config including all top-level private keys. On the client, only the public sub-object is available — private keys are stripped from the browser payload before the page is sent. Never rely on top-level keys being present in client-side code.

​
Environment variable overrides

Nuxe maps every NUXE_* environment variable to a runtime config key using the following rules:
  • camelCase config keys map to UPPER_SNAKE_CASE env var suffixes — for example dbUrl → NUXE_DB_URL
  • Keys under public use the prefix NUXE_PUBLIC_ — for example public.apiBase → NUXE_PUBLIC_API_BASE
  • Nested keys use _ as a separator at each level
  • Boolean strings "true" and "false" are coerced to boolean
  • Strings that match the pattern /^-?\d+$/ are coerced to number
  • All other string values are kept as strings

​
Playground example

Config keyEnvironment variable
apiSecretNUXE_API_SECRET
public.apiBaseNUXE_PUBLIC_API_BASE

​
Two-pass resolution

Nuxe resolves runtime config in two passes:
  1. Declared keys — any NUXE_* env var whose name matches a key already present in your config is applied first.
  2. Undeclared keys — any remaining NUXE_* env vars that did not match a declared key are injected automatically, creating new keys at runtime.
This means you can add new runtime config values purely via environment variables without touching nuxe.config.ts.

​
Reserved environment variables

The following NUXE_* names are used internally by Nuxe and must not be used as runtime config keys:

NUXE_SILENT

Suppresses Nuxe’s console output when set.

NUXE_DEV

Signals that Nuxe is running in development mode.

NUXE_BASE_URL

Sets the base URL for server-side useFetch. Overrides config.baseUrl.

NUXE_VITE_NODE_OPTIONS

Node.js options forwarded to the Vite child process.

​
Type generation

When Nuxe starts (dev or build), it inspects your resolved runtimeConfig and writes a TypeScript declaration file to .nuxe/runtime-config.d.ts. This file contains:
  • A concrete RuntimeConfig interface shaped exactly like your config
  • Module augmentation for @dvlkit/nuxe and @dvlkit/nuxe/runtime so that useRuntimeConfig() returns the typed interface everywhere
Example of a generated file for the playground config:
.nuxe/runtime-config.d.ts
// Generated by nuxe
export interface RuntimeConfig {
  apiSecret: string
  public: {
    apiBase: string
  }
}

declare module '@dvlkit/nuxe' {
  export function useRuntimeConfig(): RuntimeConfig
}

declare module '@dvlkit/nuxe/runtime' {
  export function useRuntimeConfig(): RuntimeConfig
}
The .nuxe/ directory is generated automatically. You should add it to .gitignore. The types are regenerated on every nuxe dev and nuxe build invocation, so they always reflect your current config.

Build docs developers (and LLMs) love

Get started for freeTalk to us