DEV Community

Cover image for Nuxt.js cheat sheet
Christopher Kade
Christopher Kade

Posted on • Updated on • Originally published at christopherkade.com

Nuxt.js cheat sheet

Nuxt.js is here to make your life easy, it's also here to make the Vue.js development process even nicer than it already is. But with all its good aspects, it has quirks that will have you click on every single link on Google.

This article is here to avoid these situations, it'll cover some normal use-cases and some edge-cases with quick and easy code snippets. It won't go into extreme detail on these matters, but will give you the documentation necessary to do so in case you want to.

Note: You'll need a good grasp of Vue.js concepts to take full advantage of this article !

Before we get into anything concrete, let me explain what Nuxt.js is.

What's Nuxt.js?

Nuxt.js is a framework based on Vue.js that allows you to build fully fledged server-rendered applications.

It comes out of the box with loads of useful packages:

  • πŸ’» Vue
  • ↩️ Vue Router (for easy routing)
  • πŸ’Ύ Vuex (for easy state management)
  • 🏎 Vue Server Renderer (for server-side rendering out of the box)
  • πŸ•΅οΈβ€β™‚οΈ Vue meta (for SEO)

Here's a list of what we'll cover (feel free to come back here if you're searching for something specific):

General

Routing

State management

SEO

Miscellaneous

If you have any other requests or want to add anything new, please feel free to hit me up on Twitter @christo_kade !

Creating a Nuxt.js project

yarn create nuxt-app <project-name>
Enter fullscreen mode Exit fullscreen mode

Which will prompt you to answer some questions, including:

  • Choose between integrated server-side frameworks (None by default, Express, Koa etc.)
  • Choose features to install (PWA Support, Linter / Formatter, Prettier, Axios)
  • Choose your favorite UI framework (None by default, Bootstrap, Vuetify, Bulma etc.)
  • Choose your favorite testing framework (None, Jest, AVA)
  • The Nuxt mode you want (Universal or SPA, more information)

Once done and your dependencies are installed:

$ cd <project-name>
$ yarn dev
Enter fullscreen mode Exit fullscreen mode

Documentation

Testing with Nuxt.js

The majority of your testing syntax will depend on the testing framework chosen during the project's creation.

Out of the box, Nuxt uses the @vue/test-utils package to render your components thanks to multiple methods such as mount(), shallowMount() and render(). You'll then be able to test that specific values have been displayed, that specific methods were called etc.

Nuxt will also make sure to set everything up for you, all you'll have to do is create your *.spec.js or *.test.js files and run the yarn test command.

Here's a classic (and brief) example of unit testing for a Vue component in a Nuxt project:

import { shallowMount } from "@vue/test-utils"
import cmp from "~/components/navbar/navbar"

// Mocking an icon displayed in my navbar
jest.mock("~/static/icons/svg/icon-menu.svg", () => "")

describe("Navbar component", () => {

  // We shallow mount the component while mocking some internal elements
  // Most of the time, you'll have to mock context objects such as $store or $route in order to render your component whithout any errors
  const wrapper = shallowMount(cmp, {
    // Stubbing nuxt-links in the navbar
    stubs: ["nuxt-link"],
    mocks: {
      "nuxt-Link": true,
      // Mocking the $store context object
      $store: {
        state: {
          locale: "en",
        },
      },
      // Mocking the $route context object
      $route: {
        path: "mockedPath",
      },
    },    
  })

  it("Snapshot testing", () => {
    expect(wrapper.html()).toMatchSnapshot()
  })

  describe("Components validation", () => {
    it("should return a valid component", () => {
      expect(wrapper.is(cmp)).toBe(true)
    })
  })

  describe("Content validation", () => {
    it("should render the link's name", () => {
      expect(wrapper.html()).toContain("About")
    })

    // ...
  })
})
Enter fullscreen mode Exit fullscreen mode

Documentation

Creating a new route

In the /pages folder, create a file, its name will be the name of the route.

So for example:

// /pages/about.vue

<template>
  <main>
    <h1>About page</h1>
  <main/>
</template>

<script>
export default {}
</script>

<style></style>
Enter fullscreen mode Exit fullscreen mode

Navigating to localhost:3000/about will display this component's content

Documentation

Creating dynamic routes

In the /pages folder, create a directory and a file prefixed by an underscore.

For example, the following file tree:

pages/
--| users/
-----| _id.vue
--| index.vue
Enter fullscreen mode Exit fullscreen mode

Will automatically generate the following router inside the .nuxt folder whenever you build your project:

router: {
  routes: [
    {
      name: 'index',
      path: '/',
      component: 'pages/index.vue'
    },
    {
      name: 'users-id',
      path: '/users/:id?',
      component: 'pages/users/_id.vue'
    },
  ]
}
Enter fullscreen mode Exit fullscreen mode

You can now navigate to /users/:id, with id being whatever value you need it to be.

To retrieve this value in your _id.vue component, just do the following:

// $route is a Nuxt context object, more info: https://nuxtjs.org/api/context
const { id } = this.$route.params
Enter fullscreen mode Exit fullscreen mode

Documentation, including nested routes and dynamic nested routes.

Navigating to a route in a component template

Inside of any of your components:

// /components/example.vue

// Clicking on this nuxt-link will navigate to the /pages/about.vue component
// nuxt-link renders an <a> tag in your HTML
<template>
  <section>    
    <nuxt-link to="/about">
      About
    </nuxt-link>
  </section>
</template>

// ...
Enter fullscreen mode Exit fullscreen mode

Documentation

Navigating to a route programatically

// Will add a history entry to the stack
this.$router.push({
  path: '/about'
})

// Will not
this.$router.replace({
  path: '/about'
})

// Goes back one record
this.$router.go(-1)
Enter fullscreen mode Exit fullscreen mode

Creating a new store module

In the /store folder, each file is a Vuex module.

// /store/todos.js
export const state = () => ({
  list: []
})

export const mutations = {
  add(state, text) {
    state.list.push({
      text: text,
      done: false
    })
  },
  remove(state, { todo }) {
    state.list.splice(state.list.indexOf(todo), 1)
  },
  toggle(state, todo) {
    todo.done = !todo.done
  }
}
Enter fullscreen mode Exit fullscreen mode

Each module's mutations, actions & states are now available using the context object $store:

// /components/todo.vue
<template>
  <ul>
    <li v-for="todo in todos">
      <input type="checkbox" :checked="todo.done" @change="toggle(todo)">
      <span>{{ todo.text }}</span>
    </li>
    <li><input placeholder="What needs to be done?" @keyup.enter="addTodo"></li>
  </ul>
</template>

<script>
import { mapMutations } from 'vuex'

export default {
  computed: {
    todos () {
      return this.$store.state.todos.list // highlight-line
    }
  },
  methods: {
    addTodo (e) {
      this.$store.commit('todos/add', e.target.value) // highlight-line
      e.target.value = ''
    },
    ...mapMutations({ // highlight-line
      toggle: 'todos/toggle' // highlight-line
    }) // highlight-line
  }
}
</script>
Enter fullscreen mode Exit fullscreen mode

Documentation

Updating a store before rendering a component

Sometimes you need to fill up a given state variable before rendering a component, here's how:

// In any component

export default {
  // Called before rendering the component
  fetch ({ store, params }) {
    return axios.get('https://dog.ceo/api/breeds/image/random')
    .then((res) => {
      store.commit('setDog', res.data.message)
    })
  }
}
Enter fullscreen mode Exit fullscreen mode

Warning: You don't have access of the component instance through this inside fetch because it is called before initiating the component (read more).

Documentation

Changing a page's head properties dynamically

For SEO purposes, defining the page's title, description keywords etc. can be useful. Here's how you can do it programmatically:

// In any component
export default {
  head: {
    title: 'Page title',
    meta: [
      { 
        hid: 'description', name: 'description', 
        content: 'Page description' 
      }
    ],
    // ...
  }
}
Enter fullscreen mode Exit fullscreen mode

Info: To avoid duplicated meta tags when used in child component, set up an unique identifier with the hid key for your meta elements (read more).

Documentation

SSR for dynamic routes

When running nuxt generate, the HTML file for your dynamic routes won't be generated by default.

For example, if you have an about.vue page and a _id.vue one, when running nuxt generate, the resulting dist folder will contain /about/index.html but won't generate anything for your dynamic _id.vue.

This can lead to your dynamic routes to be missed by crawlers, and therefore not referenced by search engines !

Here's how you can generate them automacially:

// nuxt.config.js

module.exports = {
  // ...

  // dynamicRoutes could be a JSON file containing your dynamic routes
  // or could be retrieved automatically based on the content of your /pages folder
  generate: {
    routes: () => {
      return dynamicRoutes.map(route => `/articles/${route}`)
    },
  },

  // ...
}
Enter fullscreen mode Exit fullscreen mode

nuxt generate will now generate the HTML file for each dynamic route returned by the generate property.

Documentation

Displaying a fixed component throughout your app

Sometimes you need to add a navbar or a footer that will be displayed no matter the current route.

There's a /layout folder that contains default.vue by default. This layout holds the <nuxt/> component that takes care of rendering the content of each one of your pages (see Creating a new route).

Simply modify that component to fit your needs, for example:

<template>
  <div>
    <navbar/>
    <nuxt/>
    <footer/>
  </div>
</template>

<script>
import navbar from "~/components/navbar/navbar"
import footer from "~/components/footer/footer"

export default {
  components: {
    cmpNavbar,    
    cmpFooter,
  },  
}
</script>
Enter fullscreen mode Exit fullscreen mode

Documentation

Changing a project's router base

In some cases, when for example you're deploying your project on Github Pages under username/my-project, you'll need to change the project's router base so that your assets are displayed correctly.

// nuxt.config.js

// Will change the router base to /my-project/ when DEPLOY_ENV equals GH_PAGES
const routerBase = process.env.DEPLOY_ENV === "GH_PAGES"
  ? {
    router: {
      base: "/my-project/",
    },
  }
  : {
    router: {
      base: "/",
    },
  }

module.exports = {  
  // ...
  routerBase,
  // ...
}
Enter fullscreen mode Exit fullscreen mode

And don't forget to change your package.json so that nuxt.config.js knows when you're building or generating for Github Pages.

// package.json

"scripts": {
  "build:gh-pages": "DEPLOY_ENV=GH_PAGES nuxt build",
  "generate:gh-pages": "DEPLOY_ENV=GH_PAGES nuxt generate"
},
Enter fullscreen mode Exit fullscreen mode

Handling internationalization (i18n)

Start by running yarn add vue-i18n

Create the following file:

// /plugins/i18n.js

import Vue from "vue"
import VueI18n from "vue-i18n"

Vue.use(VueI18n)

export default ({ app, store }) => {

  // Set i18n instance on app
  // This way we can use it globally in our components
  app.i18n = new VueI18n({
    locale: store.state.locale,
    fallbackLocale: "fr",
    messages: {
      // Add the supported languages here AND their associated content files
      en: require("~/static/json/data-en.json"),
      fr: require("~/static/json/data-fr.json"),      
    },
  })
}
Enter fullscreen mode Exit fullscreen mode

And add the following line in your nuxt.config.js to inform it we're using that plugin:

module.exports = {
  // ...
  plugins: ["~/plugins/i18n.js"],
  // ...
}
Enter fullscreen mode Exit fullscreen mode

In this example, the current locale is based on my store's content, which looks like so:

export const state = () => ({
  locales: ["en", "fr"],
  locale: "fr",
})

export const mutations = {
  setLanguage(state, locale) {
    if (state.locales.indexOf(locale) !== -1) {
      state.locale = locale
    }
  },
}
Enter fullscreen mode Exit fullscreen mode

So whenever we call setLanguage, the locale is automatically updated and the correct JSON file is loaded ! ✨

Your file contents are now available throughout your application like so:

// Here we access the 'users' array in our JSON file
this.$t("users")
Enter fullscreen mode Exit fullscreen mode

Documentation

Importing a font to your project

// nuxt.config.js

module.exports = {
  /*
   ** Headers of the page
   */
  head: {    
    // ...
    link: [
      {
        rel: "stylesheet",
        href: "https://fonts.googleapis.com/css?family=Lato",
      },
    ],
  },

  // ...
}
Enter fullscreen mode Exit fullscreen mode

Wrapping up

Alright, I believe that's enough for one article. I've covered lots of use-cases which hopefully will be useful to some of you.

If you have any questions or want to add anything to this article, feel free to message me on Twitter @christo_kade, and make sure to follow me to be informed of any new articles I write or fun discoveries related to Javascript & CSS πŸ˜„

Top comments (7)

Collapse
 
israelmuca profile image
Israel MuΓ±oz

This is super cool!
I've been using Nuxt for the last 6 months and the more I use it the more I like it!

Btw Nuxt has an i18n library that doesn't need initialization in a plugin, just a new property on nuxt.config.js!

Collapse
 
christopherkade profile image
Christopher Kade

So glad you like it !

I'll make sure to check it out and mention it, thanks Israel πŸ˜„

Collapse
 
ajayts07 profile image
ajayts07

If you're working on NuxtJS project, then I would recommend trying out this Best NuxtJS Admin Template

Materio – Free Vuetify NuxtJS 3 Admin Template The most developer friendly and highly customizable Admin template.

Collapse
 
kp profile image
KP

@christopherkade amazing post, thank you!
I love Nuxt but still think it is very complicated - there's a lot of configuration / APIs involved and there's a lot to learn. Seems like a moving target...I appreciate the SSR part of it nonetheless.

Would you mind doing a Nuxt.js tutorial on Ajax CRUD and fetching a feed using Axios?

Collapse
 
joelvarty profile image
Joel Varty

Thanks for this!
I've been using Nuxt for approx 2 days haha. Just got it integrated with a CMS for routing and stuff - really cool tool for static site generation.

Collapse
 
j0e profile image
Jochen Gererstorfer

Which CMS do you use?

Collapse
 
joelvarty profile image
Joel Varty

Agility CMS!