From b8ee56bfbc867b06241b444269334101c7f581dd Mon Sep 17 00:00:00 2001 From: Lee Robinson Date: Wed, 30 Sep 2020 13:09:50 -0500 Subject: [PATCH 01/25] Add docs on how to migrate from Gatsby. --- docs/manifest.json | 9 ++ docs/migrating/from-gatsby.md | 218 ++++++++++++++++++++++++++++++++++ 2 files changed, 227 insertions(+) create mode 100644 docs/migrating/from-gatsby.md diff --git a/docs/manifest.json b/docs/manifest.json index 0fedfb30c20b17a..a624aaae2035509 100644 --- a/docs/manifest.json +++ b/docs/manifest.json @@ -187,6 +187,15 @@ "title": "Upgrade Guide", "path": "/docs/upgrading.md" }, + { + "title": "Migrating", + "routes": [ + { + "title": "Migrating from Gatsby", + "path": "/docs/migrating/from-gatsby.md" + } + ] + }, { "title": "FAQ", "path": "/docs/faq.md" } ] }, diff --git a/docs/migrating/from-gatsby.md b/docs/migrating/from-gatsby.md new file mode 100644 index 000000000000000..140b774e0126a03 --- /dev/null +++ b/docs/migrating/from-gatsby.md @@ -0,0 +1,218 @@ +--- +description: Learn how to transition an existing Gatsby project to Next.js. +--- + +# Migrating from Gatsby + +This guide will help you understand how to transition from an existing Gatsby project to Next.js. Since both frameworks are built on top of React and share similar ideas, the transition can be broken down into a series of steps. First, let's talk about running the application. + +## Local Development + +Gatsby applications start using `gatsby develop` and run at `localhost:8000`. To create and start a production build, you run `gatsby build && gatsby serve`. Your compiled code is located at `public`. + +Next applications start using `next` (typically scripted as `yarn dev`) and run at `localhost:3000`. To create a start a production build, run `next build && next start`. Your compiled code is located at `.next`. You are free to change `package.json` script names as you like. + +The first step towards migrating to Next.js is to uninstall all related Gatsby packages and install `next`. Do not remove `react` or `react-dom` from your `package.json`. + +```bash +yarn add next +``` + +## Serving Files + +The `public` folder holds static assets in Next, instead of containing the compiled output. Update your `.gitignore` file to ensure `public` is tracked with source control and delete your existing Gatsby output. You can now move files from Gatsby's `static` folder to `public`. + +## Creating Routes + +Both Gatsby and Next support a `pages` folder, which uses [file-system based routing](/docs/routing/introduction). Gatsby's directory is `src/pages`, while Next can support `pages` with or without [src](/docs/advanced-features/src-directory). + +Gatsby creates dynamic routes using the `createPages` API inside of `gatsby-node.js`. With Next, we can use [Dynamic Routes](/docs/routing/dynamic-routes) inside of `pages` to achieve the same effect. Rather than having a `template` folder, you can use the React component inside your dynamic route file. For example: + +- **Gatsby:** `createPages` API inside `gatsby-node.js` for each blog post, then have a template file at `src/templates/blog-post.js`. +- **Next:** Create `pages/blog/[slug].js` which contains the blog post template. The value of `slug` is accessible through a [query parameter](/docs/routing/dynamic-routes). For example, the route `/blog/first-post` would forward the query object `{ 'slug': 'first-post' }` to `pages/blog/[slug].js`. + +## Styling + +With Gatsby, global CSS imports and included in `gatsby-browser.js`. With Next, you should create a [custom `_app.js`](/docs/advanced-features/custom-app) for global CSS. When migrating, you can copy your CSS imports over directly and update the relative file path, if necessary. Next.js has [built-in CSS support](/docs/basic-features/built-in-css-support). + +## Links + +The Gatsby `Link` and Next.js [`Link`](/docs/api-reference/next/link>) component have a slightly different API. First, you will need to update any import statements referencing `Link` from Gatsby to: + +```js +import Link from 'next/link' +``` + +Next, you can find and replace usages of `to="/route"` with `href="/route"`. + +## Data Fetching + +The largest difference between Gatsby and Next.js is how data fetching is implemented. Gatsby is opinionated with GraphQL being the default strategy for retrieving data across your application. With Next.js, you get to choose which strategy you want (GraphQL is one supported option). + +Gatsby pages have a `pageQuery` export that will make a GraphQL request and forward the information to the React component. This may include local data, remote data, and information about the site configuration. Gatsby only allows the creation of static pages. With Next.js, you can choose on a [per-page basis](/docs/basic-features/pages) which [data fetching strategy](/docs/basic-features/data-fetching) you want. For example, if you want to generate a static site, you'd export `getStaticProps` / `getStaticPaths` inside the page rather than using `pageQuery`. For example: + +```js +import { getPostBySlug, getAllPosts } from '../lib/blog' + +export async function getStaticProps({ params }) { + const post = getPostBySlug(params.slug) + + return { + props: { + ...post, + }, + } +} + +export async function getStaticPaths() { + const posts = getAllPosts() + + return { + paths: posts.map((post) => { + return { + params: { + slug: post.slug, + }, + } + }), + fallback: false, + } +} +``` + +You'll commonly see Gatsby plugins used for reading the file system (`gatsby-source-filesystem`), handling markdown files (`gatsby-transformer-remark`), and so on. For example, the popular starter blog example has [15 Gatsby specific packages](https://github.com/gatsbyjs/gatsby-starter-blog/blob/master/package.json). Next takes a different approach. It includes common features like [image optimization](https://github.com/vercel/next.js/discussions/17141) directly inside the framework, and gives the user full control over integrations with external packages. For example, rather than abstracting reading from the file system to a plugin, you can use the native Node.js `fs` package inside `getStaticProps` / `getStaticPaths` to read from the file system. + +```js +import fs from 'fs' +import { join } from 'path' +import matter from 'gray-matter' +import { parseISO, format } from 'date-fns' + +const postsDirectory = join(process.cwd(), 'content', 'blog') + +export function getPostBySlug(slug) { + const realSlug = slug.replace(/\\.md$/, '') + const fullPath = join(postsDirectory, `${realSlug}.md`) + const fileContents = fs.readFileSync(fullPath, 'utf8') + const { data, content } = matter(fileContents) + const date = format(parseISO(data.date), 'MMMM dd, yyyy') + + return { slug: realSlug, frontmatter: { ...data, date }, content } +} + +export function getAllPosts() { + const slugs = fs.readdirSync(postsDirectory) + const posts = slugs.map((slug) => getPostBySlug(slug)) + + return posts +} +``` + +## Site Configuration + +With Gatsby, your site's metadata (name, description, etc) is located inside `gatsby-config.js`. This is then exposed through the GraphQL API and consumed through a `pageQuery` or a static query inside a component. + +With Next.js, we recommend creating a config file similar to below. You can then import this file anywhere without having to use GraphQL to access your site's metadata. + +```js +// src/config.js + +export default { + title: 'Starter Blog', + author: { + name: 'Lee Robinson', + summary: 'who loves Next.js.', + }, + description: 'A starter blog converting Gatsby -> Next.', + social: { + twitter: 'leeerob', + }, +} +``` + +## Search Engine Optimization + +Most Gatsby examples use `react-helmet` to assist with adding `meta` tags for proper SEO. With Next.js, we recommend using `[next/head]()` to add `meta` tags to your `` element. For example, here's part of an SEO component with Gatsby: + +```js +// src/components/seo.js + +import { Helmet } from 'react-helmet' + +return ( + +) +``` + +And here's the same example using Next.js, including reading from a site config file. + +```js +// src/components/seo.js + +import Head from 'next/head' +import config from '../config' + +const SEO = ({ description, title }) => { + const metaDescription = description || config.description + const siteTitle = config.title + + return ( + + {`${title} | ${siteTitle}`} + + + + + + + + + + + + ) +} + +export default SEO +``` + +## Conclusion + +React frameworks share many core pieces and make it easy to transition between each other. While the APIs and components may vary, the underlying ideas and implementation share similar roots and provide an easy path for migration. To view an example converting a Gatsby project to Next.js, review this [pull request](https://github.com/leerob/gatsby-to-nextjs/pull/1). From c3b648d1e8b573ad382bb165be77a271967bbdc0 Mon Sep 17 00:00:00 2001 From: Lee Robinson Date: Wed, 30 Sep 2020 16:04:12 -0500 Subject: [PATCH 02/25] Clarify gatsby GQL page exports. --- docs/migrating/from-gatsby.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/migrating/from-gatsby.md b/docs/migrating/from-gatsby.md index 140b774e0126a03..01e803fa5906ba0 100644 --- a/docs/migrating/from-gatsby.md +++ b/docs/migrating/from-gatsby.md @@ -49,7 +49,7 @@ Next, you can find and replace usages of `to="/route"` with `href="/route"`. The largest difference between Gatsby and Next.js is how data fetching is implemented. Gatsby is opinionated with GraphQL being the default strategy for retrieving data across your application. With Next.js, you get to choose which strategy you want (GraphQL is one supported option). -Gatsby pages have a `pageQuery` export that will make a GraphQL request and forward the information to the React component. This may include local data, remote data, and information about the site configuration. Gatsby only allows the creation of static pages. With Next.js, you can choose on a [per-page basis](/docs/basic-features/pages) which [data fetching strategy](/docs/basic-features/data-fetching) you want. For example, if you want to generate a static site, you'd export `getStaticProps` / `getStaticPaths` inside the page rather than using `pageQuery`. For example: +Gatsby uses the `graphql` tag to query data in the pages of your site. This may include local data, remote data, or information about your site configuration. Gatsby only allows the creation of static pages. With Next.js, you can choose on a [per-page basis](/docs/basic-features/pages) which [data fetching strategy](/docs/basic-features/data-fetching) you want. For example, `getServerSideProps` allows you to do server-side rendering. If you wanted to generate a static site, you'd export `getStaticProps` / `getStaticPaths` inside the page, rather than using `pageQuery`. For example: ```js import { getPostBySlug, getAllPosts } from '../lib/blog' From 1f3f6719994c4e0e4183e092014adb1163ad9c5c Mon Sep 17 00:00:00 2001 From: Lee Robinson Date: Wed, 30 Sep 2020 16:22:24 -0500 Subject: [PATCH 03/25] Update docs/migrating/from-gatsby.md Co-authored-by: Joe Haddad --- docs/migrating/from-gatsby.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/migrating/from-gatsby.md b/docs/migrating/from-gatsby.md index 01e803fa5906ba0..3d5a51fca3975e9 100644 --- a/docs/migrating/from-gatsby.md +++ b/docs/migrating/from-gatsby.md @@ -10,7 +10,7 @@ This guide will help you understand how to transition from an existing Gatsby pr Gatsby applications start using `gatsby develop` and run at `localhost:8000`. To create and start a production build, you run `gatsby build && gatsby serve`. Your compiled code is located at `public`. -Next applications start using `next` (typically scripted as `yarn dev`) and run at `localhost:3000`. To create a start a production build, run `next build && next start`. Your compiled code is located at `.next`. You are free to change `package.json` script names as you like. +Next applications start using `next dev` and run at `localhost:3000`. To create a start a production build, run `next build && next start`. Your compiled code is located at `.next/`. The first step towards migrating to Next.js is to uninstall all related Gatsby packages and install `next`. Do not remove `react` or `react-dom` from your `package.json`. From 2f8cc37a1b842c70664a3ae6a123b919ebf178f1 Mon Sep 17 00:00:00 2001 From: Lee Robinson Date: Wed, 30 Sep 2020 16:22:39 -0500 Subject: [PATCH 04/25] Update docs/migrating/from-gatsby.md Co-authored-by: Joe Haddad --- docs/migrating/from-gatsby.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/migrating/from-gatsby.md b/docs/migrating/from-gatsby.md index 3d5a51fca3975e9..662e7fe3f864791 100644 --- a/docs/migrating/from-gatsby.md +++ b/docs/migrating/from-gatsby.md @@ -8,7 +8,7 @@ This guide will help you understand how to transition from an existing Gatsby pr ## Local Development -Gatsby applications start using `gatsby develop` and run at `localhost:8000`. To create and start a production build, you run `gatsby build && gatsby serve`. Your compiled code is located at `public`. +Gatsby applications start using `gatsby develop` and run at `localhost:8000`. To create and start a production build, you run `gatsby build && gatsby serve`. Your compiled code is located at `public/`. Next applications start using `next dev` and run at `localhost:3000`. To create a start a production build, run `next build && next start`. Your compiled code is located at `.next/`. From 0d72756f055a7f79966a295ef4e70435f5e3a221 Mon Sep 17 00:00:00 2001 From: Lee Robinson Date: Wed, 30 Sep 2020 16:22:54 -0500 Subject: [PATCH 05/25] Update docs/migrating/from-gatsby.md Co-authored-by: Joe Haddad --- docs/migrating/from-gatsby.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/migrating/from-gatsby.md b/docs/migrating/from-gatsby.md index 662e7fe3f864791..1b4027eff4ca167 100644 --- a/docs/migrating/from-gatsby.md +++ b/docs/migrating/from-gatsby.md @@ -20,7 +20,7 @@ yarn add next ## Serving Files -The `public` folder holds static assets in Next, instead of containing the compiled output. Update your `.gitignore` file to ensure `public` is tracked with source control and delete your existing Gatsby output. You can now move files from Gatsby's `static` folder to `public`. +The `public/` folder holds static assets in Next.js, instead of containing the compiled output. Update your `.gitignore` file to ensure `public/` is tracked in source control and delete your existing Gatsby output. You can now move files from Gatsby's `static/` folder to `public/`. ## Creating Routes From 2715d50595ff0ff56ecf11711b28f0da0d23ce7f Mon Sep 17 00:00:00 2001 From: Lee Robinson Date: Wed, 30 Sep 2020 16:23:17 -0500 Subject: [PATCH 06/25] Update docs/migrating/from-gatsby.md Co-authored-by: Joe Haddad --- docs/migrating/from-gatsby.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/migrating/from-gatsby.md b/docs/migrating/from-gatsby.md index 1b4027eff4ca167..fddcc345fede9a9 100644 --- a/docs/migrating/from-gatsby.md +++ b/docs/migrating/from-gatsby.md @@ -132,7 +132,7 @@ export default { ## Search Engine Optimization -Most Gatsby examples use `react-helmet` to assist with adding `meta` tags for proper SEO. With Next.js, we recommend using `[next/head]()` to add `meta` tags to your `` element. For example, here's part of an SEO component with Gatsby: +Most Gatsby examples use `react-helmet` to assist with adding `meta` tags for proper SEO. With Next.js, we recommend using [`next/head`]() to add `meta` tags to your `` element. For example, here's part of an SEO component with Gatsby: ```js // src/components/seo.js From 385f3cb0dea1f59edad51895ba6f1ec476947d2e Mon Sep 17 00:00:00 2001 From: Lee Robinson Date: Wed, 30 Sep 2020 16:28:29 -0500 Subject: [PATCH 07/25] Add package.json and remove /src confusion. --- docs/migrating/from-gatsby.md | 23 +++++++++++++++++------ 1 file changed, 17 insertions(+), 6 deletions(-) diff --git a/docs/migrating/from-gatsby.md b/docs/migrating/from-gatsby.md index fddcc345fede9a9..f5f2cacc0117cf0 100644 --- a/docs/migrating/from-gatsby.md +++ b/docs/migrating/from-gatsby.md @@ -12,10 +12,21 @@ Gatsby applications start using `gatsby develop` and run at `localhost:8000`. To Next applications start using `next dev` and run at `localhost:3000`. To create a start a production build, run `next build && next start`. Your compiled code is located at `.next/`. -The first step towards migrating to Next.js is to uninstall all related Gatsby packages and install `next`. Do not remove `react` or `react-dom` from your `package.json`. - -```bash -yarn add next +The first step towards migrating to Next.js is to uninstall all related Gatsby packages and install `next`. Do not remove `react` or `react-dom` from your `package.json`. Here's an example `package.json`: + +```json +{ + "scripts": { + "dev": "next", + "build": "next build", + "start": "next start" + }, + "dependencies": { + "next": "latest", + "react": "latest", + "react-dom": "latest" + } +} ``` ## Serving Files @@ -24,7 +35,7 @@ The `public/` folder holds static assets in Next.js, instead of containing the c ## Creating Routes -Both Gatsby and Next support a `pages` folder, which uses [file-system based routing](/docs/routing/introduction). Gatsby's directory is `src/pages`, while Next can support `pages` with or without [src](/docs/advanced-features/src-directory). +Both Gatsby and Next support a `pages` folder, which uses [file-system based routing](/docs/routing/introduction). Gatsby's directory is `src/pages`, which is also [supported by Next.js](/docs/advanced-features/src-directory). Gatsby creates dynamic routes using the `createPages` API inside of `gatsby-node.js`. With Next, we can use [Dynamic Routes](/docs/routing/dynamic-routes) inside of `pages` to achieve the same effect. Rather than having a `template` folder, you can use the React component inside your dynamic route file. For example: @@ -132,7 +143,7 @@ export default { ## Search Engine Optimization -Most Gatsby examples use `react-helmet` to assist with adding `meta` tags for proper SEO. With Next.js, we recommend using [`next/head`]() to add `meta` tags to your `` element. For example, here's part of an SEO component with Gatsby: +Most Gatsby examples use `react-helmet` to assist with adding `meta` tags for proper SEO. With Next.js, we recommend using [`next/head`](/docs/api-reference/next/head) to add `meta` tags to your `` element. For example, here's part of an SEO component with Gatsby: ```js // src/components/seo.js From 79c02c99208094cfe4b7d250ee0988def5b91ebb Mon Sep 17 00:00:00 2001 From: Lee Robinson Date: Wed, 30 Sep 2020 16:37:28 -0500 Subject: [PATCH 08/25] Add reasons to migrate. --- docs/migrating/from-gatsby.md | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/docs/migrating/from-gatsby.md b/docs/migrating/from-gatsby.md index f5f2cacc0117cf0..b623f77f2c95cb3 100644 --- a/docs/migrating/from-gatsby.md +++ b/docs/migrating/from-gatsby.md @@ -4,7 +4,13 @@ description: Learn how to transition an existing Gatsby project to Next.js. # Migrating from Gatsby -This guide will help you understand how to transition from an existing Gatsby project to Next.js. Since both frameworks are built on top of React and share similar ideas, the transition can be broken down into a series of steps. First, let's talk about running the application. +This guide will help you understand how to transition from an existing Gatsby project to Next.js. Since both frameworks are built on top of React, the transition can be broken down into a series of steps. Migrating to Next.js will allow you to: + +- Choose which [data fetching](/docs/basic-features/data-fetching) strategy you want on a per-page basis (instead of only SSG) +- Use [Incremental Static Regeneration](/docs/basic-features/data-fetching#incremental-static-regeneration) to update _existing_ pages by re-rendering them in the background as traffic comes in +- Use [API Routes](/docs/api-routes/introduction) + +And more! First, let's talk about running a Next.js application. ## Local Development From dd9ece59d076c15512661811b16e2596714df1be Mon Sep 17 00:00:00 2001 From: Lee Robinson Date: Thu, 1 Oct 2020 08:14:27 -0500 Subject: [PATCH 09/25] Update section title. --- docs/manifest.json | 2 +- docs/migrating/from-gatsby.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/manifest.json b/docs/manifest.json index a624aaae2035509..f18da6f2cd61522 100644 --- a/docs/manifest.json +++ b/docs/manifest.json @@ -188,7 +188,7 @@ "path": "/docs/upgrading.md" }, { - "title": "Migrating", + "title": "Migrating to Next.js", "routes": [ { "title": "Migrating from Gatsby", diff --git a/docs/migrating/from-gatsby.md b/docs/migrating/from-gatsby.md index b623f77f2c95cb3..6bdc2d2e65de1ab 100644 --- a/docs/migrating/from-gatsby.md +++ b/docs/migrating/from-gatsby.md @@ -6,7 +6,7 @@ description: Learn how to transition an existing Gatsby project to Next.js. This guide will help you understand how to transition from an existing Gatsby project to Next.js. Since both frameworks are built on top of React, the transition can be broken down into a series of steps. Migrating to Next.js will allow you to: -- Choose which [data fetching](/docs/basic-features/data-fetching) strategy you want on a per-page basis (instead of only SSG) +- Choose which [data fetching](/docs/basic-features/data-fetching) strategy you want on a per-page basis - Use [Incremental Static Regeneration](/docs/basic-features/data-fetching#incremental-static-regeneration) to update _existing_ pages by re-rendering them in the background as traffic comes in - Use [API Routes](/docs/api-routes/introduction) From f2fe6b3dda726ed1dbf72db31ec6a55bc2937ce2 Mon Sep 17 00:00:00 2001 From: Lee Robinson Date: Thu, 1 Oct 2020 08:22:53 -0500 Subject: [PATCH 10/25] Restructure paragraphs. --- docs/migrating/from-gatsby.md | 28 +++++++++++++++++----------- 1 file changed, 17 insertions(+), 11 deletions(-) diff --git a/docs/migrating/from-gatsby.md b/docs/migrating/from-gatsby.md index 6bdc2d2e65de1ab..ce8a5c43d2dfd8c 100644 --- a/docs/migrating/from-gatsby.md +++ b/docs/migrating/from-gatsby.md @@ -4,21 +4,23 @@ description: Learn how to transition an existing Gatsby project to Next.js. # Migrating from Gatsby -This guide will help you understand how to transition from an existing Gatsby project to Next.js. Since both frameworks are built on top of React, the transition can be broken down into a series of steps. Migrating to Next.js will allow you to: +This guide will help you understand how to transition from an existing Gatsby project to Next.js. Migrating to Next.js will allow you to: -- Choose which [data fetching](/docs/basic-features/data-fetching) strategy you want on a per-page basis -- Use [Incremental Static Regeneration](/docs/basic-features/data-fetching#incremental-static-regeneration) to update _existing_ pages by re-rendering them in the background as traffic comes in -- Use [API Routes](/docs/api-routes/introduction) +- Choose which [data fetching](/docs/basic-features/data-fetching.md) strategy you want on a per-page basis. +- Use [Incremental Static Regeneration](/docs/basic-features/data-fetching.md#incremental-static-regeneration) to update _existing_ pages by re-rendering them in the background as traffic comes in. +- Use [API Routes](/docs/api-routes/introduction.md). -And more! First, let's talk about running a Next.js application. +And more! Let’s walk through a series of steps to complete the migration. -## Local Development +## Updating `package.json` and dependencies -Gatsby applications start using `gatsby develop` and run at `localhost:8000`. To create and start a production build, you run `gatsby build && gatsby serve`. Your compiled code is located at `public/`. +The first step towards migrating to Next.js is to update `package.json` and dependencies. You should: -Next applications start using `next dev` and run at `localhost:3000`. To create a start a production build, run `next build && next start`. Your compiled code is located at `.next/`. +- Remove all Gatsby-related packages (but keep `react` and `react-dom`). +- Install `next`. +- Add Next.js related commands to `scripts`. One is `next dev`, which runs a development server at `localhost:3000`. You should also add `next build` and `next start` for creating and starting a production build. -The first step towards migrating to Next.js is to uninstall all related Gatsby packages and install `next`. Do not remove `react` or `react-dom` from your `package.json`. Here's an example `package.json`: +Here's an example `package.json` ([view diff](https://github.com/leerob/gatsby-to-nextjs/pull/1/files#diff-b9cfc7f2cdf78a7f4b91a753d10865a2)): ```json { @@ -35,9 +37,13 @@ The first step towards migrating to Next.js is to uninstall all related Gatsby p } ``` -## Serving Files +## Static Assets and Compiled Output -The `public/` folder holds static assets in Next.js, instead of containing the compiled output. Update your `.gitignore` file to ensure `public/` is tracked in source control and delete your existing Gatsby output. You can now move files from Gatsby's `static/` folder to `public/`. +Gatsby uses the `public` directory for the compiled output, whereas Next.js uses it for static assets. Here are the steps for migration ([view diff](https://github.com/leerob/gatsby-to-nextjs/pull/1/files#diff-a084b794bc0759e7a6b77810e01874f2)): + +- Remove `.cache/` and `public` from `.gitignore` and delete both directories. +- Rename Gatsby’s `static` directory as `public`. +- Add `.next` to `.gitignore`. ## Creating Routes From 0fc4f67b2e891e26a17bbc210dcf7bf5c1d151ae Mon Sep 17 00:00:00 2001 From: Lee Robinson Date: Thu, 1 Oct 2020 08:24:19 -0500 Subject: [PATCH 11/25] Update docs/migrating/from-gatsby.md Co-authored-by: Shu Uesugi --- docs/migrating/from-gatsby.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/migrating/from-gatsby.md b/docs/migrating/from-gatsby.md index ce8a5c43d2dfd8c..d396def696e8e5c 100644 --- a/docs/migrating/from-gatsby.md +++ b/docs/migrating/from-gatsby.md @@ -47,9 +47,9 @@ Gatsby uses the `public` directory for the compiled output, whereas Next.js uses ## Creating Routes -Both Gatsby and Next support a `pages` folder, which uses [file-system based routing](/docs/routing/introduction). Gatsby's directory is `src/pages`, which is also [supported by Next.js](/docs/advanced-features/src-directory). +Both Gatsby and Next support a `pages` directory, which uses [file-system based routing](/docs/routing/introduction.md). Gatsby's directory is `src/pages`, which is also [supported by Next.js](/docs/advanced-features/src-directory.md). -Gatsby creates dynamic routes using the `createPages` API inside of `gatsby-node.js`. With Next, we can use [Dynamic Routes](/docs/routing/dynamic-routes) inside of `pages` to achieve the same effect. Rather than having a `template` folder, you can use the React component inside your dynamic route file. For example: +Gatsby creates dynamic routes using the `createPages` API inside of `gatsby-node.js`. With Next, we can use [Dynamic Routes](/docs/routing/dynamic-routes.md) inside of `pages` to achieve the same effect. Rather than having a `template` directory, you can use the React component inside your dynamic route file. For example: - **Gatsby:** `createPages` API inside `gatsby-node.js` for each blog post, then have a template file at `src/templates/blog-post.js`. - **Next:** Create `pages/blog/[slug].js` which contains the blog post template. The value of `slug` is accessible through a [query parameter](/docs/routing/dynamic-routes). For example, the route `/blog/first-post` would forward the query object `{ 'slug': 'first-post' }` to `pages/blog/[slug].js`. From 0aba4db524df36fb776e9781f5417d2e67601901 Mon Sep 17 00:00:00 2001 From: Lee Robinson Date: Thu, 1 Oct 2020 08:24:48 -0500 Subject: [PATCH 12/25] Update docs/migrating/from-gatsby.md Co-authored-by: Shu Uesugi --- docs/migrating/from-gatsby.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/migrating/from-gatsby.md b/docs/migrating/from-gatsby.md index d396def696e8e5c..38fab6bc95ade3d 100644 --- a/docs/migrating/from-gatsby.md +++ b/docs/migrating/from-gatsby.md @@ -52,7 +52,7 @@ Both Gatsby and Next support a `pages` directory, which uses [file-system based Gatsby creates dynamic routes using the `createPages` API inside of `gatsby-node.js`. With Next, we can use [Dynamic Routes](/docs/routing/dynamic-routes.md) inside of `pages` to achieve the same effect. Rather than having a `template` directory, you can use the React component inside your dynamic route file. For example: - **Gatsby:** `createPages` API inside `gatsby-node.js` for each blog post, then have a template file at `src/templates/blog-post.js`. -- **Next:** Create `pages/blog/[slug].js` which contains the blog post template. The value of `slug` is accessible through a [query parameter](/docs/routing/dynamic-routes). For example, the route `/blog/first-post` would forward the query object `{ 'slug': 'first-post' }` to `pages/blog/[slug].js`. +- **Next:** Create `pages/blog/[slug].js` which contains the blog post template. The value of `slug` is accessible through a [query parameter](/docs/routing/dynamic-routes.md). For example, the route `/blog/first-post` would forward the query object `{ 'slug': 'first-post' }` to `pages/blog/[slug].js` ([learn more here](/docs/basic-features/data-fetching.md#getstaticpaths-static-generation`)). ## Styling From 2ed017263e1a6c85d6a367b11b427d2b3e883d73 Mon Sep 17 00:00:00 2001 From: Lee Robinson Date: Thu, 1 Oct 2020 08:25:12 -0500 Subject: [PATCH 13/25] Update docs/migrating/from-gatsby.md Co-authored-by: Shu Uesugi --- docs/migrating/from-gatsby.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/migrating/from-gatsby.md b/docs/migrating/from-gatsby.md index 38fab6bc95ade3d..b2898e31c4e5eba 100644 --- a/docs/migrating/from-gatsby.md +++ b/docs/migrating/from-gatsby.md @@ -56,7 +56,7 @@ Gatsby creates dynamic routes using the `createPages` API inside of `gatsby-node ## Styling -With Gatsby, global CSS imports and included in `gatsby-browser.js`. With Next, you should create a [custom `_app.js`](/docs/advanced-features/custom-app) for global CSS. When migrating, you can copy your CSS imports over directly and update the relative file path, if necessary. Next.js has [built-in CSS support](/docs/basic-features/built-in-css-support). +With Gatsby, global CSS imports are included in `gatsby-browser.js`. With Next, you should create a [custom `_app.js`](/docs/advanced-features/custom-app.md) for global CSS. When migrating, you can copy over your CSS imports directly and update the relative file path, if necessary. Next.js has [built-in CSS support](/docs/basic-features/built-in-css-support). ## Links From 6f402b41318bdb16186e872cad7723558ca77d25 Mon Sep 17 00:00:00 2001 From: Lee Robinson Date: Thu, 1 Oct 2020 08:25:25 -0500 Subject: [PATCH 14/25] Update docs/migrating/from-gatsby.md Co-authored-by: Shu Uesugi --- docs/migrating/from-gatsby.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/migrating/from-gatsby.md b/docs/migrating/from-gatsby.md index b2898e31c4e5eba..e355a6b86c45677 100644 --- a/docs/migrating/from-gatsby.md +++ b/docs/migrating/from-gatsby.md @@ -60,7 +60,7 @@ With Gatsby, global CSS imports are included in `gatsby-browser.js`. With Next, ## Links -The Gatsby `Link` and Next.js [`Link`](/docs/api-reference/next/link>) component have a slightly different API. First, you will need to update any import statements referencing `Link` from Gatsby to: +The Gatsby `Link` and Next.js [`Link`](/docs/api-reference/next/link.md) component have a slightly different API. First, you will need to update any import statements referencing `Link` from Gatsby to: ```js import Link from 'next/link' From 3f4ef3d1fde9bb7c2890d23dd5aaf3bc14c759bf Mon Sep 17 00:00:00 2001 From: Lee Robinson Date: Thu, 1 Oct 2020 08:25:40 -0500 Subject: [PATCH 15/25] Update docs/migrating/from-gatsby.md Co-authored-by: Shu Uesugi --- docs/migrating/from-gatsby.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/migrating/from-gatsby.md b/docs/migrating/from-gatsby.md index e355a6b86c45677..2a54b97bf9df557 100644 --- a/docs/migrating/from-gatsby.md +++ b/docs/migrating/from-gatsby.md @@ -72,7 +72,7 @@ Next, you can find and replace usages of `to="/route"` with `href="/route"`. The largest difference between Gatsby and Next.js is how data fetching is implemented. Gatsby is opinionated with GraphQL being the default strategy for retrieving data across your application. With Next.js, you get to choose which strategy you want (GraphQL is one supported option). -Gatsby uses the `graphql` tag to query data in the pages of your site. This may include local data, remote data, or information about your site configuration. Gatsby only allows the creation of static pages. With Next.js, you can choose on a [per-page basis](/docs/basic-features/pages) which [data fetching strategy](/docs/basic-features/data-fetching) you want. For example, `getServerSideProps` allows you to do server-side rendering. If you wanted to generate a static site, you'd export `getStaticProps` / `getStaticPaths` inside the page, rather than using `pageQuery`. For example: +Gatsby uses the `graphql` tag to query data in the pages of your site. This may include local data, remote data, or information about your site configuration. Gatsby only allows the creation of static pages. With Next.js, you can choose on a [per-page basis](/docs/basic-features/pages.md) which [data fetching strategy](/docs/basic-features/data-fetching.md) you want. For example, `getServerSideProps` allows you to do server-side rendering. If you wanted to generate a static page, you'd export `getStaticProps` / `getStaticPaths` inside the page, rather than using `pageQuery`. For example: ```js import { getPostBySlug, getAllPosts } from '../lib/blog' From 60bc70d5b88a7f4dd17372ad00754973a544916f Mon Sep 17 00:00:00 2001 From: Lee Robinson Date: Thu, 1 Oct 2020 08:25:52 -0500 Subject: [PATCH 16/25] Update docs/migrating/from-gatsby.md Co-authored-by: Shu Uesugi --- docs/migrating/from-gatsby.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/docs/migrating/from-gatsby.md b/docs/migrating/from-gatsby.md index 2a54b97bf9df557..5451ae4e3113013 100644 --- a/docs/migrating/from-gatsby.md +++ b/docs/migrating/from-gatsby.md @@ -81,9 +81,7 @@ export async function getStaticProps({ params }) { const post = getPostBySlug(params.slug) return { - props: { - ...post, - }, + props: post, } } From 84ae59d3835da6851537274307b985464d7ffe87 Mon Sep 17 00:00:00 2001 From: Lee Robinson Date: Thu, 1 Oct 2020 08:26:37 -0500 Subject: [PATCH 17/25] Update docs/migrating/from-gatsby.md Co-authored-by: Shu Uesugi --- docs/migrating/from-gatsby.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/migrating/from-gatsby.md b/docs/migrating/from-gatsby.md index 5451ae4e3113013..e3c3266955d0974 100644 --- a/docs/migrating/from-gatsby.md +++ b/docs/migrating/from-gatsby.md @@ -153,7 +153,7 @@ export default { ## Search Engine Optimization -Most Gatsby examples use `react-helmet` to assist with adding `meta` tags for proper SEO. With Next.js, we recommend using [`next/head`](/docs/api-reference/next/head) to add `meta` tags to your `` element. For example, here's part of an SEO component with Gatsby: +Most Gatsby examples use `react-helmet` to assist with adding `meta` tags for proper SEO. With Next.js, we recommend using [`next/head`](/docs/api-reference/next/head.md) to add `meta` tags to your `` element. For example, here's part of an SEO component with Gatsby: ```js // src/components/seo.js From c8226cb1bbdb6755c202beddc9c342237770d382 Mon Sep 17 00:00:00 2001 From: Lee Robinson Date: Thu, 1 Oct 2020 08:26:49 -0500 Subject: [PATCH 18/25] Update docs/migrating/from-gatsby.md Co-authored-by: Shu Uesugi --- docs/migrating/from-gatsby.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/migrating/from-gatsby.md b/docs/migrating/from-gatsby.md index e3c3266955d0974..3143611c7c81f29 100644 --- a/docs/migrating/from-gatsby.md +++ b/docs/migrating/from-gatsby.md @@ -210,7 +210,7 @@ And here's the same example using Next.js, including reading from a site config import Head from 'next/head' import config from '../config' -const SEO = ({ description, title }) => { +export default function SEO({ description, title }) { const metaDescription = description || config.description const siteTitle = config.title From d5656d043a013ff6e7ee3f698f7fed221989255f Mon Sep 17 00:00:00 2001 From: Lee Robinson Date: Thu, 1 Oct 2020 08:27:26 -0500 Subject: [PATCH 19/25] Update docs/migrating/from-gatsby.md Co-authored-by: Shu Uesugi --- docs/migrating/from-gatsby.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/migrating/from-gatsby.md b/docs/migrating/from-gatsby.md index 3143611c7c81f29..88f3b873e9309ae 100644 --- a/docs/migrating/from-gatsby.md +++ b/docs/migrating/from-gatsby.md @@ -234,6 +234,6 @@ export default function SEO({ description, title }) { export default SEO ``` -## Conclusion +## Learn more -React frameworks share many core pieces and make it easy to transition between each other. While the APIs and components may vary, the underlying ideas and implementation share similar roots and provide an easy path for migration. To view an example converting a Gatsby project to Next.js, review this [pull request](https://github.com/leerob/gatsby-to-nextjs/pull/1). +Please take a look at [this pull request](https://github.com/leerob/gatsby-to-nextjs/pull/1) to learn more. If you have questions, please ask on [our discussion board](https://github.com/vercel/next.js/discussions). From d164d70c58d9fd860534cac745365e266a740993 Mon Sep 17 00:00:00 2001 From: Lee Robinson Date: Thu, 1 Oct 2020 08:32:01 -0500 Subject: [PATCH 20/25] Add component function for SEO. --- docs/migrating/from-gatsby.md | 91 +++++++++++++++++------------------ 1 file changed, 45 insertions(+), 46 deletions(-) diff --git a/docs/migrating/from-gatsby.md b/docs/migrating/from-gatsby.md index 88f3b873e9309ae..3cc3d0143103a6b 100644 --- a/docs/migrating/from-gatsby.md +++ b/docs/migrating/from-gatsby.md @@ -160,46 +160,48 @@ Most Gatsby examples use `react-helmet` to assist with adding `meta` tags for pr import { Helmet } from 'react-helmet' -return ( - -) +export default function SEO({ description, title, siteTitle }) { + return ( + + ) +} ``` And here's the same example using Next.js, including reading from a site config file. @@ -211,27 +213,24 @@ import Head from 'next/head' import config from '../config' export default function SEO({ description, title }) { - const metaDescription = description || config.description const siteTitle = config.title return ( {`${title} | ${siteTitle}`} - + - + - + ) } - -export default SEO ``` ## Learn more From 1b250e34750c4fd138fcdb95b9ec8e6212839a8c Mon Sep 17 00:00:00 2001 From: Lee Robinson Date: Thu, 1 Oct 2020 08:42:23 -0500 Subject: [PATCH 21/25] Add remark. --- docs/migrating/from-gatsby.md | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) diff --git a/docs/migrating/from-gatsby.md b/docs/migrating/from-gatsby.md index 3cc3d0143103a6b..21e993f0f6c572f 100644 --- a/docs/migrating/from-gatsby.md +++ b/docs/migrating/from-gatsby.md @@ -75,13 +75,22 @@ The largest difference between Gatsby and Next.js is how data fetching is implem Gatsby uses the `graphql` tag to query data in the pages of your site. This may include local data, remote data, or information about your site configuration. Gatsby only allows the creation of static pages. With Next.js, you can choose on a [per-page basis](/docs/basic-features/pages.md) which [data fetching strategy](/docs/basic-features/data-fetching.md) you want. For example, `getServerSideProps` allows you to do server-side rendering. If you wanted to generate a static page, you'd export `getStaticProps` / `getStaticPaths` inside the page, rather than using `pageQuery`. For example: ```js +import remark from 'remark' +import html from 'remark-html' import { getPostBySlug, getAllPosts } from '../lib/blog' export async function getStaticProps({ params }) { const post = getPostBySlug(params.slug) + const content = await remark() + .use(html) + .process(post.content || '') + .toString() return { - props: post, + props: { + ...post, + content, + }, } } From 20bcf9cbb5a97fd52910f2480fd6754d650fdb76 Mon Sep 17 00:00:00 2001 From: Lee Robinson Date: Thu, 1 Oct 2020 09:48:20 -0500 Subject: [PATCH 22/25] Add one missing .md reference. --- docs/migrating/from-gatsby.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/migrating/from-gatsby.md b/docs/migrating/from-gatsby.md index 21e993f0f6c572f..ade59527838842f 100644 --- a/docs/migrating/from-gatsby.md +++ b/docs/migrating/from-gatsby.md @@ -56,7 +56,7 @@ Gatsby creates dynamic routes using the `createPages` API inside of `gatsby-node ## Styling -With Gatsby, global CSS imports are included in `gatsby-browser.js`. With Next, you should create a [custom `_app.js`](/docs/advanced-features/custom-app.md) for global CSS. When migrating, you can copy over your CSS imports directly and update the relative file path, if necessary. Next.js has [built-in CSS support](/docs/basic-features/built-in-css-support). +With Gatsby, global CSS imports are included in `gatsby-browser.js`. With Next, you should create a [custom `_app.js`](/docs/advanced-features/custom-app.md) for global CSS. When migrating, you can copy over your CSS imports directly and update the relative file path, if necessary. Next.js has [built-in CSS support](/docs/basic-features/built-in-css-support.md). ## Links From d2fe9d49ee08e3434012a1853045c9e909dc9585 Mon Sep 17 00:00:00 2001 From: Lee Robinson Date: Thu, 1 Oct 2020 11:41:19 -0500 Subject: [PATCH 23/25] Update docs/migrating/from-gatsby.md Co-authored-by: Luis Alvarez D. --- docs/migrating/from-gatsby.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/migrating/from-gatsby.md b/docs/migrating/from-gatsby.md index ade59527838842f..a1552a838933b49 100644 --- a/docs/migrating/from-gatsby.md +++ b/docs/migrating/from-gatsby.md @@ -25,7 +25,7 @@ Here's an example `package.json` ([view diff](https://github.com/leerob/gatsby-t ```json { "scripts": { - "dev": "next", + "dev": "next dev", "build": "next build", "start": "next start" }, From 553c3221c4bf8c8fc5202207cbf9e2c7e0336c8f Mon Sep 17 00:00:00 2001 From: Lee Robinson Date: Mon, 5 Oct 2020 11:48:43 -0500 Subject: [PATCH 24/25] Update docs/migrating/from-gatsby.md Co-authored-by: Shu Uesugi --- docs/migrating/from-gatsby.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/migrating/from-gatsby.md b/docs/migrating/from-gatsby.md index a1552a838933b49..6807af74cebf111 100644 --- a/docs/migrating/from-gatsby.md +++ b/docs/migrating/from-gatsby.md @@ -227,8 +227,7 @@ export default function SEO({ description, title }) { return ( {`${title} | ${siteTitle}`} - - + From c029acfebfe1c28f4ba5b5c40bc82cd7764edd8e Mon Sep 17 00:00:00 2001 From: Shu Uesugi Date: Mon, 5 Oct 2020 10:05:17 -0700 Subject: [PATCH 25/25] Apply suggestions from code review --- docs/migrating/from-gatsby.md | 13 ++++++++++--- 1 file changed, 10 insertions(+), 3 deletions(-) diff --git a/docs/migrating/from-gatsby.md b/docs/migrating/from-gatsby.md index 6807af74cebf111..841e0fe4f695fd1 100644 --- a/docs/migrating/from-gatsby.md +++ b/docs/migrating/from-gatsby.md @@ -75,6 +75,9 @@ The largest difference between Gatsby and Next.js is how data fetching is implem Gatsby uses the `graphql` tag to query data in the pages of your site. This may include local data, remote data, or information about your site configuration. Gatsby only allows the creation of static pages. With Next.js, you can choose on a [per-page basis](/docs/basic-features/pages.md) which [data fetching strategy](/docs/basic-features/data-fetching.md) you want. For example, `getServerSideProps` allows you to do server-side rendering. If you wanted to generate a static page, you'd export `getStaticProps` / `getStaticPaths` inside the page, rather than using `pageQuery`. For example: ```js +// src/pages/[slug].js + +// Install remark and remark-html import remark from 'remark' import html from 'remark-html' import { getPostBySlug, getAllPosts } from '../lib/blog' @@ -113,12 +116,16 @@ export async function getStaticPaths() { You'll commonly see Gatsby plugins used for reading the file system (`gatsby-source-filesystem`), handling markdown files (`gatsby-transformer-remark`), and so on. For example, the popular starter blog example has [15 Gatsby specific packages](https://github.com/gatsbyjs/gatsby-starter-blog/blob/master/package.json). Next takes a different approach. It includes common features like [image optimization](https://github.com/vercel/next.js/discussions/17141) directly inside the framework, and gives the user full control over integrations with external packages. For example, rather than abstracting reading from the file system to a plugin, you can use the native Node.js `fs` package inside `getStaticProps` / `getStaticPaths` to read from the file system. ```js -import fs from 'fs' -import { join } from 'path' +// src/lib/blog.js + +// Install gray-matter and date-fns import matter from 'gray-matter' import { parseISO, format } from 'date-fns' +import fs from 'fs' +import { join } from 'path' -const postsDirectory = join(process.cwd(), 'content', 'blog') +// Add markdown files in `src/content/blog` +const postsDirectory = join(process.cwd(), 'src', 'content', 'blog') export function getPostBySlug(slug) { const realSlug = slug.replace(/\\.md$/, '')