DEV Community: Josip Ivancic

Build a typescript component library with Vite

Josip Ivancic — Fri, 26 Nov 2021 14:19:11 +0000

Example repo at: https://github.com/josip2312/typescript-lib-vite

Why Vite

Vite ships with a pre-configured build command that has many performance optimizations out of the box. It uses Rollup under the hood and provides an abstraction over the default rollup configuration. This makes it way easier to set up the build step without knowing all the internals of rollup.

Components

For the sake of the example, I'm going to create a simple button component, but the build step remains the same for any number of components. In this example, I'm using the <script setup> syntax.

Component code:

<script setup lang="ts">
import { reactive } from "vue";

interface Props {
  primary?: boolean;
}

const props = withDefaults(defineProps<Props>(), {
  primary: false,
});

const { primary } = reactive(props);
</script>

<template>
  <button class="btn" :class="{ primary }">
    <slot />
  </button>
</template>

<style scoped>
.btn {
  padding: 0.5rem 1rem;
}
.btn.primary {
  background: hsl(239, 100%, 27%);
  color: #fff;
}
</style>

Next, I'm going to create the entry file for the library where all the components will be exported.

// src/index.ts
export { default as MyButton } from "./MyButton";

Vite config

Vite is a fast new build tool that is intended for modern web projects. It uses native ES modules and provides a blazing-fast dev server and hot module replacement. Learn more about it on the official website.

Vite is framework agnostic which means you can use it with most frontend frameworks, and the build config is pretty much the same. There is a section on the official website which describes different build modes, our interest is in the library mode build.

So we need to add the following to our vite.config.ts (or .js).

// vite.config.ts
const path = require("path");
const { defineConfig } = require("vite");

module.exports = defineConfig({
  build: {
    lib: {
      entry: path.resolve(__dirname, "src/index.ts"),
      name: "MyComponentLib",
      fileName: (format) => `my-component-lib.${format}.js`,
    },
    rollupOptions: {
      // make sure to externalize deps that shouldn't be bundled
      // into your library
      external: ["vue"],
      output: {
        // Provide global variables to use in the UMD build
        // for externalized deps
        globals: {
          vue: "Vue",
        },
      },
    },
  },
});

If you now run npm run build you should get the output in the dist folder.

If you're getting an error regarding __dirname or path you need to install node type declarations

npm i -D @types/node

Package.json config

Before testing our build output we need to configure the package.json to point at correct built files. We are defining the entry point to the library.
You can learn more about what each option does by hovering the properties in VS Code.

// "my-component-lib" should match the "name" field in your package.json
{
  "files": ["dist"],
  "main": "./dist/my-component-lib.umd.js",
  "module": "./dist/my-component-lib.es.js",
  "exports": {
    ".": {
      "import": "./dist/my-component-lib.es.js",
      "require": "./dist/my-component-lib.umd.js"
    }
  }
}

Test build output

To test the library locally we can zip the dist file, before running the below change the name field in your package.json to your preferred library name.

Run the following:

npm pack

This command provides us with a zipped file that we can map to the library dependency in the package.json. After running this add the following to the dependencies field:

 "dependencies": {
 "my-component-lib": "my-component-lib-0.0.0.tgz"
  },

After importing the library it should now work.

If you run into dependency errors try deleting the zipped file and packing it again, or deleting the package.lock.json and node_modules and runningnpm install again.

<script setup lang="ts">
import { MyButton } from "my-component-lib";
import "/node_modules/my-component-lib/dist/style.css";
</script>

However, you'll notice we get an error regarding missing declaration files, we will solve this in the next step.

Typescript declarations

To solve the typescript declarations error, we need to generate type declaration files for the components. We will do this using the vue-tsc package.

Make sure to update vue-tsc to a newer version since the create-vue CLI defaults to an older version.

You need to add the following to tsconfig.json:

{
  "outDir": "dist",
  "declaration": true
}

Change the build script to the following:

{
  "build": "vite build && vue-tsc --emitDeclarationOnly && mv dist/src dist/types"
}

Lastly, set the path for the type declarations inside package.json

{
  "types": "./dist/types/index.d.ts"
}

The last command in the build script moves the types to a types directory, by default they would be in a src directory since that is our target inside the tsconfig.

If you now repeat the build and pack process, the type error should not be there.

If it's still there try deleting your node_modules and package.lock.json and installing the packages again.

Publish to npm

Everything is already set up for publishing, you can just authenticate with npm and publish.

npm login # authenticate

npm publish # publish

Conclusion

Vite makes it incredibly easy to build a component library with a very slim config. Coupled with the amazing development experience it provides I can conclude it is the next big thing in frontend development.

Vue 3 and Vite with typescript and tooling

Josip Ivancic — Sat, 20 Nov 2021 13:51:45 +0000

Create-vue

See full example on repo: vue-ts-eslint-template.

Use the repo create-vue to get started, this will be the official way to set up a new Vue project with Vite in the future. After running npm init vue@next choose the options appropriate for your use case.

Volar

The first step is to enable the Volar extension and disable the Vetur extension.
Volar is the new recommended extension to use with Vue 3 and typescript.

Typescript

If you chose the Typescript option offered by the CLI tool you should be good to go.

If you run into some issues regarding types try adding the following to your tsconfig.json

{
  "compilerOptions": {
    ...
    "types": ["vite/cli"], // add this
  }
}

ESLint

You will need several packages, run the commands below in your terminal:

ESLint:

npm i -D eslint eslint-plugin-vue eslint-config-prettier

Typescript:

npm i -D @typescript-eslint/eslint-plugin @typescript-eslint/parser @vue/eslint-config-typescript

Next, create a .eslintrc.js which will look something like this, can be extended to fit your use case.

module.exports = {
  env: {
    node: true,
  },
  globals: {
    defineProps: "readonly",
    defineEmits: "readonly",
    withDefaults: "readonly",
  },
  extends: [
    "@vue/typescript/recommended",
    "eslint:recommended",
    "plugin:vue/vue3-recommended",
    "prettier",
  ],
};

Prettier

You can add a .prettierrc.js with the config that fits your needs.

Example config:

module.exports = {
  singleQuote: true,
  trailingComma: "all",
};

Format on commit

Sass modules with the Vue CLI

Josip Ivancic — Mon, 08 Nov 2021 18:21:58 +0000

The new sass modules are only compatible with Dart Sass which you should be using. More info can be found on the official sass-lang.com page.

See full example on repo: vue-cli-sass.

Not enough people are aware of the announcement of the new Sass module system, of which the primary aim is to replace the @import rule with @use and @forward. It also exposes various built-in modules such as sass:color, sass:map, etc. If you're wondering why you should use @use over @import, in short, @import is being replaced with more explicit @use and @forward rules, it forces you to a more complex setup but will be worth it in the long run, especially if you're building some kind of library or package. Over the next few years Sass @import will be deprecated, and then removed.

The @use rule

The @use rule makes variables, mixins, and functions from another stylesheet available in the current stylesheet. It pretty much does the same thing as @import, but with namespacing. Example from sass-lang.com:

@use "bootstrap";

.element {
  background-color: bootstrap.$body-bg;
  @include bootstrap.float-left;
}

You can also explicitly set the namespace by using as.

@use "bootstrap" as b;

.element {
  @include b.float-left;
}

To include everything in the top-level namespace, use the special * symbol.

@use "bootstrap" as *;

.element {
  @include float-left;
}

The @forward rule

The other important feature of the module system is the @forward rule. It includes another module's variables, mixins, and functions without making them visible to the code within the current module. Basically, it makes it possible to organize across many files and load the styles from a single entry point file.

If you had multiple partial files in a components folder, you would @forward them through an _index.scss entry file. For example:

// components/_index.scss
@forward "buttons";
@forward "tags";

Then you would @use the appropriate stylesheet (pointing to the folder automatically references the _index.scss file).

// styles.scss
@use ‘components’;

To learn more about all the benefits and features introduced with modules, be sure to check out the official sass-lang.com website, there is also a great article on css-tricks.com.

Using it with Vue

Create a new project with the Vue CLI, if you don't have it installed go to vue-cli and follow the instructions given. We need to run:

vue create using-sass-modules # or whatever name you want

After the prompt in the terminal, select manually select features and check the CSS pre-processor option. Choose the rest of the options by your project needs.

Directory structure

First, we will create a directory to hold our styles, I named mine styles. How you organize your directories is your business, but I like to use an architecture similar to the one described in sass-guidelines.es. Inside of styles, we'll have an abstracts, base and utilities folder and inside each one partial file which will be @forward-ed through an _index.scss entry file ending up with this structure:

src/styles
├── abstracts
│   ├── _breakpoints.scss
│   ├── _colors.scss
│   ├── _font.scss
│   ├── _index.scss
│   └── _mixins.scss
├── base
│   ├── _base.scss
│   ├── _index.scss
│   ├── _reset.scss
│   ├── _root.scss
│   └── _typography.scss
├── main.scss
└── utilities
    ├── _colors.scss
    ├── _index.scss
    └── _layout.scss

The main.scss file will @use all our global styles. Obviously, you can adjust the files to your specific needs.

File structure

The contents of the entry files will be:

// abstracts/_index.scss
@forward "breakpoints";
@forward "colors";
@forward "font";
@forward "mixins";
@forward "variables";

// base/_index.scss
@forward "reset";
@forward "root";
@forward "typography";
@forward "base";

// utilities/_index.scss
@forward "colors";
@forward "layout";

and inside main.scss. Notice we are not including abstracts since they wouldn't work inside components because of the scoped attribute.

// main.scss
@use "base";
@use "utilities";

If we now @use the main.scss file in our App.vue, the styles should apply. However, if we try to use a mixin or a variable you'll notice we get an error since they aren't @use-d inside of our components.

Vue config

To handle this we will add a vue.config.js file which is a wrapper for webpack configuration. With the help of this, we can include variables and mixins into every component in order not to repeat ourselves with a @use statement inside each component. Learn more about the config file here.

module.exports = {
  css: {
    loaderOptions: {
      sass: {
        prependData: `@use '@/styles/abstracts/_mixins.scss' as *;`,
      },
    },
  },
};

I am only including the mixins here since my variables are defined as custom properties.

If you now @include a media query or use a sass variable inside of your components it should work!

// HelloWorld.vue
<template>
  <h1 class="h1 hello">Hello world</h1>
</template>

<script>
export default {
  name: "HelloWorld",
};
</script>

<style scoped lang="scss">
.hello {
  color: $primary;

  @include mq(small) {
    font-size: 7rem;
  }
}
</style>

And the result is:

Congratulations, you are now all set up for developing a large-scale application with well-organized and scalable stylesheets!