The Vue CLI: current setup and migration guide

Vue CLI was the standard way to create a Vue application for several years.

It is now in maintenance mode. Do not install Vue CLI to start a new project. The Vue team recommends the official create-vue tool, which creates a Vite-based Vue project.

This article shows the current workflow and then explains what to do when you inherit an older Vue CLI project.

How do you create a Vue project today?

Install a current supported version of Node.js, open the terminal in the directory where you keep your projects, and run:

npm create vue@latest

This downloads and runs create-vue. You do not need to install it globally.

The command asks for a project name and offers optional features such as:

• TypeScript
• JSX
• Vue Router
• Pinia
• Unit and end-to-end testing
• ESLint
• Prettier

Choose only what the project needs. You can add another feature later.

Once the project is created, enter its directory and install the dependencies:

cd my-vue-app
npm install

Start the development server:

npm run dev

Vite prints the local URL in the terminal. Open that URL in the browser and edit src/App.vue to see updates.

How do you create a production build?

Run:

npm run build

Vite builds the production files in dist.

You can inspect that build locally:

npm run preview

preview is useful for checking the output. It is not intended to be your production server.

Where is the configuration?

A project generated by create-vue normally has a vite.config.js or vite.config.ts file.

A basic configuration looks like this:

import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'

export default defineConfig({
  plugins: [vue()]
})

Vite has sensible defaults, so many projects need very little configuration.

The generated package.json contains the available scripts. Run those scripts with npm run, rather than depending on a globally installed command.

What happened to Vue CLI?

Vue CLI is the older webpack-based toolchain. It uses packages such as @vue/cli-service and normally keeps its custom configuration in vue.config.js.

An existing Vue CLI project may still have scripts like these:

{
  "scripts": {
    "serve": "vue-cli-service serve",
    "build": "vue-cli-service build",
    "lint": "vue-cli-service lint"
  }
}

You can continue to run them:

npm install
npm run serve

Maintenance mode does not mean that every old project suddenly stops working. It means the tool is no longer the recommended foundation for new applications and does not receive normal feature development.

Pin the project’s dependency versions, keep an eye on security advisories, and test upgrades carefully.

Should you migrate a Vue CLI project to Vite?

For an actively developed project, migration is usually worth considering. Vite normally starts faster and gives quicker updates during development.

Do not treat it as a blind package replacement. Vue CLI and Vite use different configuration systems and make different assumptions.

Check these areas one at a time:

Environment variables

Vue CLI exposes client variables beginning with VUE_APP_:

process.env.VUE_APP_API_URL

Vite exposes variables beginning with VITE_ through import.meta.env:

import.meta.env.VITE_API_URL

Both values become part of the browser bundle. Never put a secret in either kind of client environment variable.

Configuration and plugins

Translate settings from vue.config.js to vite.config.js.

Webpack loaders and plugins do not work directly in Vite. Find the Vite equivalent, use a framework plugin, or replace the custom build behavior.

Pay particular attention to aliases, CSS preprocessors, SVG handling, legacy-browser requirements, and any custom webpack chain.

Static files and HTML

Review files in public, references to %BASE_URL%, and custom HTML template interpolation.

Vite serves public files from the root path, but its HTML processing is different from Vue CLI’s webpack setup.

Tests

Run the existing unit and end-to-end tests before the migration so you have a baseline.

If the project uses Jest through Vue CLI, you can keep Jest at first or migrate tests separately to Vitest. Changing the app build and the test runner at the same time makes failures harder to diagnose.

Vue 2 versus Vue 3

Migrating the build tool does not automatically migrate the application from Vue 2 to Vue 3.

Treat those as separate projects. A Vue 2 application may use the Vite plugin intended for Vue 2, while a Vue 3 application uses @vitejs/plugin-vue. Check every dependency for compatibility before changing the framework version.

What should you use for quick experiments?

For a real project, use create-vue.

For a small example, the Vue Playground lets you edit a Vue single-file component in the browser. You can also load Vue directly from a CDN when you want to try the framework without a build step.

The old Vue CLI global serve command is no longer the best starting point for this.

See the official Vue quick start for the current setup and the Vue tooling guide for the Vue CLI maintenance status and migration resources.

Related posts about vue: