How to deploy on GitHub Pages?

Nuxt.js gives you the possibility to host your web application on any static hosting like GitHub Pages for example.

To deploy on GitHub Pages, you need to generate your static web application:

  1. npm run generate

It will create a dist folder with everything inside ready to be deployed on GitHub Pages hosting. Branch gh-pages for project repository OR branch master for user or organization site

Info: If you use a custom domain for your GitHub Pages and put CNAME file, it is recommended that CNAME file is put in the static directory. More documentation about it.

Deploying to GitHub Pages for repository

First of all, you want to make sure to use static target since we are hosting on GitHub pages:

nuxt.config.js

  1. export default {
  2. target: 'static'
  3. }

If you are creating GitHub Pages for one specific repository, and you don’t have any custom domain, the URL of the page will be in this format: http://<username>.github.io/<repository-name>.

If you deployed dist folder without adding router base, when you visit the deployed site you will find that the site is not working due to missing assets. This is because we assume that the website root will be /, but in this case it is /<repository-name>.

To fix the issue we need to add router base configuration in nuxt.config.js:

nuxt.config.js

  1. export default {
  2. target: 'static',
  3. router: {
  4. base: '/<repository-name>/'
  5. }
  6. }

This way, all generated path asset will be prefixed with /<repository-name>/, and the next time you deploy the code to repository GitHub Pages, the site should be working properly.

Command line deployment

You can also use push-dir package:

First install it via npm:

  1. npm install push-dir --save-dev

Add a deploy command to your package.json with the branch as gh-pages for project repository OR master for user or organization site.

  1. "scripts": {
  2. "dev": "nuxt",
  3. "generate": "nuxt generate",
  4. "start": "nuxt start",
  5. "deploy": "push-dir --dir=dist --branch=gh-pages --cleanup"
  6. },

Then generate and deploy your static application:

  1. npm run generate
  2. npm run deploy

Build server deployment

You can take deployment one step further and rather than having to manually compile and deploy the files from your local install, you can make use of a build server to monitor your GitHub repository for new commits and then checkout, compile and deploy everything for you automatically.

Before you configure the build server, you’ll first need to generate a GitHub personal access token in order to grant the build server permission to perform tasks on your behalf. Once you have created your token, keep a copy of it safe ready to use a little later on.

Travis CI

To deploy with Travis CI, a free for open source projects build server, sign in via your GitHub account, granting Travis access to view your repositories, and then enable the build server for your repository by toggling the switch next to your repositories name in the list displayed.

Travis Builder Server Enable

Next, click the cog icon beside your repository name to configure the general settings of the build sever and enable the ‘Build only if .travis.yml is present’ feature by toggling the switch.

Travis Builder Server Settings

On the same screen, scroll down to the Environment Variables section and create a new variables named GITHUB_ACCESS_TOKEN and in the value field paste a copy of the GitHub personal access token your created earlier and click the ‘Add’ button.

Travis Builder Server Environment Variables

Finally, create a .travis.yml configuration file in the root of your repository with the following contents

  1. language: node_js
  2. node_js:
  3. - '8'
  4. cache:
  5. directories:
  6. - 'node_modules'
  7. branches:
  8. only:
  9. - master
  10. install:
  11. - npm install
  12. - npm run generate
  13. script:
  14. - echo "Skipping tests"
  15. deploy:
  16. provider: pages
  17. skip-cleanup: true
  18. github-token: $GITHUB_ACCESS_TOKEN # Set in travis-ci.org dashboard, marked secure https://docs.travis-ci.com/user/deployment/pages/#Setting-the-GitHub-token
  19. target-branch: gh-pages
  20. local-dir: dist
  21. on:
  22. branch: master

and then commit this to your repository

  1. git add .travis.yml
  2. git commit -m "Adding travis deploy configuration"
  3. git push origin

Now, whenever you commit any changes to your repository, from within Travis, you’ll see a new build start up

Travis Builder Server Output

and on completion, you’ll see your GitHub pages site automatically updated.

Appveyor

To deploy via Appveyor, another free for open source projects build server, sign up for a new account choosing the GitHub authentication option to sign in using your GitHub account.

Once signed in, click the ‘New project’ link and then click the ‘Add’ button beside your repository name in the list displayed to enable the build server on your repository.

Appveyor Builder Server Enable

Next, in the root of your repository, create an appveyor.yml configuration file with the following contents

  1. environment:
  2. # Nuxt requires node v8 minimum
  3. nodejs_version: '8'
  4. # Encrypt sensitive data (https://ci.appveyor.com/tools/encrypt)
  5. github_access_token:
  6. secure: ENCRYPTED_GITHUB_ACCESS_TOKEN
  7. github_email:
  8. secure: ENCRYPTED_GITHUB_EMAIL
  9. # Only run on master branch
  10. branches:
  11. only:
  12. - master
  13. # Install scripts. (runs after repo cloning)
  14. install:
  15. # switch nodejs version
  16. - ps: Install-Product node $env:nodejs_version
  17. # install modules
  18. - npm install
  19. # generate static files
  20. - npm run generate
  21. # configure global git credentials store (https://www.appveyor.com/docs/how-to/git-push/)
  22. - git config --global credential.helper store
  23. - ps: Add-Content "$env:USERPROFILE\.git-credentials" "https://$($env:github_access_token):x-oauth-basic@github.com`n"
  24. - git config --global user.email $env:github_email
  25. # deploy to GitHub pages
  26. - npm run deploy
  27. # No tests to run
  28. test: off
  29. # Don't actually build.
  30. build: off

NB This configuration assumes you’ve configured your package.json file as per the Command line deployment instructions

Before you commit this file however, you’ll need to change the ENCRYPTED_GITHUB_ACCESS_TOKEN and ENCRYPTED_GITHUB_EMAIL variables with your GitHub personal access token from earlier and your GitHub email address, encrypted using the Appveyor encryption tool.

Once updated, commit the file to your repository

  1. git add appveyor.yml
  2. git commit -m "Adding appveyor deploy configuration"
  3. git push origin

Now, whenever you commit any changes to your repository, from within Appveyor, you’ll see a new build start up

Appveyor Builder Server Output

and on completion, you’ll see your GitHub pages site automatically updated.