diff --git a/docs/content/1.getting-started/1.introduction.md b/docs/content/1.getting-started/1.introduction.md
index d710da05ec..51d695333d 100644
--- a/docs/content/1.getting-started/1.introduction.md
+++ b/docs/content/1.getting-started/1.introduction.md
@@ -1,12 +1,12 @@
# Introduction
-## β What is Nuxt?
+## What is Nuxt?
-Is it the first time Learning about Nuxt or want to get familiar to the new Concepts or Nuxt 3, then we recommand to read the [Concepts section](/concepts)
+If this is the first time your are learning about Nuxt or you want to get familiar with Nuxt 3, then we recommend to first read the [Concepts section](/concepts).
-## π οΈ Prerequisites
+## Prerequisites
-Before getting started, please make sure you have installed recommended development software.
+Before getting started, please make sure you have installed the recommended setup.
* **Node.js*** (latest LTS version) π [[Download](https://nodejs.org/en/download/)]
* **Visual Studio Code** π [[Download](https://code.visualstudio.com/)]
@@ -14,39 +14,47 @@ Before getting started, please make sure you have installed recommended developm
* If you already have Node.js installed, check with `node --version` to ensure using `v14` or `v16`.
-## π Bridge or Nuxt 3
+## Nuxt 3 or Bridge
You must decide if you are starting from scratch or upgrading an existing Nuxt 2 project.
-### π± I am starting a fresh Nuxt project
+### Starting a fresh Nuxt project
-- Enjoy using latest Vue 3
+::list{type=info}
+- Enjoy using Vue 3
- All of new composables are available
- New templating system and conventions are enabled
+::
-π You can go to the [Installation section](/getting-started/installation).
+::alert{icon=π}
+Checkout the [Installation section](/getting-started/installation).
+::
-### β¬οΈ I have an existing Nuxt 2 project
+### Migrating a Nuxt 2 project
If you have an existing Nuxt 2 project, we **strongly recommend** to start migrating your Nuxt 2 project with Bridge module. This way you can try most of new features without opting-in to more breaking changes.
+::list{type=info}
- It is risk-free! You can roll back by just commenting out one line in config
-- Makes your project almost ready for nuxt3 migration
-- Enjoy new DX improvements without major rewrites for vue3
-- Use nitro engine for platform agnostic and optimized deployments
-- Help us stabilize nuxt3 and discover flows
-- Bridge is more stable than nuxt3 at the moment for migration
+- Makes your project almost ready for Nuxt 3 migration
+- Enjoy new DX improvements without major rewrites for Vue 3
+- Use Nitro engine for platform agnostic and optimized deployments
+- Help us stabilize Nuxt 3 and discover flows
+- Bridge is more stable than Nuxt 3 at the moment for migration
+::
-π You can go to the [Bridge installation section](/getting-started/bridge).
+::alert{icon=π}
+Checkout the [Bridge installation section](/getting-started/bridge).
+::
-### ββοΈ Comparation
+### βComparation
In the table below, there is a quick comparison between 3 versions of nuxt:
Feature / Version | Nuxt 2 | Nuxt Bridge | Nuxt 3
-------------------------|-----------------|------------------|---------
-Stability | πΈ Stable | πΊ Semi Stable | π Unstable
-Performance | π Slower | π Enhanced | π₯ Fastest
+Stability | π Stable | βΊοΈ Semi-stable | π¬ Unstable
+Performance | π Fast | π Faster | π Fastest
Nitro Engine | β | β
| β
ESM support | π Partial | π Better | β
TypeScript | βοΈ Opt-in | π§ Faster | β
@@ -56,4 +64,4 @@ Components Auto Import | β
| β
| β
Auto Imports | β | β
| β
Webpack | 4 | 4 | 5
Vite | β οΈ Partial | π§ Partial | π§ Experimental
-Nuxi CLI | β Old | β
| β
+Nuxi CLI | β Old | β
nuxi | β
nuxi
diff --git a/docs/content/1.getting-started/2.installation.md b/docs/content/1.getting-started/2.installation.md
index 0bf07337bb..9ee07ffbc2 100644
--- a/docs/content/1.getting-started/2.installation.md
+++ b/docs/content/1.getting-started/2.installation.md
@@ -1,43 +1,57 @@
# Installation
-Getting started with Nuxt3 is straightforward.
+Getting started with Nuxt 3 is straightforward.
-> Please skip this section if want to upgrade an existing Nuxt 2 project and go to [Bridge](/getting-started/bridge) instead.
-> Learn more in the [Introduction](/getting-started/introduction).
+::alert
+Please skip this section if want to migrate an existing Nuxt 2 project and go to the [Bridge section](/getting-started/bridge).
+Learn more in [Introduction](/getting-started/introduction).
+::
-## β¨ Create a new project
+## New project
-Open a terminal, or from visual studio code, open an [integrated terminal](https://code.visualstudio.com/docs/editor/integrated-terminal) and use the following command to create a new starter project:
+Open a terminal, or from [Visual Studio Code](https://code.visualstudio.com/), open an [integrated terminal](https://code.visualstudio.com/docs/editor/integrated-terminal) and use the following command to create a new starter project:
```bash
-npx nuxi init my-nuxt3-website
+npx nuxi init nuxt3-app
```
-Open `my-nuxt3-projewebsitect` folder in visual studio code:
+Open `nuxt3-app` folder in visual studio code:
```bash
-code -r my-nuxt3-website
+code -r nuxt3-app
```
-Install dependencies using yarn:
+Install the dependencies:
-```bash
+::code-group
+```bash [Yarn]
yarn install
```
+```bash [NPM]
+npm install
+```
+::
-## π Start Development Server
+## Development Server
Now you'll be able to use `yarn dev` to start nuxt app in development mode:
-```bash
+::code-group
+```bash [Yarn]
yarn dev -o
```
+```bash [NPM]
+npm run dev -- -o
+```
+::
-β¨Well done! A browser window should automatically open to `http://localhost:3000`
+::alert{type=success icon=β¨ .font-bold}
+Well done! A browser window should automatically open http://localhost:3000
+::
-# Next steps
+## Next steps
-Once you created your Nuxt 3 application, you are ready to start building you next application.
+Once you created your Nuxt 3 project, you are ready to start building your application.
- Learn about the [Concepts](/concepts)
-- Learn more about [Usage](/docs)
+- Learn more about the [Usage](/docs)
diff --git a/docs/content/1.getting-started/3.bridge.md b/docs/content/1.getting-started/3.bridge.md
index b39d08c179..550331b039 100644
--- a/docs/content/1.getting-started/3.bridge.md
+++ b/docs/content/1.getting-started/3.bridge.md
@@ -1,15 +1,18 @@
# Bridge
-Experience Nuxt 3 on existing Nuxt 2 projects
+Experience Nuxt 3 features on existing Nuxt 2 projects.
-> Please skip this section if starting a new Nuxt 3 project and go to [Installation](/getting-started/installation) instead.
-> Learn more in the [Intorduction](/getting-started/introduction).
+::alert
+Please skip this section if starting a fresh Nuxt 3 project and go to [Installation](/getting-started/installation).
+Learn more in [Introduction](/getting-started/introduction).
+::
-Bridge, is a forward-compatibility layer as a module that allows you to opt-in and experience many of new Nuxt 3 features.
-Using bridge, you can make sure your project is almost ready for Nuxt 3 and have the latest DX experience without major rewrites and risk of breaking changes by adding a simple module.
+Bridge is a forward-compatibility layer as a module that allows you to opt-in and experience many of new Nuxt 3 features.
+
+Using bridge, you can make sure your project is almost ready for Nuxt 3 and have the best developer experience without major rewrites and risk of breaking changes.
-### **Step 1:** Upgrade to the latest version of Nuxt 2
+### Upgrade Nuxt 2
Remove package lock-file (`package-lock.json` and `yarn.lock`) and use latest `nuxt-edge`:
@@ -20,23 +23,39 @@ Remove package lock-file (`package-lock.json` and `yarn.lock`) and use latest `n
+ "nuxt-edge": "latest"
```
-βοΈ After upgrade, please make sure both development and production builds are working fine before proceed to the module installation.
+Then, install again the dependencies:
-### **Step 2:** Install bridge module
+::code-group
+```bash [Yarn]
+yarn install
+```
+```bash [NPM]
+npm install
+```
+::
-Install `@nuxt/bridge-edge` as a devDependency:
+::alert
+Once the installation is done, make sure both development and production builds are working fine before proceed to the module installation.
+::
-```bash
-# Using npm
+### Install Nuxt Bridge
+
+Install `@nuxt/bridge-edge` as a development dependency:
+
+::code-group
+```bash [NPM]
npm install -D @nuxt/bridge@npm:@nuxt/bridge-edge
-
-# Using yarn
+```
+```bash [Yarn]
yarn add --dev @nuxt/bridge@npm:@nuxt/bridge-edge
```
+::
-### **Step 3:** Update `nuxt.config`
+### Update `nuxt.config`
-Please make sure to avoid any CommonJS syntax such as `module.exports`, `require` or `require.resolve` in config file. It will be soon deprecated and unsupported. You can use static `import`, dynamic `import()` and `export default` instead. Using typescript by renaming to `nuxt.config.ts` is also possible and recommended.
+Please make sure to avoid any CommonJS syntax such as `module.exports`, `require` or `require.resolve` in config file. It will be soon deprecated and unsupported.
+
+You can use static `import`, dynamic `import()` and `export default` instead. Using TypeScript by renaming to `nuxt.config.ts` is also possible and recommended.
```ts [nuxt.config.js]
import { defineNuxtConfig } from '@nuxt/bridge'
@@ -46,15 +65,16 @@ export default defineNuxtConfig({
})
```
-### **Step 4:** Avoid CommonJS syntax
+### Avoid CommonJS syntax
-Nuxt natively supports TypeScript and ECMAScript modules. In every file make sure to:
+Nuxt 3 natively supports TypeScript and ECMAScript modules.
+In every file make sure to:
- Change `require('lib')` to `import lib from 'lib'` or `await import('lib').then(e => e.default || e)`
- Change `module.exports` to `export default` or `export const`
- Avoid usage of `__dirname` and `__filename` as much as possible
-### **Step 5:** Remove incompatible and obsolete modules
+### Remove incompatible and obsolete modules
- Remove `@nuxt/content` (1.x) a v2 rewrite for nuxt 3 support is planned, or you may also use docus
- Remove `nuxt-vite`: Bridge enables same functionality
@@ -63,7 +83,7 @@ Nuxt natively supports TypeScript and ECMAScript modules. In every file make sur
- Remove `@nuxt/nitro`: Bridge injects same functionality
- Remove `@nuxtjs/composition-api`: Bridge provides a Nuxt 3 compatible composition-api layer and help to remove dependency
-### **Step 6:** Ensure everything goes well
+### Ensure everything goes well
βοΈ Try with `nuxt dev` and `nuxt build` (or `nuxt generate`) to see if everything goes well.
diff --git a/docs/content/1.getting-started/4.commands.md b/docs/content/1.getting-started/4.commands.md
index ddc9d87a38..94118ffc19 100644
--- a/docs/content/1.getting-started/4.commands.md
+++ b/docs/content/1.getting-started/4.commands.md
@@ -2,9 +2,9 @@
Nuxi is the new CLI experience for Nuxt 3
-Nuxt 3 has two main commands, one to start development server and one to make production assets prepared.
+Nuxt 3 has two main commands, one to start development server and one to make production assets.
-Since Nuxt 3 becomes a dev dependency thanks to the new Nitro server, you only need to add two commands in your `package.json`:
+Since Nuxt 3 becomes a dev dependency thanks to the new [Nitro server](/concepts/server-engine), you only need to add two commands in your `package.json`:
```json
"scripts": {
@@ -13,7 +13,7 @@ Since Nuxt 3 becomes a dev dependency thanks to the new Nitro server, you only n
}
```
-Then, you can run each command using `npm run ` `yarn `.
+Then, you can run each command using `npm run ` or `yarn `.
## Development Server
@@ -41,4 +41,4 @@ npm run build
```
::
-Nuxt will create a `.output` directory with all your application, server and dependencies ready to be deployed. Checkout the [deployment](/docs/deployment) section to learn where and how you can deploy a Nuxt application using Nitro.
+Nuxt will create a [`.output`](/docs/directory-structure/output) directory with all your application, server and dependencies ready to be deployed. Checkout the [deployment](/docs/deployment) section to learn where and how you can deploy a Nuxt application using Nitro.
diff --git a/docs/content/1.getting-started/5.migration.md b/docs/content/1.getting-started/5.migration.md
index ef02a1eb33..4d59ac86a7 100644
--- a/docs/content/1.getting-started/5.migration.md
+++ b/docs/content/1.getting-started/5.migration.md
@@ -1,8 +1,8 @@
# Migration
-Nuxt 3 migration guide (Work in progress)
+Nuxt 3 migration guide. Work in progress π§
-## β¬οΈ Nuxt 2 to Nuxt 3
+## Nuxt 2 to Nuxt 3
At the moment, there is no Nuxt 2 to Nuxt 3 migration guide nor is recommanded to do it due to potentially more changes coming.
We are working to provide a stable migration guide and tooling to make it as smooth as possible. Please check [Bridge](/getting-started/bridge) for the alternative.
@@ -11,14 +11,16 @@ Some features have been dropped from Nuxt 2, some yet need to be implemented for
Noticable and/or Breaking changes with Nuxt 3 other than the requirements of bridge are:
+::list{type=warning}
- Vue app templates are rewritten
- Vue upgraded to `3.x`
-- Using suspense for async data fetching
+- Using `` for async data fetching
- Webpack `5.x` (if not using `vite`)
- Components discovery is rewritten
-- Introduced new `App.vue`
-- Introduced new `layouts`
-- `pages/` directory conventions changed
+- Introduced main [`app.vue` component](/docs/directory-structure/app)
+- Introduced new [`layouts` system](/docs/directory-structure/layouts)
+- The [`pages/` directory](/docs/directory-structure/pages) conventions changed
+::
In table below there is an overall feature comparation table:
@@ -41,51 +43,100 @@ Options API: `asyncData` | β
| π§ | ?
Options API: `fetch` | β
| π§ | ?
-### Nuxt Module Compatibility
+### Module Compatibility
-- All Nuxt 2 modules should be forward compatible with Nuxt 3 as long as they migrate to bridge or if they are already following guidelines
-- All (upcoming) modules made with `@nuxt/kit` should be backward compatible with Nuxt 2 projects (even without bridge) as long as they are not depending on a nuxt3/bridge-only feature
+All Nuxt 2 modules should be forward compatible with Nuxt 3 as long as they migrate to bridge or if they are already following guidelines.
-### Nuxt Plugin Compatibility
+All (upcoming) modules made with `@nuxt/kit` should be backward compatible with Nuxt 2 projects (even without bridge) as long as they are not depending on a Nuxt 3 / Bridge-only feature.
-- Most Nuxt 2 plugins should be forward compatible with nuxt3 with a magical compat layer we inject
-- Nuxt3 plugins are **not** backward compatible with Nuxt 2
+### Plugin Compatibility
+
+Most Nuxt 2 plugins should be forward compatible with Nuxt 3 with a magical compat layer we inject.
+
+Nuxt 3 plugins are **not** backward compatible with Nuxt 2.
### Vue Compatibility
-For plugins and composition API and components, it needs exclusive vue2 or vue3 support from plugins.
-By using [vue-demi](https://github.com/vueuse/vue-demi) they should be compatible with both nuxt2 and nuxt3.
+For plugins using composition API or components, it needs exclusive Vue 2 or Vue 3 support.
-## π¦ Module Migration Guide
+By using [vue-demi](https://github.com/vueuse/vue-demi) they should be compatible with both Nuxt 2 and 3.
-When users of nuxt3 use your module, a compatible module container layer from `@nuxt/kit` is automatically injected
-so as long as your code is following below guidelines, it should continue working as is.
+## Module Migration
-### Test it with `@nuxt/bridge`:
+When Nuxt 3 users add your module, a compatible module container layer from `@nuxt/kit` is **automatically injected**,
+as long as your code is following below guidelines, it should continue working as is.
-Migrating to `@nuxt/bridge` is the first and most important step for supporting nuxt3.
+### Test with `@nuxt/bridge`
-If you have a fixture in your module, add `@nuxt/bridge` package to its config (same steps as previous section for nuxt2 projects)
+Migrating to `@nuxt/bridge` is the first and most important step for supporting Nuxt 3.
-### Avoid CommonJS syntax:
+If you have a fixture or example in your module, add `@nuxt/bridge` package to its config (see [example](/getting-started/bridge#update-nuxtconfig))
-Nuxt natively supports TypeScript and ECMAScript Modules. In every file make sure to:
+### Avoid CommonJS syntax
-- Change `require('lib')` to `import lib from 'lib'` or `await import('lib').then(e => e.default || e)`
-- Change `module.exports` to `export default` or `export const`
-- Avoid usage of `__dirname` and `__filename` as much as possible
+Nuxt natively supports TypeScript and ECMAScript Modules.
-### Ensure plugins have default export
+#### Update the imports
+
+::code-group
+```js [Before]
+const lib = require('lib')
+```
+```js [After]
+import lib from 'lib'
+// or using code-splitting
+const lib = await import('lib').then(e => e.default || e)
+```
+::
+
+#### Update the exports
+
+::code-group
+```js [Before]
+module.exports = ...
+```
+```js [After]
+export default ...
+// or using named export
+export const hello = ...
+```
+::
+
+#### Avoid using specific CJS syntax
+
+Avoid the usage of `__dirname` and `__filename` as much as possible.
+
+### 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 {}
+```
+::
-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
### Avoid runtime modules
-With nuxt3 and nitro project, we started to rethink how the nuxt build process should work and modules hooking into the Nuxt runtime is now considered an anti-pattern and will not work with nuxt3.
+With Nuxt 3, we changed how the build process should work and modules hooking into the Nuxt runtime is now considered an anti-pattern and will not work.
-Your module should work fine by adding only to `buildModules[]` (instead of `modules[]`):
+Your module should work fine by adding only to [`buildModules`](/docs/directory-structure/nuxt.config#buildmodules) (instead of `modules`):
-- Avoid updating `process.env` within nuxt module and reading by a nuxt plugin. Use `runtimeConfig` instead
+- Avoid updating `process.env` within a Nuxt module and reading by a nuxt plugin, use [`runtimeConfig`](/docs/directory-structure/nuxt.config#publicruntimeconfig) instead.
- (*) Avoid depending on runtime hooks like `vue-renderer:*` for production
- (*) Avoid adding `serverMiddleware` by importing them inside module. Add them by referencing to file path so that they are independent of module context
@@ -95,12 +146,16 @@ Your module should work fine by adding only to `buildModules[]` (instead of `mod
Ensure your module is exporting meta object.
-[TODO]
+\[TODO\]
-### Migrate to TypeScript (optional)
+### Use TypeScript (optional)
-While it is not essential, most of nuxt ecosystem is shifting to use TypeScript, it is highly recommended to consider migration.
+While it is not essential, most of Nuxt ecosystem is shifting to use TypeScript, it is highly recommended to consider migration.
-**Tip:** You can start migration by simply renaming `.js` files, to `.ts`. TypeScript is designed to be progressive!
+::alert{icon=π‘}
+You can start migration by simply renaming `.js` files, to `.ts`. TypeScript is designed to be progressive!
+::
-**Tip:** You can use TypeScript syntax for nuxt 2/3 modules and plugins without any extra dependencies.
+::alert{icon=π‘}
+You can use TypeScript syntax for Nuxt 2 and 3 modules and plugins without any extra dependencies.
+::