Migrating from Gatsby

Gatsby is a static-site web builder based on React.

Key Similarities

Section titled Key Similarities

Gatsby and Astro share some similarities that will help you migrate your project:

  • Astro’s JSX-like syntax should feel familiar if you are used to writing React.

  • Astro has built-in support for Markdown and an integration for using MDX files. Both Gatsby and Astro use Remark by default for Markdown manipulation and pre-processing, so you can continue to use many of your existing Remark plugins.

  • Astro has an official integrations for using React component. Note that in Astro, React files must have a .jsx or .tsx extension.

  • Astro supports installing NPM packages, including several for React. You may be able to keep some or all of your existing React components and dependencies.

  • Astro projects can also be SSG or SSR. (Support for per-page rendering strategy is planned.)

Key Differences

Section titled Key Differences

When you rebuild your Gatsby site in Astro, you will notice some important differences:

  • MPA vs SPA: Gatsby is a React-based single-page application (SPA). Astro sites are multi-page apps built using .astro components, but can also support React, Preact, Vue.js, Svelte, SolidJS, AlpineJS, Lit and raw HTML templating.

  • Astro components are not written as exported functions that return page templating. Instead, you’ll split your code into a “code fence” and a body exclusively for the HTML you generate.

  • Local file data: Gatsby uses GraphQL to retrieve data from your project files. Astro uses ESM imports and the Astro.glob() helper to import data from your project files. GraphQL may be optionally added to your Astro project, but is not included by default.

Switch from Gatsby to Astro

Section titled Switch from Gatsby to Astro

To convert a Gatsby blog to Astro, start with our official blog theme starter template, or explore more community blog themes in our theme showcase.

You can pass a --template argument to the create astro command to start a new Astro project with one of our official starters. Or, you can start a new project from any existing Astro repository on GitHub.

pnpm create astro@latest --template blog

Bring your existing Markdown (or MDX, with our optional integration) files as content to create Markdown or MDX pages.

While file-based routing and layout components are similar in Astro, you may wish to read about Astro’s project structure to learn where files should be located. For example, you will need to rename your Gatsby static assets folder from static/ to public/.

To convert other types of sites, such as a portfolio or documentation site, see more official starter templates on astro.new. You’ll find a link to each project’s GitHub repository, as well as one-click links to open a working project in StackBlitz, CodeSandbox and Gitpod online development environments.

Community Resources

Section titled Community Resources

More migration guides