Getting Started

Nuxt's configuration file cannot await anything. Nuxt Prepare fills that gap: it runs your async code once, while Nuxt builds, and folds the result into the configuration and into a state your app can import. See Core Concepts for what that means for runtime cost and serialization.

Step 1: Install Nuxt Prepare

npx nuxt module add prepare

Step 2: Add the Module

Add nuxt-prepare to your Nuxt configuration:

nuxt.config.ts

export default defineNuxtConfig({
  modules: ['nuxt-prepare']
})

Step 3: Create Your First Prepare Script

By default, Nuxt Prepare looks for server.prepare.ts in your project root. Create this file and export a handler function:

server.prepare.ts

import { defineNuxtPrepareHandler } from 'nuxt-prepare/config'

export default defineNuxtPrepareHandler(async () => {
  // Fetch data from an API, read a file, query a database …

  return {
    // If not set, defaults to `true`
    ok: true,

    // Overwrite the runtime config variable `foo`
    runtimeConfig: {
      public: {
        foo: 'Overwritten by "server.prepare" script'
      }
    },

    // Pass custom state to Nuxt and import it
    // anywhere from `#nuxt-prepare`
    state: {
      foo: 'bar'
    }
  }
})

TIP

Return ok: false to signal failure and halt the build process.

Step 4: Import Your Prepare State

Whatever the script returns under state is generated as typed exports at .nuxt/module/nuxt-prepare.mjs, reachable through the #nuxt-prepare alias from both your Nuxt app and the Nitro server:

<script setup lang="ts">
import { foo } from '#nuxt-prepare'

console.log(foo) // 'bar'
</script>

// server/api/example.ts
import { foo } from '#nuxt-prepare'

export default defineEventHandler(() => {
  return { foo } // 'bar'
})

Step 5: Run Multiple Prepare Scripts

Add additional scripts to the prepare.scripts configuration:

nuxt.config.ts

export default defineNuxtConfig({
  modules: ['nuxt-prepare'],

  prepare: {
    scripts: ['server.prepare', 'process.prepare']
  }
})

TIP

Scripts run in series by default. Set the prepare.parallel option to true to run them all at once.

Next Steps

• Core Concepts – When scripts run, in what order, and what survives serialization.
• Prepare State – Pass build-time data to your app.
• Runtime & App Config – Set configuration values from a script.
• Error Handling – Fail the build, or carry on.