❤
npm
Sign UpSign In

@stefandesu/vite-test-library

0.2.1 • Public • Published

vite-test-library

Test and build GitHub package version NPM package name standard-readme compliant

Using Vite for creating Vue 3 component libraries.

Table of Contents

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:

  • [x] Add pre-commit rules
  • [ ] Add testing
    • See here for Vue-specific testing
  • [x] Add dev branch and adjust release script accordingly
  • [ ] Extend README
  • [x] 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.

License

MIT Copyright (c) 2021 Stefan です

Readme

Keywords

none

Package Sidebar

Install

npm i @stefandesu/vite-test-library

Weekly Downloads

1

Version

0.2.1

License

MIT

Unpacked Size

19.5 kB

Total Files

13

Last publish

Collaborators

  • stefandesu
Try on RunKit
Report malware