Phil's Notes

Migrating a Vue 3 Project from Vue CLI to Vite

javascriptvue

Recently I migrated a Vue 3 project from Vue CLI to Vite. During the process, I took a bunch of notes. This project was using Javascript as opposed to TypeScript, so you might need to take that into account.

In my project, I will not be supporting older browsers, but Vite does have an official plugin for legacy browsers which you can find here:

https://github.com/vitejs/vite/tree/main/packages/plugin-legacy

package.json

First things first, you want to remove the @vue/cli-service package from your project as well as any other Vue CLI plugins you might have. You can remove the @vue/cli-service package with this command:

npm un @vue/cli-service

In your package.json file, you also want to make sure you remove any dependencies that start with "@vue/cli-plugin". Here's an example of what was in mine:

"devDependencies": {
    "@vue/cli-plugin-babel": "~4.5.0",
    "@vue/cli-plugin-eslint": "~4.5.0",
    "@vue/cli-plugin-router": "~4.5.0",
    "@vue/cli-plugin-vuex": "~4.5.0",
    // plus others
}

You can remove all of those at one with a command like this:

npm un @vue/cli-plugin-babel @vue/cli-plugin-eslint @vue/cli-plugin-router @vue/cli-plugin-vuex

Since I'm not supporting older browsers, I'm also removing babel:

npm un babel-eslint

Also, I need to delete the babel.config.js file.

Once all of those have been removed, add Vite and the @vitejs/plugin-vue as dev dependencies to your project.

npm i vite @vitejs/plugin-vue -D

Now, inside your package.json file, you will also want to add a "dev" script that you will use to start the local server for testing instead of using "serve" anymore as with Vue CLI. There will still be a "serve" script, but it is used to preview the production build locally, so instead of using "npm run serve" to test and develop, use "npm run dev" instead.

You will also want to change your build and lint scripts in that file as well. Just replacing vue-cli-service with vite should do the trick. Here's my old scripts section:

"scripts": {
    "serve": "vue-cli-service serve",
    "build-dev": "vue-cli-service build --mode development", // This is one I added
    "build": "vue-cli-service build",
    "lint": "vue-cli-service lint"
}

And my new one:

"scripts": {
    "dev": "vite", // Use this to test locally
    "serve": "vite preview",
    "build-dev": "vite build --mode development", // This is one I added
    "build": "vite build",
    "lint": "vite lint"
}

index.html

With Vue CLI, the index.html file is in public/index.html. You should move that file over to your project root directly instead.

You won't need to use the BASE_URL variable to find your favicon anymore, so replace:

<link rel="icon" href="<%= BASE_URL %>favicon.ico">

With this:

<link rel="icon" href="/favicon.ico">

Vite will check your public folder for the favicon.

Vite does not auto-inject the main.js file into the index.html page, so you will need to add this line underneath the line:

<script type="module" src="/src/main.js"></script>

vite.config.js

In the root folder, create the file vite.config.js. Inside, paste this code:

import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
 
// https://vitejs.dev/config/
export default defineConfig({
  plugins: [vue()]
})

If in your old vue.config.js file you have publicPath defined, you can add that right underneath the plugins line in your vite.config.js like this:

export default defineConfig({
    plugins: [vue()],
    base: '/YourBasePath/'
  })

And if you need to have a different port number, you can also do so by adding this line under the plugins line:

server: { port: 8080 } // Or specify a different port number

If you've been using the @ alias in your paths, you will also want to add this under the plugins line:

resolve: {
        alias: [
            {
            find: '@',
            replacement: path.resolve(__dirname, 'src')
            }
        ]
    }

And to use the above, you will also need to import path like so:

import path from "path"

Once you have that all configured, you can delete the old vue.config.js file. Here's what my completed vite.config.js file looks like:

import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import path from 'path'
 
// https://vitejs.dev/config/
export default defineConfig({
  plugins: [vue()],
  base: '/NewBasePath/',
  server: { port: 8080 },
  resolve: {
      alias: [
          {
              find: '@',
              replacement: path.resolve(__dirname, 'src')
          }
      ]
  }
})

Environment Variables

If you are using any environment variables (.env, .env.development, .env.production, etc.), you will want to change the VUE_APP_ prefix to VITE_.

Whenever you need to use your environment variables in your code, you should now use import.meta.env.YOUR_VARIABLE_NAME instead of process.env.YOUR_VARIABLE_NAME.

For example, instead of using:

process.env.VUE_APP_TITLE

Use:

import.meta.env.VITE_TITLE

.vue Extensions

One more thing you want to be aware of is when you are importing your components, you will now want to include the .vue extension, otherwise, Vite will not be able to find it. If you miss that step anywhere, you'll get an error in the console like this:

Uncaught (in promise) TypeError: Cannot destructure property ‘default' of ‘undefined' as it is undefined.

That's It

Hopefully, this guide was able to help you out and you start enjoying how fast you can work with Vite is.