From 34a7057c22ccffc8a66b24b3c28b11e5b840bd48 Mon Sep 17 00:00:00 2001 From: Peter Mekhaeil <4616064+petermekhaeil@users.noreply.github.com> Date: Fri, 25 Jun 2021 20:06:08 +0800 Subject: [PATCH] Enable Alex documentation linting for docs --- .alexignore | 1 - .alexrc | 11 ++++++++++- docs/advanced-features/codemods.md | 2 +- docs/advanced-features/custom-app.md | 2 +- docs/advanced-features/debugging.md | 2 +- docs/advanced-features/dynamic-import.md | 2 +- docs/advanced-features/multi-zones.md | 2 +- docs/advanced-features/static-html-export.md | 2 +- docs/api-reference/cli.md | 2 +- docs/api-reference/create-next-app.md | 2 +- docs/api-reference/next/link.md | 2 +- docs/api-reference/next/router.md | 2 +- docs/basic-features/data-fetching.md | 10 +++++----- docs/basic-features/pages.md | 4 ++-- docs/deployment.md | 4 ++-- docs/migrating/incremental-adoption.md | 2 +- docs/upgrading.md | 2 +- 17 files changed, 31 insertions(+), 23 deletions(-) diff --git a/.alexignore b/.alexignore index 68d446f20be81..1bf6581c26b1e 100644 --- a/.alexignore +++ b/.alexignore @@ -1,3 +1,2 @@ CODE_OF_CONDUCT.md -docs/ examples/ diff --git a/.alexrc b/.alexrc index 5feb2df2c9fb2..157d1da8cca53 100644 --- a/.alexrc +++ b/.alexrc @@ -1,12 +1,21 @@ { "allow": [ + "attacks", + "color", "dead", + "execute", "executed", "executes", + "execution", + "executions", "failed", "failure", + "failures", + "fire", + "fires", "hook", + "hooks", "host-hostess", "invalid" ] -} \ No newline at end of file +} diff --git a/docs/advanced-features/codemods.md b/docs/advanced-features/codemods.md index 27f3bc59fc546..f897c89f206ea 100644 --- a/docs/advanced-features/codemods.md +++ b/docs/advanced-features/codemods.md @@ -169,7 +169,7 @@ export default withRouter( ) ``` -This is just one case. All the cases that are transformed (and tested) can be found in the [`__testfixtures__` directory](https://github.com/vercel/next.js/tree/canary/packages/next-codemod/transforms/__testfixtures__/url-to-withrouter). +This is one case. All the cases that are transformed (and tested) can be found in the [`__testfixtures__` directory](https://github.com/vercel/next.js/tree/canary/packages/next-codemod/transforms/__testfixtures__/url-to-withrouter). #### Usage diff --git a/docs/advanced-features/custom-app.md b/docs/advanced-features/custom-app.md index 4f0cdead04d92..71dd20af32577 100644 --- a/docs/advanced-features/custom-app.md +++ b/docs/advanced-features/custom-app.md @@ -42,7 +42,7 @@ The `Component` prop is the active `page`, so whenever you navigate between rout ### Caveats -- If your app is running and you just added a custom `App`, you'll need to restart the development server. Only required if `pages/_app.js` didn't exist before. +- If your app is running and you added a custom `App`, you'll need to restart the development server. Only required if `pages/_app.js` didn't exist before. - Adding a custom `getInitialProps` in your `App` will disable [Automatic Static Optimization](/docs/advanced-features/automatic-static-optimization.md) in pages without [Static Generation](/docs/basic-features/data-fetching.md#getstaticprops-static-generation). - When you add `getInitialProps` in your custom app, you must `import App from "next/app"`, call `App.getInitialProps(appContext)` inside `getInitialProps` and merge the returned object into the return value. - `App` currently does not support Next.js [Data Fetching methods](/docs/basic-features/data-fetching.md) like [`getStaticProps`](/docs/basic-features/data-fetching.md#getstaticprops-static-generation) or [`getServerSideProps`](/docs/basic-features/data-fetching.md#getserversideprops-server-side-rendering). diff --git a/docs/advanced-features/debugging.md b/docs/advanced-features/debugging.md index 3c3b30e735504..3e195e012ed22 100644 --- a/docs/advanced-features/debugging.md +++ b/docs/advanced-features/debugging.md @@ -69,7 +69,7 @@ Now hit F5 or select **Debug: Start Debugging** from the Command Pale Now you can use the [`debugger`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/debugger) statement to pause your backend or frontend code anytime you want to observe and debug your code more precisely. -If you trigger the underlying code by refreshing the current page, clicking on a page link or fetching an API route, your code will be paused and the debugger window will pop up. +If you trigger the underlying code by refreshing the current page, clicking on a page link or fetching an API route, your code will be paused and the debugger window will appear. To learn more on how to use a JavaScript debugger, take a look at the following documentation: diff --git a/docs/advanced-features/dynamic-import.md b/docs/advanced-features/dynamic-import.md index 2f9c8b37e7cce..9bd60726971b5 100644 --- a/docs/advanced-features/dynamic-import.md +++ b/docs/advanced-features/dynamic-import.md @@ -45,7 +45,7 @@ export default function Page() { You can think of dynamic imports as another way to split your code into manageable chunks. -React components can also be imported using dynamic imports, but in this case we use it in conjunction with `next/dynamic` to make sure it works just like any other React Component. Check out the sections below for more details on how it works. +React components can also be imported using dynamic imports, but in this case we use it in conjunction with `next/dynamic` to make sure it works like any other React Component. Check out the sections below for more details on how it works. ## Basic usage diff --git a/docs/advanced-features/multi-zones.md b/docs/advanced-features/multi-zones.md index 1fce98d049e58..ec29f22f33b75 100644 --- a/docs/advanced-features/multi-zones.md +++ b/docs/advanced-features/multi-zones.md @@ -18,7 +18,7 @@ With multi zones support, you can merge both these apps into a single one allowi ## How to define a zone -There are no special zones related APIs. You only need to do following: +There are no zone related APIs. You only need to do following: - Make sure to keep only the pages you need in your app, meaning that an app can't have pages from another app, if app `A` has `/blog` then app `B` shouldn't have it too. - Make sure to configure a [basePath](/docs/api-reference/next.config.js/basepath.md) to avoid conflicts with pages and static files. diff --git a/docs/advanced-features/static-html-export.md b/docs/advanced-features/static-html-export.md index 4451680a3544f..c217b55d952ac 100644 --- a/docs/advanced-features/static-html-export.md +++ b/docs/advanced-features/static-html-export.md @@ -17,7 +17,7 @@ The exported app supports almost every feature of Next.js, including dynamic rou `next export` works by prerendering all pages to HTML. For [dynamic routes](/docs/routing/dynamic-routes.md), your page can export a [`getStaticPaths`](/docs/basic-features/data-fetching.md#getstaticpaths-static-generation) function to let the exporter know which HTML pages to generate for that route. -> `next export` is intended for scenarios where **none** of your pages have server-side or incremental data requirements (though statically-rendered pages can still [fetch data on the client side](/docs/basic-features/data-fetching.md#fetching-data-on-the-client-side) just fine). +> `next export` is intended for scenarios where **none** of your pages have server-side or incremental data requirements (though statically-rendered pages can still [fetch data on the client side](/docs/basic-features/data-fetching.md#fetching-data-on-the-client-side)). > > If you're looking to make a hybrid site where only _some_ pages are prerendered to static HTML, Next.js already does that automatically for you! Read up on [Automatic Static Optimization](/docs/advanced-features/automatic-static-optimization.md) for details. > diff --git a/docs/api-reference/cli.md b/docs/api-reference/cli.md index 2f88d1c19d8a7..b79edb5f0bbce 100644 --- a/docs/api-reference/cli.md +++ b/docs/api-reference/cli.md @@ -46,7 +46,7 @@ NODE_OPTIONS='--inspect' next - **Size** – The number of assets downloaded when navigating to the page client-side. The size for each route only includes its dependencies. - **First Load JS** – The number of assets downloaded when visiting the page from the server. The amount of JS shared by all is shown as a separate metric. -The first load is colored green, yellow, or red. Aim for green for performant applications. +The first load is indicated by green, yellow, or red. Aim for green for performant applications. You can enable production profiling for React with the `--profile` flag in `next build`. This requires [Next.js 9.5](https://nextjs.org/blog/next-9-5): diff --git a/docs/api-reference/create-next-app.md b/docs/api-reference/create-next-app.md index d82dfdfc6d757..1192865d09c00 100644 --- a/docs/api-reference/create-next-app.md +++ b/docs/api-reference/create-next-app.md @@ -4,7 +4,7 @@ description: Create Next.js apps in one command with create-next-app. # Create Next App -The easiest way to get started with Next.js is by using `create-next-app`. This simple CLI tool enables you to quickly start building a new Next.js application, with everything set up for you. You can create a new app using the default Next.js template, or by using one of the [official Next.js examples](https://github.com/vercel/next.js/tree/canary/examples). To get started, use the following command: +The easiest way to get started with Next.js is by using `create-next-app`. This CLI tool enables you to quickly start building a new Next.js application, with everything set up for you. You can create a new app using the default Next.js template, or by using one of the [official Next.js examples](https://github.com/vercel/next.js/tree/canary/examples). To get started, use the following command: ```bash npx create-next-app diff --git a/docs/api-reference/next/link.md b/docs/api-reference/next/link.md index 9abe8ec06c0d7..a5272331968a4 100644 --- a/docs/api-reference/next/link.md +++ b/docs/api-reference/next/link.md @@ -65,7 +65,7 @@ export default Home ## If the route has dynamic segments -There is nothing special to do when linking to a [dynamic route](/docs/routing/dynamic-routes.md), including [catch all routes](/docs/routing/dynamic-routes.md#catch-all-routes), since Next.js 9.5.3 (for older versions check our [previous docs](https://nextjs.org/docs/tag/v9.5.2/api-reference/next/link#dynamic-routes)). However, it can become quite common and handy to use [interpolation](/docs/routing/introduction.md#linking-to-dynamic-paths) or an [URL Object](#with-url-object) to generate the link. +There is nothing to do when linking to a [dynamic route](/docs/routing/dynamic-routes.md), including [catch all routes](/docs/routing/dynamic-routes.md#catch-all-routes), since Next.js 9.5.3 (for older versions check our [previous docs](https://nextjs.org/docs/tag/v9.5.2/api-reference/next/link#dynamic-routes)). However, it can become quite common and handy to use [interpolation](/docs/routing/introduction.md#linking-to-dynamic-paths) or an [URL Object](#with-url-object) to generate the link. For example, the dynamic route `pages/blog/[slug].js` will match the following link: diff --git a/docs/api-reference/next/router.md b/docs/api-reference/next/router.md index 2499edade2bc0..60aa34f7f7092 100644 --- a/docs/api-reference/next/router.md +++ b/docs/api-reference/next/router.md @@ -342,7 +342,7 @@ You can listen to different events happening inside the Next.js Router. Here's a - `routeChangeComplete(url, { shallow })` - Fires when a route changed completely - `routeChangeError(err, url, { shallow })` - Fires when there's an error when changing routes, or a route load is cancelled - `err.cancelled` - Indicates if the navigation was cancelled -- `beforeHistoryChange(url, { shallow })` - Fires just before changing the browser's history +- `beforeHistoryChange(url, { shallow })` - Fires before changing the browser's history - `hashChangeStart(url, { shallow })` - Fires when the hash will change but not the page - `hashChangeComplete(url, { shallow })` - Fires when the hash has changed but not the page diff --git a/docs/basic-features/data-fetching.md b/docs/basic-features/data-fetching.md index 436ee3fbe54fb..93f5ae012ae1b 100644 --- a/docs/basic-features/data-fetching.md +++ b/docs/basic-features/data-fetching.md @@ -134,7 +134,7 @@ The `context` parameter is an object containing the following keys: > > Fetching from an external API is fine! -### Simple Example +### Example Here’s an example which uses `getStaticProps` to fetch a list of blog posts from a CMS (content management system). This example is also in the [Pages documentation](/docs/basic-features/pages.md). @@ -299,7 +299,7 @@ When a request is made to a page that was pre-rendered at build time, it will in - Any requests to the page after the initial request and before 10 seconds are also cached and instantaneous. - After the 10-second window, the next request will still show the cached (stale) page - Next.js triggers a regeneration of the page in the background. -- Once the page has been successfully generated, Next.js will invalidate the cache and show the updated product page. If the background regeneration fails, the old page remains unaltered. +- Once the page has been successfully generated, Next.js will invalidate the cache and show the updated product page. If the background regeneration fails, the old page will stay unaltered. When a request is made to a path that hasn’t been generated, Next.js will server-render the page on the first request. Future requests will serve the static file from the cache. @@ -513,7 +513,7 @@ If `fallback` is `true`, then the behavior of `getStaticProps` changes: - The paths that have not been generated at build time will **not** result in a 404 page. Instead, Next.js will serve a “fallback” version of the page on the first request to such a path (see [“Fallback pages”](#fallback-pages) below for details). - In the background, Next.js will statically generate the requested path HTML and JSON. This includes running `getStaticProps`. - When that’s done, the browser receives the JSON for the generated path. This will be used to automatically render the page with the required props. From the user’s perspective, the page will be swapped from the fallback page to the full page. -- At the same time, Next.js adds this path to the list of pre-rendered pages. Subsequent requests to the same path will serve the generated page, just like other pages pre-rendered at build time. +- At the same time, Next.js adds this path to the list of pre-rendered pages. Subsequent requests to the same path will serve the generated page, like other pages pre-rendered at build time. > `fallback: true` is not supported when using [`next export`](/docs/advanced-features/static-html-export.md). @@ -591,7 +591,7 @@ If `fallback` is `'blocking'`, new paths not returned by `getStaticPaths` will w - The paths returned from `getStaticPaths` will be rendered to HTML at build time by `getStaticProps`. - The paths that have not been generated at build time will **not** result in a 404 page. Instead, Next.js will SSR on the first request and return the generated HTML. - When that’s done, the browser receives the HTML for the generated path. From the user’s perspective, it will transition from "the browser is requesting the page" to "the full page is loaded". There is no flash of loading/fallback state. -- At the same time, Next.js adds this path to the list of pre-rendered pages. Subsequent requests to the same path will serve the generated page, just like other pages pre-rendered at build time. +- At the same time, Next.js adds this path to the list of pre-rendered pages. Subsequent requests to the same path will serve the generated page, like other pages pre-rendered at build time. `fallback: 'blocking'` will not _update_ generated pages by default. To update generated pages, use [Incremental Static Regeneration](#incremental-static-regeneration) in conjunction with `fallback: 'blocking'`. @@ -727,7 +727,7 @@ The `context` parameter is an object containing the following keys: > > Fetching from an external API is fine! -### Simple example +### Example Here’s an example which uses `getServerSideProps` to fetch data at request time and pre-renders it. This example is also in the [Pages documentation](/docs/basic-features/pages.md). diff --git a/docs/basic-features/pages.md b/docs/basic-features/pages.md index 93ff1a28fd537..7efbfc1382f1c 100644 --- a/docs/basic-features/pages.md +++ b/docs/basic-features/pages.md @@ -56,7 +56,7 @@ You can also use **Client-side Rendering** along with Static Generation or Serve
  • Prismic Example (Demo)
  • Contentful Example (Demo)
  • Strapi Example (Demo)
    • -
  • Prepr Example (Demo)
    • +
  • Prepr Example (Demo)
  • Agility CMS Example (Demo)
  • Cosmic Example (Demo)
  • ButterCMS Example (Demo)
    • @@ -87,7 +87,7 @@ Note that this page does not need to fetch any external data to be pre-rendered. ### Static Generation with data -Some pages require fetching external data for pre-rendering. There are two scenarios, and one or both might apply. In each case, you can use a special function Next.js provides: +Some pages require fetching external data for pre-rendering. There are two scenarios, and one or both might apply. In each case, you can use these functions that Next.js provides: 1. Your page **content** depends on external data: Use `getStaticProps`. 2. Your page **paths** depend on external data: Use `getStaticPaths` (usually in addition to `getStaticProps`). diff --git a/docs/deployment.md b/docs/deployment.md index be727ca69a1bb..79b70ad999a7d 100644 --- a/docs/deployment.md +++ b/docs/deployment.md @@ -16,10 +16,10 @@ Then, follow these steps: 1. [Sign up to Vercel](https://vercel.com/signup) (no credit card is required). 2. After signing up, you’ll arrive on the [“Import Project”](https://vercel.com/new) page. Under “From Git Repository”, choose the Git provider you use and set up an integration. (Instructions: [GitHub](https://vercel.com/docs/git/vercel-for-github) / [GitLab](https://vercel.com/docs/git/vercel-for-gitlab) / [BitBucket](https://vercel.com/docs/git/vercel-for-bitbucket)). -3. Once that’s set up, click “Import Project From …” and import your Next.js app. It auto-detects that your app is using Next.js and sets up the build configuration for you. No need to change anything — everything should work just fine! +3. Once that’s set up, click “Import Project From …” and import your Next.js app. It auto-detects that your app is using Next.js and sets up the build configuration for you. No need to change anything — everything should work fine! 4. After importing, it’ll deploy your Next.js app and provide you with a deployment URL. Click “Visit” to see your app in production. -Congratulations! You’ve just deployed your Next.js app! If you have questions, take a look at the [Vercel documentation](https://vercel.com/docs). +Congratulations! You’ve deployed your Next.js app! If you have questions, take a look at the [Vercel documentation](https://vercel.com/docs). > If you’re using a [custom server](/docs/advanced-features/custom-server.md), we strongly recommend migrating away from it (for example, by using [dynamic routing](/docs/routing/dynamic-routes.md)). If you cannot migrate, consider [other hosting options](#other-hosting-options). diff --git a/docs/migrating/incremental-adoption.md b/docs/migrating/incremental-adoption.md index c56ee8363d4b9..5330d8bc17dc5 100644 --- a/docs/migrating/incremental-adoption.md +++ b/docs/migrating/incremental-adoption.md @@ -80,7 +80,7 @@ To learn more about rewrites, take a look at our [documentation](/docs/api-refer ### Micro-Frontends with Monorepos and Subdomains -Next.js and [Vercel](https://vercel.com) make it easy to adopt [micro-frontends](https://martinfowler.com/articles/micro-frontends.html) and deploy as a [Monorepo](https://vercel.com/blog/monorepos). This allows you to use [subdomains](https://en.wikipedia.org/wiki/Subdomain) to adopt new applications incrementally. Some benefits of micro-frontends: +Next.js and [Vercel](https://vercel.com) make it straightforward to adopt [micro-frontends](https://martinfowler.com/articles/micro-frontends.html) and deploy as a [Monorepo](https://vercel.com/blog/monorepos). This allows you to use [subdomains](https://en.wikipedia.org/wiki/Subdomain) to adopt new applications incrementally. Some benefits of micro-frontends: - Smaller, more cohesive and maintainable codebases. - More scalable organizations with decoupled, autonomous teams. diff --git a/docs/upgrading.md b/docs/upgrading.md index f59f4a1522c9e..f5d0ce5b0eeaf 100644 --- a/docs/upgrading.md +++ b/docs/upgrading.md @@ -222,7 +222,7 @@ import { AppContext, AppInitialProps } from 'next/app' import { DocumentContext, DocumentInitialProps } from 'next/document' ``` -#### The `config` key is now a special export on a page +#### The `config` key is now an export on a page You may no longer export a custom variable named `config` from a page (i.e. `export { config }` / `export const config ...`). This exported variable is now used to specify page-level Next.js configuration like Opt-in AMP and API Route features.