mirror of
https://github.com/nuxt/nuxt.git
synced 2025-01-18 09:25:54 +00:00
docs: grammar and style tweaks (#723)
This commit is contained in:
Daniel Roe
GitHub
parent
0287b46fed
commit
051289af4e
4
.github/PULL_REQUEST_TEMPLATE.md
vendored
4
.github/PULL_REQUEST_TEMPLATE.md
vendored
@ -7,11 +7,11 @@ Please carefully read the contribution docs before creating a pull request
|
||||
|
||||
### 🔗 Linked issue
|
||||
|
||||
<!-- Please ensure there is an open issue and mention it's number as #123 -->
|
||||
<!-- Please ensure there is an open issue and mention its number as #123 -->
|
||||
|
||||
### ❓ Type of change
|
||||
|
||||
<!-- What types of changes does your code introduce? Put `x's in all the boxes -->
|
||||
<!-- What types of changes does your code introduce? Put an `x` in all the boxes that apply. -->
|
||||
|
||||
- [ ] 📖 Documentation (updates to the documentation or readme)
|
||||
- [ ] 🐞 Bug fix (a non-breaking change that fixes an issue)
|
||||
|
||||
@ -2,7 +2,7 @@
|
||||
|
||||
## What is Nuxt?
|
||||
|
||||
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).
|
||||
If this is the first time you're learning about Nuxt or you want to get more familiar with Nuxt 3, we recommend you begin by reading the [Concepts section](/concepts).
|
||||
|
||||
## Prerequisites
|
||||
|
||||
@ -12,17 +12,17 @@ Before getting started, please make sure you have installed the recommended setu
|
||||
* **Visual Studio Code** 👉 [[Download](https://code.visualstudio.com/)]
|
||||
* **Volar Extension** 👉 [[Download](https://marketplace.visualstudio.com/items?itemName=johnsoncodehk.volar)]
|
||||
|
||||
<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` that you are using `v14` or `v16`.
|
||||
|
||||
## Nuxt 3 or Bridge
|
||||
|
||||
You must decide if you are starting from scratch or upgrading an existing Nuxt 2 project.
|
||||
Next, decide whether to start from scratch or upgrade an existing Nuxt 2 project.
|
||||
|
||||
### Starting a fresh Nuxt project
|
||||
|
||||
::list{type=info}
|
||||
- Enjoy using Vue 3
|
||||
- All of new composables are available
|
||||
- All the new composables are available
|
||||
- New templating system and conventions are enabled
|
||||
::
|
||||
|
||||
@ -32,15 +32,15 @@ Checkout the [Installation section](/getting-started/installation).
|
||||
|
||||
### 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** you begin by using Nuxt Bridge. This way you can try most new features while keeping breaking changes to a minimum.
|
||||
|
||||
::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 Nuxt 3 migration
|
||||
- It's risk free! You can always remove the module from your config
|
||||
- Makes your project (almost) ready for Nuxt 3
|
||||
- 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
|
||||
- Use Nitro engine for platform-agnostic and optimized deployments
|
||||
- Help us stabilize Nuxt 3 and discover flaws
|
||||
- Nuxt Bridge is more stable than Nuxt 3 at the moment
|
||||
::
|
||||
|
||||
::alert{icon=👉}
|
||||
@ -54,7 +54,7 @@ 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 | 🐎 Fast | 🏎 Faster | 🚀 Fastest
|
||||
Performance | 🐎 Fast | 🏎 Faster | 🚀 Fastest
|
||||
Nitro Engine | ❌ | ✅ | ✅
|
||||
ESM support | 🌙 Partial | 👍 Better | ✅
|
||||
TypeScript | ☑️ Opt-in | 🚧 Faster | ✅
|
||||
@ -64,4 +64,5 @@ Components Auto Import | ✅ | ✅ | ✅
|
||||
Auto Imports | ❌ | ✅ | ✅
|
||||
Webpack | 4 | 4 | 5
|
||||
Vite | ⚠️ Partial | 🚧 Partial | 🚧 Experimental
|
||||
Nuxi CLI | ❌ Old | ✅ nuxi | ✅ nuxi
|
||||
Nuxi CLI | ❌ Old | ✅ nuxi | ✅ nuxi
|
||||
Static sites | ✅ | ✅ | 🚧
|
||||
|
||||
@ -3,7 +3,7 @@
|
||||
Getting started with Nuxt 3 is straightforward.
|
||||
|
||||
::alert
|
||||
Please skip this section if want to migrate an existing Nuxt 2 project and go to the [Bridge section](/getting-started/bridge).<br>
|
||||
If you want to migrate an existing Nuxt 2 project, skip this and follow the [Bridge instructions](/getting-started/bridge) instead.<br>
|
||||
Learn more in [Introduction](/getting-started/introduction).
|
||||
::
|
||||
|
||||
@ -34,7 +34,7 @@ npm install
|
||||
|
||||
## 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 your nuxt app in development mode:
|
||||
|
||||
::code-group
|
||||
```bash [Yarn]
|
||||
@ -46,12 +46,12 @@ npm run dev -- -o
|
||||
::
|
||||
|
||||
::alert{type=success icon=✨ .font-bold}
|
||||
Well done! A browser window should automatically open http://localhost:3000
|
||||
Well done! A browser window should automatically open for http://localhost:3000
|
||||
::
|
||||
|
||||
## Next steps
|
||||
|
||||
Once you created your Nuxt 3 project, you are ready to start building your application.
|
||||
Now that you've created your Nuxt 3 project, you are ready to start building your application.
|
||||
|
||||
- Learn about the [Concepts](/concepts)
|
||||
- Learn more about the [Usage](/docs)
|
||||
|
||||
@ -3,18 +3,18 @@
|
||||
Experience Nuxt 3 features on existing Nuxt 2 projects.
|
||||
|
||||
::alert
|
||||
Please skip this section if starting a fresh Nuxt 3 project and go to [Installation](/getting-started/installation).<br>
|
||||
If you're starting a fresh Nuxt 3 project, please skip this section and go to [Nuxt 3 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 that allows you to experience many of new Nuxt 3 features by simply installing and enabling a Nuxt 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.
|
||||
Using Nuxt Bridge, you can make sure your project is (almost) ready for Nuxt 3 and have the best developer experience without needing a major rewrite or risk breaking changes.
|
||||
|
||||
|
||||
### Upgrade Nuxt 2
|
||||
|
||||
Remove package lock-file (`package-lock.json` and `yarn.lock`) and use latest `nuxt-edge`:
|
||||
Remove any package lockfiles (`package-lock.json` and `yarn.lock`) and use the latest `nuxt-edge`:
|
||||
|
||||
**package.json**
|
||||
|
||||
@ -23,7 +23,7 @@ Remove package lock-file (`package-lock.json` and `yarn.lock`) and use latest `n
|
||||
+ "nuxt-edge": "latest"
|
||||
```
|
||||
|
||||
Then, install again the dependencies:
|
||||
Then, reinstall your dependencies:
|
||||
|
||||
::code-group
|
||||
```bash [Yarn]
|
||||
@ -35,7 +35,7 @@ npm install
|
||||
::
|
||||
|
||||
::alert
|
||||
Once the installation is done, make sure both development and production builds are working fine before proceed to the module installation.
|
||||
Once the installation is complete, make sure both development and production builds are working as expected before proceeding.
|
||||
::
|
||||
|
||||
### Install Nuxt Bridge
|
||||
@ -53,7 +53,7 @@ yarn add --dev @nuxt/bridge@npm:@nuxt/bridge-edge
|
||||
|
||||
### 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.
|
||||
Please make sure to avoid any CommonJS syntax such as `module.exports`, `require` or `require.resolve` in your config file. It will soon be 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.
|
||||
|
||||
@ -87,12 +87,12 @@ In every file make sure to:
|
||||
|
||||
✔️ Try with `nuxt dev` and `nuxt build` (or `nuxt generate`) to see if everything goes well.
|
||||
|
||||
🐛 Something is wrong? Please report us by creating an issue. Also, you can easily disable bridge in the meantime:
|
||||
🐛 Is something wrong? Please let us know by creating an issue. Also, you can easily disable bridge in the meantime:
|
||||
|
||||
```ts [nuxt.config.js]
|
||||
import { defineNuxtConfig } from '@nuxt/bridge'
|
||||
|
||||
export default defineNuxtConfig({
|
||||
bridge: false // Temporary disable bridge integration
|
||||
bridge: false // Temporarily disable bridge integration
|
||||
})
|
||||
```
|
||||
|
||||
@ -4,12 +4,12 @@ Nuxt 3 migration guide. Work in progress 🚧
|
||||
|
||||
## 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 it recommanded 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.
|
||||
|
||||
Some features have been dropped from Nuxt 2, some yet need to be implemented for Nuxt 3 and some are new in Nuxt 3 (and Bridge).
|
||||
Some features have been dropped from Nuxt 2, some are yet to be implemented for Nuxt 3 and some are new in Nuxt 3 (and Bridge).
|
||||
|
||||
Noticable and/or Breaking changes with Nuxt 3 other than the requirements of bridge are:
|
||||
Noticeable and/or breaking changes for Nuxt 3 other than the requirements of Nuxt Bridge are:
|
||||
|
||||
::list{type=warning}
|
||||
- Vue app templates are rewritten
|
||||
@ -42,7 +42,6 @@ Suspense | ❌ | ✅ | -
|
||||
Options API: `asyncData` | ✅ | 🚧 | ?
|
||||
Options API: `fetch` | ✅ | 🚧 | ?
|
||||
|
||||
|
||||
### 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.
|
||||
@ -63,8 +62,7 @@ By using [vue-demi](https://github.com/vueuse/vue-demi) they should be compatibl
|
||||
|
||||
## Module Migration
|
||||
|
||||
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.
|
||||
When Nuxt 3 users add your module, a compatible module container layer from `@nuxt/kit` is **automatically injected**, so as long as your code is following the guidelines below, it should continue working as-is.
|
||||
|
||||
### Test with `@nuxt/bridge`
|
||||
|
||||
@ -132,13 +130,13 @@ export default {}
|
||||
|
||||
### Avoid runtime modules
|
||||
|
||||
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.
|
||||
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 fine by adding only to [`buildModules`](/docs/directory-structure/nuxt.config#buildmodules) (instead of `modules`):
|
||||
Your module needs should work even if it's only added to [`buildModules`](/docs/directory-structure/nuxt.config#buildmodules) (instead of `modules`). For example:
|
||||
|
||||
- Avoid updating `process.env` within a Nuxt module and reading by a nuxt plugin, use [`runtimeConfig`](/docs/directory-structure/nuxt.config#publicruntimeconfig) 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
|
||||
- (*) Avoid adding `serverMiddleware` by importing them inside module. Instead, add them by referencing a file path so that they are independent of module context
|
||||
|
||||
(*) Unless it is for `nuxt dev` purpose only and guarded with `if (nuxt.options.dev) { }`.
|
||||
|
||||
@ -150,7 +148,7 @@ Ensure your module is exporting meta object.
|
||||
|
||||
### 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 the Nuxt ecosystem is shifting to use TypeScript, so it is highly recommended to consider migration.
|
||||
|
||||
::alert{icon=💡}
|
||||
You can start migration by simply renaming `.js` files, to `.ts`. TypeScript is designed to be progressive!
|
||||
|
||||
@ -1,6 +1,6 @@
|
||||
# Data Fetching
|
||||
|
||||
Nuxt provides `useAsyncData` to handle data fetching within you application.
|
||||
Nuxt provides `useAsyncData` to handle data fetching within your application.
|
||||
|
||||
## `useAsyncData`
|
||||
|
||||
@ -13,7 +13,7 @@ useAsyncData(key: string, fn: () => Object, options?: { defer: boolean, server:
|
||||
```
|
||||
|
||||
* **key**: a unique key to ensure that data fetching can be properly de-duplicated across requests
|
||||
* **fn** an asynchronous function that **must return an object**.
|
||||
* **fn** an asynchronous function that returns a value.
|
||||
* **options**:
|
||||
- _defer_: whether to load the route before resolving the async function (defaults to `false`)
|
||||
- _server_: whether the fetch the data on server-side (defaults to `true`)
|
||||
|
||||
@ -5,7 +5,8 @@ Nuxt provides `useState` to create a globally shared state.
|
||||
## `useState`
|
||||
|
||||
Within your pages, components and plugins you can use `useState`. It can be used to create your own store implementation.
|
||||
You can think of it as a ssr-friendly ref that it's value will be hydrated (preserved) after Server-Side rendering and it is shared across all components.
|
||||
|
||||
You can think of it as an SSR-friendly ref in that its value will be hydrated (preserved) after server-side rendering. It is shared across all components.
|
||||
|
||||
|
||||
### Usage
|
||||
|
||||
Loading…
Reference in New Issue
Block a user