nuxt/nuxt
github.com/nuxt/nuxt ↗ · 2361 files · 6.7 MB
Nuxt Nuxt is a free and open-source framework with an intuitive and extendable way to create type-safe, performant and production-grade full-stack web applications and websites with Vue.js.
Overview
Nuxt is a Vue full-stack framework for developers building server-rendered, static, hybrid, and client-rendered websites and applications. At commit 3fde4d625cc353e83ac10f6b75db8ca480167be4, this monorepo contains the core framework, module toolkit, configuration schema, app builders, and separate server integrations, with package manifests on the 5.0.0-0 prerelease line. Its distinctive architecture combines filesystem discovery and generated modules with request-scoped Vue applications, serialized hydration payloads, and an extensible renderer. This brief is agent-authored and has not been human-reviewed; it reflects bounded source inspection, with no repository code or tests executed.
System map
This is a framework monorepo rather than a single deployed application. Configuration loading and module initialization produce generated application modules consumed by an app builder and a separately selected server builder. Vue application state lives within NuxtApp instances, while renderer artifacts are cached per renderer instance and sessions persist through sealed cookies. Published package exports, documentation packaging, playground scripts, and release automation form separate delivery surfaces.
- The core programmatic entrypoint exports createNuxt and loadNuxt from core/nuxt.ts and build from core/builder.ts; the nuxt and nuxi executables delegate directly to the external @nuxt/cli/cli package.
- The documented package split assigns module authoring to packages/kit, framework orchestration to packages/nuxt, configuration types/defaults to packages/schema, and compilation to the Vite, Webpack, and Rspack packages.
- createNuxt constructs the Hookable lifecycle, virtual filesystem, application registry, build-output providers, and serverBuild description; ready enters initNuxt within Nuxt context.
- App-builder configuration maps vite, webpack, and rspack names to their packages and defaults to Vite; server.builder independently maps nitro and vite and defaults to @nuxt/nitro-server.
- The server renderer exposes createNuxtRenderer(...).fetch(event) returning Promise<Response>; Nitro adapts ServerRequest into an event, optionally decorates legacy semantics, and calls that renderer.
- NuxtApp owns reactive payload.data, payload.state, payload._errors, async-data registries, and state defaults; createRendererInstance separately owns renderer options and lazily loaded build artifacts.
- The inspected persistence paths include hydration payloads, optional template writes, renderer prerender payload-cache operations, and sealed session cookies; these have distinct state owners.
- Root scripts build workspace packages, prepare development artifacts, run the playground, and expose distinct unit, runtime, fixture, type, bundle, public-API, and Playwright test commands; the package manager is pinned to pnpm@12.6.0.
- The documented Nitro Node deployment starts .output/server/index.mjs and uses NITRO_PORT/PORT and NITRO_HOST/HOST; the default server-build description resolves client/server inputs under buildDir and deployment output under .output.
- The docs package distributes raw Markdown/YAML. UI templates are built with Vite, UnoCSS, and rendering plugins, while docs deployment automation triggers a webhook on documentation pushes.
- Release automation creates release PRs, handles merged release branches, packs tarballs, and publishes through npm OIDC; the main branch remains a v5 prerelease line and v5 tags publish under 5x.
Feature catalog
The developer-facing surface centers on convention-based Vue applications, generated routing, SSR-friendly data access, and deployment choices. The inspected implementation also supports metadata management, component discovery, plugin execution, navigation prefetching, cookie sessions, and route-specific rendering behavior. Development tooling includes filesystem-driven regeneration and optional DevTools integration. This catalog covers the evidenced feature families and explicit experimental limits, rather than claiming an exhaustive inventory of every composable or external CLI command.
- Filesystem routing scans page directories across layers, builds a route tree, resolves metadata, and emits routes.mjs through normalizeRoutes.
- Navigation middleware combines global middleware, matched-page metadata, and routeRules.appMiddleware; named middleware loads on demand and may continue, cancel, redirect, or return an error.
- SSR, client-only shells, prerender payload extraction, cached-route payload extraction, noScripts, and streaming are selected through build flags and route rules in renderRoute.
- useFetch and useLazyFetch wrap typed fetching with reactive request keys and fetch options; useAsyncData supplies default values, transforms, pick, deduplication, cancellation, and status/error refs.
- useState creates keyed reactive hydration state using the $s prefix; clearNuxtState can target all keys, selected keys, or a predicate, then reset defaults or delete values.
- useHead, useHeadSafe, and useSeoMeta obtain the request/server head or injected client head and delegate to Unhead.
- Auto-imports use an Unimport context with an OXC parser, generated #imports exports, source transforms, and composables/utils scanning; component discovery separately scans component directories and exposes components:extend.
- NuxtLink supports visibility and interaction prefetch triggers, opt-outs, a link:prefetch hook, production route-component prefetching, and cleanup of observation and idle callbacks.
- Core initialization registers NuxtLayout, NuxtErrorBoundary, ClientOnly, DevOnly, ServerPlaceholder, and NuxtLink as built-in components.
- Component-island requests have a dedicated /__nuxt_island/ dispatch boundary, and client payload revival can schedule island JSON fetches and retain their results in payload.data.
- The nuxt/server surface exports session management, purpose-specific secret derivation, CORS handling, validated query/body helpers, and request-event types.
- Layered configuration supports theme, _extends, and extends sources, a custom layer resolver, remote-layer support checks, and aliases such as #layers/<name>.
Data flow
Configuration and filesystem inputs are transformed into resolved options, discovered application structure, generated modules, and bundled artifacts. Incoming requests enter a server adapter and receive a fresh SSR context before Vue plugins, routing, and page data execute. Async results and useState values become serialized payloads that the browser revives before mounting. Session persistence follows a separate cookie-sealing path and does not use the hydration-state registry.
- loadNuxtConfig populates environment-based defaults before loading the schema, imports executable config with native import or Jiti fallback, and passes layered configuration through c12.
- Resolved layer configuration supplies user hooks in reverse layer order; module resolution similarly registers extended-layer modules before project modules and deduplicates resolved module paths.
- generateApp resolves application structure, combines default and user templates, invokes app:templates, compiles contents, and stores changed results under absolute paths and #build aliases in nuxt.vfs.
- Page files from layer appPages directories become prioritized InputFile entries, then a PagesContext route tree and augmented NuxtPage records; routes.mjs serializes normalized routes and imports for runtime use.
- Nitro's renderer adapter converts ServerRequest through createEvent, then renderRoute calls createSSRContext to attach URL, runtime config, head manager, payload, reducer registry, and module tracking.
- createNuxtApp connects its payload to ssrContext and exposes only runtimeConfig.public and runtimeConfig.app as client config, while private runtime config remains available through the server context.
- useFetch derives a hashed key from the request and option segments, selects custom $fetch or request-scoped server fetching, and delegates execution to useAsyncData with a cancellation signal.
- Async-data execution applies transform and pick before assigning data/status; unless serialize is false, the same result is written into nuxtApp.payload.data[key], and stale replaced promises are prevented from updating state.
- Payload output uses devalue stringify with custom reducers; splitPayload separates data and prerenderedAt from initial state, and renderRoute chooses full inline JSON or initial JSON referencing an external payload URL.
- Client payload loading parses __NUXT_DATA__, optionally retrieves external JSON with force-cache for prerendered pages or no-cache for runtime pages, merges client config, and installs registered revivers before assigning the result to NuxtApp.
- Hydration reads async-data values from payload.data and useState values from payload.state; ordinary nonmanual async-data cache lookup can instead read nuxtApp.static.data after hydration.
- Session input arrives through a named request cookie, is unsealed once per event/name, and becomes a cached Session object; updates merge data, reseal the versioned payload, and replace that session's Set-Cookie header.
Behavior traces
The traced flows cover framework startup/build, an SSR page request through browser hydration, SSR-friendly fetching, and cookie persistence across requests. Each trace follows concrete functions and state transitions in the inspected implementation. Development regeneration and error rendering add alternate paths that influence these flows. These are source-derived execution sequences, not observed runtime executions.
- Startup begins with kit loadNuxt normalizing cwd and dev overrides, resolving the installed nuxt package, and importing its loadNuxt; core loadNuxt then calls loadNuxtConfig and createNuxt, and awaits ready unless ready:false.
- Initialization registers core pages/head/components/compiler/import/schema modules, installs resolved modules, emits modules:done, calls bundleServer, registers payload support, and emits ready.
- A normal build calls ensureGeneratedTsConfigs → createApp → generateApp → resolveBuilder → build:before → builder.bundle → build:done; a production build then closes Nuxt.
- In the separate Nitro build path, build:done invokes nitro:build:before → prepare; development calls build and waits for compiled, while production calls prerender and then build, with public assets copied through rollup:before.
- A buffered SSR request follows Nitro handler.fetch → createEvent → renderer.fetch → renderRoute → createSSRContext → instance.getRenderer; build-files loads the server entry and creates vue-bundle-renderer's renderer.
- The server entry runs createApp(RootComponent) → createNuxtApp → applyPlugins → app:created; buffered rendering then calls renderToString, app:rendered, render:html, and runtime.createResponse for the document.
- Browser startup detects serverRendered/data-ssr → chooses createSSRApp or createApp → creates NuxtApp → applies plugins, including payload revival → emits app:created and app:beforeMount → mounts → emits app:mounted.
- SSR fetching follows useFetch → useAsyncData → createInitialFetch/buildAsyncData → execute → selected $fetch; server execution registers its promise with onServerPrefetch or app:created, then applies transforms and writes serializable data to the payload.
- Cookie persistence follows useSession → getSession → loadSession → getCookie/unsealSession; missing or invalid seals create a UUID session, and updateSession → sealSession → setSessionCookie writes a cookie that the next request can load.
- Development changes enter builder:watch: structural changes invalidate application discovery, eligible content changes regenerate filtered templates, and unfiltered builder:generateApp requests force complete structure resolution.
- Renderer error dispatch rejects direct external /__nuxt_error access, avoids inline HTML handling for JSON requests and recursive error renders, and otherwise catches route-render failures through renderErrorResponse.
Testing signals
Tests and CI were inspected, not executed; their existence and assertions establish intended coverage, not passing results. Vitest separates unit, renderer, Nuxt-environment, fixture-matrix, bundle, and type-performance projects, while Playwright drives browser scenarios. CI schedules type/API checks, runtime/unit tests, fixture tests, browser tests, and security analysis with event-specific gates. The inspection is bounded, and explicit exclusions, disabled jobs, and a fixme prevent treating the configured suite as exhaustive coverage.
- The unit Vitest project discovers package test/spec files and supplies generated-module/runtime aliases; Nuxt-environment projects run test/nuxt with @nuxt/test-utils configuration and fixture preparation.
- Fixture projects exercise Vite dev/built, async/default context, and manifest-on/off combinations; Nitro-Vite, Rspack, and Webpack intentionally use smaller matrices, with additional legacy-error projects.
- Renderer tests prepare standalone generated artifacts and inject renderer configuration; standalone.test.ts asserts HTML, asset URL helpers, SPA route behavior, hooks, and isolation between renderer options.
- Inline-error tests assert preservation of Set-Cookie and middleware headers, static fallback after an error-page failure, rejection rather than HTML for payload failures, and 404 handling for the retired error route.
- Session unit tests use synthetic Web Request events and mocked runtime config to check cookie flags, cross-request round trips, tampering, expiry, format rejection, cookie-size limits, and missing appSecret failures.
- Nuxt runtime fetching tests register local endpoints and inspect payload entries, computed request equivalence, removed params handling, serialize:false, reactive keys, basic async-data return shape, and shallow refs.
- Builder tests create temporary applications and exercise chokidar, granular chokidar, and Parcel watcher strategies, including parent-path changes and selective template recompilation.
- Playwright uses Desktop Chrome across Vite dev/built, Nitro-Vite dev/built, and built Webpack/Rspack projects; it excludes dev-only, build-only, Vite-only, shared-fixture mutation, and Rspack chunk-error scenarios as configured.
- Streaming browser tests assert redirects, pre-shell error fallback, mid-stream error payloads/client error pages, and late-status behavior; the dev SFC stylesheet-before-shell scenario is explicitly test.fixme.
- CI defines built-type/public-API checks, prepared runtime/unit/no-Jiti tests, Linux/Windows fixture projects, and Linux/Windows Playwright runs; these workflow definitions were read without executing or retrieving run results.
- The benchmark CI job is disabled with if:false pending CodSpeed's Vitest 5 support. Root test:unit includes unit and renderer but omits the separately configured renderer-legacy-errors project.
- Security/documentation checks include CodeQL for JavaScript/TypeScript and Actions, OpenSSF SARIF analysis, and Lychee checks that limit pull requests to internal docs links but expand scheduled/manual runs.
Risk map
The following items are sensitive source boundaries and explicit limitations, not confirmed vulnerabilities. Executable configuration, remote layers, dependency installation, development HTTP handlers, and request-header forwarding deserve focused review when changed. Hydration serialization and streaming response commitment impose correctness constraints that cross package boundaries. The strongest observed testing limits are configured exclusions, a disabled benchmark job, and a documented development CSS fixme.
- Configuration is executable input: importConfigFile uses native dynamic import and may retry through Jiti, while c12 enables global rc loading by default and accepts remote extends sources.
- Dependency recovery can mutate a consumer project and spawn a package-manager process: ensureDependencyInstalled prompts outside CI, permits StackBlitz-specific auto-install behavior, and runCommand invokes tinyexec with the detected command and arguments.
- The Vite builder includes workspaceDir, module directories, layer roots, and discovered component/plugin/middleware/layout directories in its allowDirs calculation, so development file access must be reviewed beyond the application's immediate root.
- Request-scoped fetch forwards incoming headers, excluding a defined denylist, only when the underlying request is a string beginning with '/'; the wrapper sits below user hooks. useFetch separately rejects protocol-relative requests without baseURL.
- Public/app runtime config and serializable async-data results reach browser-visible scripts or payload JSON; private values placed into those objects would therefore cross the client boundary. (inferred)
- deriveSecret fails with status 500 when appSecret is unset or shorter than 32 characters and derives purpose-specific HKDF-SHA256 material; session sealing depends on that derivation unless an explicit password is supplied.
- Session data is sealed into the cookie and limited to 4096 serialized characters; default HttpOnly, Secure, SameSite=Lax, and root-path settings can be overridden through config.cookie.
- getRequestIP trusts the first x-forwarded-for value only when explicitly enabled. Applications using that option for access decisions depend on their proxy's header handling; this is an integration hypothesis, not a demonstrated exploit. (inferred)
- The optional Chrome DevTools workspace endpoint exposes an absolute root and stable UUID, but its implementation requires both a loopback peer and isLocalDevRequest; allowedHosts:true changes the host policy input.
- Streaming commits response status before delayed page work completes: tests explicitly expect a mid-stream error to retain HTTP 200 and a late 418 to be dropped, while buffered rendering applies the late status.
- Compatibility code is an active transition surface: nitroLegacy has independent imports/h3/specifier/runtimeConfig/config toggles, detects migrated Nitro v3 specifiers, and states that the compatibility layer is intended for removal in Nuxt 6.
- Source-recorded verification gaps include disabled benchmark CI, excluded Rspack chunk-error browser tests, excluded mutation suites under Nitro-Vite, and a fixme for dev streaming CSS; these do not establish failures in other configurations.
Extension points
Nuxt exposes build-time modules, hooks, templates, discovery registries, and runtime plugins as its primary extension model. App and server builders can be supplied independently, with renderer options providing a further runtime adapter boundary. Fetch factories and middleware allow reusable application-level policy without replacing the core async-data machinery. Some server-build helpers are explicitly internal and experimental, so their existence does not imply stable public API.
- defineNuxtModule accepts function or object definitions and normalizes metadata; getOptions merges inline options, configKey values, defaults, and optional schema defaults, with duplicate installation prevented by module name/configKey.
- Modules can enter through layer configuration, automatically scanned local module directories, project modules, or private _modules; resolveModules tracks both module identity and resolved paths.
- Build-time hooks are attached through layer config.hooks and caller override hooks, while createNuxt exposes hook, addHooks, callHook, and runWithContext.
- addTemplate registers generated files and replaces entries targeting the same destination; addServerTemplate contributes Nitro virtual files, and addTypeTemplate attaches declarations to selected type contexts.
- Auto-import customization uses imports:sources, imports:context, imports:extend, presets, and Unimport addons; component customization receives scan results through components:extend.
- Router customization can replace or modify generated routes through routerOptions.routes and supply a custom history implementation, while router.options.mjs aggregates discovered router-options files.
- Runtime plugins can provide injected values, register hooks, declare dependsOn, execute in parallel, and opt out of island execution; applyPlugins selects dependency-aware execution when needed.
- A custom app builder can be supplied as a bundle-capable object; a server builder can likewise be an object or package, and core wrappers route failures through build:error.
- setServerBuild updates input/output paths, capabilities, runtime descriptors, and other server-build properties; the source explicitly marks this internal shape as subject to change without a major release.
- createNuxtRenderer accepts runtime options or an existing renderer instance; runtime hooks can adjust streaming preference through render:route and mutate final document fragments through render:html.
- createUseFetch and createUseAsyncData are keyed composable factories with addon handling; plain factory options act as defaults while function-derived fetch options override caller options.
- Async-data middleware wraps the handler in reverse registration order, receiving next and a signal-bearing context; payload revivers provide a separate registration point for reconstructing rich client values.
Contributor handoff
Begin with repository contribution policy, the relevant package manifest, and the build/runtime boundary that owns the requested behavior. Tests and CI were inspected, not executed, so this brief supplies test targets rather than validation results. Preserve generated-module contracts, request-scoped state, cookie headers, and builder compatibility when making later authorized changes. The inventory is bounded; investigate neighboring consumers and tests before drawing absence or vulnerability conclusions.
- Read AGENTS.md and CONTRIBUTING.md before authoring artifacts: AGENTS prohibits AI-authored public writing and autonomous submitted contributions and requires disclosure of agent authorship and human-review status.
- CONTRIBUTING contains an automated-agent fast-track note that conflicts with AGENTS; agent-scan automation can label and close automated PRs. Treat the note as a policy conflict to resolve, not authorization to submit.
- Use the pinned pnpm@12.6.0 workspace and its catalogs/overrides; Vite, Rolldown, OXC, and Vue are explicitly pinned together, and Renovate explains the risk of loading a second Rolldown native binding.
- For initialization or build changes, read core/nuxt.ts, core/builder.ts, core/app.ts, schema builder resolvers, and the chosen server integration; app-builder bundle and server-builder setup are separate lifecycle responsibilities.
- Change template generators and discovery logic at their owners: app generation populates nuxt.vfs/#build and writes only templates marked write, while routes.mjs and imports.mjs are generated outputs.
- Preserve TypeScript strictness and generated context separation: root options enable strict/noUncheckedIndexedAccess/noUncheckedSideEffectImports, and addTypeTemplate distinguishes Nuxt, node, and shared references.
- After separately authorized runtime changes, the existing focused targets are test:runtime and test:unit; renderer legacy-error changes also require selecting renderer-legacy-errors explicitly because test:unit does not include it.
- Browser verification should select the matching Playwright matrix project and inspect its exclusions first; fixture mutation suites intentionally avoid the Nitro-Vite shared project, and dev/build/Vite/Rspack applicability differs.
- Tests and CI were inspected rather than executed in this investigation; their configured commands and source assertions are future verification pointers, not proof that this checkout passes.
- Preparation is material to test/build behavior: renderer projects generate fixture artifacts, and build ensures generated tsconfigs exist before starting a bundler because missing references can be cached as failures.
- Keep application and request isolation intact: createNuxtApp owns reactive payload registries, renderer instances own options/artifact loaders, and sessionCache keys sessions by event object and cookie name.
- Do not equate server.builder:'vite' with Nitro feature parity or treat internal server-build helpers as stable public APIs; both sources explicitly describe experimental limitations.
Languages
| Language | Files | Share of source |
|---|---|---|
| TypeScript | 1160 | 64% |
| Vue | 613 | 34% |
| Markdown | 263 | docs/config |
| JSON | 137 | docs/config |
| YAML | 54 | docs/config |
| JavaScript | 23 | 1% |
| CSS | 19 | docs/config |
| HTML | 8 | docs/config |
Start reading here
Probable source entrypoint: packages/ — inferred from the directory tree and manifest, not the upstream docs.
Source roots
packages/ (852 files)
Repository structure
| Top-level path | Files |
|---|---|
test/ | 1152 |
packages/ | 852 |
docs/ | 275 |
.github/ | 37 |
scripts/ | 9 |
playground/ | 5 |
.devcontainer/ | 2 |
.stackblitz/ | 2 |
Docs found: AGENTS.mdCLAUDE.mdCONTRIBUTING.mdREADME.mddocs/1.getting-started/01.introduction.mddocs/1.getting-started/02.installation.mddocs/1.getting-started/03.configuration.mddocs/1.getting-started/04.views.mddocs/1.getting-started/05.assets.mddocs/1.getting-started/06.styling.md
Package
package.json — nuxt-framework, 70 declared dependencies.
@arethetypeswrong/cli@babel/core@codspeed/core@codspeed/vitest-plugin@eslint/markdown@flakiness/playwright@flakiness/vitest@nuxt/cli@nuxt/eslint-config@nuxt/kit@nuxt/rspack-builder@nuxt/test-utils
CI & config entrypoints
README.md— Repository readmeAGENTS.md— Agent instructionsCLAUDE.md— Claude instructionspackages/ui-templates/vite.config.ts— Vite config.github/workflows/docs-deploy.yml— GitHub Actions workflow.github/workflows/agent-scan.yml— GitHub Actions workflow.github/workflows/autofix.yml— GitHub Actions workflow.github/workflows/release.yml— GitHub Actions workflow.github/workflows/docs-check-links.yml— GitHub Actions workflow.github/workflows/semantic-pull-requests.yml— GitHub Actions workflow
Structural health signals
Average score 7.4/10 across 96 analyzed source files; 17 hotspots surfaced.
packages/webpack/src/plugins/ssr-styles.ts— 510 lines, score 4.5 (Large file, Deep nesting)packages/nuxt/src/app/composables/asyncData.ts— 1081 lines, score 4.7 (Large file, Deep nesting)test/fixtures/basic-types/app/app-types.ts— 1312 lines, score 5.2 (Large file, Deep nesting)
These are deterministic review leads — size, churn, and structural signals — not proof of a bug in this project.
Recent history
3fde4d625cc32026-10-01 — feat(kit): add `resolveServerVariant` + `addServerImports` variant support (#36445)7802b2c216832026-09-30 — feat(nitro): improve scanning + reporting for nitro v2-style code (#36442)ebdec4cb5ad12026-09-27 — docs: document typing runtime config and events in modulesee2bac0856db2026-09-27 — fix(schema,vite-server): accept `null` from prerender ignore functionse43d847a6bf52026-09-27 — fix(nuxt): keep `CookieOptions` compatible with cookie serialize options