Zengtudor
/
Nuxt
mirror of https://github.com/nuxt/nuxt.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

docs: grammar and style tweaks (#723)

This commit is contained in:
Daniel Roe 2021-10-11 22:49:54 +01:00 committed by GitHub
parent 0287b46fed
commit 051289af4e
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
7 changed files with 41 additions and 41 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
.github/PULL_REQUEST_TEMPLATE.md vendored
View File

@ -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)

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

@ -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 | 🏎 &nbsp;Faster | 🚀 Fastest
Performance | 🐎 Fast | 🏎 &nbsp;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 | ✅ | ✅ | 🚧

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

@ -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)

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

@ -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
})
```

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

@ -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!

4
docs/content/3.docs/1.usage/1.data-fetching.md
View File

@ -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`)

3
docs/content/3.docs/1.usage/2.state.md
View File

@ -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