Migrating from Gatsby

    • Choose which data fetching strategy you want on a per-page basis.
    • Use to update existing pages by re-rendering them in the background as traffic comes in.
    • Use API Routes.

    And more! Let’s walk through a series of steps to complete the migration.

    The first step towards migrating to Next.js is to update and dependencies. You should:

    • 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.

    Here’s an example package.json (view diff):

    Static Assets and Compiled Output

    Gatsby uses the public directory for the compiled output, whereas Next.js uses it for static assets. Here are the steps for migration ():

    • Remove .cache/ and public from .gitignore and delete both directories.
    • Rename Gatsby’s static directory as public.
    • Add .next to .gitignore.

    Both Gatsby and Next support a pages directory, which uses file-system based routing. Gatsby’s directory is src/pages, which is also .

    Gatsby creates dynamic routes using the createPages API inside of gatsby-node.js. With Next, we can use Dynamic Routes 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 . For example, the route /blog/first-post would forward the query object { 'slug': 'first-post' } to pages/blog/[slug].js (learn more here).

    With Gatsby, global CSS imports are included in gatsby-browser.js. With Next, you should create a custom _app.js for global CSS. When migrating, you can copy over your CSS imports directly and update the relative file path, if necessary. Next.js has .

    1. // Gatsby
    3. import { Link } from 'gatsby'
    5. export default function Home() {
    6.   return <Link to="/blog">blog</Link>
    7. }
    1. // Next.js
    3. import Link from 'next/link'
    5. export default function Home() {
    6.   return (
    7.     <Link href="/blog">
    8.       <a>blog</a>
    9.     </Link>
    10.   )
    11. }

    Update any import statements, switch to to href, and add an <a> tag as a child of the element.

    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 which 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:

    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. Next takes a different approach. It includes common features 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.

    3. // Install gray-matter and date-fns
    4. import matter from 'gray-matter'
    5. import { parseISO, format } from 'date-fns'
    6. import fs from 'fs'
    7. import { join } from 'path'
    9. // Add markdown files in `src/content/blog`
    10. const postsDirectory = join(process.cwd(), 'src', 'content', 'blog')
    12. export function getPostBySlug(slug) {
    13.   const realSlug = slug.replace(/\.md$/, '')
    14.   const fullPath = join(postsDirectory, `${realSlug}.md`)
    15.   const { data, content } = matter(fileContents)
    16.   const date = format(parseISO(data.date), 'MMMM dd, yyyy')
    18.   return { slug: realSlug, frontmatter: { ...data, date }, content }
    19. }
    21. export function getAllPosts() {
    22.   const slugs = fs.readdirSync(postsDirectory)
    23.   const posts = slugs.map((slug) => getPostBySlug(slug))
    25.   return posts
    26. }

    Next.js has a built-in Image Component and Automatic Image Optimization.

    The Next.js Image Component, , is an extension of the HTML <img> element, evolved for the modern web.

    The Automatic Image Optimization allows for resizing, optimizing, and serving images in modern formats like WebP when the browser supports it. This avoids shipping large images to devices with a smaller viewport. It also allows Next.js to automatically adopt future image formats and serve them to browsers that support those formats.

    This means you can remove common Gatsby plugins like:

    • gatsby-image
    • gatsby-transformer-sharp
    • gatsby-plugin-sharp

    Instead, use the built-in next/image component and .

    1. import Image from 'next/image'
    2. import profilePic from '../public/me.png'
    4. export default function Home() {
    5.   return (
    6.     <>
    7.       <h1>My Homepage</h1>
    8.       <Image
    9.         src={profilePic}
    10.         alt="Picture of the author"
    11.         // When "responsive", similar to "fluid" from Gatsby
    12.         // When "intrinsic", similar to "fluid" with maxWidth from Gatsby
    13.         // When "fixed", similar to "fixed" from Gatsby
    14.         layout="responsive"
    15.         // Optional, similar to "blur-up" from Gatsby
    16.         placeholder="blur"
    17.         // Optional, similar to "width" in Gatsby GraphQL
    18.         width={500}
    19.         // Optional, similar to "height" in Gatsby GraphQL
    20.         height={500}
    21.       />
    22.       <p>Welcome to my homepage!</p>
    23.     </>
    24.   )
    25. }

    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.

    Most Gatsby examples use react-helmet to assist with adding meta tags for proper SEO. With Next.js, we use next/head to add meta tags to your <head /> element. For example, here’s an SEO component with Gatsby:

    1. // src/components/seo.js
    5. export default function SEO({ description, title, siteTitle }) {
    6.   return (
    7.     <Helmet
    8.       title={title}
    9.       titleTemplate={siteTitle ? `%s | ${siteTitle}` : null}
    10.       meta={[
    11.         {
    12.           name: `description`,
    13.           content: description,
    14.         },
    15.           property: `og:title`,
    16.           content: title,
    17.         },
    18.         {
    19.           property: `og:description`,
    20.           content: description,
    21.         },
    22.         {
    23.           property: `og:type`,
    24.           content: `website`,
    25.         },
    26.         {
    27.           name: `twitter:card`,
    28.           content: `summary`,
    29.         },
    30.         {
    31.           name: `twitter:creator`,
    32.           content: twitter,
    33.         },
    34.         {
    35.           name: `twitter:title`,
    36.           content: title,
    37.         },
    38.         {
    39.           name: `twitter:description`,
    40.           content: description,
    41.         },
    42.       ]}
    43.     />
    44.   )
    45. }

    And here’s the same example using Next.js, including reading from a site config file.

    1. // src/components/seo.js
    3. import Head from 'next/head'
    4. import config from '../config'
    6. export default function SEO({ description, title }) {
    7.   const siteTitle = config.title
    9.   return (
    10.     <Head>
    11.       <title>{`${title} | ${siteTitle}`}</title>
    12.       <meta name="description" content={description} />
    13.       <meta property="og:type" content="website" />
    14.       <meta property="og:title" content={title} />
    15.       <meta property="og:description" content={description} />
    16.       <meta property="og:site_name" content={siteTitle} />
    17.       <meta property="twitter:card" content="summary" />
    18.       <meta property="twitter:creator" content={config.social.twitter} />
    19.       <meta property="twitter:title" content={title} />
    20.       <meta property="twitter:description" content={description} />
    21.     </Head>
    23. }