diff --git a/src/content/docs/en/guides/migrate-to-astro/from-gatsby.mdx b/src/content/docs/en/guides/migrate-to-astro/from-gatsby.mdx index b2f609e013d61..29f15c2552da6 100644 --- a/src/content/docs/en/guides/migrate-to-astro/from-gatsby.mdx +++ b/src/content/docs/en/guides/migrate-to-astro/from-gatsby.mdx @@ -6,8 +6,9 @@ stub: false framework: Gatsby i18nReady: true --- -import AstroJSXTabs from '~/components/tabs/AstroJSXTabs.astro' -import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro' +import { Steps } from '@astrojs/starlight/components'; +import AstroJSXTabs from '~/components/tabs/AstroJSXTabs.astro'; +import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro'; Here are some key concepts and migration strategies to help you get started. Use the rest of our docs and our [Discord community](https://astro.build/chat) to keep going! @@ -35,7 +36,6 @@ When you rebuild your Gatsby site in Astro, you will notice some important diffe - [Local file data](/en/guides/imports/): Gatsby uses GraphQL to retrieve data from your project files. Astro uses ESM imports and top-level await functions (e.g. [`Astro.glob()`](/en/guides/imports/#astroglob), [`getCollection()`](/en/guides/content-collections/#querying-collections)) to import data from your project files. You can manually add GraphQL to your Astro project but it is not included by default. - ## Convert your Gatsby Project Each project migration will look different, but there are some common actions you will perform when converting from Gatsby to Astro. @@ -89,11 +89,11 @@ You may find it useful to install some of [Astro's optional integrations](/en/gu - **@astrojs/mdx**: to bring existing MDX files from your Gatsby project, or to use MDX in your new Astro site. - ### Put your code in `src` Following [Astro's project structure](/en/basics/project-structure/): + 1. **Delete** Gatsby's `public/` folder. Gatsby uses the `public/` directory for its build output, so you can safely discard this folder. You will no longer need a built version of your Gatsby site. (Astro uses `dist/` by default for the build output.) @@ -104,9 +104,10 @@ Following [Astro's project structure](/en/basics/project-structure/): 3. **Copy or Move** Gatsby's other files and folders (e.g. `components`, `pages`, etc.) as needed into your Astro `src/` folder as you rebuild your site, following [Astro's project structure](/en/basics/project-structure/). - Astro's `src/pages/` folder is a special folder used for file-based routing to create your site's pages and posts from `.astro`, `.md` and `.mdx` files. You will not have to configure any routing behavior for your Astro, Markdown, and MDX files. + Astro's `src/pages/` folder is a special folder used for file-based routing to create your site's pages and posts from `.astro`, `.md` and `.mdx` files. You will not have to configure any routing behavior for your Astro, Markdown, and MDX files. - All other folders are optional, and you can organize the contents of your `src/` folder any way you like. Other common folders in Astro projects include `src/layouts/`, `src/components`, `src/styles`, and `src/scripts`. + All other folders are optional, and you can organize the contents of your `src/` folder any way you like. Other common folders in Astro projects include `src/layouts/`, `src/components`, `src/styles`, and `src/scripts`. + ### Tips: Convert JSX files to `.astro` files @@ -114,15 +115,15 @@ Here are some tips for converting a Gatsby `.js` component into a `.astro` compo 1. Use only the `return()` of the existing Gatsby component function as your HTML template. -1. Change any [Gatsby or JSX syntax to Astro syntax](#reference-convert-to-astro-syntax) or to HTML web standards. This includes ``, `{children}`, and `className`, for example. +2. Change any [Gatsby or JSX syntax to Astro syntax](#reference-convert-to-astro-syntax) or to HTML web standards. This includes ``, `{children}`, and `className`, for example. -1. Move any necessary JavaScript, including import statements, into a ["code fence" (`---`)](/en/basics/astro-components/#the-component-script). Note: JavaScript to [conditionally render content](/en/basics/astro-syntax/#dynamic-html) is often written inside the HTML template directly in Astro. +3. Move any necessary JavaScript, including import statements, into a ["code fence" (`---`)](/en/basics/astro-components/#the-component-script). Note: JavaScript to [conditionally render content](/en/basics/astro-syntax/#dynamic-html) is often written inside the HTML template directly in Astro. 4. Use [`Astro.props`](/en/reference/api-reference/#astroprops) to access any additional props that were previously passed to your Gatsby function. -4. Decide whether any imported components also need to be converted to Astro. With the official React integration installed, you can [use existing React components in your Astro files](/en/guides/framework-components/). But, you may want to convert them to `.astro` components, especially if they do not need to be interactive! +5. Decide whether any imported components also need to be converted to Astro. With the official React integration installed, you can [use existing React components in your Astro files](/en/guides/framework-components/). But, you may want to convert them to `.astro` components, especially if they do not need to be interactive! -4. Remove any GraphQL queries. Instead, use import and [`Astro.glob()`](/en/reference/api-reference/#astroglob) statements to query your local files. +6. Remove any GraphQL queries. Instead, use import and [`Astro.glob()`](/en/reference/api-reference/#astroglob) statements to query your local files. See [an example from Gatsby's Blog starter template converted step-by-step](#guided-example-gatsby-layout-to-astro) @@ -393,7 +394,8 @@ This example converts the main project layout (`layout.js`) from Gatsby's blog s This page layout shows one header when visiting the home page, and a different header with a link back to Home for all other pages. -1. Identify the return() JSX. + +1. Identify the `return()` JSX. ```jsx {21-29} title="layout.js" import * as React from "react" @@ -559,6 +561,7 @@ This page layout shows one header when visiting the home page, and a different h ``` You should see a link to "Home" only when visiting the About page. + ## Community Resources