Skip to content

Commit

Permalink
New docs (vercel#9301)
Browse files Browse the repository at this point in the history
* Added the docs from Notion

* Updated the links from notion to relative links

* Added a routes manifest to the docs

* Removed the <br> after examples toggle

* Use the name of the section instead of Introduction

* Fixed spelling errors

* Optimize the content for Algolia

* Add a paragraph for `pageProps`

* Add welcome section

* Transpile -> Compile

* Update getting-started.md

* Update getting-started.md

* Update getting-started.md

* Update getting-started.md

* Update getting-started.md

* Update getting-started.md

* Update getting-started.md

* Update getting-started.md

* Update getting-started.md

* Update getting-started.md

* Test extra room between

* Update getting-started.md

* Update getting-started.md

* Update getting-started.md

* Update getting-started.md

* Update getting-started.md

* Update manifest.json

* Update getting-started.md

* Update getting-started.md

* Add concepts section

* Update pages.md

* Update pages.md

* Add data fetching section

* Update pages.md

* See how a card looks like

* Undo card changes

* Added related section to getting-started

* Fixed wrong markdown syntax in the withRouter page

* Moved the server-side-and-client-side section

* Updated next-cli reference

* updated getInitialProps section

* Minor fixes

* Added more Related sections

* Add html to the related section in getting-started

* Use small for the card

* Use cards for all related sections

* Added src directory docs

* Added src directory to the manifest

* Add note about API routes in next export

* Add initial data fetching docs (private until new methods are released)

* Fix typos

* Improve wording

* Update getting-started.md

* Update getting-started.md

* Move advanced concepts to advanced section

* Hide server-side vs client-side

* Move AMP support

* Move typescript into one page

* Add routing concepts page

* Remove introduction page

* Update section on different route types

* Update routing.md

* Update routing.md

* Update routing.md

* Update routing.md

* Combine router injection pages

* Update pages.md

* Update routing.md

* Update using-link.md

* Update using-link.md

* Update typescript.md

* Move the API Routes typescript to basic features

* Added links to the typescript section

* Updated links to useRouter and withRouter

* Add singleLevel prop to manifest

* Added single page for router docs

* Updated description

* Updated the routes in the manifest

* Add data fetching section

* Update data-fetching.md

* Update data-fetching.md

* Update dynamic-routes.md

* Update manifest.json

* Only use the single router API page

* Moved the concepts pages

* Updated links

* Removed extra space

* Updated title for Router API

* Added a description with frontmatter

* Add open prop to the manifest

* Added datafetching section to API Reference

* Updated links to the getInitialProps reference

* Moved some sections to API

* Added next/head to API reference

* Added next/link to the API Reference

* Removed the populating-head section

* Updated links to the new next/link API

* Added link from dynamic-routes to next/link docs

* use a paragraph

* Added next/router API

* Added next/amp

* Updated the docs for next/amp

* Moved the AMP support folder

* Updated title

* Content updates

* Added more links to the data fetching section

* Added links from the API to introductions

* changing the router API

* Updates to the router API

* Updated the routing section

* life improvements

* Added shallow routing section

* Small fix

* Removed old routing sections

* Updated link to shallow routing

* Removed unrequired page

* Removed /pages

* Update data-fetching.md

* Add initial deployments section

* Update manifest.json

* Update introduction.md

* Update deployment doc

* Add static export section updates

* link ssg/ssr

* Update deployment.md

* Add syntax highlighting

Co-authored-by: Tim Neutkens <[email protected]>
  • Loading branch information
Luis Alvarez D and timneutkens committed Dec 23, 2019
1 parent b95228e commit e346561
Show file tree
Hide file tree
Showing 56 changed files with 3,450 additions and 0 deletions.
40 changes: 40 additions & 0 deletions docs/advanced-features/amp-support/adding-amp-components.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,40 @@
# Adding AMP Components

The AMP community provide [many components](https://amp.dev/documentation/components/) to make AMP pages more interactive. You can add these components to your page by using `next/head`, as in the following example:

```jsx
import Head from 'next/head'

export const config = { amp: true }

function MyAmpPage() {
const date = new Date()

return (
<div>
<Head>
<script
async
key="amp-timeago"
custom-element="amp-timeago"
src="https://cdn.ampproject.org/v0/amp-timeago-0.1.js"
/>
</Head>

<p>Some time: {date.toJSON()}</p>
<amp-timeago
width="0"
height="15"
datetime={date.toJSON()}
layout="responsive"
>
.
</amp-timeago>
</div>
)
}

export default MyAmpPage
```

The above example uses the [`amp-timeago`](https://amp.dev/documentation/components/amp-timeago/?format=websites) component.
29 changes: 29 additions & 0 deletions docs/advanced-features/amp-support/amp-in-static-html-export.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,29 @@
# AMP in Static HTML export

When using `next export` to do [Static HTML export](/docs/advanced-features/static-html-export.md) statically prerender pages, Next.js will detect if the page supports AMP and change the exporting behavior based on that.

For example, the hybrid AMP page `pages/about.js` would output:

- `out/about.html` - HTML page with client-side React runtime
- `out/about.amp.html` - AMP page

And if `pages/about.js` is an AMP-only page, then it would output:

- `out/about.html` - Optimized AMP page

Next.js will automatically insert a link to the AMP version of your page in the HTML version, so you don't have to, like so:

```jsx
<link rel="amphtml" href="/about.amp.html" />
```

And the AMP version of your page will include a link to the HTML page:

```jsx
<link rel="canonical" href="/about" />
```

When [`exportTrailingSlash`](/docs/api-reference/next.config.js/exportPathMap.md#0cf7d6666b394c5d8d08a16a933e86ea) is enabled the exported pages for `pages/about.js` would be:

- `out/about/index.html` - HTML page
- `out/about.amp/index.html` - AMP page
5 changes: 5 additions & 0 deletions docs/advanced-features/amp-support/amp-validation.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
# AMP Validation

AMP pages are automatically validated with [amphtml-validator](https://www.npmjs.com/package/amphtml-validator) during development. Errors and warnings will appear in the terminal where you started Next.js.

Pages are also validated during [Static HTML export](/docs/advanced-features/static-html-export.md) and any warnings / errors will be printed to the terminal. Any AMP errors will cause the export to exit with status code `1` because the export is not valid AMP.
36 changes: 36 additions & 0 deletions docs/advanced-features/amp-support/introduction.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,36 @@
# AMP Support

<details>
<summary><b>Examples</b></summary>
<ul>
<li><a href="https://github.com/zeit/next.js/tree/canary/examples/amp">AMP</a></li>
</ul>
</details>

AMP means "_Accelerated Mobile Pages_", and it's, in short words: A faster HTML.

With Next.js you can turn any React page into an AMP page, with minimal config, and without leaving React.

You can read more about AMP in the official [amp.dev](https://amp.dev/) site.

## Enabling AMP

To enable AMP support for a page, and to learn more about the different AMP configs, read the [API documentation for `next/amp`](/docs/api-reference/next/amp.md).

## Related

For more information on what to do next, we recommend the following sections:

<div class="card">
<a href="/docs/advanced-features/amp-support/adding-amp-components.md">
<b>AMP Components:</b>
<small>Make your pages more interactive with AMP components.</small>
</a>
</div>

<div class="card">
<a href="/docs/advanced-features/amp-support/amp-validation.md">
<b>AMP Validation:</b>
<small>Learn about how Next.js validates AMP pages.</small>
</a>
</div>
5 changes: 5 additions & 0 deletions docs/advanced-features/amp-support/typescript.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
# TypeScript

AMP currently doesn't have built-in types for TypeScript, but it's in their roadmap ([#13791](https://github.com/ampproject/amphtml/issues/13791)).

As a workaround you can manually create a file called `amp.d.ts` inside your project and add the custom types described [here](https://stackoverflow.com/a/50601125).
34 changes: 34 additions & 0 deletions docs/advanced-features/automatic-static-optimization.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,34 @@
# Automatic Static Optimization

Next.js automatically determines that a page is static (can be prerendered) if it has no blocking data requirements. This determination is made by the absence of `getInitialProps` in the page.

This feature allows Next.js to emit hybrid applications that contain **both server-rendered and statically generated pages**.

> Statically generated pages are still reactive: Next.js will hydrate your application client-side to give it full interactivity.
One of the main benefits this feature is that optimized pages require no server-side computation, and can be instantly streamed to the end-user from multiple CDN locations. The result is an _ultra fast_ loading experience for your users.

## How it works

If `getInitialProps` is present, Next.js will use its default behavior and render the page on-demand, per-request (meaning Server-Side Rendering).

If `getInitialProps` is absent, Next.js will **statically optimize** your page automatically by prerendering the page to static HTML. During prerendering, the router's `query` object will be empty since we do not have `query` information to provide during this phase. Any `query` values will be populated client-side after hydration.

`next build` will emit `.html` files for statically optimized pages. For example, the result for the page `pages/about.js` would be:

```bash
.next/server/static/${BUILD_ID}/about.html
```

And if you add `getInitialProps` to the page, it will then be JavaScript, like so:

```bash
.next/server/static/${BUILD_ID}/about.js
```

In development you'll know if `pages/about.js` is optimized or not thanks to the included [static optimization indicator](/docs/api-reference/next.config.js/static-optimization-indicator.md).

## Caveats

- If you have a [custom `App`](/docs/advanced-features/custom-app.md) with `getInitialProps` then this optimization will be disabled for all pages.
- If you have a [custom `Document`](/docs/advanced-features/custom-document.md) with `getInitialProps` be sure you check if `ctx.req` is defined before assuming the page is server-side rendered. `ctx.req` will be `undefined` for pages that are prerendered.
54 changes: 54 additions & 0 deletions docs/advanced-features/custom-app.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,54 @@
# Custom `App`

Next.js uses the `App` component to initialize pages. You can override it and control the page initialization. Which allows you to do amazing things like:

- Persisting layout between page changes
- Keeping state when navigating pages
- Custom error handling using `componentDidCatch`
- Inject additional data into pages

To override the default `App`, create the file `./pages/_app.js` as shown below:

```jsx
function MyApp({ Component, pageProps }) {
return <Component {...pageProps} />
}

// Only uncomment this method if you have blocking data requirements for
// every single page in your application. This disables the ability to
// perform automatic static optimization, causing every page in your app to
// be server-side rendered.
//
// MyApp.getInitialProps = async (appContext) => {
// // calls page's `getInitialProps` and fills `appProps.pageProps`
// const appProps = await App.getInitialProps(appContext);
//
// return { ...appProps }
// }

export default MyApp
```

The `Component` prop is the active `page`, so whenever you navigate between routes, `Component` will change to the new `page`. Therefore, any props you send to `Component` will be received by the `page`.

`pageProps` is an object with the initial props that were preloaded for your page, it's an empty object if the page is not using [`getInitialProps`](/docs/api-reference/data-fetching/getInitialProps.md).

> Adding a custom `getInitialProps` in your `App` will disable [Automatic Static Optimization](/docs/advanced-features/automatic-static-optimization.md).
## Related

For more information on what to do next, we recommend the following sections:

<div class="card">
<a href="/docs/advanced-features/automatic-static-optimization.md">
<b>Automatic Static Optimization:</b>
<small>Learn more about how Next.js automatically optimizes your pages.</small>
</a>
</div>

<div class="card">
<a href="/docs/advanced-features/custom-error-page.md">
<b>Custom Error Page:</b>
<small>Learn more about the built-in Error page.</small>
</a>
</div>
3 changes: 3 additions & 0 deletions docs/advanced-features/custom-configuration.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
# Custom Configuration

Next.js can be enhanced with the usage of `next.config.js`. To learn more about it please refer to the [`next.config.js` documentation](/docs/api-reference/next.config.js/introduction.md).
76 changes: 76 additions & 0 deletions docs/advanced-features/custom-document.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,76 @@
# Custom `Document`

A custom `Document` is commonly used to augment your application's `<html>` and `<body>` tags. This is necessary because Next.js pages skip the definition of the surrounding document's markup.

A custom `Document` can also include `getInitialProps` for expressing asynchronous server-rendering data requirements.

To override the default `Document`, create the file `./pages/_document.js` and extend the `Document` class as shown below:

```jsx
import Document, { Html, Head, Main, NextScript } from 'next/document'

class MyDocument extends Document {
static async getInitialProps(ctx) {
const initialProps = await Document.getInitialProps(ctx)
return { ...initialProps }
}

render() {
return (
<Html>
<Head />
<body>
<Main />
<NextScript />
</body>
</Html>
)
}
}

export default MyDocument
```

`<Html>`, `<Head />`, `<Main />` and `<NextScript />` are required for the page to be properly rendered.

The `ctx` object is equivalent to the one received in [`getInitialProps`](/docs/api-reference/data-fetching/getInitialProps.md#context-object), with one addition:

- `renderPage`: `Function` - a callback that executes the actual React rendering logic (synchronously). It's useful to decorate this function in order to support server-rendering wrappers like Aphrodite's [`renderStatic`](https://github.com/Khan/aphrodite#server-side-rendering)

## Caveats

- `Document` is only rendered in the server, event handlers like `onClick` won't work
- React components outside of `<Main />` will not be initialized by the browser. Do _not_ add application logic here. If you need shared components in all your pages (like a menu or a toolbar), take a look at the [`App`](/docs/advanced-features/custom-app.md) component instead
- `Document`'s `getInitialProps` function is not called during client-side transitions, nor when a page is [statically optimized](/docs/advanced-features/automatic-static-optimization.md)
- Make sure to check if `ctx.req` / `ctx.res` are defined in `getInitialProps`. Those variables will be `undefined` when a page is being statically exported by [Automatic Static Optimization](/docs/advanced-features/automatic-static-optimization.md) or by [`next export`](/docs/advanced-features/static-html-export.md)

## Customizing `renderPage`

> It should be noted that the only reason you should be customizing `renderPage` is for usage with **css-in-js** libraries that need to wrap the application to properly work with server-side rendering.
It takes as argument an options object for further customization:

```jsx
import Document from 'next/document'

class MyDocument extends Document {
static async getInitialProps(ctx) {
const originalRenderPage = ctx.renderPage

ctx.renderPage = () =>
originalRenderPage({
// useful for wrapping the whole react tree
enhanceApp: App => App,
// useful for wrapping in a per-page basis
enhanceComponent: Component => Component,
})

// Run the parent `getInitialProps`, it now includes the custom `renderPage`
const initialProps = await Document.getInitialProps(ctx)

return initialProps
}
}

export default MyDocument
```
53 changes: 53 additions & 0 deletions docs/advanced-features/custom-error-page.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,53 @@
# Custom Error Page

**404** or **500** errors are handled both client-side and server-side by the `Error` component. If you wish to override it, define the file `pages/_error.js` and add the following code:

```jsx
function Error({ statusCode }) {
return (
<p>
{statusCode
? `An error ${statusCode} occurred on server`
: 'An error occurred on client'}
</p>
)
}

Error.getInitialProps = ({ res, err }) => {
const statusCode = res ? res.statusCode : err ? err.statusCode : 404
return { statusCode }
}

export default Error
```

> `pages/_error.js` is only used in production. In development you'll get an error with the call stack to know where the error originated from.
## Reusing the built-in error page

If you want to render the built-in error page you can by importing the `Error` component:

```jsx
import Error from 'next/error'
import fetch from 'isomorphic-unfetch'

const Page = ({ errorCode, stars }) => {
if (errorCode) {
return <Error statusCode={errorCode} />
}

return <div>Next stars: {stars}</div>
}

Page.getInitialProps = async () => {
const res = await fetch('https://api.github.com/repos/zeit/next.js')
const errorCode = res.statusCode > 200 ? res.statusCode : false
const json = await res.json()

return { errorCode, stars: json.stargazers_count }
}

export default Page
```

The `Error` component also takes `title` as a property if you want to pass in a text message along with a `statusCode`.
Loading

0 comments on commit e346561

Please sign in to comment.