Site Config
Getting Started

How it works

Learn how the Nuxt Site Config module works, so you can get the most out of it.

Config Sources

Site config is resolved from the following sources, in order of precedence:

Build Time

1. System

System details relate to the environment the app is running in.

export default {
  name: rootDirBaseName, // e.g. '/home/harlan/projects/my-nuxt-app' -> 'my-nuxt-app'
  indexable: process.env.NODE_ENV === 'production'

2. Package.json

Site config provided by the package.json file.

export default {
  description: pkgJson.description,

3. Vendor Environment Variables

Environment variables provided by the hosting providers.

export default {
  url: [
    // vercel, netlify
    // cloudflare pages
  // vercel, netlify
  name: [process.env.NUXT_ENV_VERCEL_GIT_REPO_SLUG, process.env.SITE_NAME]

4. Module overrides

Build time site config provided by modules.

5. Nuxt Config site key

Site config provided by the user in the Nuxt config.

6. Runtime Config and Environment Variables

Site config provided by the user at runtime. and associated environment variables.

This will also attempt to use legacy environment variables from Nuxt:

  • Private / public runtime config camel cased siteUrl, public.siteUrl
  • Environment variables with and without PUBLIC: NUXT_ENV_SITE_URL, NUXT_ENV_PUBLIC_SITE_URL

7. Nuxt Hook

The site-config:resolve hook is called to allow any final build-time modifications to the config.

SSR / Nitro Runtime

1. Request URL

The request URL is used to determine the site URL at runtime.

2. Build Time Site Config

Config resolved in the build step. This is stored on the key.

3. App Config

Config resolved from the App Config using the site key.

4. Route Rules

Config resolved from the route rules of the request path, the site key. This allows for multi-site support.

CSR Runtime

1. Browser Context

Uses the site URL from the window.location.origin.

2. SSR Runtime Config

The SSR runtime config created in the SSR step. This is sent to the client-side to avoid hydration errors.