Vue CLI

⚠️ Vue CLI is in Maintenance Mode!

For new projects, it is now recommended to use create-vue to scaffold Vite-based projects. Also refer to the Vue 3 Tooling Guide for the latest recommendations.

Deployment

General Guidelines

If you are using Vue CLI along with a backend framework that handles static assets as part of its deployment, all you need to do is make sure Vue CLI generates the built files in the correct location, and then follow the deployment instruction of your backend framework.

If you are developing your frontend app separately from your backend - i.e. your backend exposes an API for your frontend to talk to, then your frontend is essentially a purely static app. You can deploy the built content in the dist directory to any static file server, but make sure to set the correct publicPath.

Previewing Locally

The dist directory is meant to be served by an HTTP server (unless you've configured publicPath to be a relative value), so it will not work if you open dist/index.html directly over file:// protocol. The easiest way to preview your production build locally is using a Node.js static file server, for example serve:

npm install -g serve
# -s flag means serve it in Single-Page Application mode
# which deals with the routing problem below
serve -s dist

Routing with history.pushState

If you are using Vue Router in history mode, a simple static file server will fail. For example, if you used Vue Router with a route for /todos/42, the dev server has been configured to respond to localhost:3000/todos/42 properly, but a simple static server serving a production build will respond with a 404 instead.

To fix that, you will need to configure your production server to fallback to index.html for any requests that do not match a static file. The Vue Router docs provide configuration instructions for common server setups.

CORS

If your static frontend is deployed to a different domain from your backend API, you will need to properly configure CORS.

PWA

If you are using the PWA plugin, your app must be served over HTTPS so that Service Worker can be properly registered.

Platform Guides

GitHub Pages

Pushing updates manually

  1. Set correct publicPath in vue.config.js.

    If you are deploying to https://<USERNAME>.github.io/ or to a custom domain, you can omit publicPath as it defaults to "/".

    If you are deploying to https://<USERNAME>.github.io/<REPO>/, (i.e. your repository is at https://github.com/<USERNAME>/<REPO>), set publicPath to "/<REPO>/". For example, if your repo name is "my-project", your vue.config.js should look like this:

    // vue.config.js file to be placed in the root of your repository

module.exports = {
  publicPath: process.env.NODE_ENV === 'production'
    ? '/my-project/'
    : '/'
}

  2. Inside your project, create deploy.sh with the following content (with highlighted lines uncommented appropriately) and run it to deploy:













     






     


     



    #!/usr/bin/env sh

# abort on errors
set -e

# build
npm run build

# navigate into the build output directory
cd dist

# if you are deploying to a custom domain
# echo 'www.example.com' > CNAME

git init
git add -A
git commit -m 'deploy'

# if you are deploying to https://<USERNAME>.github.io
# git push -f git@github.com:<USERNAME>/<USERNAME>.github.io.git main

# if you are deploying to https://<USERNAME>.github.io/<REPO>
# git push -f git@github.com:<USERNAME>/<REPO>.git main:gh-pages

cd -

Using Travis CI for automatic updates

  1. Set correct publicPath in vue.config.js as explained above.

  2. Install the Travis CLI client: gem install travis && travis --login

  3. Generate a GitHub access token with repo permissions.

  4. Grant the Travis job access to your repository: travis env set GITHUB_TOKEN xxx (xxx is the personal access token from step 3.)

  5. Create a .travis.yml file in the root of your project.

    language: node_js
node_js:
 - "node"

cache: npm

script: npm run build

deploy:
 provider: pages
 skip_cleanup: true
 github_token: $GITHUB_TOKEN
 local_dir: dist
 on:
   branch: main

  6. Push the .travis.yml file to your repository to trigger the first build.

GitLab Pages

As described by GitLab Pages documentation, everything happens with a .gitlab-ci.yml file placed in the root of your repository. This working example will get you started:

# .gitlab-ci.yml file to be placed in the root of your repository

pages: # the job must be named pages
  image: node:latest
  stage: deploy
  script:
    - npm ci
    - npm run build
    - mv public public-vue # GitLab Pages hooks on the public folder
    - mv dist public # rename the dist folder (result of npm run build)
    # optionally, you can activate gzip support with the following line:
    - find public -type f -regex '.*\.\(htm\|html\|txt\|text\|js\|css\)$' -exec gzip -f -k {} \;
  artifacts:
    paths:
      - public # artifact path must be /public for GitLab Pages to pick it up
  only:
    - master

Typically, your static website will be hosted on https://yourUserName.gitlab.io/yourProjectName, so you will also want to create an initial vue.config.js file to update the BASE_URL value to match your project name (the CI_PROJECT_NAME environment variable contains this value):

// vue.config.js file to be placed in the root of your repository

module.exports = {
  publicPath: process.env.NODE_ENV === 'production'
    ? '/' + process.env.CI_PROJECT_NAME + '/'
    : '/'
}

Please read through the docs on GitLab Pages domains for more info about the URL where your project website will be hosted. Be aware you can also use a custom domain.

Commit both the .gitlab-ci.yml and vue.config.js files before pushing to your repository. A GitLab CI pipeline will be triggered: when successful, visit your project's Settings > Pages to see your website link, and click on it.

Netlify

  1. On Netlify, setup up a new project from GitHub with the following settings:

    • Build Command: npm run build or yarn build
    • Publish directory: dist

  2. Hit the deploy button!

Also checkout vue-cli-plugin-netlify-lambda.

Use history mode on Vue Router

In order to receive direct hits using history mode on Vue Router, you need to redirect all traffic to the /index.html file.

More information on Netlify redirects documentation.

Recomended method

Create a file called netlify.toml in the root of your repository with the following content:

[[redirects]]
  from = "/*"
  to = "/index.html"
  status = 200
Alternative method

Create a file called _redirects under /public with the following content:

# Netlify settings for single-page application
/*    /index.html   200

If you are using @vue/cli-plugin-pwa make sure to exclude the _redirects file from being cached by the service worker. To do so, add the following to your vue.config.js:

// vue.config.js file to be placed in the root of your repository

module.exports = {
  pwa: {
      workboxOptions: {
        exclude: [/_redirects/]
      }
    }
}

Checkout workboxOptions and exclude for more.

Render

Render offers free static site hosting with fully managed SSL, a global CDN and continuous auto deploys from GitHub.

  1. Create a new Static Site on Render, and give Render’s GitHub app permission to access your Vue repo.

  2. Use the following values during creation:

    • Build Command: npm run build or yarn build
    • Publish directory: dist

That’s it! Your app will be live on your Render URL as soon as the build finishes.

In order to receive direct hits using history mode on Vue Router, you need to add the following rewrite rule in the Redirects/Rewrites tab for your site.

  • Source: /*
  • Destination: /index.html
  • Status Rewrite

Learn more about setting up redirects, rewrites and