defineNuxtPrepareHandler

This helper method defines a prepare script with full type safety. The init parameter can be:

• A synchronous function that returns a NuxtPrepareResult
• An asynchronous function that returns a Promise<NuxtPrepareResult>
• An object of type NuxtPrepareResult

Type Declarations

export interface NuxtPrepareResult {
  /**
   * Whether the prepare script ran successfully. If an async operation
   * inside your prepare script fails, you can return `ok: false` to let the
   * Nuxt Prepare module know that the script failed.
   *
   * @default true
   */
  ok?: boolean
  /**
   * Runtime config to merge with `nuxt.options.runtimeConfig`.
   */
  runtimeConfig?: PartialDeep<RuntimeConfig>
  /**
   * App config to merge with `nuxt.options.appConfig`.
   */
  appConfig?: PartialDeep<AppConfig>
  /**
   * Custom state to pass to Nuxt and import anywhere from `#nuxt-prepare`.
   *
   * @remarks
   * Use this to prefetch data, i.e. populate the Pinia store with data from
   * your API.
   *
   * @example
   * // `stores/todo.ts`
   * import { defineStore } from 'pinia'
   * import { todos } from '#nuxt-prepare'
   *
   * export const useTodos = defineStore('todos', {
   *   state: () => ({
   *     todos: todos || [],
   *   })
   * })
   */
  state?: Record<string, unknown>
}

function defineNuxtPrepareHandler<T extends NuxtPrepareResult>(
  init: T | (() => T | Promise<T>)
): Promise<T>

Return Value Properties

The NuxtPrepareResult object can include the following properties:

ok

Whether the script succeeded. Return ok: false to stop the build – see continueOnError for the other way that can go.

Type: boolean

Default Value: true

Reach for it when you need to:

• Validation fails (missing environment variables, invalid configuration)
• Critical API calls fail
• Required data cannot be fetched

return {
  ok: !error
}

runtimeConfig

Runtime config to merge over the one from nuxt.config.ts, taking precedence where both set a key. Read it back with useRuntimeConfig().

Type: PartialDeep<RuntimeConfig>

Reach for it when you need to:

• Set configuration based on async operations
• Fetch API URLs or credentials from external sources
• Compute configuration values at build time

return {
  runtimeConfig: {
    apiSecret: 'secret-key', // Private (server-only)
    public: {
      apiUrl: 'https://api.example.com' // Public (everywhere)
    }
  }
}

appConfig

App config to merge over the one from app.config.ts, taking precedence where both set a key. Read it back with useAppConfig().

Type: PartialDeep<AppConfig>

Reach for it when you need to:

• Set feature flags from a CMS or feature flag service
• Configure themes based on tenant data
• Define app-wide settings computed at build time

return {
  appConfig: {
    theme: {
      primaryColor: '#86CA39'
    }
  }
}

state

Build-time data importable from #nuxt-prepare. Values are JSON-serialized, and their types are inferred from the values themselves.

Type: Record<string, unknown>

Reach for it when you need to:

• Prefetch data to embed in your app
• Share constants computed at build time
• Populate stores or provide initial data

return {
  state: {
    todos: [{ id: 1, title: 'Learn Nuxt Prepare' }]
  }
}

Then import anywhere:

import { todos } from '#nuxt-prepare'

Example

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 prepare script'
      }
    },

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