Nuxt Prepare is a Nuxt module that runs synchronous or asynchronous initialization steps at build-time, letting developers fetch data, overwrite runtime config, and prepare application state before the app is built.
What is Nuxt Prepare?
Nuxt Prepare is a zero-config Nuxt module that executes prepare scripts during the Nuxt build process. It takes a handler function defined in server.prepare.ts as input, runs it at build time, and returns runtime config overrides and custom state that get passed to your Nuxt application. The module is developed by Johann Schopplich and is available on npm under the name nuxt-prepare.
It works with any Nuxt project, including those using Nitro as the server engine, and integrates directly with the Nuxt module system. The module is open-source under the MIT license and is actively maintained since 2023.
Key Features
- Zero-Config Setup — Add
'nuxt-prepare'to themodulesarray innuxt.config.tsand the module automatically looks for aserver.prepare.tsfile in your project root; no additional configuration required. - Sync or Async Operations — The default handler can be an async function, so you can perform API calls, database reads, or any promise-based work before the build finishes.
- Conditional Runtime Config Overwrites — Return a
runtimeConfigobject from your prepare handler to overwrite specific values (e.g.public.foo) at build time, allowing environment-specific configuration. - Custom State Passing — Return a
stateobject that becomes importable anywhere in your app via#nuxt-prepare, letting you share build-time data with components, composables, or pages. - Series or Parallel Execution — Configure multiple prepare scripts via
prepare.scriptsin module options; they can run in series or in parallel according to your setup. - Nitro Server Route Ready — The module is compatible with Nitro, Nuxt's server engine, so prepare scripts can prepare data for server routes or API endpoints.
- First-Class TypeScript DX — Offers
defineNuxtPrepareHandlerfromnuxt-prepare/configto give typed hints and autocompletion when writing your prepare handler.
Who is it for?
Nuxt Prepare is for Nuxt developers who need to run logic at build time rather than at runtime. Use cases include fetching remote data during the build, injecting environment-specific config, and preparing static data for server routes.
- Nuxt.js application developers — Add the module to run pre-build scripts that populate runtime config or app state without recreating external fetch logic.
- Teams maintaining multiple environments — Overwrite
runtimeConfigvalues per build (e.g. staging vs production) by returning different values from the prepare handler. - Developers building Nitro server routes — Prepare data in advance so server routes can serve pre-fetched or pre-computed content without runtime delays.
What can you do with Nuxt Prepare?
- Fetch data at build-time — In your
server.prepare.tshandler, call an external API and return the result asstate; then import that state anywhere in your Nuxt app using#nuxt-prepare. - Overwrite runtime config — Set
runtimeConfig.publicvalues to build-specific values, enabling different feature flags or API endpoints without changing code. - Run multiple prepare scripts — Define several scripts in
prepare.scriptsand control whether they run in series or parallel, useful for complex build pipelines. - Prepare Nitro server routes — Use the module to pre-compute data that Nitro routes will serve, reducing runtime processing.
How does Nuxt Prepare work?
The module hooks into Nuxt's build lifecycle. After adding the module and creating server.prepare.ts, define a default exported handler using defineNuxtPrepareHandler. When Nuxt builds your app, the handler executes, and its returned runtimeConfig and state are merged into your Nuxt app. You can then import the state anywhere via #nuxt-prepare alias. Scripts can be registered under prepare.scripts for more advanced orchestration.
