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.
Nuxt and Astro share some similarities that will help you migrate your project:
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-focus: Astro was designed to excel at making content-focused sites. 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 it may be difficult to replicate items with complex shared state, such as dashboards, using .astro components.
Each project migration will look different, but there are some common actions you will perform when converting from Nuxt to Astro.
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.
Then, copy your existing Nuxt project files over to your new Astro project in a separate folder outside of src.
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.
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.
.astro filesHere 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 the following Nuxt component and a corresponding Astro component:
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>:
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.
In NuxtJS, your pages live in /pages. In Astro, all your page’s content must live within src/pages or src/content.
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.
In Nuxt, your dynamic pages use an underscore to represent a dynamic page property that’s then passed to the page generation:
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):
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.
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.
To use local variables in an Astro component’s HTML, change the set of two curly braces to one set of curly braces:
To bind an attribute or component property in an Astro component, change this syntax to the following:
Convert any Nuxt <NuxtLink to=""> components to HTML <a href=""> tags.
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.
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.
In Nuxt, to generate a dynamic page you either must:
generate function in nuxt.config.js to define all possible static routes.In Astro, you similarly have two choices:
getStaticPaths() function in the frontmatter of an Astro page to tell the framework which static routes to generate dynamically.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:
Nuxt has two methods of fetching server-side data:
In Astro, fetch data inside of your page’s code fence.
Migrate the following:
To a code fence without a wrapper function:
Nuxt utilizes Vue’s component styling to generate a page’s style.
Similarly, in Astro you can drop in a <style> element in your page’s template to provide scoped styles to the component.
<style> tags are scoped by default in Astro. To make a <style> tag global, mark it with the is:global attribute:
Astro supports the most popular CSS preprocessors by installing them as a dev dependency. For example, to use SCSS:
After doing so, you’re then able to use .scss or .sass styled without modification from your Vue components.
See more about Styling in 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.
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.
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().
<template> and <style> in the Vue SFC.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.
Note that:
asyncData function is no longer needed. Data from the API is fetched directly in the code fence.<Layout> component is imported, and wraps the page templating. head() Nuxt method is passed to the <Layout> component, which is passed to the <title> element as a property.
© 2021 Fred K. Schott
Licensed under the MIT License.
https://docs.astro.build/en/guides/migrate-to-astro/from-nuxtjs/