Custom routes with Nuxt.js

Update: https://github.com/nuxt-community/router-module the nuxt-community router module is available!

Nuxt.js is a framework for Vue.js developers which minimises the work required to setup a Vue application and provides at the same time the freedom to extend or customise its core functionalities.

In this article I’ll show how Nuxt automatically generates the vue-router configuration by parsing the files in your pages directory. Secondly I’ll present a case, or rather localised paths, where it is required to ‘switch off’ automatic routes generation and to manually create the vue-router configuration through a Nuxt module.

Nuxt.js Routes

The way routes are generated it’s pretty simple: assuming you have your Nuxt.js project set up it’s enough add a file with extension .vue within the pages directory.

During the build Nuxt will check what is inside the pages directory and for each file found a route will be added to the vue-router configuration. The name given to the file will correspond to the route path and the route name.

Nuxt can also handle nested routes or dynamic routes. In the first case it’s enough to add a sub-folder with your page component. In the second case prefixing a page component or a sub-folder with an underscore will do the trick. The example below show the combination of the two.

And the generated vue-router configuration.

Having Nuxt handling the routes setup it’s extremely useful because it allows us to maximise our time and productivity focusing on the development of the features we want to bring to our end-users.

However, there are some cases where the vue-router configuration needs some additional work, and therefore it is needed to manually create it, without Nuxt doing it for you.

Localised paths

Let’s consider a running Nuxt.js application listening for requests coming from different country domains and which requires the path of each page to be localised. For example, for the about-us.vue it is required to have:

mydomain.com/about-us
mydomain.fr/qui-sommes-nous
mydomain.es/quienes-somos

If I like to keep Nuxt handling the routes for me, then I could create different files within the pages directory, each one with its localised name, and import in any of them a component responsible for the template and the i18n part.

Despite this approach might seem a quick win it’s actually not a good solution as it creates duplication and it increases the complexity of your app.

A better solution is to define aliases for your routes. With aliases you can have multiple path names associated to a single page component.

Since Nuxt generates the vue-router configuration by looking at the files names in the page directory, there is no way to communicate the intention of having aliases.

In this case Nuxt needs to know that you don’t want the router.js to be generated but instead you want to manually create it yourself. Here’s is where modules come to help us.

Nuxt.js Modules

Modules are a clever approach adopted by the Nuxt.js team to give to the developers the freedom to extend or modify core functionalities. Modules are functions that run just before the end of the application boot. This allows to access and customise almost any aspect of the framework, and so the routes.

To manually create the vue-router configuration simply add a file to the modules folder.

And in the module add the code below.

This will disable the parsing of the pages components for the creation of routes and will indicate the router.js file in the main directory as the one responsible for the vue-router configuration.

Now you can add the required configuration in the router.js file.

Thanks to the use of a module the vue-router configuration is now manually setup for the use of aliases so that multiple localised paths can reference to a single page component.

Hope you found that useful!