Migrating from NuxtJS

Here are some key concepts and migration strategies to help you get started. Use the rest of our docs and our Discord community to keep going!

This guide is referring to Nuxt 2, not the newer Nuxt 3. While some of the concepts are similar, Nuxt 3 is a newer version of the framework and may require different strategies for parts of your migration.

Key Similarities between Nuxt and Astro

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

Astro projects can also be SSG or SSR with page level prerendering.
Astro uses file-based routing, and allows specially named pages to create dynamic routes.
Astro is component-based, and your markup structure will be similar before and after your migration.
Astro has an official integration for using Vue components.
Astro has support for installing NPM packages, including Vue libraries. You may be able to keep some or all of your existing Vue components and dependencies.

Key Differences between Nuxt and Astro

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

MPA vs SPA: Nuxt is a Vue-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.
Page Routing: Nuxt uses vue-router for SPA routing, and vue-meta for managing <head>. In Astro, you will create separate HTML page routes and control your page <head> directly, or in a layout component.
Content-first: Astro was designed to showcase your content and to allow you to opt-in to interactivity only as needed. While Nuxt can do content-focused sites through @nuxt/content, an existing Nuxt app may be built for high client-side interactivity. Astro has built-in capabilities for working with your content, such as page generation, but may require advanced Astro techniques to include items that are more challenging to replicate using .astro components, such as dashboards.

Convert your NuxtJS Project

Each project migration will look different, but there are some common actions you will perform when converting from Nuxt to Astro.

Create a new Astro project

Use the create astro command for your package manager to launch Astro’s CLI wizard or choose a community theme from the Astro 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 (e.g. docs, blog, portfolio). Or, you can start a new project from any existing Astro repository on GitHub.

# launch the Astro CLI Wizard
npm create astro@latest

# create a new project with an official example
npm create astro@latest -- --template <example-name>

# launch the Astro CLI Wizard
pnpm create astro@latest

# create a new project with an official example
pnpm create astro@latest --template <example-name>

# launch the Astro CLI Wizard
yarn create astro@latest

# create a new project with an official example
yarn create astro@latest --template <example-name>

Then, copy your existing Nuxt project files over to your new Astro project in a separate folder outside of src.

Install integrations (optional)

You may find it useful to install some of Astro’s optional integrations to use while converting your Nuxt project to Astro:

@astrojs/vue: to reuse some existing Vue UI components in your new Astro site, or keep writing with Vue components.
@astrojs/image: to replace Nuxt’s Image plugin with Astro’s own image-optimizing components.
@astrojs/mdx: to bring existing MDX files from your Nuxt project, or to use MDX in your new Astro site.

Put your source code in `src`

Move the contents of Nuxt’s static/ folder into public/.

Astro uses the public/ directory for static assets, similar to Nuxt’s static/ folder.
Copy or Move Nuxt’s other files and folders (e.g. pages, layouts etc.) into Astro’s src/ folder.

Like Nuxt, Astro’s src/pages/ folder is a special folder used for file-based routing. 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, src/scripts.

Convert Vue SFC pages to `.astro` files

Here are some tips for converting a Nuxt .vue component into a .astro component:

Use the <template> of the existing NuxtJS component function as the basis for your HTML template.
Change any Nuxt or Vue syntax to Astro or to HTML web standards. This includes <NextLink>, :class, {{variable}}, and v-if, for example.
Move <script> JavaScript, into a “code fence” (---). Convert your component’s data-fetching properties to server-side JavaScript - see Nuxt data fetching to Astro.
Use Astro.props to access any additional props that were previously passed to your Vue component.
Decide whether any imported components also need to be converted to Astro. With the official integration installed, you can use existing Vue components in your Astro file. But, you may want to convert them to Astro, especially if they do not need to be interactive!

See an example from a Nuxt app converted step-by-step.

Compare: Vue vs Astro

Compare the following Nuxt component and a corresponding Astro component:

<template>
  <div>
    <p v-if="message === 'Not found'">
      The repository you're looking up doesn't exist
    </p>
    <div v-else>
      <Header/>
      <p class="banner">Astro has {{stars}} 🧑‍🚀</p>
      <Footer />
    </div>
  </div>
</template>

<script>
import Vue from 'vue'

export default Vue.extend({
  name: 'IndexPage',
  async asyncData() {
    const res = await fetch('https://api.github.com/repos/withastro/astro')
    const json = await res.json();
    return {
      message: json.message,
      stars: json.stargazers_count || 0,
    };
  }
});
</script>

<style scoped>
.banner {
  background-color: #f4f4f4;
  padding: 1em 1.5em;
  text-align: center;
  margin-bottom: 1em;
}
<style>

---
import Header from "./header";
import Footer from './footer';
import "./layout.css";

const res = await fetch('https://api.github.com/repos/withastro/astro')
const json = await res.json()
const message = json.message;
const stars = json.stargazers_count || 0;
---

{message === "Not Found" ?
      <p>The repository you're looking up doesn't exist</p> :
      <>
            <Header />
            <p class="banner">Astro has {stars} 🧑‍🚀</p>
            <Footer />
        </>
}

<style>
  .banner {
    background-color: #f4f4f4;
    padding: 1em 1.5em;
    text-align: center;
    margin-bottom: 1em;
  }
<style>

Migrating Layout Files

You may find it helpful to start by converting your Nuxt layouts and templates into Astro layout components.

Each Astro page explicitly requires <html>, <head>, and <body> tags to be present. Your Nuxt layout.vue and templates will not include these.

Note the standard HTML templating, and direct access to <head>:

<html lang="en">
  <head>
    <meta charset="utf-8" />
    <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
    <meta name="viewport" content="width=device-width" />
    <title>Astro</title>
  </head>
  <body>
    <!-- Wrap the slot element with your existing layout templating -->
    <slot />
  </body>
</html>

You may also wish to reuse code from your Nuxt’s page’s head property to include additional site metadata. Notice that Astro uses neither vue-meta nor a component’s head property but instead creates <head> directly. You may import and use components, even within <head>, to separate and organize your page content.

Migrating Pages and Posts

In NuxtJS, your pages live in /pages. In Astro, all your page’s content must live within src/pages or src/content.

Vue Pages

Your existing Nuxt Vue (.vue) pages will need to be converted from Vue files to .astro pages. You cannot use an existing Vue page file in Astro.

These .astro pages must be located within src/pages/ and will have page routes generated automatically based on their file path.

Dynamic File Path Naming

In Nuxt, your dynamic pages use an underscore to represent a dynamic page property that’s then passed to the page generation:

Directorypages/
- Directorypokemon/
  - _name.vue
- index.vue
nuxt.config.js

To convert to Astro, change this underscored dynamic path property (e.g. _name.vue) to be wrapped in a pair of square brackets (e.g. [name].astro):

Directorysrc/
- Directorypages/
  - Directorypokemon/
    [name].astro
  - index.astro
astro.config.mjs

Markdown and MDX pages

Astro has built-in support for Markdown and an optional integration for MDX files. You can reuse any existing Markdown and MDX pages, but they may require some adjustments to their frontmatter, such as adding Astro’s special layout frontmatter property.

You will no longer need to manually create pages for each Markdown-generated route or use an external package like @nuxt/content. These files can be placed within src/pages/ to take advantage of automatic file-based routing.

When part of a content collection, Markdown and MDX files will live in folders within src/content/ and you will generate those pages dynamically.

Migrating Tests

As Astro outputs raw HTML, it is possible to write end-to-end tests using the output of the build step. Any end-to-end tests written previously might work out-of-the-box, if you have been able to match the markup of your Nuxt site. Testing libraries such as Jest and Vue Testing Library can be imported and used in Astro to test your Vue components.

See Astro’s testing guide for more.

Reference: Convert NuxtJS Syntax to Astro

Nuxt Local Variables to Astro

To use local variables in an Astro component’s HTML, change the set of two curly braces to one set of curly braces:

---
const message = "Hello!"
---
<p>{{message}}</p>
<p>{message}</p>

Nuxt Property Passing to Astro

To bind an attribute or component property in an Astro component, change this syntax to the following:

---
---
<p v-bind:aria-label="message">...</p>
<!-- Or -->
<p :aria-label="message">...</p>
<!-- Also support component props -->
<Header title="Page"/>

<p aria-label={message}>...</p>
<!-- Also support component props -->
<Header title={"Page"}/>

Nuxt Links to Astro

Convert any Nuxt <NuxtLink to=""> components to HTML <a href=""> tags.

<NuxtLink to="/blog">Blog</Link>
<a href="/blog">Blog</a>

Astro does not use any special component for links, although you are welcome to build custom link components. You can then import and use this <Link> just as you would any other component.

---
const { to } = Astro.props
---
<a href={to}><slot /></a>

Nuxt Imports to Astro

If necessary, update any file imports to reference relative file paths exactly. This can be done using import aliases, or by writing out a relative path in full.

Note that .astro and several other file types must be imported with their full file extension.

---
import Card from `../../components/Card.astro`;
---
<Card />

Nuxt Dynamic Page Generation to Astro

In Nuxt, to generate a dynamic page you either must:

Use SSR.
Use the generate function in nuxt.config.js to define all possible static routes.

In Astro, you similarly have two choices:

Use SSR.
Export a getStaticPaths() function in the frontmatter of an Astro page to tell the framework which static routes to generate dynamically.

Convert a `generate` function in Nuxt to a `getStaticPaths` function in Astro.

To generate multiple pages, replace the function to create routes in your nuxt.config.js with getStaticPaths() directly inside a dynamic routing page itself:

{
  // ...
    generate: {
        async routes() {
          // Axios is required here unless you're using Node 18
          const res = await axios.get("https://pokeapi.co/api/v2/pokemon?limit=151")
          const pokemons = res.data.results;
          return pokemons.map(pokemon => {
            return '/pokemon/' + pokemon.name
          })
        }
      }
}

---
export const getStaticPaths = async () => {
  const res = await fetch("https://pokeapi.co/api/v2/pokemon?limit=151")
  const resJson = await res.json();
  const pokemons = resJson.results;
  return pokemons.map(({ name }) => ({
      params: { name },
    }))
}
// ...
---
<!-- Your template here -->

Nuxt Data Fetching to Astro

Nuxt has two methods of fetching server-side data:

In Astro, fetch data inside of your page’s code fence.

Migrate the following:

{
  // ...
  async asyncData() {
    const res = await fetch("https://pokeapi.co/api/v2/pokemon?limit=151")
    const resJson = await res.json();
    const pokemons = resJson.results;
    return {
      pokemons,
    }
  },
}

To a code fence without a wrapper function:

---
const res = await fetch("https://pokeapi.co/api/v2/pokemon?limit=151")
const resJson = await res.json();
const pokemons = resJson.results;
---

<!-- Your template here -->

Nuxt Styling to Astro

Nuxt utilizes Vue’s component styling to generate a page’s style.

<template>
  <!-- Your template here -->
</template>

<script>
  // Your server logic here
</script>

<style scoped>
    .class {
        color: red;
    }
</style>

Similarly, in Astro you can drop in a <style> element in your page’s template to provide scoped styles to the component.

---
// Your server logic here
---

<style>
    .class {
        color: red;
    }
</style>

Global Styling

<style> tags are scoped by default in Astro. To make a <style> tag global, mark it with the is:global attribute:

<style is:global>
  p {
    color: red;
  }
</style>

Pre-processor support

Astro supports the most popular CSS preprocessors by installing them as a dev dependency. For example, to use SCSS:

npm install -D sass

After doing so, you’re then able to use .scss or .sass styled without modification from your Vue components.

<p>Hello, world</p>
<style lang="scss">
p {
   color: black;

   &:hover {
       color: red;
   }
}
</style>

See more about Styling in Astro.

Nuxt Image Plugin to Astro

Convert any Nuxt <nuxt-img/> or <nuxt-picture/> components to Astro’s own image integration components, or to a standard HTML <img> tag.

See a full list of component attributes available for Astro’s <Image /> and <Picture /> components, and note that several will differ from Nuxt’s attributes.

---
import { Image } from '@astrojs/image/components';
import localImage from "../images/brand/logo.png";
import rocket from '../images/rocket.svg';
---
<Image src={localImage} alt="The Astro Logo" />
<img src={rocket} alt="A rocketship in space.">

In Vue (.vue) components within your Astro app, use standard JSX image syntax (<img />). Astro will not optimize these images, but you can install and use NPM packages for more flexibility.

You can learn more about using images in Astro in the Images Guide.

Guided example: See the steps!

Here is an example of Nuxt Pokédex data fetch converted to Astro.

pages/index.vue fetches and displays a list of the first 151 Pokémon using the REST PokéAPI.

Here’s how to recreate that in src/pages/index.astro, replacing asyncData() with fetch().

Identify the <template> and <style> in the Vue SFC.

<template>
  <ul class="plain-list pokeList">
            <li v-for="pokemon of pokemons" class="pokemonListItem" :key="pokemon.name">
                <NuxtLink class="pokemonContainer" :to="`/pokemon/${pokemon.name}`">
                    <p class="pokemonId">No. {{pokemon.id}}</p>
                    <img
                      class="pokemonImage"
                      :src="`https://raw.githubusercontent.com/PokeAPI/sprites/master/sprites/pokemon/${pokemon.id}.png`"
                      :alt="`${pokemon.name} picture`"/>
                    <h2 class="pokemonName">{{pokemon.name}}</h2>
                </NuxtLink>
            </li>
    </ul>
</template>

<script>
import Vue from 'vue'
export default Vue.extend({
  name: 'IndexPage',
  layout: 'default',
  async asyncData() {
    const res = await fetch("https://pokeapi.co/api/v2/pokemon?limit=151")
    const resJson = await res.json();
    const pokemons = resJson.results.map(pokemon => {
        const name = pokemon.name;
        // https://pokeapi.co/api/v2/pokemon/1/
        const url = pokemon.url;
        const id = url.split("/")[url.split("/").length - 2];
        return {
            name,
            url,
            id
        }
    });
    return {
      pokemons,
    }
  },
  head() {
    return {
      title: "Pokedex: Generation 1"
    }
  }
});
</script>

<style scoped>
.pokeList {
  display: grid;
  grid-template-columns: repeat( auto-fit, minmax(250px, 1fr) );
  gap: 1rem;
}

/* ... */
</style>

Create src/pages/index.astro

Use the <template> and <style> tags of the Nuxt SFC. Convert any Nuxt or Vue syntax to Astro.

Note that:

<template> is removed
<style> has its scoped attribute removed
v-for becomes .map.
:attr="val" becomes attr={val}
<NuxtLink> becomes <a>.
The <> </> fragment is not required in Astro templating.

---
---
<ul class="plain-list pokeList">
    {pokemons.map((pokemon) => (
        <li class="pokemonListItem" key={pokemon.name}>
            <a class="pokemonContainer" href={`/pokemon/${pokemon.name}`}>
                <p class="pokemonId">No. {pokemon.id}</p>
                <img class="pokemonImage" src={`https://raw.githubusercontent.com/PokeAPI/sprites/master/sprites/pokemon/${pokemon.id}.png`} alt={`${pokemon.name} picture`}/>
                <h2 class="pokemonName">{pokemon.name}</h2>
            </a>
        </li>
    ))}
</ul>

<style>
.pokeList {
  display: grid;
  grid-template-columns: repeat( auto-fit, minmax(250px, 1fr) );
  gap: 1rem;
}

/* ... */
</style>

Add any needed imports, props and JavaScript