@nuxt/docs 0.0.0 → 3.17.1

package/7.migration/1.overview.md

@@ -0,0 +1,24 @@
+---
+title: Overview
+description: Nuxt 3 is a complete rewrite of Nuxt 2, and also based on a new set of underlying technologies.
+---
+
+There are significant changes when migrating a Nuxt 2 app to Nuxt 3, although you can expect migration to become more straightforward as we move toward a stable release.
+
+::note
+This migration guide is under progress to align with the development of Nuxt 3.
+::
+
+Some of these significant changes include:
+
+1. Moving from Vue 2 to Vue 3, including defaulting to the Composition API and script setup.
+1. Moving from webpack 4 and Babel to Vite or webpack 5 and esbuild.
+1. Moving from a runtime Nuxt dependency to a minimal, standalone server compiled with nitropack.
+
+::tip
+If you need to remain on Nuxt 2, but want to benefit from Nuxt 3 features in Nuxt 2, you can alternatively check out [how to get started with Bridge](/docs/bridge/overview).
+::
+
+## Next Steps
+
+- Learn about differences in [configuration](/docs/migration/configuration)

package/7.migration/10.bundling.md

@@ -0,0 +1,28 @@
+---
+title: Build Tooling
+description: 'Learn how to migrate from Nuxt 2 to Nuxt 3 build tooling.'
+---
+
+We use the following build tools by default:
+
+- [Vite](https://vite.dev) or [webpack](https://webpack.js.org)
+- [Rollup](https://rollupjs.org)
+- [PostCSS](https://postcss.org)
+- [esbuild](https://esbuild.github.io)
+
+For this reason, most of your previous `build` configuration in `nuxt.config` will now be ignored, including any custom babel configuration.
+
+If you need to configure any of Nuxt's build tools, you can do so in your `nuxt.config`, using the new top-level `vite`, `webpack` and `postcss` keys.
+
+In addition, Nuxt ships with TypeScript support.
+
+:read-more{to="/docs/guide/concepts/typescript"}
+
+## Steps
+
+1. Remove `@nuxt/typescript-build` and `@nuxt/typescript-runtime` from your dependencies and modules.
+2. Remove any unused babel dependencies from your project.
+3. Remove any explicit core-js dependencies.
+4. Migrate `require` to `import`.
+
+<!-- TODO: Enabling webpack builder -->

package/7.migration/11.server.md

@@ -0,0 +1,17 @@
+---
+title: Server
+description: 'Learn how to migrate from Nuxt 2 to Nuxt 3 server.'
+---
+
+In a built Nuxt 3 application, there is no runtime Nuxt dependency. That means your site will be highly performant, and ultra-slim. But it also means you can no longer hook into runtime Nuxt server hooks.
+
+:read-more{to="/docs/guide/concepts/server-engine"}
+
+## Steps
+
+1. Remove the `render` key in your `nuxt.config`.
+2. Any files in `~/server/api` and `~/server/middleware` will be automatically registered; you can remove them from your `serverMiddleware` array.
+3. Update any other items in your `serverMiddleware` array to point to files or npm packages directly, rather than using inline functions.
+
+:read-more{to="/docs/guide/directory-structure/server"}
+:read-more{to="/docs/guide/going-further/hooks#server-hooks-runtime"}

package/7.migration/2.configuration.md

@@ -0,0 +1,240 @@
+---
+title: Configuration
+description: 'Learn how to migrate from Nuxt 2 to Nuxt 3 new configuration.'
+---
+
+## `nuxt.config`
+
+The starting point for your Nuxt app remains your `nuxt.config` file.
+
+::note
+Nuxt configuration will be loaded using [`unjs/jiti`](https://github.com/unjs/jiti) and [`unjs/c12`](https://github.com/unjs/c12).
+::
+
+### Migration
+
+1. You should migrate to the new `defineNuxtConfig` function that provides a typed configuration schema.
+
+   ::code-group
+
+   ```ts [Nuxt 2]
+   export default {
+     // ...
+   }
+   ```
+
+   ```ts [Nuxt 3]
+   export default defineNuxtConfig({
+     // ...
+   })
+   ```
+
+   ::
+
+1. If you were using `router.extendRoutes` you can migrate to the new `pages:extend` hook:
+
+   ::code-group
+
+   ```ts [Nuxt 2]
+   export default {
+     router: {
+       extendRoutes (routes) {
+         //
+       }
+     }
+   }
+   ```
+
+   ```ts [Nuxt 3]
+   export default defineNuxtConfig({
+     hooks: {
+       'pages:extend' (routes) {
+         //
+       }
+     }
+   })
+   ```
+
+   ::
+
+1. If you were using `router.routeNameSplitter` you can achieve same result by updating route name generation logic in the new `pages:extend` hook:
+
+   ::code-group
+
+   ```ts [Nuxt 2]
+   export default {
+     router: {
+       routeNameSplitter: '/'
+     }
+   }
+   ```
+
+   ```ts [Nuxt 3]
+   import { createResolver } from '@nuxt/kit'
+
+   export default defineNuxtConfig({
+     hooks: {
+       'pages:extend' (routes) {
+         const routeNameSplitter = '/'
+         const root = createResolver(import.meta.url).resolve('./pages')
+
+         function updateName(routes) {
+           if (!routes) return
+
+           for (const route of routes) {
+             const relativePath = route.file.substring(root.length + 1)
+             route.name = relativePath.slice(0, -4).replace(/\/index$/, '').replace(/\//g, routeNameSplitter)
+
+             updateName(route.children)
+           }
+         }
+         updateName(routes)
+       },
+     },
+   })
+   ```
+
+   ::
+
+#### ESM Syntax
+
+Nuxt 3 is an [ESM native framework](/docs/guide/concepts/esm). Although [`unjs/jiti`](https://github.com/unjs/jiti) provides semi compatibility when loading `nuxt.config` file, avoid any usage of `require` and `module.exports` in this file.
+
+1. Change `module.exports` to `export default`
+1. Change `const lib = require('lib')` to `import lib from 'lib'`
+
+#### Async Configuration
+
+In order to make Nuxt loading behavior more predictable, async config syntax is deprecated. Consider using Nuxt hooks for async operations.
+
+#### Dotenv
+
+Nuxt has built-in support for loading `.env` files. Avoid directly importing it from `nuxt.config`.
+
+## Modules
+
+Nuxt and Nuxt Modules are now build-time-only.
+
+### Migration
+
+1. Move all your `buildModules` into `modules`.
+2. Check for Nuxt 3 compatibility of modules.
+3. If you have any local modules pointing to a directory you should update this to point to the entry file:
+
+```diff
+  export default defineNuxtConfig({
+    modules: [
+-     '~/modules/my-module'
++     '~/modules/my-module/index'
+    ]
+  })
+```
+
+::tip
+If you are a module author, you can check out [more information about module compatibility](/docs/migration/module-authors) and [our module author guide](/docs/guide/going-further/modules).
+::
+
+## Directory Changes
+
+The `static/` (for storing static assets) has been renamed to `public/`. You can either rename your `static` directory to `public`, or keep the name by setting `dir.public` in your `nuxt.config`.
+
+:read-more{to="/docs/guide/directory-structure/public"}
+
+## TypeScript
+
+It will be much easier to migrate your application if you use Nuxt's TypeScript integration. This does not mean you need to write your application in TypeScript, just that Nuxt will provide automatic type hints for your editor.
+
+You can read more about Nuxt's TypeScript support [in the docs](/docs/guide/concepts/typescript).
+
+::note
+Nuxt can type-check your app using [`vue-tsc`](https://github.com/vuejs/language-tools/tree/master/packages/tsc) with `nuxi typecheck` command.
+::
+
+### Migration
+
+1. Create a `tsconfig.json` with the following content:
+
+   ```json
+   {
+     "extends": "./.nuxt/tsconfig.json"
+   }
+   ```
+
+1. Run `npx nuxi prepare` to generate `.nuxt/tsconfig.json`.
+1. Install Volar following the instructions in the [docs](/docs/getting-started/introduction#prerequisites).
+
+## Vue Changes
+
+There are a number of changes to what is recommended Vue best practice, as well as a number of breaking changes between Vue 2 and 3.
+
+It is recommended to read the [Vue 3 migration guide](https://v3-migration.vuejs.org) and in particular the [breaking changes list](https://v3-migration.vuejs.org/breaking-changes).
+
+It is not currently possible to use the [Vue 3 migration build](https://v3-migration.vuejs.org/migration-build.html) with Nuxt 3.
+
+## Vuex
+
+Nuxt no longer provides a Vuex integration. Instead, the official Vue recommendation is to use `pinia`, which has built-in Nuxt support via a [Nuxt module](https://pinia.vuejs.org/ssr/nuxt.html). [Find out more about pinia here](https://pinia.vuejs.org).
+
+A simple way to provide global state management with pinia would be:
+
+Install the [`@pinia/nuxt`](/modules/pinia) module:
+
+```bash [Terminal]
+yarn add pinia @pinia/nuxt
+```
+
+Enable the module in your nuxt configuration:
+
+```ts [nuxt.config.ts]
+import { defineNuxtConfig } from 'nuxt/config';
+
+export default defineNuxtConfig({
+  modules: ['@pinia/nuxt']
+})
+```
+
+Create a `store` folder at the root of your application:
+
+```ts [store/index.ts]
+import { defineStore } from 'pinia'
+
+export const useMainStore = defineStore('main', {
+  state: () => ({
+    counter: 0,
+  }),
+  actions: {
+    increment() {
+      // `this` is the store instance
+      this.counter++
+    },
+  },
+})
+```
+
+Create a [plugin](/docs/guide/directory-structure/plugins) file to globalize your store:
+
+```ts [plugins/pinia.ts]
+import { useMainStore } from '~/store'
+
+export default defineNuxtPlugin(({ $pinia }) => {
+  return {
+    provide: {
+      store: useMainStore($pinia)
+    }
+  }
+})
+```
+
+If you want to keep using Vuex, you can manually migrate to Vuex 4 following [these steps](https://vuex.vuejs.org/guide/migrating-to-4-0-from-3-x.html).
+
+Once it's done you will need to add the following plugin to your Nuxt app:
+
+```ts [plugins/vuex.ts]
+import store from '~/store'
+
+export default defineNuxtPlugin(nuxtApp => {
+  nuxtApp.vueApp.use(store);
+})
+```
+
+For larger apps, this migration can entail a lot of work. If updating Vuex still creates roadblocks, you may want to use the community module: [nuxt3-vuex-module](https://github.com/vedmant/nuxt3-vuex#nuxt3-vuex-module), which should work out of the box.

package/7.migration/20.module-authors.md

@@ -0,0 +1,94 @@
+---
+title: Modules
+description: 'Learn how to migrate from Nuxt 2 to Nuxt 3 modules.'
+---
+
+## Module Compatibility
+
+Nuxt 3 has a basic backward compatibility layer for Nuxt 2 modules using `@nuxt/kit` auto wrappers. But there are usually steps to follow to make modules compatible with Nuxt 3 and sometimes, using Nuxt Bridge is required for cross-version compatibility.
+
+We have prepared a [Dedicated Guide](/docs/guide/going-further/modules) for authoring Nuxt 3 ready modules using `@nuxt/kit`. Currently best migration path is to follow it and rewrite your modules. Rest of this guide includes preparation steps if you prefer to avoid a full rewrite yet making modules compatible with Nuxt 3.
+
+::tip{icon="i-lucide-puzzle" to="/modules"}
+Explore Nuxt 3 compatible modules.
+::
+
+### Plugin Compatibility
+
+Nuxt 3 plugins are **not** fully backward compatible with Nuxt 2.
+
+:read-more{to="/docs/guide/directory-structure/plugins"}
+
+### Vue Compatibility
+
+Plugins or components using the Composition API need exclusive Vue 2 or Vue 3 support.
+
+By using [vue-demi](https://github.com/vueuse/vue-demi) they should be compatible with both Nuxt 2 and 3.
+
+## Module Migration
+
+When Nuxt 3 users add your module, you will not have access to the module container (`this.*`) so you will need to use utilities from `@nuxt/kit` to access the container functionality.
+
+### Test with `@nuxt/bridge`
+
+Migrating to `@nuxt/bridge` is the first and most important step for supporting Nuxt 3.
+
+If you have a fixture or example in your module, add `@nuxt/bridge` package to its config (see [example](/docs/bridge/overview#update-nuxtconfig))
+
+### Migrate from CommonJS to ESM
+
+Nuxt 3 natively supports TypeScript and ECMAScript Modules. Please check [Native ES Modules](/docs/guide/concepts/esm) for more info and upgrading.
+
+### Ensure Plugins Default Export
+
+If you inject a Nuxt plugin that does not have `export default` (such as global Vue plugins), ensure you add `export default () => { }` to the end of it.
+
+::code-group
+
+```js [Before]
+// ~/plugins/vuelidate.js
+import Vue from 'vue'
+import Vuelidate from 'vuelidate'
+
+Vue.use(Vuelidate)
+```
+
+```js [After]
+// ~/plugins/vuelidate.js
+import Vue from 'vue'
+import Vuelidate from 'vuelidate'
+
+Vue.use(Vuelidate)
+
+export default () => { }
+```
+
+::
+
+### Avoid Runtime Modules
+
+With Nuxt 3, Nuxt is now a build-time-only dependency, which means that modules shouldn't attempt to hook into the Nuxt runtime.
+
+Your module should work even if it's only added to [`buildModules`](/docs/api/nuxt-config#runtimeconfig) (instead of `modules`). For example:
+
+- Avoid updating `process.env` within a Nuxt module and reading by a Nuxt plugin; use [`runtimeConfig`](/docs/api/nuxt-config#runtimeconfig) instead.
+- (*) Avoid depending on runtime hooks like `vue-renderer:*` for production
+- (*) Avoid adding `serverMiddleware` by importing them inside the module. Instead, add them by referencing a file path so that they are independent of the module's context
+
+(*) Unless it is for `nuxt dev` purpose only and guarded with `if (nuxt.options.dev) { }`.
+
+::tip
+Continue reading about Nuxt 3 modules in the [Modules Author Guide](/docs/guide/going-further/modules).
+::
+
+### Use TypeScript (Optional)
+
+While it is not essential, most of the Nuxt ecosystem is shifting to use TypeScript, so it is highly recommended to consider migration.
+
+::tip
+You can start migration by renaming `.js` files, to `.ts`. TypeScript is designed to be progressive!
+::
+
+::tip
+You can use TypeScript syntax for Nuxt 2 and 3 modules and plugins without any extra dependencies.
+::

package/7.migration/3.auto-imports.md

@@ -0,0 +1,18 @@
+---
+title: Auto Imports
+description:  Nuxt 3 adopts a minimal friction approach, meaning wherever possible components and composables are auto-imported.
+---
+
+::note
+In the rest of the migration documentation, you will notice that key Nuxt and Vue utilities do not have explicit imports. This is not a typo; Nuxt will automatically import them for you, and you should get full type hinting if you have followed [the instructions](/docs/migration/configuration#typescript) to use Nuxt's TypeScript support.
+::
+
+[Read more about auto imports](/docs/guide/concepts/auto-imports)
+
+## Migration
+
+1. If you have been using `@nuxt/components` in Nuxt 2, you can remove `components: true` in your `nuxt.config`. If you had a more complex setup, then note that the component options have changed somewhat. See the [components documentation](/docs/guide/directory-structure/components) for more information.
+
+::tip
+You can look at `.nuxt/types/components.d.ts` and `.nuxt/types/imports.d.ts` to see how Nuxt has resolved your components and composable auto-imports.
+::

package/7.migration/4.meta.md

@@ -0,0 +1,127 @@
+---
+title: Meta Tags
+description: Manage your meta tags, from Nuxt 2 to Nuxt 3.
+---
+
+Nuxt 3 provides several different ways to manage your meta tags:
+1. Through your `nuxt.config`.
+2. Through the [`useHead`](/docs/api/composables/use-head) [composable](/docs/getting-started/seo-meta)
+3. Through [global meta components](/docs/getting-started/seo-meta)
+
+You can customize `title`, `titleTemplate`, `base`, `script`, `noscript`, `style`, `meta`, `link`, `htmlAttrs` and `bodyAttrs`.
+
+::tip
+Nuxt currently uses [`Unhead`](https://github.com/unjs/unhead) to manage your meta tags, but implementation details may change.
+::
+
+:read-more{to="/docs/getting-started/seo-meta"}
+
+## Migration
+
+1. In your `nuxt.config`, rename `head` to `meta`. Consider moving this shared meta configuration into your `app.vue` instead. (Note that objects no longer have a `hid` key for deduplication.)
+2. If you need to access the component state with `head`, you should migrate to using [`useHead`](/docs/api/composables/use-head) . You might also consider using the built-in meta-components.
+3. If you need to use the Options API, there is a `head()` method you can use when you use `defineNuxtComponent`.
+
+### useHead
+
+::code-group
+
+```vue [Nuxt 2]
+<script>
+export default {
+  data: () => ({
+    title: 'My App',
+    description: 'My App Description'
+  })
+  head () {
+    return {
+      title: this.title,
+      meta: [{
+        hid: 'description',
+        name: 'description',
+        content: this.description
+      }]
+    }
+  }
+}
+</script>
+```
+
+```vue [Nuxt 3]
+<script setup lang="ts">
+const title = ref('My App')
+const description = ref('My App Description')
+
+// This will be reactive when you change title/description above
+useHead({
+  title,
+  meta: [{
+    name: 'description',
+    content: description
+  }]
+})
+</script>
+```
+
+::
+
+### Meta-components
+
+Nuxt 3 also provides meta components that you can use to accomplish the same task. While these components look similar to HTML tags, they are provided by Nuxt and have similar functionality.
+
+::code-group
+
+```vue [Nuxt 2]
+<script>
+export default {
+  head () {
+    return {
+      title: 'My App',
+      meta: [{
+        hid: 'description',
+        name: 'description',
+        content: 'My App Description'
+      }]
+    }
+  }
+}
+</script>
+```
+
+```vue [Nuxt 3]
+<template>
+  <div>
+    <Head>
+      <Title>My App</Title>
+      <Meta name="description" content="My app description"/>
+    </Head>
+    <!-- -->
+  </div>
+</template>
+```
+
+::
+
+::important
+1. Make sure you use capital letters for these component names to distinguish them from native HTML elements (`<Title>` rather than `<title>`).
+2. You can place these components anywhere in your template for your page.
+::
+
+### Options API
+
+```vue [Nuxt 3 (Options API)]
+<script>
+// if using options API `head` method you must use `defineNuxtComponent`
+export default defineNuxtComponent({
+  head (nuxtApp) {
+    // `head` receives the nuxt app but cannot access the component instance
+    return {
+      meta: [{
+        name: 'description',
+        content: 'This is my page description.'
+      }]
+    }
+  }
+})
+</script>
+```

package/7.migration/5.plugins-and-middleware.md

@@ -0,0 +1,80 @@
+---
+title: Plugins and Middleware
+description: 'Learn how to migrate from Nuxt 2 to Nuxt 3 plugins and middleware.'
+---
+
+## Plugins
+
+Plugins now have a different format, and take only one argument (`nuxtApp`).
+
+::code-group
+
+```js [Nuxt 2]
+export default (ctx, inject) => {
+  inject('injected', () => 'my injected function')
+})
+```
+
+```ts [Nuxt 3]
+export default defineNuxtPlugin(nuxtApp => {
+  // now available on `nuxtApp.$injected`
+  nuxtApp.provide('injected', () => 'my injected function')
+
+  // You can alternatively use this format, which comes with automatic type support
+  return {
+    provide: {
+      injected: () => 'my injected function'
+    }
+  }
+})
+```
+
+::
+
+:read-more{to="/docs/guide/directory-structure/plugins"}
+
+::read-more{to="/docs/api/composables/use-nuxt-app"}
+Read more about the format of `nuxtApp`.
+::
+
+### Migration
+
+1. Migrate your plugins to use the `defineNuxtPlugin` helper function.
+2. Remove any entries in your `nuxt.config` plugins array that are located in your `plugins/` folder. All files in this directory at the top level (and any index files in any subdirectories) will be automatically registered. Instead of setting `mode` to `client` or `server`, you can indicate this in the file name. For example, `~/plugins/my-plugin.client.ts` will only be loaded on client-side.
+
+## Route Middleware
+
+Route middleware has a different format.
+
+::code-group
+
+```js [Nuxt 2]
+export default function ({ store, redirect }) {
+  // If the user is not authenticated
+  if (!store.state.authenticated) {
+    return redirect('/login')
+  }
+}
+```
+
+```ts [Nuxt 3]
+export default defineNuxtRouteMiddleware((to, from) => {
+  const auth = useState('auth')
+  if (!auth.value.authenticated) {
+    return navigateTo('/login')
+  }
+})
+```
+
+::
+
+Much like Nuxt 2, route middleware placed in your `~/middleware` folder is automatically registered. You can then specify it by name in a component. However, this is done with `definePageMeta` rather than as a component option.
+
+`navigateTo` is one of a number of route helper functions.
+
+:read-more{to="/docs/guide/directory-structure/middleware"}
+
+### Migration
+
+1. Migrate your route middleware to use the `defineNuxtRouteMiddleware` helper function.
+1. Any global middleware (such as in your `nuxt.config`) can be placed in your `~/middleware` folder with a `.global` extension, for example `~/middleware/auth.global.ts`.