From b13892e0070993e4d014a70f6b424302fe583635 Mon Sep 17 00:00:00 2001
From: Shu Uesugi <shu@chibicode.com>
Date: Fri, 6 Mar 2020 03:12:46 -0800
Subject: [PATCH] Add TypeScript docs for SSG (#10865)

* Add TypeScript docs

* Fix types
---
 .../data-fetching/getInitialProps.md          | 54 +++++++++++++++++++
 docs/basic-features/data-fetching.md          | 36 +++++++++++++
 docs/basic-features/typescript.md             | 48 +++++------------
 3 files changed, 102 insertions(+), 36 deletions(-)

diff --git a/docs/api-reference/data-fetching/getInitialProps.md b/docs/api-reference/data-fetching/getInitialProps.md
index 710bdc772596515..0ef43956d60711b 100644
--- a/docs/api-reference/data-fetching/getInitialProps.md
+++ b/docs/api-reference/data-fetching/getInitialProps.md
@@ -4,6 +4,14 @@ description: Enable Server-Side Rendering in a page and do initial data populati
 
 # getInitialProps
 
+## Recommended: Use `getStaticProps` or `getServerSideProps` instead
+
+If you're using Next.js 9.3 or newer, you should use `getStaticProps` or `getServerSideProps` instead of `getInitialProps`.
+
+Learn more on the [Pages documentation](/docs/basic-features/pages.md) and the [Data fetching documentation](/docs/basic-features/data-fetching.md):
+
+## `getInitialProps` (for older versions of Next.js)
+
 <details>
   <summary><b>Examples</b></summary>
   <ul>
@@ -76,6 +84,52 @@ For the initial page load, `getInitialProps` will execute on the server only. `g
 - `getInitialProps` can **not** be used in children components, only in the default export of every page
 - If you are using server-side only modules inside `getInitialProps`, make sure to [import them properly](https://arunoda.me/blog/ssr-and-server-only-modules), otherwise it'll slow down your app
 
+## TypeScript
+
+If you're using TypeScript, you can use the `NextPage` type for functional components:
+
+```jsx
+import { NextPage } from 'next'
+
+interface Props {
+  userAgent?: string;
+}
+
+const Page: NextPage<Props> = ({ userAgent }) => (
+  <main>Your user agent: {userAgent}</main>
+)
+
+Page.getInitialProps = async ({ req }) => {
+  const userAgent = req ? req.headers['user-agent'] : navigator.userAgent
+  return { userAgent }
+}
+
+export default Page
+```
+
+And for `React.Component`, you can use `NextPageContext`:
+
+```jsx
+import React from 'react'
+import { NextPageContext } from 'next'
+
+interface Props {
+  userAgent?: string;
+}
+
+export default class Page extends React.Component<Props> {
+  static async getInitialProps({ req }: NextPageContext) {
+    const userAgent = req ? req.headers['user-agent'] : navigator.userAgent
+    return { userAgent }
+  }
+
+  render() {
+    const { userAgent } = this.props
+    return <main>Your user agent: {userAgent}</main>
+  }
+}
+```
+
 ## Related
 
 For more information on what to do next, we recommend the following sections:
diff --git a/docs/basic-features/data-fetching.md b/docs/basic-features/data-fetching.md
index b6e71809895f664..3dc2d1585c4db07 100644
--- a/docs/basic-features/data-fetching.md
+++ b/docs/basic-features/data-fetching.md
@@ -82,6 +82,18 @@ You should use `getStaticProps` if:
 - The data can be publicly cached (not user-specific).
 - The page must be pre-rendered (for SEO) and be very fast — `getStaticProps` generates HTML and JSON files, both of which can be cached by a CDN for performance.
 
+### TypeScript: Use `GetStaticProps`
+
+For TypeScript, you can use the `GetStaticProps` type from `next`:
+
+```ts
+import { GetStaticProps } from 'next'
+
+export const getStaticProps: GetStaticProps = async context => {
+  // ...
+}
+```
+
 ### Technical details
 
 #### Only runs at build time
@@ -273,6 +285,18 @@ This ensures that users always have a fast experience while preserving fast buil
 
 You should use `getStaticPaths` if you’re statically pre-rendering pages that use dynamic routes.
 
+### TypeScript: Use `GetStaticPaths`
+
+For TypeScript, you can use the `GetStaticPaths` type from `next`:
+
+```ts
+import { GetStaticPaths } from 'next'
+
+export const getStaticPaths: GetStaticPaths = async () => {
+  // ...
+}
+```
+
 ### Technical details
 
 #### Use together with `getStaticProps`
@@ -344,6 +368,18 @@ You should use `getServerSideProps` only if you need to pre-render a page whose
 
 If you don’t need to pre-render the data, then you should consider fetching data on the client side. [Click here to learn more](#fetching-data-on-the-client-side).
 
+### TypeScript: Use `GetServerSideProps`
+
+For TypeScript, you can use the `GetServerSideProps` type from `next`:
+
+```ts
+import { GetServerSideProps } from 'next'
+
+export const getServerSideProps: GetServerSideProps = async context => {
+  // ...
+}
+```
+
 ### Technical details
 
 #### Only runs on server-side
diff --git a/docs/basic-features/typescript.md b/docs/basic-features/typescript.md
index 6abba785392c211..17269a8f816a553 100644
--- a/docs/basic-features/typescript.md
+++ b/docs/basic-features/typescript.md
@@ -47,52 +47,28 @@ By default, Next.js reports TypeScript errors during development for pages you a
 
 If you want to silence the error reports, refer to the documentation for [Ignoring TypeScript errors](/docs/api-reference/next.config.js/ignoring-typescript-errors.md).
 
-## Pages
+## Static Generation and Server-side Rendering
 
-For function components the `NextPage` type is exported, here's how to use it:
+For `getStaticProps`, `getStaticPaths`, and `getServerSideProps`, you can use the `GetStaticProps`, `GetStaticPaths`, and `GetServerSideProps` types respectively:
 
-```jsx
-import { NextPage } from 'next'
-
-interface Props {
-  userAgent?: string;
-}
-
-const Page: NextPage<Props> = ({ userAgent }) => (
-  <main>Your user agent: {userAgent}</main>
-)
+```ts
+import { GetStaticProps, GetStaticPaths, GetServerSideProps } from 'next'
 
-Page.getInitialProps = async ({ req }) => {
-  const userAgent = req ? req.headers['user-agent'] : navigator.userAgent
-  return { userAgent }
+export const getStaticProps: GetStaticProps = async context => {
+  // ...
 }
 
-export default Page
-```
-
-And for `React.Component` you can use `NextPageContext`:
-
-```jsx
-import React from 'react'
-import { NextPageContext } from 'next'
-
-interface Props {
-  userAgent?: string;
+export const getStaticPaths: GetStaticPaths = async () => {
+  // ...
 }
 
-export default class Page extends React.Component<Props> {
-  static async getInitialProps({ req }: NextPageContext) {
-    const userAgent = req ? req.headers['user-agent'] : navigator.userAgent
-    return { userAgent }
-  }
-
-  render() {
-    const { userAgent } = this.props
-    return <main>Your user agent: {userAgent}</main>
-  }
+export const getServerSideProps: GetServerSideProps = async context => {
+  // ...
 }
 ```
 
+> If you're using `getInitialProps`, you can [follow the directions on this page](/docs/api-reference/data-fetching/getInitialProps.md#typescript).
+
 ## API Routes
 
 The following is an example of how to use the built-in types for API routes: