Migrating from Next.js

Next.js is a framework for building web applications on top of React.

Next.js 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.

• Both Next.js and Astro are modern Javascript static-site generators. Both use a src/ folder for your project files and a special folder for file-based routing. Creating and managing pages for your site should feel familiar.

• Astro has an official integration for using React components. 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.)

When you rebuild your Next.js site in Astro, you will notice some important differences:

• MPA vs SPA: Next.js is a React-based SPA (single-page application). 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.

• Content-focus: Astro was designed to excel at making content-focused websites. An existing Next.js app might be built for high client-side interactivity and may include items that are difficult to replicate in Astro, such as dashboards.

To convert a Next.js 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

yarn create astro --template blog

npm 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, Astro uses a public/ folder outside of src/ for static assets.

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.

• Blog Post: From NextJS to Astro.

More migration guides