Nuxt

https://nuxt.com/docs/3.x
Admin
Nuxt is a progressive Vue framework for building modern web applications with server-side rendering,...
Tokens:452,650
Snippets:4,094
Trust Score:9.9
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Install module in setup with options and nuxt

Source: https://nuxt.com/docs/3.x/api/kit/modules

Example of installing @nuxtjs/fontaine within a module's setup function, using the options and nuxt parameters. The inline options configure Roboto font with Impact fallback.

```ts
import { defineNuxtModule, installModule } from '@nuxt/kit'

export default defineNuxtModule({
  async setup (options, nuxt) {
    // will install @nuxtjs/fontaine with Roboto font and Impact fallback
    await installModule('@nuxtjs/fontaine', {
      // module configuration
      fonts: [
        {
          family: 'Roboto',
          fallbacks: ['Impact'],
          fallbackName: 'fallback-a',
        },
      ],
    })
  },
})

```

--------------------------------

### .nuxtrc flat syntax configuration example

Source: https://nuxt.com/docs/3.x/directory-structure/nuxtrc

Example of a .nuxtrc file using flat syntax to configure Nuxt. It disables SSR, enables devtools, adds modules, and includes a setups section that Nuxt automatically adds for module installation tracking.

```bash
# Disable SSR
ssr=false

# Configuration for `@nuxt/devtools`
devtools.enabled=true

# Add Nuxt modules
modules[]=@nuxt/image
modules[]=nuxt-security

# Module setups (automatically added by Nuxt)
setups.@nuxt/test-utils="3.23.0"
```

--------------------------------

### Target host end-to-end example with setup host option

Source: https://nuxt.com/docs/3.x/getting-started/testing

Runs end-to-end tests against a separate target host by providing the host property to setup. Useful for testing a deployed application or an already running local server, which can reduce test execution time.

```ts
import { createPage, setup } from '@nuxt/test-utils/e2e'
import { describe, expect, it } from 'vitest'

describe('login page', async () => {
  await setup({
    host: 'http://localhost:8787',
  })

  it('displays the email and password fields', async () => {
    const page = await createPage('/login')
    expect(await page.getByTestId('email').isVisible()).toBe(true)
    expect(await page.getByTestId('password').isVisible()).toBe(true)
  })
})
```

--------------------------------

### Providing helpers with object syntax (plugins/hello-object-syntax.ts)

Source: https://nuxt.com/docs/3.x/directory-structure/plugins

Alternative object syntax for providing helpers, using `name` and `setup` properties. Equivalent to the function syntax example.

```ts
export default defineNuxtPlugin({
  name: 'hello',
  setup () {
    return {
      provide: {
        hello: (msg: string) => `Hello ${msg}!`,
      },
    }
  },
})
```

--------------------------------

### npx nuxt add pinia example

Source: https://nuxt.com/docs/3.x/api/commands/add

Installs the Pinia module. If no module name is passed, you are prompted to search for and select modules to add.

```bash
npx nuxt add pinia
```

--------------------------------

### useLoadingIndicator start with force option

Source: https://nuxt.com/docs/3.x/api/composables/use-loading-indicator

Example of using useLoadingIndicator's start method with the force option to show loading immediately. The comment notes that start({ force: true }) is equivalent to set(0, { force: true }).

```vue
<script setup lang="ts">
const { start, set } = useLoadingIndicator()
// same as set(0, { force: true })
// set the progress to 0, and show loading immediately
start({ force: true })
</script>
```

--------------------------------

### Install Pinia and @pinia/nuxt

Source: https://nuxt.com/docs/3.x/migration/configuration

Install the Pinia module and its Nuxt integration.

```bash
yarn add pinia @pinia/nuxt
```

--------------------------------

### Install Sass/SCSS, Less, and Stylus preprocessors

Source: https://nuxt.com/docs/3.x/getting-started/styling

Install the required npm packages for each preprocessor. Use the command matching your chosen preprocessor.

```bash
npm install -D sass
```

```bash
npm install -D less
```

```bash
npm install -D stylus
```

--------------------------------

### vue:setup

Source: https://nuxt.com/docs/3.x/api/advanced/hooks

Called when the setup of Nuxt root is initialized. This callback must be synchronous. Available on both server and client.

```APIDOC
## vue:setup

### Description
Called when the setup of Nuxt root is initialized. This callback must be synchronous.

### Hook Name
`vue:setup`

### Arguments
None

### Environment
Server & Client

### Usage
Register a hook to be called when the Nuxt root setup is initialized.

### Example
```js
nuxt.hook('vue:setup', () => {
  // synchronous setup
})
```
```

--------------------------------

### tryUseNuxt usage example

Source: https://nuxt.com/docs/3.x/api/kit/context

Shows how to import and call tryUseNuxt to get the Nuxt instance, checking for null before using it.

```ts
import { tryUseNuxt } from '@nuxt/kit'

function setupSomething () {
  const nuxt = tryUseNuxt()

  if (nuxt) {
    // You can now use the nuxt instance
    console.log(nuxt.options)
  } else {
    console.log('Nuxt is not available')
  }
}
```

--------------------------------

### Use useNuxt to configure transpilation and call from module

Source: https://nuxt.com/docs/3.x/api/kit/context

Two-file example showing how to use useNuxt to conditionally add a transpile entry for the webpack builder, and how to call that setup function from a Nuxt module's setup hook.

```ts
import { useNuxt } from '@nuxt/kit'

export const setupTranspilation = () => {
  const nuxt = useNuxt()

  if (nuxt.options.builder === '@nuxt/webpack-builder') {
    nuxt.options.build.transpile ||= []
    nuxt.options.build.transpile.push('xstate')
  }
}
```

```ts
// @module: esnext
// @filename: setupTranspilation.ts
export const setupTranspilation = () => {}
// @filename: module.ts
import { defineNuxtModule } from '@nuxt/kit'
// ---cut---
import { setupTranspilation } from './setupTranspilation'

export default defineNuxtModule({
  setup () {
    setupTranspilation()
  },
})
```

--------------------------------

### Using tryUseNuxt with custom Nuxt options

Source: https://nuxt.com/docs/3.x/api/kit/context

Two-file example showing how to use tryUseNuxt to access custom Nuxt options (siteConfig) and then use that config in a module setup.

```ts
declare module 'nuxt/schema' {
  interface NuxtOptions {
    siteConfig: SiteConfig
  }
}
// ---cut---
import { tryUseNuxt } from '@nuxt/kit'

interface SiteConfig {
  title?: string
}

export const requireSiteConfig = (): SiteConfig => {
  const nuxt = tryUseNuxt()
  if (!nuxt) {
    return {}
  }
  return nuxt.options.siteConfig
}
```

```ts
// @module: esnext
// @filename: requireSiteConfig.ts
interface SiteConfig {
  title?: string
}
export const requireSiteConfig = (): SiteConfig => {
  return {}
}
// @filename: module.ts
// ---cut---
import { defineNuxtModule, useNuxt } from '@nuxt/kit'
import { requireSiteConfig } from './requireSiteConfig'

export default defineNuxtModule({
  setup (_, nuxt) {
    const config = requireSiteConfig()
    nuxt.options.app.head.title = config.title
  },
})
```

--------------------------------

### generate.routes example

Source: https://nuxt.com/docs/3.x/api/configuration/nuxt-config

Sets the starting routes for static generation when using the crawler. This is often necessary for dynamic routes. Prefer using `nitro.prerender.routes` instead.

```javascript
routes: ['/users/1', '/users/2', '/users/3']

```

--------------------------------

### setup(options)

Source: https://nuxt.com/docs/3.x/getting-started/testing

The `setup` function initializes the Nuxt test environment for end-to-end testing. It accepts an options object to configure the test context, including Nuxt config, timings, and features.

```APIDOC
## `setup(options)`

### Description
Sets up the Nuxt test environment for end-to-end testing. It performs tasks in `beforeAll`, `beforeEach`, `afterEach`, and `afterAll` to correctly configure the test context.

### Parameters
#### Options
- **rootDir** (string) - Optional - Path to a directory with a Nuxt app to be put under test. Default: `'.'`
- **configFile** (string) - Optional - Name of the configuration file. Default: `'nuxt.config'`
- **setupTimeout** (number) - Optional - The amount of time (in milliseconds) to allow for `setupTest` to complete its work. Default: `120000` (or `240000` on Windows)
- **teardownTimeout** (number) - Optional - The amount of time (in milliseconds) to allow tearing down the test environment. Default: `30000`
- **build** (boolean) - Optional - Whether to run a separate build step. Default: `true` (or `false` if `browser` or `server` is disabled, or if a `host` is provided)
- **server** (boolean) - Optional - Whether to launch a server to respond to requests in the test suite. Default: `true` (or `false` if a `host` is provided)
- **port** (number | undefined) - Optional - If provided, set the launched test server port to the value. Default: `undefined`
- **host** (string) - Optional - If provided, a URL to use as the test target instead of building and running a new server. Default: `undefined`
- **browser** (boolean) - Optional - Whether to launch a browser for testing. Default: `false`
- **browserOptions** (object) - Optional - Options for the browser. Contains `type` (string: `chromium`, `firefox`, or `webkit`) and `launch` (object: options passed to Playwright when launching the browser).
- **runner** ('vitest' | 'jest' | 'cucumber') - Optional - Specify the runner for the test suite. Default: `'vitest'`

### Example
```ts
import { describe, test } from 'vitest'
import { $fetch, setup } from '@nuxt/test-utils/e2e'

describe('My test', async () => {
  await setup({
    // test context options
  })

  test('my test', () => {
    // ...
  })
})
```
```

--------------------------------

### Get router instance with useRouter in pages

Source: https://nuxt.com/docs/3.x/api/composables/use-router

Use this in a page component to access the router instance. The example is placed inside the script setup block, making the router available for use in the component's logic.

```vue
<script setup lang="ts">
const router = useRouter()
</script>
```

--------------------------------

### findPath Usage Example

Source: https://nuxt.com/docs/3.x/api/kit/resolving

Example of using findPath inside a Nuxt module setup to resolve the main component (app.vue) from a list of candidate paths.

```ts
import { defineNuxtModule, findPath } from '@nuxt/kit'
import { join } from 'pathe'

export default defineNuxtModule({
  async setup (_, nuxt) {
    // Resolve main (app.vue)
    const mainComponent = await findPath([
      join(nuxt.options.srcDir, 'App'),
      join(nuxt.options.srcDir, 'app'),
    ])
  },
})
```

--------------------------------

### Example page using usePreviewMode (pages/some-page.vue)

Source: https://nuxt.com/docs/3.x/api/composables/use-preview-mode

Creates a page where part of the content is rendered only in preview mode. Uses usePreviewMode to get enabled and state, and useFetch to fetch data with the token from state. The template conditionally shows preview content and a button to disable preview mode.

```vue
<script setup>
const { enabled, state } = usePreviewMode()

const { data } = await useFetch('/api/preview', {
  query: {
    apiKey: state.token,
  },
})
</script>

<template>
  <div>
    Some base content
    <p v-if="enabled">
      Only preview content: {{ state.token }}
      <br>
      <button @click="enabled = false">
        disable preview mode
      </button>
    </p>
  </div>
</template>
```

--------------------------------

### npx nuxt preview command

Source: https://nuxt.com/docs/3.x/api/commands/preview

Starts a preview server for a Nuxt application after building. The `start` command is an alias. Options include `--cwd`, `--logLevel`, `--envName`, `--extends`, `--port`, and `--dotenv`.

```bash
npx nuxt preview [ROOTDIR] [--cwd=<directory>] [--logLevel=<silent|info|verbose>] [--envName] [-e, --extends=<layer-name>] [-p, --port] [--dotenv]
```

--------------------------------

### Server target build and start scripts

Source: https://nuxt.com/docs/3.x/bridge/nitro

For server targets, use nuxi build and nuxi preview for the build and start scripts.

```json
{
  "scripts": {
    "build": "nuxi build",
    "start": "nuxi preview"
  }
}
```

--------------------------------

### Set up end-to-end test with @nuxt/test-utils/e2e

Source: https://nuxt.com/docs/3.x/getting-started/testing

Sets up end-to-end testing with @nuxt/test-utils/e2e. This example is from app.e2e.spec.ts and shows the setup call with a custom timeout.

```tstwoslash
import { $fetch, setup } from '@nuxt/test-utils/e2e'

await setup({
  setupTimeout: 10000,
})

// ...
```

--------------------------------

### Run Nuxt dev server with npx

Source: https://nuxt.com/docs/3.x/api/commands

Starts the Nuxt development server using the `nuxt` command from `@nuxt/cli`, which is a dependency of `nuxt`. The binary is also installed as `nuxi`, `nuxi-ng`, and `nuxt-cli` for compatibility.

```terminal
npx nuxt dev

```

--------------------------------

### Install and run nightly CLI

Source: https://nuxt.com/docs/3.x/api/commands

Installs the nightly build of `@nuxt/cli` and runs the dev server with it. Every commit is published to the nightly channel.

```terminal
npm install -D @nuxt/cli-nightly
npx @nuxt/cli-nightly dev

```

--------------------------------

### Example v4 folder structure

Source: https://nuxt.com/docs/3.x/getting-started/upgrade

Example v4 folder structure showing the new default directory layout with app/ as srcDir and server/, content/, layers/, modules/, public/, shared/ resolved from rootDir.

```sh
.output/
.nuxt/
app/
  assets/
  components/
  composables/
  layouts/
  middleware/
  pages/
  plugins/
  utils/
  app.config.ts
  app.vue
  router.options.ts
content/
layers/
modules/
node_modules/
public/
shared/
  types/
  utils/
server/
  api/
  middleware/
  plugins/
  routes/
  utils/
nuxt.config.ts
```

--------------------------------

### Install @nuxt/content module

Source: https://nuxt.com/docs/3.x/directory-structure/content

Installs the @nuxt/content module and adds it to nuxt.config.ts.

```bash
npx nuxt module add content
```

--------------------------------

### Start Nuxt development server with deno

Source: https://nuxt.com/docs/3.x/getting-started/installation

Starts the Nuxt app in development mode and automatically opens a browser window to http://localhost:3000.

```bash
deno run dev -o
```

--------------------------------

### Folder structure for srcDir example

Source: https://nuxt.com/docs/3.x/api/configuration/nuxt-config

Folder structure that works with the srcDir example. Shows the expected layout when srcDir is set to 'src/'.

```text
-| app/
---| node_modules/
---| nuxt.config.js
---| package.json
---| src/
------| assets/
------| components/
------| layouts/
------| middleware/
------| pages/
------| plugins/
------| public/
------| store/
------| server/
------| app.config.ts
------| app.vue
------| error.vue

```

--------------------------------

### Install nuxt-auth-utils module

Source: https://nuxt.com/docs/3.x/guide/recipes/sessions-and-authentication

Installs the nuxt-auth-utils module and adds it to the modules section of nuxt.config.ts.

```bash
npx nuxt module add auth-utils
```

--------------------------------

### Install animate.css with various package managers

Source: https://nuxt.com/docs/3.x/getting-started/styling

Commands to install the `animate.css` package using npm, yarn, pnpm, bun, and deno. These are alternatives; choose the one for your package manager.

```bash
npm install animate.css
```

```bash
yarn add animate.css
```

```bash
pnpm install animate.css
```

```bash
bun install animate.css
```

```bash
deno install npm:animate.css
```

--------------------------------

### Install @nuxt/bridge and nuxi

Source: https://nuxt.com/docs/3.x/bridge/overview

Install @nuxt/bridge and nuxi as development dependencies. Choose the command for your package manager.

```bash
npm install -D @nuxt/bridge nuxi
```

```bash
yarn add --dev @nuxt/bridge nuxi
```

```bash
pnpm add -D @nuxt/bridge nuxi
```

```bash
bun add -D @nuxt/bridge nuxi
```

```bash
deno add -D npm:@nuxt/bridge npm:nuxi
```

--------------------------------

### Start Nuxt development server with bun

Source: https://nuxt.com/docs/3.x/getting-started/installation

Starts the Nuxt app in development mode and automatically opens a browser window to http://localhost:3000. The commented line shows how to use the Bun runtime during development.

```bash
bun run dev -o

# To use the Bun runtime during development
# bun --bun run dev -o
```

--------------------------------

### Start Nuxt development server with npm

Source: https://nuxt.com/docs/3.x/getting-started/installation

Starts the Nuxt app in development mode and automatically opens a browser window to http://localhost:3000.

```bash
npm run dev -- -o
```

--------------------------------

### Example usage

Source: https://nuxt.com/docs/3.x/api/composables/use-preview-mode

A complete example of using `usePreviewMode` in a Nuxt page to conditionally render content and use the preview token in an API call.

```APIDOC
## Example: Using preview mode in a page

### Description
Creates a page where part of the content is rendered only in preview mode. The preview state token is used in an API request.

### Example
```vue [pages/some-page.vue]
<script setup>
const { enabled, state } = usePreviewMode()

const { data } = await useFetch('/api/preview', {
  query: {
    apiKey: state.token,
  },
})
</script>

<template>
  <div>
    Some base content
    <p v-if="enabled">
      Only preview content: {{ state.token }}
      <br>
      <button @click="enabled = false">
        disable preview mode
      </button>
    </p>
  </div>
</template>
```
```

--------------------------------

### Install Nuxt Image module

Source: https://nuxt.com/docs/3.x/api/components/nuxt-img

Installs and enables the Nuxt Image module, which is required to use the <NuxtImg> component.

```bash
npx nuxt module add image
```

--------------------------------

### .nuxtignore file example

Source: https://nuxt.com/docs/3.x/directory-structure/nuxtignore

Example .nuxtignore file with glob patterns to ignore specific files and directories during the build phase. Supports negation with ! to re-include files, as shown by re-including middleware/foo/bar.js after ignoring middleware/foo/*.js.

```bash
# ignore layout foo.vue
layouts/foo.vue
# ignore layout files whose name ends with -ignore.vue
layouts/*-ignore.vue

# ignore page bar.vue
pages/bar.vue
# ignore page inside ignore folder
pages/ignore/*.vue

# ignore route middleware files under foo folder except foo/bar.js
middleware/foo/*.js
!middleware/foo/bar.js
```

--------------------------------

### Install dependencies with pnpm

Source: https://nuxt.com/docs/3.x/community/framework-contribution

Installs all dependencies with pnpm using the frozen lockfile, which is the source of truth for Nuxt dependencies.

```bash
pnpm install --frozen-lockfile
```

--------------------------------

### Install and run Nuxt CLI nightly

Source: https://nuxt.com/docs/3.x/api/commands/overview

Installs and runs the nightly channel of the Nuxt CLI. Every commit is published to the nightly channel, and `create-nuxt-nightly` scaffolds with it.

```bash
npm install -D @nuxt/cli-nightly
npx @nuxt/cli-nightly dev
```

--------------------------------

### Run the playground

Source: https://nuxt.com/docs/3.x/community/framework-contribution

Runs the example app in the playground directory to test changes locally.

```bash
pnpm dev
```

--------------------------------

### Start Nuxt development server with pnpm

Source: https://nuxt.com/docs/3.x/getting-started/installation

Starts the Nuxt app in development mode and automatically opens a browser window to http://localhost:3000.

```bash
pnpm dev -o
```

--------------------------------

### Create a Nuxt layer with the starter template

Source: https://nuxt.com/docs/3.x/guide/going-further/layers

Initializes a new Nuxt layer project using the official starter template. Run this command in the terminal to create a basic structure to build upon.

```bash
npm create nuxt -- --template layer nuxt-layer
```

--------------------------------

### hasNuxtCompatibility usage in module setup

Source: https://nuxt.com/docs/3.x/api/kit/compatibility

Usage example for hasNuxtCompatibility inside a Nuxt module setup. It checks if the Nuxt version satisfies the constraint and branches accordingly.

```typescript
import { defineNuxtModule, hasNuxtCompatibility } from '@nuxt/kit'

export default defineNuxtModule({
  async setup (_options, nuxt) {
    const usingNewPostcss = await hasNuxtCompatibility({ nuxt: '^2.16.0' }, nuxt)
    if (usingNewPostcss) {
      // do something
    } else {
      // do something else
    }
  },
})
```

--------------------------------

### Auto-imported useFetch() example

Source: https://nuxt.com/docs/3.x/guide/concepts/auto-imports

Shows that useFetch() is auto-imported in a Vue component's script setup. The example fetches data from '/api/hello' and destructures data, refresh, and status.

```vue
<script setup lang="ts">
/* useFetch() is auto-imported */
const { data, refresh, status } = await useFetch('/api/hello')
</script>
```

--------------------------------

### Install @nuxt/bridge and nuxi with npm, yarn, pnpm, bun, and deno

Source: https://nuxt.com/docs/3.x/bridge

Commands to install @nuxt/bridge and nuxi as development dependencies. Each command is for a different package manager.

```bash
npm install -D @nuxt/bridge nuxi

```

```bash
yarn add --dev @nuxt/bridge nuxi

```

```bash
pnpm add -D @nuxt/bridge nuxi

```

```bash
bun add -D @nuxt/bridge nuxi

```

```bash
deno add -D npm:@nuxt/bridge npm:nuxi

```

--------------------------------

### defineNuxtModule

Source: https://nuxt.com/docs/3.x/api/kit/modules

Defines a Nuxt module with automatic merging of defaults, hook installation, and an optional setup function.

```APIDOC
## defineNuxtModule

### Description
Defines a Nuxt module, automatically merging defaults with user provided options, installing any hooks that are provided, and calling an optional setup function for full control.

### Signature
```ts
export function defineNuxtModule<TOptions extends ModuleOptions> (
  definition?: ModuleDefinition<TOptions, Partial<TOptions>, false> | NuxtModule<TOptions, Partial<TOptions>, false>,
): NuxtModule<TOptions, TOptions, false>

export function defineNuxtModule<TOptions extends ModuleOptions> (): {
  with: <TOptionsDefaults extends Partial<TOptions>> (
    definition: ModuleDefinition<TOptions, TOptionsDefaults, true> | NuxtModule<TOptions, TOptionsDefaults, true>,
  ) => NuxtModule<TOptions, TOptionsDefaults, true>
}
```

### Parameters

**definition**: A module definition object or a module function. The module definition object should contain the following properties:

- **meta** (ModuleMeta) - Optional - Metadata of the module. It defines the module name, version, config key and compatibility.
- **defaults** (T | ((nuxt: Nuxt) => T)) - Optional - Default options for the module. If a function is provided, it will be called with the Nuxt instance as the first argument.
- **schema** (T) - Optional - Schema for the module options. If provided, options will be applied to the schema.
- **hooks** (Partial<NuxtHooks>) - Optional - Hooks to be installed for the module. If provided, the module will install the hooks.
- **moduleDependencies** (ModuleDependencies) - Optional - Dependencies of the module. If provided, the module will be installed after the dependencies.
- **setup** (function) - Optional - Setup function for the module. If provided, it will be called with the resolved options and the Nuxt instance.

### Usage Example
```ts
import { defineNuxtModule } from '@nuxt/kit'

export default defineNuxtModule({
  meta: {
    name: 'my-module',
    configKey: 'myModule',
  },
  defaults: {
    enabled: true,
  },
  setup (options) {
    if (options.enabled) {
      console.log('My Nuxt module is enabled!')
    }
  },
})
```
```

--------------------------------

### Install a Nuxt module with installModule

Source: https://nuxt.com/docs/3.x/api/kit/modules

Install the @nuxtjs/fontaine module programmatically with inline options for Roboto font and Impact fallback. Use this when your module depends on other modules. The inlineOptions are passed to the module's setup function.

```ts
import { defineNuxtModule, installModule } from '@nuxt/kit'

export default defineNuxtModule({
  async setup () {
    // will install @nuxtjs/fontaine with Roboto font and Impact fallback
    await installModule('@nuxtjs/fontaine', {
      // module configuration
      fonts: [
        {
          family: 'Roboto',
          fallbacks: ['Impact'],
          fallbackName: 'fallback-a',
        },
      ],
    })
  },
})

```

--------------------------------

### Navigate with back, forward, go, push, replace

Source: https://nuxt.com/docs/3.x/api/composables/use-router

Example using history-based navigation methods. push() and replace() are available, but using navigateTo is recommended instead.

```ts
const router = useRouter()

router.back()
router.forward()
router.go(3)
router.push({ path: '/home' })
router.replace({ hash: '#bio' })
```

--------------------------------

### Enable devServer HTTPS with key and cert

Source: https://nuxt.com/docs/3.x/api/configuration/nuxt-config

Example configuration enabling HTTPS for the dev server by providing key and certificate file paths.

```javascript
export default defineNuxtConfig({
  devServer: {
    https: {
      key: './server.key',
      cert: './server.crt'
    }
  }
})
```

--------------------------------

### Create a new Nuxt project with deno

Source: https://nuxt.com/docs/3.x/getting-started/installation

Use this command in your terminal to create a new Nuxt 3 starter project. Replace <project-name> with your desired project name.

```bash
deno -A npm:create-nuxt@latest <project-name> -t v3
```

--------------------------------

### Register App hooks in a Nuxt plugin

Source: https://nuxt.com/docs/3.x/guide/going-further/hooks

Use nuxtApp.hook() in a Nuxt plugin to hook into the rendering lifecycle. The example registers a 'page:start' hook.

```ts
export default defineNuxtPlugin((nuxtApp) => {
  nuxtApp.hook('page:start', () => {
    /* your code goes here */
  })
})
```

--------------------------------

### Create a Nuxt module with the starter template

Source: https://nuxt.com/docs/3.x/guide/modules/getting-started

Commands to scaffold a new Nuxt module project using the official starter template. Each command uses the respective package manager (npm, yarn, pnpm, bun) and creates a `my-module` directory with all necessary boilerplate.

```bash
npm create nuxt -- -t module my-module
```

```bash
yarn create nuxt -t module my-module
```

```bash
pnpm create nuxt -t module my-module
```

```bash
bun create nuxt --template=module my-module
```

--------------------------------

### Prepare development environment

Source: https://nuxt.com/docs/3.x/community/framework-contribution

Activates the passive development system for the Nuxt monorepo.

```bash
pnpm dev:prepare
```

--------------------------------

### useFetch composable example

Source: https://nuxt.com/docs/3.x/getting-started/data-fetching

Use useFetch to make SSR-safe network calls in the setup function. It uses $fetch under-the-hood and is a wrapper around useAsyncData.

```vue
<script setup lang="ts">
const { data: count } = await useFetch('/api/count')
</script>

<template>
  <p>Page visits: {{ count }}</p>
</template>
```

--------------------------------

### Set up Nuxt test context with @nuxt/test-utils/e2e

Source: https://nuxt.com/docs/3.x/getting-started/testing

Sets up the Nuxt test environment in a Vitest describe block using the setup method from @nuxt/test-utils/e2e. The setup method runs beforeAll, beforeEach, afterEach, and afterAll hooks to configure the test context.

```ts
import { describe, test } from 'vitest'
import { $fetch, setup } from '@nuxt/test-utils/e2e'

describe('My test', async () => {
  await setup({
    // test context options
  })

  test('my test', () => {
    // ...
  })
})
```

--------------------------------

### Create a new Nuxt project with bun

Source: https://nuxt.com/docs/3.x/getting-started/installation

Use this command in your terminal to create a new Nuxt 3 starter project. Replace <project-name> with your desired project name. The commented line is a workaround for a known bun issue.

```bash
# you can use this when https://github.com/oven-sh/bun/issues/29087 is resolved
# bun create nuxt@latest <project-name> -t v3
bunx create-nuxt@latest init <project-name> -t v3
```

--------------------------------

### Update package.json scripts to use nuxt2 command

Source: https://nuxt.com/docs/3.x/bridge

Shows the diff to change the dev, build, and start scripts from nuxt to nuxt2. This is required after installing Nuxt Bridge.

```json
{
  "scripts": {
-   "dev": "nuxt",
+   "dev": "nuxt2",
-   "build": "nuxt build",
+   "build": "nuxt2 build",
-   "start": "nuxt start",
+   "start": "nuxt2 start"
  }
}

```

--------------------------------

### create nuxt command syntax

Source: https://nuxt.com/docs/3.x/api/commands/init

Initializes a fresh Nuxt project. The command accepts an optional directory argument and various options such as `--cwd`, `--logLevel`, `--template`, `--force`, `--offline`, `--preferOffline`, `--no-install`, `--gitInit`, `--shell`, `--packageManager`, `-M, --modules`, `--no-modules`, and `--nightly`.

```bash
npm create nuxt@latest [DIR] [--cwd=<directory>] [--logLevel=<silent|info|verbose>] [-t, --template] [-f, --force] [--offline] [--preferOffline] [--no-install] [--gitInit] [--shell] [--packageManager] [-M, --modules] [--no-modules] [--nightly]
```

--------------------------------

### Default components directory structure

Source: https://nuxt.com/docs/3.x/directory-structure/components

Shows the default structure of the components/ directory with two example component files.

```bash
-| components/
---| AppHeader.vue
---| AppFooter.vue
```

--------------------------------

### Register Nuxt hooks within a Nuxt module

Source: https://nuxt.com/docs/3.x/guide/going-further/hooks

Use nuxt.hook() inside a Nuxt module's setup to register build-time hooks. The example registers a 'close' hook.

```js
import { defineNuxtModule } from '@nuxt/kit'

export default defineNuxtModule({
  setup (options, nuxt) {
    nuxt.hook('close', async () => { })
  },
})
```

--------------------------------

### useLazyAsyncData with watch in pages/index.vue

Source: https://nuxt.com/docs/3.x/api/composables/use-lazy-async-data

Example showing that count may start out null, so you can watch it to react to changes. Navigation occurs before fetching completes, so handle 'pending' and 'error' states in the template.

```vue
<script setup lang="ts">
/* Navigation will occur before fetching is complete.
  Handle 'pending' and 'error' states directly within your component's template
*/
const { status, data: count } = await useLazyAsyncData('count', () => $fetch('/api/count'))

watch(count, (newCount) => {
  // Because count might start out null, you won't have access
  // to its contents immediately, but you can watch it.
})
</script>

<template>
  <div>
    {{ status === 'pending' ? 'Loading' : count }}
  </div>
</template>
```

--------------------------------

### Add custom server directory with utility function

Source: https://nuxt.com/docs/3.x/api/kit/nitro

Example showing how to add a custom server directory and define a utility function in that directory. The module registers the runtime/server directory, and the utility file exports a hello function that can be used in server code.

```ts
import { addServerScanDir, createResolver, defineNuxtModule } from '@nuxt/kit'

export default defineNuxtModule({
  meta: {
    name: 'my-module',
    configKey: 'myModule',
  },
  setup (options) {
    const { resolve } = createResolver(import.meta.url)
    addServerScanDir(resolve('./runtime/server'))
  },
})
```

```ts
export function hello () {
  return 'Hello from server utils!'
}
```

--------------------------------

### Access request event and URL with useRequestEvent

Source: https://nuxt.com/docs/3.x/api/composables/use-request-event

Use useRequestEvent within the Nuxt context to access the incoming request event. The example gets the event and then the URL path. In the browser, useRequestEvent returns undefined.

```ts
// Get underlying request event
const event = useRequestEvent()

// Get the URL
const url = event?.path
```

--------------------------------

### Register a runtime hook in pages/index.vue

Source: https://nuxt.com/docs/3.x/api/composables/use-runtime-hook

Example usage in a Vue component's script setup. Registers a runtime hook for 'link:prefetch' that logs the link. The hook is automatically unregistered when the component is unmounted.

```vue
<script setup lang="ts">
// Register a hook that runs every time a link is prefetched, but which will be
// automatically cleaned up (and not called again) when the component is unmounted
useRuntimeHook('link:prefetch', (link) => {
  console.log('Prefetching', link)
})
</script>
```

--------------------------------

### Usage: addImports with @nuxt/kit

Source: https://nuxt.com/docs/3.x/api/kit/autoimports

Shows how to use `addImports` inside a Nuxt module's `setup` to register multiple imports from a single module. The example imports `addImports` and `defineNuxtModule` from `@nuxt/kit` and adds imports from `@storyblok/vue`.

```ts
import { addImports, defineNuxtModule } from '@nuxt/kit'

export default defineNuxtModule({
  setup (options, nuxt) {
    const names = [
      'useStoryblok',
      'useStoryblokApi',
      'useStoryblokBridge',
      'renderRichText',
      'RichTextSchema',
    ]

    names.forEach(name =>
      addImports({ name, as: name, from: '@storyblok/vue' }),
    )
  },
})
```

--------------------------------

### Register runtime hooks with nuxtApp.hook in a plugin

Source: https://nuxt.com/docs/3.x/api/composables/use-nuxt-app

Register runtime hooks in a Nuxt plugin using the hook method. This example hooks into the page:start and vue:error lifecycle events, useful for adding custom logic during rendering.

```ts
export default defineNuxtPlugin((nuxtApp) => {
  nuxtApp.hook('page:start', () => {
    /* your code goes here */
  })
  nuxtApp.hook('vue:error', (..._args) => {
    console.log('vue:error')
    // if (import.meta.client) {
    //   console.log(..._args)
    // }
  })
})
```

--------------------------------

### Start Nuxt Node.js server

Source: https://nuxt.com/docs/3.x/getting-started/deployment

Launches the production Nuxt server built with the Node.js server preset. Set NODE_ENV=production to avoid development-only warnings from dependencies like Vue Router.

```bash
NODE_ENV=production node .output/server/index.mjs
```

--------------------------------

### Run nuxt prepare command

Source: https://nuxt.com/docs/3.x/api/commands/prepare

Run the prepare command to create a .nuxt directory and generate types. Useful in CI environments or as a postinstall command in package.json. Sets process.env.NODE_ENV to production.

```bash
npx nuxt prepare [ROOTDIR] [--dotenv] [--cwd=<directory>] [--logLevel=<silent|info|verbose>] [--envName] [-e, --extends=<layer-name>]
```

--------------------------------

### Access runtime config in server route (server/api/test.ts)

Source: https://nuxt.com/docs/3.x/guide/going-further/runtime-config

Use useRuntimeConfig(event) in a server route to access runtime config. Passing the event is optional but recommended to get environment variable overrides. The example uses the API secret in an Authorization header.

```ts
export default defineEventHandler(async (event) => {
  const { apiSecret } = useRuntimeConfig(event)
  const result = await $fetch('https://my.api.com/test', {
    headers: {
      Authorization: `Bearer ${apiSecret}`,
    },
  })
  return result
})
```

--------------------------------

### onPrehydrate Usage in app.vue

Source: https://nuxt.com/docs/3.x/api/composables/on-prehydrate

Example usage of onPrehydrate in a Vue component. Shows running code before hydration, accessing the root element, and using the advanced key to get the prehydrate id. The callback is stringified and inlined in the HTML, so it must not have external dependencies.

```vue
<script setup lang="ts">
declare const window: Window
// ---cut---
// Run code before Nuxt hydrates
onPrehydrate(() => {
  console.log(window)
})

// Access the root element
onPrehydrate((el) => {
  console.log(el.outerHTML)
  // <div data-v-inspector="app.vue:15:3" data-prehydrate-id=":b3qlvSiBeH:"> Hi there </div>
})

// Advanced: access/set `data-prehydrate-id` yourself
const prehydrateId = onPrehydrate((el) => {})
</script>

<template>
  <div>
    Hi there
  </div>
</template>
```

--------------------------------

### Using import.meta.url to resolve files within modules

Source: https://nuxt.com/docs/3.x/api/advanced/import-meta

This example shows how to use `import.meta.url` with `createResolver` from `nuxt/kit` to resolve file paths relative to the current module. It is used in a Nuxt module's setup to add a component with a resolved file path.

```TypeScript
import { createResolver } from 'nuxt/kit'

// Resolve relative from the current file
const resolver = createResolver(import.meta.url)

export default defineNuxtModule({
  meta: { name: 'myModule' },
  setup () {
    addComponent({
      name: 'MyModuleComponent',
      // Resolves to '/modules/my-module/components/MyModuleComponent.vue'
      filePath: resolver.resolve('./components/MyModuleComponent.vue'),
    })
  },
})
```

--------------------------------

### Add Vue components with addComponent

Source: https://nuxt.com/docs/3.x/guide/modules/recipes-basics

Registers Vue components as auto-imports using `addComponent`. Shows two examples: one from the module's runtime directory and one from an external library. The `export` option is optional for named exports. Use in a Nuxt module's `setup`.

```tstwoslash
import { addComponent, createResolver, defineNuxtModule, useRuntimeConfig } from '@nuxt/kit'

export default defineNuxtModule({
  setup (options, nuxt) {
    const resolver = createResolver(import.meta.url)

    // From the runtime directory
    addComponent({
      name: 'MySuperComponent', // name of the component to be used in vue templates
      export: 'MySuperComponent', // (optional) if the component is a named (rather than default) export
      filePath: resolver.resolve('runtime/app/components/MySuperComponent.vue'),
    })

    // From a library
    addComponent({
      name: 'MyAwesomeComponent', // name of the component to be used in vue templates
      export: 'MyAwesomeComponent', // (optional) if the component is a named (rather than default) export
      filePath: '@vue/awesome-components',
    })
  },
})

```

--------------------------------

### server/ directory structure

Source: https://nuxt.com/docs/3.x/directory-structure/server

Shows the expected directory structure for the server/ directory, including api/, routes/, and middleware/ subdirectories with example files and their corresponding routes.

```bash
-| server/
---| api/
-----| hello.ts      # /api/hello
---| routes/
-----| bonjour.ts    # /bonjour
---| middleware/
-----| log.ts        # log all requests
```

--------------------------------

### Lifecycle hooks with onInstall and onUpgrade

Source: https://nuxt.com/docs/3.x/api/kit/modules

Define `onInstall` and `onUpgrade` lifecycle hooks for a Nuxt module. Both `meta.name` and `meta.version` are required; hooks run before `setup`, and errors are logged without stopping the build. `onInstall` fires once on first install, while `onUpgrade` fires once per version bump (semver comparison).

```ts
import { defineNuxtModule } from '@nuxt/kit'
import semver from 'semver'

export default defineNuxtModule({
  meta: {
    name: 'my-awesome-module',
    version: '1.2.0', // Required for lifecycle hooks
    configKey: 'myAwesomeModule',
  },
  defaults: {
    apiKey: '',
    enabled: true,
  },

  onInstall (nuxt) {
    // This runs only when the module is first installed
    console.log('Setting up my-awesome-module for the first time!')

    // You might want to:
    // - Create initial configuration files
    // - Set up database schemas
    // - Display welcome messages
    // - Perform initial data migration
  },

  onUpgrade (nuxt, options, previousVersion) {
    // This runs when the module is upgraded to a newer version
    console.log(`Upgrading my-awesome-module from ${previousVersion} to 1.2.0`)

    // You might want to:
    // - Migrate configuration files
    // - Update database schemas
    // - Clean up deprecated files
    // - Display upgrade notes

    if (semver.lt(previousVersion, '1.1.0')) {
      console.log('⚠️  Breaking changes in 1.1.0 - please check the migration guide')
    }
  },

  setup (options, nuxt) {
    // Regular setup logic runs on every build
    if (options.enabled) {
      // Configure the module
    }
  },
})
```

--------------------------------

### Add ESLint webpack plugin with addWebpackPlugin

Source: https://nuxt.com/docs/3.x/api/kit/builder

Shows how to use addWebpackPlugin inside a Nuxt module's setup to append an ESLint webpack plugin. The example passes a plugin instance and sets server: false so the plugin is only applied to client builds. It also demonstrates building webpack options from module defaults and the nuxt options.

```ts
import EslintWebpackPlugin from 'eslint-webpack-plugin'
import { addWebpackPlugin, defineNuxtModule } from '@nuxt/kit'

export default defineNuxtModule({
  meta: {
    name: 'nuxt-eslint',
    configKey: 'eslint',
  },
  defaults: nuxt => ({
    include: [`${nuxt.options.srcDir}/**/*.{js,jsx,ts,tsx,vue}`],
    lintOnStart: true,
  }),
  setup (options, nuxt) {
    const webpackOptions = {
      ...options,
      context: nuxt.options.srcDir,
      files: options.include,
      lintDirtyModulesOnly: !options.lintOnStart,
    }
    addWebpackPlugin(new EslintWebpackPlugin(webpackOptions), { server: false })
  },
})
```

--------------------------------

### Extend a git remote source with install option

Source: https://nuxt.com/docs/3.x/guide/going-further/layers

Extends a git remote source with the `install: true` option to install npm dependencies from the layer. This is necessary when the layer has npm dependencies and you want to install them.

```ts
export default defineNuxtConfig({
  extends: [
    ['github:username/repoName', { install: true }],
  ],
})
```

--------------------------------

### Example directory structure for tests

Source: https://nuxt.com/docs/3.x/getting-started/testing

Shows a recommended directory structure separating e2e, nuxt, and unit tests. Keeping the Nuxt runtime environment separated from end-to-end tests is important for stability.

```bash
test/
├── e2e/
│   └── ssr.test.ts
├── nuxt/
│   ├── components.test.ts
│   └── composables.test.ts
├── unit/
│   └── utils.test.ts
```

--------------------------------

### Create a new Nuxt project with pnpm

Source: https://nuxt.com/docs/3.x/getting-started/installation

Use this command in your terminal to create a new Nuxt 3 starter project. Replace <project-name> with your desired project name.

```bash
pnpm create nuxt@latest <project-name> -t v3
```

--------------------------------

### Get all or specific request headers with useRequestHeaders

Source: https://nuxt.com/docs/3.x/api/composables/use-request-headers

Shows two ways to use useRequestHeaders: without arguments to get all request headers, or with an array of header names to get only those. In the browser, useRequestHeaders returns an empty object.

```ts
// Get all request headers
const headers = useRequestHeaders()

// Get only cookie request header
const { cookie } = useRequestHeaders(['cookie'])
```

--------------------------------

### treeShake.composables example

Source: https://nuxt.com/docs/3.x/api/configuration/nuxt-config

Example configuration for `treeShake.composables`. Tree shakes the specified composable from the client build.

```javascript
treeShake: { client: { myPackage: ['useServerOnlyComposable'] } }
```

--------------------------------

### Recommended .gitignore entries for Nuxt projects

Source: https://nuxt.com/docs/3.x/directory-structure/gitignore

Recommended .gitignore entries for Nuxt projects. Includes Nuxt dev/build outputs, node dependencies, logs, and local env files. The pattern !.env.example ensures the example env file is not ignored.

```bash
# Nuxt dev/build outputs
.output
.data
.nuxt
.nitro
.cache
dist

# Node dependencies
node_modules

# Logs
logs
*.log

# Misc
.DS_Store

# Local env files
.env
.env.*
!.env.example
```

--------------------------------

### NuxtTime custom formatting example

Source: https://nuxt.com/docs/3.x/api/components/nuxt-time

Custom formatting example using multiple Intl.DateTimeFormat options including timeZoneName.

```vue
<template>
  <NuxtTime
    :datetime="Date.now()"
    weekday="long"
    year="numeric"
    month="short"
    day="numeric"
    hour="numeric"
    minute="numeric"
    second="numeric"
    time-zone-name="short"
  />
</template>
```
Tokens:
Raw