vite-test-library

Using Vite for creating Vue 3 component libraries.

Background
To-Dos for adjusting to your project
Development
Using the library
- Node
- Browser
Note about external dependencies
Notes about building a Vue 3 application with Vite
Publish
License

Background

We need to create some Vue 3 component libraries and I wanted to use Vite for this since it offers a great developer experience. A fast hot-reloading dev server as well as fast builds are already included, making it the obvious choice. However, creating a component library with it wasn't as easy as I had hoped. I had trouble in particular with it being tree-shakable. I'm still not sure whether I'm doing things correctly, but they seem to be working as expected.

Some requirements:

Use Vite for development and builds.
Offer browser builds.
Allow it to be tree-shakable when used as a dependency in another project. (This means that only the code that is really used is going to be included in a build.)
Add other developer tools that we are using (ESLint via eslint-config-gbv, testing, etc.).

To-dos:

Add pre-commit rules
Add testing
- See here for Vue-specific testing
Add dev branch and adjust release script accordingly
Extend README
Add GitHub workflows for tests, building, and releases (GitHub + npm)
Consider adding JSDoc for documentation
Consider adding TypeScript declaration files (we might be able to generate these from JSDoc tags after we added them)
Figure out why built library does not work in https://observablehq.com

To-Dos for adjusting to your project

Copy this repo: npx degit https://github.com/stefandesu/vite-test-library.git your-library-name
Update GitHub release workflow: sed -i '' 's/vite-test-library/your-library-name/g' .github/workflows/release.yml
Update package.json:
- sed -i '' 's/vite-test-library/your-library-name/g' package.json
- Also adjust name (namespace), version, author, description
Adjust package name in vite.config.js
Adjust README
- Badges
- ...
Adjust license if necessary
Create Git repository: git init -b main
Add remote and push repo to GitHub
- ...
Add NPM_TOKEN secret to GitHub project (Settings - Secrets - New repository secrets)
Create a dev branch and push it to GitHub:
- git checkout -b dev
- git push -u origin dev
...

Development

git clone https://github.com/stefandesu/vite-test-library.git
cd vite-test-library
npm install
npm run dev # for Vite dev server
npm run build # for Vite build

Using the library

Node

1. Add the library to your Vue project:

npm install @stefandesu/vite-test-library

2a. Add all components globally (in src/main.js for your project):

import { createApp } from 'vue'
import App from './App.vue'

const app = createApp(App)

import * as ViteTestLibrary from "@stefandesu/vite-test-library"
app.use(ViteTestLibrary)

// Import stylesheet
import "@stefandesu/vite-test-library/dist/style.css"

app.mount('#app')

2b. Add individual components globally (tree-shakable):

import { createApp } from 'vue'
import App from './App.vue'

const app = createApp(App)

import { Bold } from "@stefandesu/vite-test-library"
app.use(Bold)

// Import stylesheet
import "@stefandesu/vite-test-library/dist/style.css"

app.mount('#app')

2c. Add individual components where needed (e.g. in some SFC, tree-shakable):

import { defineComponent } from "vue"
import { Bold } from "@stefandesu/vite-test-library"
// Import stylesheet
import "@stefandesu/vite-test-library/dist/style.css"

export default defineComponent({
  // ...
  components: {
    Bold,
  },
  // ...
})

Browser

The library can be used in the browser, for example via jsDelivr.

Fully working HTML example:

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Vue App</title>
    <!-- Our library's stylesheet here (adjust version if necessary) -->
    <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@stefandesu/vite-test-library@0.2/dist/style.css">
  </head>
  <body>
    <div id="app">
      <Bold>
        Test bold
      </Bold>
      <Italic>
        Test italic
      </Italic>
    </div>
    <!-- Vue 3 production build -->
    <script src="https://cdn.jsdelivr.net/npm/vue@3/dist/vue.global.prod.js"></script>
    <!-- Our library (adjust version if necessary) -->
    <script src="https://cdn.jsdelivr.net/npm/@stefandesu/vite-test-library@0.2/dist/vite-test-library.umd.min.js"></script>
    <script>
      // Here, we are creating an empty Vue app and include the library as a plugin.
      Vue.createApp({}).use(ViteTestLibrary).mount("#app")
    </script>
  </body>
</html>

Note about external dependencies

As an example, a component ItemName was added to this repository that depends on jskos-tools. However, jskos-tools is not part of the build, which means that it must be installed via npm or included via the <script> tag.

The nice thing about this is that if that particular component is not used or needed, it is not necessary to install/include jskos-tools.

Notes about building a Vue 3 application with Vite

Legacy browser support

By default, only modern browsers are supported by Vite's builds. In most cases, legacy browsers (which does not mean IE11, but rather older versions of Firefox and Chrome) should be supported as well. It is recommended to use @vitejs/plugin-legacy for this.

Base path

In many cases, applications will not be hosted under the root base path (/). In those cases, it is necessary to define the base option in vite.config.js, or provide it as an argument for the build command. See also: Vite Docs: Public Base Path

Defining environment variables

Some packages use the process.browser variable to determine whether the code is run in the browser or in Node.js. Vite's build does not define this variable by default. If necessary, it can be defined in vite.config.js like this:

export default defineConfig({
  // ...
  define: {
    "process.browser": true,
  },
})

For a detailed example that also includes other process.env variables, see the vite.config.js in coli-ana.

Publish

Please work on the dev branch during development (or better yet, develop in a feature branch and merge into dev when ready).

When a new release is ready (i.e. the features are finished, merged into dev, and all tests succeed), run the included release script (replace "patch" with "minor" or "major" if necessary):

npm run release:patch

This will:

Check that we are on dev
Run tests and build to make sure everything works
Make sure dev is up-to-date
Run npm version patch (or "minor"/"major")
Push changes to dev
Switch to main
Merge changes from dev
Push main with tags
Switch back to dev

After running this, GitHub Actions will automatically publish the new version to npm. It will also create a new GitHub Release draft. Please edit and publish the release draft manually.

stefandesu/vite-test-library