diff --git a/docs/advanced-features/custom-error-page.md b/docs/advanced-features/custom-error-page.md index 9b2971d0765e2..243a76ce5164b 100644 --- a/docs/advanced-features/custom-error-page.md +++ b/docs/advanced-features/custom-error-page.md @@ -2,6 +2,8 @@ description: Override and extend the built-in Error page to handle custom errors. --- +# Custom Error Page + ## 404 Page A 404 page may be accessed very often. Server-rendering an error page for every visit increases the load of the Next.js server. This can result in increased costs and slow experiences. diff --git a/docs/advanced-features/static-html-export.md b/docs/advanced-features/static-html-export.md index becfd255d69ed..969a2d20a7c25 100644 --- a/docs/advanced-features/static-html-export.md +++ b/docs/advanced-features/static-html-export.md @@ -21,7 +21,7 @@ The exported app supports almost every feature of Next.js, including dynamic rou > > 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. > -> `next export` also causes features like Incremental Static Generation and Regeneration to be disabled, as they require `next start` or a serverless deployment to function. +> `next export` also causes features like [Incremental Static Generation](/docs/basic-features/data-fetching.md#fallback-true) and [Regeneration](/docs/basic-features/data-fetching.md#incremental-static-regeneration) to be disabled, as they require [`next start`](/docs/api-reference/cli.md#production) or a serverless deployment to function. ## How to use it @@ -53,7 +53,9 @@ For more advanced scenarios, you can define a parameter called [`exportPathMap`] ## Deployment -You can read about deploying your Next.js application in the [deployment section](/docs/deployment.md). +By default, `next export` will generate an `out` directory, which can be served by any static hosting service or CDN. + +> We strongly recommend using [Vercel](https://vercel.com/) even if your Next.js app is fully static. [Vercel](https://vercel.com/) is optimized to make static Next.js apps blazingly fast. `next export` works with Zero Config deployments on Vercel. ## Caveats @@ -62,11 +64,10 @@ You can read about deploying your Next.js application in the [deployment section - `getInitialProps` cannot be used alongside `getStaticProps` or `getStaticPaths` on any given page. If you have dynamic routes, instead of using `getStaticPaths` you'll need to configure the [`exportPathMap`](/docs/api-reference/next.config.js/exportPathMap.md) parameter in your [`next.config.js`](/docs/api-reference/next.config.js/introduction.md) file to let the exporter know which HTML files it should output. - When `getInitialProps` is called during export, the `req` and `res` fields of its [`context`](/docs/api-reference/data-fetching/getInitialProps.md#context-object) parameter will be empty objects, since during export there is no server running. - `getInitialProps` **will be called on every client-side navigation**, if you'd like to only fetch data at build-time, switch to `getStaticProps`. - - `getInitialProps` cannot use Node.js-specific libraries or the file system like `getStaticProps` can. `getInitialProps` must fetch from an API. + - `getInitialProps` should fetch from an API and cannot use Node.js-specific libraries or the file system like `getStaticProps` can. - For static export, the `getStaticProps` API is always preferred over `getInitialProps`: it's recommended you convert your pages to use the `getStaticProps` if possible. + It's recommended to use and migrate towards `getStaticProps` over `getInitialProps` whenever possible. -- The `fallback: true` mode of `getStaticPaths` is not supported when using `next export`. -- You won't be able to render HTML dynamically when static exporting, as the HTML files are pre-build. Your application can be a hybrid of [Static Generation](/docs/basic-features/pages.md#static-generation) and [Server-Side Rendering](/docs/basic-features/pages.md#server-side-rendering) when you don't use `next export`. You can learn more about it in the [pages section](/docs/basic-features/pages.md). +- The [`fallback: true`](/docs/basic-features/data-fetching.md#fallback-true) mode of `getStaticPaths` is not supported when using `next export`. - [API Routes](/docs/api-routes/introduction.md) are not supported by this method because they can't be prerendered to HTML. - [`getServerSideProps`](/docs/basic-features/data-fetching.md#getserversideprops-server-side-rendering) cannot be used within pages because the method requires a server. Consider using [`getStaticProps`](/docs/basic-features/data-fetching.md#getstaticprops-static-generation) instead. diff --git a/docs/api-reference/cli.md b/docs/api-reference/cli.md index 5b63772e85a2d..bd9959252349e 100644 --- a/docs/api-reference/cli.md +++ b/docs/api-reference/cli.md @@ -48,7 +48,7 @@ NODE_OPTIONS='--inspect' next The first load is colored 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: +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): ```bash next build --profile diff --git a/docs/api-reference/data-fetching/getInitialProps.md b/docs/api-reference/data-fetching/getInitialProps.md index 6e428820ecd96..cc0d690119a27 100644 --- a/docs/api-reference/data-fetching/getInitialProps.md +++ b/docs/api-reference/data-fetching/getInitialProps.md @@ -4,19 +4,11 @@ description: Enable Server-Side Rendering in a page and do initial data populati # getInitialProps -> **Recommended: [`getStaticProps`](/docs/basic-features/data-fetching.md#getstaticprops-static-generation) or [`getServerSideProps`](/docs/basic-features/data-fetching.md#getserversideprops-server-side-rendering)** +> **Recommended: [`getStaticProps`](/docs/basic-features/data-fetching.md#getstaticprops-static-generation) or [`getServerSideProps`](/docs/basic-features/data-fetching.md#getserversideprops-server-side-rendering)**. > > If you're using Next.js 9.3 or newer, we recommend that you use `getStaticProps` or `getServerSideProps` instead of `getInitialProps`. > -> These new data fetching methods allow you to have a granular choice between static generation and server-side rendering. -> Learn more on the documentation for [Pages](/docs/basic-features/pages.md) and [Data fetching](/docs/basic-features/data-fetching.md): - -
- Examples - -
+> These new data fetching methods allow you to have a granular choice between static generation and server-side rendering. Learn more on the documentation for [Pages](/docs/basic-features/pages.md) and [Data fetching](/docs/basic-features/data-fetching.md). `getInitialProps` enables [server-side rendering](/docs/basic-features/pages.md#server-side-rendering) in a page and allows you to do **initial data population**, it means sending the [page](/docs/basic-features/pages.md) with the data already populated from the server. This is especially useful for [SEO](https://en.wikipedia.org/wiki/Search_engine_optimization). diff --git a/docs/api-reference/next.config.js/environment-variables.md b/docs/api-reference/next.config.js/environment-variables.md index 9a3536fa0c9b3..a0766ef442dbc 100644 --- a/docs/api-reference/next.config.js/environment-variables.md +++ b/docs/api-reference/next.config.js/environment-variables.md @@ -4,7 +4,7 @@ description: Learn to add and access environment variables in your Next.js appli # Environment Variables -> Since the release of Next.js 9.4 we now have a more intuitive and ergonomic experience for [adding environment variables](/docs/basic-features/environment-variables.md). Give it a try! +> Since the release of [Next.js 9.4](https://nextjs.org/blog/next-9-4) we now have a more intuitive and ergonomic experience for [adding environment variables](/docs/basic-features/environment-variables.md). Give it a try!
Examples diff --git a/docs/api-routes/dynamic-api-routes.md b/docs/api-routes/dynamic-api-routes.md index 8c49755693a6b..272f68025f7e2 100644 --- a/docs/api-routes/dynamic-api-routes.md +++ b/docs/api-routes/dynamic-api-routes.md @@ -31,7 +31,7 @@ Now, a request to `/api/post/abc` will respond with the text: `Post: abc`. A very common RESTful pattern is to set up routes like this: -- `GET api/posts/` - gets a list of posts, probably paginated +- `GET api/posts` - gets a list of posts, probably paginated - `GET api/posts/12345` - gets post id 12345 We can model this in two ways: @@ -40,11 +40,10 @@ We can model this in two ways: - `/api/posts.js` - `/api/posts/[postId].js` - Option 2: - - `/api/posts/index.js` - `/api/posts/[postId].js` -Both are equivalent. A third option of only using `/api/posts/[postId].js` is not valid because Dynamic Routes (including Catch-all routes - see below) do not have an `undefined` state and `GET api/posts/` will not match `/api/posts/[postId].js` under any circumstances. +Both are equivalent. A third option of only using `/api/posts/[postId].js` is not valid because Dynamic Routes (including Catch-all routes - see below) do not have an `undefined` state and `GET api/posts` will not match `/api/posts/[postId].js` under any circumstances. ### Catch all API routes diff --git a/docs/api-routes/introduction.md b/docs/api-routes/introduction.md index eac86c6ab3db0..9d71dc4aca031 100644 --- a/docs/api-routes/introduction.md +++ b/docs/api-routes/introduction.md @@ -17,7 +17,7 @@ description: Next.js supports API Routes, which allow you to build your API with API routes provide a straightforward solution to build your **API** with Next.js. -Any file inside the folder `pages/api` is mapped to `/api/*` and will be treated as an API endpoint instead of a `page`. +Any file inside the folder `pages/api` is mapped to `/api/*` and will be treated as an API endpoint instead of a `page`. They are server-side only bundles and won't increase your client-side bundle size. For example, the following API route `pages/api/user.js` handles a `json` response: @@ -48,9 +48,10 @@ export default (req, res) => { To fetch API endpoints, take a look into any of the examples at the start of this section. -> API Routes [do not specify CORS headers](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS), meaning they are **same-origin only** by default. You can customize such behavior by wrapping the request handler with the [cors middleware](/docs/api-routes/api-middlewares.md#connectexpress-middleware-support). +## Caveats -> API Routes do not increase your client-side bundle size. They are server-side only bundles. +- API Routes [do not specify CORS headers](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS), meaning they are **same-origin only** by default. You can customize such behavior by wrapping the request handler with the [cors middleware](/docs/api-routes/api-middlewares.md#connectexpress-middleware-support). +- API Routes can't be used with [`next export`](/docs/advanced-features/static-html-export.md) ## Related diff --git a/docs/basic-features/supported-browsers-features.md b/docs/basic-features/supported-browsers-features.md index e073c9433608f..9da03b356a6b1 100644 --- a/docs/basic-features/supported-browsers-features.md +++ b/docs/basic-features/supported-browsers-features.md @@ -26,7 +26,7 @@ In addition to `fetch()` on the client side, Next.js polyfills `fetch()` in the If your own code or any external npm dependencies require features not supported by your target browsers, you need to add polyfills yourself. -In this case, you should add a top-level import for the **specific polyfill** you need in your [Custom ``](docs/advanced-features/custom-app.md) or the individual component. +In this case, you should add a top-level import for the **specific polyfill** you need in your [Custom ``](/docs/advanced-features/custom-app.md) or the individual component. ## JavaScript Language Features diff --git a/docs/deployment.md b/docs/deployment.md index eddcc9acd5949..fc1a806e9ccf8 100644 --- a/docs/deployment.md +++ b/docs/deployment.md @@ -72,6 +72,4 @@ Make sure your `package.json` has the `"build"` and `"start"` scripts: ### Static HTML Export -If you’d like to do a static HTML export of your Next.js app, follow the directions on [our documentation](/docs/advanced-features/static-html-export.md). By default, `next export` will generate an `out` directory, which can be served by any static hosting service or CDN. - -> We strongly recommend using [Vercel](https://vercel.com/) even if your Next.js app is fully static. [Vercel](https://vercel.com/) is optimized to make static Next.js apps blazingly fast. `next export` works with Zero Config deployments on Vercel. +If you’d like to do a static HTML export of your Next.js app, follow the directions on [our documentation](/docs/advanced-features/static-html-export.md). diff --git a/docs/faq.md b/docs/faq.md index d13c94b2ff984..8593eed265d7f 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -74,6 +74,6 @@ description: Get to know more about Next.js with the frequently asked questions.
- Can I make a Next.js Progressive Web App? -

Yes! Here's an example.

+ Can I make a Next.js Progressive Web App (PWA)? +

Yes! Check out our PWA Example to see how it works.

diff --git a/examples/data-fetch/README.md b/examples/data-fetch/README.md index d7146d911d652..6dc5c58e7ed8c 100644 --- a/examples/data-fetch/README.md +++ b/examples/data-fetch/README.md @@ -1,9 +1,9 @@ # Data fetch example Next.js was conceived to make it easy to create universal apps. That's why fetching data -on the server and the client when necessary is so easy with Next. +on the server and the client when necessary is so easy with Next.js. -Using `getStaticProps` fetches data at build time from a page, Next.js will pre-render this page at build time. +By using `getStaticProps` Next.js will fetch data at build time from a page, and pre-render the page to static assets. ## Deploy your own @@ -13,8 +13,6 @@ Deploy the example using [Vercel](https://vercel.com): ## How to use -### Using `create-next-app` - Execute [`create-next-app`](https://github.com/vercel/next.js/tree/canary/packages/create-next-app) with [npm](https://docs.npmjs.com/cli/init) or [Yarn](https://yarnpkg.com/lang/en/docs/cli/create/) to bootstrap the example: ```bash @@ -23,23 +21,4 @@ npx create-next-app --example data-fetch data-fetch-app yarn create next-app --example data-fetch data-fetch-app ``` -### Download manually - -Download the example: - -```bash -curl https://codeload.github.com/vercel/next.js/tar.gz/canary | tar -xz --strip=2 next.js-canary/examples/data-fetch -cd data-fetch -``` - -Install it and run: - -```bash -npm install -npm run dev -# or -yarn -yarn dev -``` - Deploy it to the cloud with [Vercel](https://vercel.com/import?filter=next.js&utm_source=github&utm_medium=readme&utm_campaign=next-example) ([Documentation](https://nextjs.org/docs/deployment)). diff --git a/examples/data-fetch/package.json b/examples/data-fetch/package.json index 55d94b79a3ea6..17aacdb9fe651 100644 --- a/examples/data-fetch/package.json +++ b/examples/data-fetch/package.json @@ -8,9 +8,8 @@ }, "dependencies": { "next": "latest", - "node-fetch": "^2.6.0", - "react": "^16.8.4", - "react-dom": "^16.8.4" + "react": "^16.13.1", + "react-dom": "^16.13.1" }, - "license": "ISC" + "license": "MIT" } diff --git a/examples/data-fetch/pages/index.js b/examples/data-fetch/pages/index.js index 90dc176afd3cd..d668c07e8fd6c 100644 --- a/examples/data-fetch/pages/index.js +++ b/examples/data-fetch/pages/index.js @@ -1,5 +1,4 @@ import Link from 'next/link' -import fetch from 'node-fetch' function Index({ stars }) { return ( diff --git a/examples/data-fetch/pages/preact-stars.js b/examples/data-fetch/pages/preact-stars.js index a8435ed70c3ff..0db33607dde37 100644 --- a/examples/data-fetch/pages/preact-stars.js +++ b/examples/data-fetch/pages/preact-stars.js @@ -1,5 +1,4 @@ import Link from 'next/link' -import fetch from 'node-fetch' function PreactStars({ stars }) { return (