Zengtudor/Nuxt
1
0
Fork 0
mirror of https://github.com/nuxt/nuxt.git synced 2025-01-18 09:25:54 +00:00
Code Issues Packages Projects Releases Wiki Activity

chore(docs): Improve getting started section (#717)

Browse Source
This commit is contained in:
Sébastien Chopin 2021-10-11 18:37:38 +02:00 committed by GitHub
parent 34ebfa0d1e
commit 45728735ad
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
7 changed files with 192 additions and 95 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
docs/components/atoms/GitHubButton.vue
View File

@ -1,5 +1,5 @@
<template> <template>
<Link to="https://github.com/nuxt/nuxt.js" aria-label="gitHubLink" blank class="d-icon p-3"> <Link to="https://github.com/nuxt/framework" aria-label="gitHubLink" blank class="d-icon p-3">
<IconGitHub class="w-6 h-6" /> <IconGitHub class="w-6 h-6" />
</Link> </Link>
</template> </template>

2
docs/components/molecules/HomeHero.vue
View File

@ -1,5 +1,5 @@
<template> <template>
<div class="overflow-hidden relative dark:bg-sky-black dark:text-white pt-14 md:pt-18"> <div class="overflow-hidden relative dark:bg-sky-black dark:text-white pt-12">
<div class="flex flex-wrap justify-center py-0 section d-container-content"> <div class="flex flex-wrap justify-center py-0 section d-container-content">
<section class="flex flex-col justify-start w-full px-4 pt-36 pb-48 md:pt-44 lg:pb-56 lg:pt-24 text-center z-20"> <section class="flex flex-col justify-start w-full px-4 pt-36 pb-48 md:pt-44 lg:pb-56 lg:pt-24 text-center z-20">
<Gem class="block m-x-auto" /> <Gem class="block m-x-auto" />

46
docs/content/1.getting-started/1.introduction.md
View File

@ -1,12 +1,12 @@
# Introduction # 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**<sup>*</sup> (latest LTS version) 👉 [[Download](https://nodejs.org/en/download/)] * **Node.js**<sup>*</sup> (latest LTS version) 👉 [[Download](https://nodejs.org/en/download/)]
* **Visual Studio Code** 👉 [[Download](https://code.visualstudio.com/)] * **Visual Studio Code** 👉 [[Download](https://code.visualstudio.com/)]
@ -14,39 +14,47 @@ Before getting started, please make sure you have installed recommended developm
<sup>*</sup> If you already have Node.js installed, check with `node --version` to ensure using `v14` or `v16`. <sup>*</sup> 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. 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 - All of new composables are available
- New templating system and conventions are enabled - 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. 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 - It is risk-free! You can roll back by just commenting out one line in config
- Makes your project almost ready for nuxt3 migration - Makes your project almost ready for Nuxt 3 migration
- Enjoy new DX improvements without major rewrites for vue3 - Enjoy new DX improvements without major rewrites for Vue 3
- Use nitro engine for platform agnostic and optimized deployments - Use Nitro engine for platform agnostic and optimized deployments
- Help us stabilize nuxt3 and discover flows - Help us stabilize Nuxt 3 and discover flows
- Bridge is more stable than nuxt3 at the moment for migration - 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: In the table below, there is a quick comparison between 3 versions of nuxt:
Feature / Version | Nuxt 2 | Nuxt Bridge | Nuxt 3 Feature / Version | Nuxt 2 | Nuxt Bridge | Nuxt 3
-------------------------|-----------------|------------------|--------- -------------------------|-----------------|------------------|---------
Stability | 😸 Stable | 😺 Semi Stable | 🙀 Unstable Stability | 😊 Stable | ☺️ Semi-stable | 😬 Unstable
Performance | 👎 Slower | 👍 Enhanced | 🔥 Fastest Performance | 🐎 Fast | 🏎 &nbsp;Faster | 🚀 Fastest
Nitro Engine | ❌ | ✅ | ✅ Nitro Engine | ❌ | ✅ | ✅
ESM support | 🌙 Partial | 👍 Better | ✅ ESM support | 🌙 Partial | 👍 Better | ✅
TypeScript | ☑️ Opt-in | 🚧 Faster | ✅ TypeScript | ☑️ Opt-in | 🚧 Faster | ✅
@ -56,4 +64,4 @@ Components Auto Import | ✅ | ✅ | ✅
Auto Imports | ❌ | ✅ | ✅ Auto Imports | ❌ | ✅ | ✅
Webpack | 4 | 4 | 5 Webpack | 4 | 4 | 5
Vite | ⚠️ Partial | 🚧 Partial | 🚧 Experimental Vite | ⚠️ Partial | 🚧 Partial | 🚧 Experimental
Nuxi CLI | ❌ Old | ✅ | ✅ Nuxi CLI | ❌ Old | ✅ nuxi | ✅ nuxi

46
docs/content/1.getting-started/2.installation.md
View File

@ -1,43 +1,57 @@
# Installation # 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. ::alert
> Learn more in the [Introduction](/getting-started/introduction). Please skip this section if want to migrate an existing Nuxt 2 project and go to the [Bridge section](/getting-started/bridge).<br>
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 ```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 ```bash
code -r my-nuxt3-website code -r nuxt3-app
``` ```
Install dependencies using yarn: Install the dependencies:
```bash ::code-group
```bash [Yarn]
yarn install 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: Now you'll be able to use `yarn dev` to start nuxt app in development mode:
```bash ::code-group
```bash [Yarn]
yarn dev -o 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 about the [Concepts](/concepts)
- Learn more about [Usage](/docs) - Learn more about the [Usage](/docs)

58
docs/content/1.getting-started/3.bridge.md
View File

@ -1,15 +1,18 @@
# Bridge # 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. ::alert
> Learn more in the [Intorduction](/getting-started/introduction). Please skip this section if starting a fresh Nuxt 3 project and go to [Installation](/getting-started/installation).<br>
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. 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.
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`: 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" + "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 ### Install Nuxt Bridge
# Using npm
Install `@nuxt/bridge-edge` as a development dependency:
::code-group
```bash [NPM]
npm install -D @nuxt/bridge@npm:@nuxt/bridge-edge npm install -D @nuxt/bridge@npm:@nuxt/bridge-edge
```
# Using yarn ```bash [Yarn]
yarn add --dev @nuxt/bridge@npm:@nuxt/bridge-edge 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] ```ts [nuxt.config.js]
import { defineNuxtConfig } from '@nuxt/bridge' 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 `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` - Change `module.exports` to `export default` or `export const`
- Avoid usage of `__dirname` and `__filename` as much as possible - 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/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 - 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 `@nuxt/nitro`: Bridge injects same functionality
- Remove `@nuxtjs/composition-api`: Bridge provides a Nuxt 3 compatible composition-api layer and help to remove dependency - 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. ✔️ Try with `nuxt dev` and `nuxt build` (or `nuxt generate`) to see if everything goes well.

8
docs/content/1.getting-started/4.commands.md
View File

@ -2,9 +2,9 @@
Nuxi is the new CLI experience for Nuxt 3 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 ```json
"scripts": { "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 <command>` `yarn <command>`. Then, you can run each command using `npm run <command>` or `yarn <command>`.
## Development Server ## 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.

125
docs/content/1.getting-started/5.migration.md
View File

@ -1,8 +1,8 @@
# Migration # 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. 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. 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: Noticable and/or Breaking changes with Nuxt 3 other than the requirements of bridge are:
::list{type=warning}
- Vue app templates are rewritten - Vue app templates are rewritten
- Vue upgraded to `3.x` - Vue upgraded to `3.x`
- Using suspense for async data fetching - Using `<Suspense>` for async data fetching
- Webpack `5.x` (if not using `vite`) - Webpack `5.x` (if not using `vite`)
- Components discovery is rewritten - Components discovery is rewritten
- Introduced new `App.vue` - Introduced main [`app.vue` component](/docs/directory-structure/app)
- Introduced new `layouts` - Introduced new [`layouts` system](/docs/directory-structure/layouts)
- `pages/` directory conventions changed - The [`pages/` directory](/docs/directory-structure/pages) conventions changed
::
In table below there is an overall feature comparation table: In table below there is an overall feature comparation table:
@ -41,51 +43,100 @@ Options API: `asyncData` | ✅ | 🚧 | ?
Options API: `fetch` | ✅ | 🚧 | ? 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 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
### 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 ### Plugin Compatibility
- Nuxt3 plugins are **not** backward compatible with Nuxt 2
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 ### Vue Compatibility
For plugins and composition API and components, it needs exclusive vue2 or vue3 support from plugins. For plugins using composition API or components, it needs exclusive Vue 2 or Vue 3 support.
By using [vue-demi](https://github.com/vueuse/vue-demi) they should be compatible with both nuxt2 and nuxt3.
## 📦 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 ## Module Migration
so as long as your code is following below guidelines, it should continue working as is.
### 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)` Nuxt natively supports TypeScript and ECMAScript Modules.
- Change `module.exports` to `export default` or `export const`
- Avoid usage of `__dirname` and `__filename` as much as possible
### 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 ### 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 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 - (*) 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. 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.
::