vercel · timneutkens · Dec 23, 2019 · Nov 2, 2019 · Nov 4, 2019 · Nov 4, 2019
@@ -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.
@@ -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
@@ -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.
@@ -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>
@@ -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).
@@ -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.
@@ -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>
@@ -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).
@@ -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
+```
@@ -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`.