v5.0.0

Introduction

Nuxt Site Config v5 supports Nuxt 4.6 and Nuxt 5. It uses the portable nuxt/server request APIs.

v5 ships in Nuxt SEO v6. If you use @nuxtjs/seo, follow the Nuxt SEO v5 to v6 migration guide.

Read the upgrade steps before you upgrade.

Breaking Changes

Nuxt 4.6 and Node 22 Required

The module requires Nuxt ^4.6.0 || ^5.0.0 and Node ^22.22.3 || ^24.15.0 || >=26.0.0. Nuxt 3 is no longer supported. (#121)

Upgrade Nuxt and Node before you upgrade Site Config.

DevTools Needs nuxtseo-devtools-host

The Site Config DevTools tab moved to an optional package. Install it as a dev dependency:

pnpm add -D nuxtseo-devtools-host

Restart the dev server after you install it. Without the package, the tab shows an install button. (#121)

trailingSlash and indexable Values

Two resolved values change. (#113)

• NUXT_SITE_TRAILING_SLASH=false now disables trailing slashes. In v4, the string "false" enabled them.
• If you do not set indexable, it resolves from env. In v4, getSiteConfig(event).indexable returned undefined.

const { indexable } = getSiteConfig(event)
// v4: undefined
// v5: true when env is 'production', else false

Module Authors: installNuxtSiteConfig() Removed

nuxt-site-config/kit and nuxt-site-config-kit no longer export installNuxtSiteConfig(). Declare Site Config as a module dependency instead. (#137)

+import { fileURLToPath } from 'node:url'
 import { defineNuxtModule } from '@nuxt/kit'
-import { installNuxtSiteConfig, updateSiteConfig } from 'nuxt-site-config/kit'
+import { updateSiteConfig } from 'nuxt-site-config/kit'

 export default defineNuxtModule({
+  moduleDependencies: {
+    [fileURLToPath(import.meta.resolve('nuxt-site-config'))]: { version: '>=5.0.0' },
+  },
   async setup() {
-    await installNuxtSiteConfig()
     updateSiteConfig({ _context: 'my-module', name: 'My Site' })
   },
 })

Keep nuxt-site-config in your package dependencies. Resolve it from your package to support pnpm's global virtual store.

Kit functions now set up the config stack on first use. To read values that other modules set, read them in the modules:done hook or later.

Module Authors: Build Time Priority

In v4, a build time updateSiteConfig() without _priority ranked above every other source. It now ranks with the user's site key, SiteConfigPriority.config. (#117)

The build time order, from lowest to highest priority:

1. Modules that call updateSiteConfig()
2. The site key in nuxt.config.ts
3. The site-config:resolve hook
4. i18n
5. NUXT_SITE_* env vars at build
6. NUXT_SITE_* env vars at runtime

The user's site key and NUXT_SITE_URL now override a module value. To keep the v4 rank, pass a priority:

import { SiteConfigPriority, updateSiteConfig } from 'nuxt-site-config/kit'

updateSiteConfig({
  _context: 'my-module',
  url: 'https://example.com',
  _priority: SiteConfigPriority.runtime,
})

Runtime pushes keep the highest rank. These are route rules, the site-config:init hook, and Nitro updateSiteConfig(event).

New Features

📦 Typed Runtime Imports. Import app helpers from #site-config/app and server helpers from #site-config/server. Each path has generated types. Auto imports still work. (#121)

import { defineEventHandler } from 'nuxt/server'
import { getSiteConfig } from '#site-config/server'

export default defineEventHandler((event) => {
  const { url, name } = getSiteConfig(event)
  return { url, name }
})

⏱️ Site Config Before Your Middleware. Site config now resolves in the Nitro request hook. In v4, getSiteConfig(event) returned empty values in your own server/middleware/. It now returns the resolved config. (#114)

A request hook from nitro.plugins can also read the resolved config. (#117)

🔔 Prerender Warning. The build now warns if it prerenders any route without a site url. In that case, prerendered pages render absolute URLs as relative paths. (#114)

[Nuxt Site Config] Invalid config for prerendering, please correct:
  - url is not set, so prerendered pages render absolute URLs as relative paths. Set site.url or NUXT_SITE_URL

🤖 Agent Skill. The package ships an Agent Skill at node_modules/nuxt-site-config/skills/nuxt-site-config/SKILL.md. Coding agents read it for the rules of the installed version. (#112)

Bug Fixes

• Multi-tenancy: The client payload now holds only the matched tenant. In v4, it held the hosts and config of every tenant. (#113)
• Path resolver: Without a url, the server createSitePathResolver() returned relative URLs, even with absolute: true. It now uses the request origin. (#129)
• i18n: With a non-root app.baseURL and @nuxtjs/i18n, the canonical URL and og:url repeated the base path. They now include it once. (#135)

Dependencies

• nuxt-site-config no longer depends on h3, pathe, or pkg-types.
• nuxt-site-config-kit no longer depends on std-env.

Upgrading

1. Upgrade to Nuxt 4.6 or Nuxt 5. Use Node 22.22.3+, 24.15.0+, or 26+.
2. If you use @nuxtjs/seo, upgrade it to v6. Otherwise, upgrade nuxt-site-config to v5.
3. If you use the DevTools tab, run pnpm add -D nuxtseo-devtools-host.
4. If you set NUXT_SITE_TRAILING_SLASH=false, check your URLs. Trailing slashes are now off.
5. Module authors: replace installNuxtSiteConfig() with moduleDependencies.
6. Module authors: if an updateSiteConfig() call must override the user's config, pass _priority.