Skip to content

Commit

Permalink
Documentation updates (vercel#16503)
Browse files Browse the repository at this point in the history
Fixes vercel#16502

Check the issue for more details.
  • Loading branch information
lfades authored Aug 24, 2020
1 parent c97e53e commit 333a9ea
Show file tree
Hide file tree
Showing 14 changed files with 28 additions and 59 deletions.
2 changes: 2 additions & 0 deletions docs/advanced-features/custom-error-page.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
13 changes: 7 additions & 6 deletions docs/advanced-features/static-html-export.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -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

Expand All @@ -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.
2 changes: 1 addition & 1 deletion docs/api-reference/cli.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
12 changes: 2 additions & 10 deletions docs/api-reference/data-fetching/getInitialProps.md
Original file line number Diff line number Diff line change
Expand Up @@ -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):
<details>
<summary><b>Examples</b></summary>
<ul>
<li><a href="https://github.com/vercel/next.js/tree/canary/examples/data-fetch">Data fetch</a></li>
</ul>
</details>
> 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).

Expand Down
2 changes: 1 addition & 1 deletion docs/api-reference/next.config.js/environment-variables.md
Original file line number Diff line number Diff line change
Expand Up @@ -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!
<details>
<summary><b>Examples</b></summary>
Expand Down
5 changes: 2 additions & 3 deletions docs/api-routes/dynamic-api-routes.md
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand All @@ -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

Expand Down
7 changes: 4 additions & 3 deletions docs/api-routes/introduction.md
Original file line number Diff line number Diff line change
Expand Up @@ -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:

Expand Down Expand Up @@ -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

Expand Down
2 changes: 1 addition & 1 deletion docs/basic-features/supported-browsers-features.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 `<App>`](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 `<App>`](/docs/advanced-features/custom-app.md) or the individual component.

## JavaScript Language Features

Expand Down
4 changes: 1 addition & 3 deletions docs/deployment.md
Original file line number Diff line number Diff line change
Expand Up @@ -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).
4 changes: 2 additions & 2 deletions docs/faq.md
Original file line number Diff line number Diff line change
Expand Up @@ -74,6 +74,6 @@ description: Get to know more about Next.js with the frequently asked questions.
</details>

<details>
<summary>Can I make a Next.js Progressive Web App?</summary>
<p>Yes! Here's an <a href="https://github.com/vercel/next.js/tree/canary/examples/progressive-web-app">example</a>.</p>
<summary>Can I make a Next.js Progressive Web App (PWA)?</summary>
<p>Yes! Check out our <a href="https://github.com/vercel/next.js/tree/canary/examples/progressive-web-app">PWA Example</a> to see how it works.</p>
</details>
25 changes: 2 additions & 23 deletions examples/data-fetch/README.md
Original file line number Diff line number Diff line change
@@ -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

Expand All @@ -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
Expand All @@ -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)).
7 changes: 3 additions & 4 deletions examples/data-fetch/package.json
Original file line number Diff line number Diff line change
Expand Up @@ -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"
}
1 change: 0 additions & 1 deletion examples/data-fetch/pages/index.js
Original file line number Diff line number Diff line change
@@ -1,5 +1,4 @@
import Link from 'next/link'
import fetch from 'node-fetch'

function Index({ stars }) {
return (
Expand Down
1 change: 0 additions & 1 deletion examples/data-fetch/pages/preact-stars.js
Original file line number Diff line number Diff line change
@@ -1,5 +1,4 @@
import Link from 'next/link'
import fetch from 'node-fetch'

function PreactStars({ stars }) {
return (
Expand Down

0 comments on commit 333a9ea

Please sign in to comment.