Nuxt.js — gh-pages deployment

4 min readFeb 19, 2019

https://github.com/akozyreva/nuxt-gh-pages

New technologies — new problems: I wasted several hours to publish my nuxt project on gh-pages and it was real pain. Now I want to explain, how to publish your static app in 5 minutes.

Create nuxt-app project for publishing.

Firstly, we need to create a simple nuxt-app project — for that, please open terminal and execute the following command:

npx create-nuxt-app nuxt-gh-pages

After that you will be asked about properties of project: name, author, etc. I advise you to leave the values by default, simply pressing Enter on answers:

After finishing of installation, you can run locally app, using following commands:

cd nuxt-gh-pages
npm run dev

And on localhost:3000 you see you nuxt-app:

More pages in app!

By default we have only one page in the site. Let me to create another one for making our example more representative. Open project folder (nuxt-gh-pages) and in folder pages create file about.vue with the following content:

<template lang="html">
  <div class="">
    About 
  </div>
</template><script>
export default {
}
</script><style lang="css" scoped>
</style>

Brief explanation: in Nuxt in folder pages contains files, which specify pages of your site. Every *.vue file is page(and available in site by the name of *.vue file). index.vue is the main page of your site. If you want to add page for your site, simply add *.vue file in your pages dir.

So, in our example we’ve created page About, which now is available, if you visit your http://localhost:3000/about :

Connection with the Github

Now it’s time to put our project on the Github for synchronisation. Open Github and create new repository, naming it nuxt-gh-pages — you see starting page of project:

Now in you terminal, being in project folder, interrupt process of running server, pressing CTRL+C, and type the following:

git add .
git commit -am "first commit"
git remote add git@github.com:<your-nick-on-github>/nuxt-gh-pages.git
git push -u origin master

Well done! What’s next?

Reconfiguration of nuxt.config.js for gh-pages deploying

And now let’s open nuxt.config.js in our project and edit it for deploying.

First of all, in module.exports section change mode to ‘spa’ and add configuration for router:

module.exports = {
  mode: 'spa',
  router: {
     base: '/nuxt-gh-pages/'
   },
.....
}

‘spa’ means, that our app is simply static, in router section we specify the name of repository, which will be used for rendering site.

Next go in the terminal and run:

npm run generate

It will generate dist folder with all static information of our site:

Gh-pages package

For deploying on Github pages I usually use gh-pages package — it allows to push directory dist in gh-pages branch in your project. Please, execute the following in your project:

npm install gh-pages --save-dev

And in your package.json file in scripts section, add “deploy” script:

"scripts": {
    "dev": "nuxt",
    "build": "nuxt build",
    "start": "nuxt start",
    "generate": "nuxt generate",
     "deploy": "gh-pages -d dist"
  },....

Finally, run in terminal:

npm run deploy

Next open your project in Github and open Settings section. In Section “GitHub Pages” you see the message, that your site is published:

My site now is available by url: https://akozyreva.github.io/nuxt-gh-pages/ You can also see about page: https://akozyreva.github.io/nuxt-gh-pages/about/

Problem? Do you see only white screen?

You’re trying to open your site and see only white screen? I know, in what can be problem. Please open your project in gh-pages branch and add manually empty .nojekyll file in project. Somehow it can be ignored while deploying site on gh-pages.

So, it works! Don’t hesitate to ask questions, if you have them!

Links:

https://nuxtjs.org/faq/github-pages/