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:

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

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.

More migration guides