Vite Library Mode: How to Build and Publish a JavaScript Package

Building a JavaScript application with Vite is straightforward. Publishing a reusable JavaScript library, however, requires a few additional decisions. You need to configure the entry point, generate the right output formats, manage dependencies, and make sure other developers can import your package without running into compatibility problems.

For example, you might build a shared date utility, a collection of reusable UI components, or a small validation library. Instead of copying the code into every project, you can package it and publish it to npm.

Vite provides a library mode designed for this purpose. It uses Vite's build pipeline to produce distributable files for JavaScript libraries, while allowing you to control how consumers import and use the package.

In this article, you will learn how to create a reusable library with Vite, configure its build output, manage dependencies, test the generated package, and prepare it for publishing.

What Is Vite Library Mode?

Vite is a frontend build tool that provides development features and a production build process. Its library mode configures the production build for distributing reusable code rather than producing a complete website.

A normal Vite application build typically generates assets for a browser application. A library build generates files that other projects can import.

For example, a utility library might expose this function:

export function formatCurrency(amount) {
    return new Intl.NumberFormat("en-US", {
        style: "currency",
        currency: "USD"
    }).format(amount);
}

After building the library, another project can install the package and import the function:

import { formatCurrency } from "@example/format-utils";

console.log(formatCurrency(1250));

The package name is illustrative. A real package needs a unique name and a correctly configured package.json.

Vite library mode is useful when you want to reuse code across applications, distribute a component library, or publish a JavaScript package without manually configuring every part of the bundling process.

Step 1: Create a Vite Project

Start by creating a new project directory:

mkdir format-utils
cd format-utils
npm init -y
npm install --save-dev vite

These commands create a package and install Vite as a development dependency.

Create the following structure:

format-utils/
├── src/
│   └── index.js
├── package.json
└── vite.config.js

The src/index.js file will serve as the library's entry point.

Add the following code:

export function formatCurrency(amount, currency = "USD") {
    if (!Number.isFinite(amount)) {
        throw new TypeError("Amount must be a finite number.");
    }

    return new Intl.NumberFormat("en-US", {
        style: "currency",
        currency
    }).format(amount);
}

export function formatPercentage(value) {
    if (!Number.isFinite(value)) {
        throw new TypeError("Value must be a finite number.");
    }

    return `${value}%`;
}

This module exports two functions. The first formats a number as currency, while the second formats a number as a percentage string.

The example keeps the library small so that you can focus on the packaging process. A production library should also document its supported inputs, expected outputs, error behavior, and compatibility requirements.

Step 2: Configure Vite Library Mode

Create a vite.config.js file:

import { defineConfig } from "vite";

export default defineConfig({
    build: {
        lib: {
            entry: "src/index.js",
            name: "FormatUtils",
            formats: ["es", "cjs"],
            fileName: (format) => {
                return format === "es"
                    ? "format-utils.js"
                    : "format-utils.cjs";
            }
        }
    }
});

This configuration tells Vite to build the library from src/index.js.

The important options are:

• entry: identifies the main source file.

• name: defines a library name used by applicable output formats, such as UMD or IIFE.

• formats: specifies the module formats to generate.

• fileName: controls the generated filenames.

In this example, the build produces an ES module and a CommonJS file.

ES modules use import and export. CommonJS uses require() and module.exports.

The name property is not required for every format. It becomes relevant for formats such as UMD and IIFE that expose a global variable in environments where native module imports are not used.

Step 3: Add Build Scripts and Package Metadata

Update package.json to describe the package and its generated files:

{
    "name": "@example/format-utils",
    "version": "1.0.0",
    "description": "Reusable JavaScript formatting utilities",
    "type": "module",
    "main": "./dist/format-utils.cjs",
    "module": "./dist/format-utils.js",
    "exports": {
        ".": {
            "import": "./dist/format-utils.js",
            "require": "./dist/format-utils.cjs"
        }
    },
    "files": [
        "dist"
    ],
    "scripts": {
        "build": "vite build"
    },
    "devDependencies": {
        "vite": "YOUR_INSTALLED_VERSION"
    }
}

The version placeholder is illustrative. Keep the actual Vite version installed by your package manager.

Several fields are important when publishing a library.

The exports field is particularly important because it gives consumers a defined public entry point.

Because this example uses "type": "module", the .js output is interpreted as an ES module by Node.js. The .cjs extension explicitly identifies the CommonJS output.

The main and module fields are included for compatibility with tools that recognize them. Modern package resolution should generally rely on a correctly configured exports field.

The package name @example/format-utils is a placeholder. Replace it with a package name you are authorized to publish.

Step 4: Build the Library

Run the build command:

npm run build

Vite generates the configured output files in the dist directory.

The resulting structure should look similar to this:

format-utils/
├── dist/
│   ├── format-utils.js
│   └── format-utils.cjs
├── src/
│   └── index.js
├── package.json
└── vite.config.js

The exact output can vary depending on your Vite version and build configuration.

The generated ES module can be consumed by modern JavaScript applications. The CommonJS output can be used by compatible Node.js tools and projects.

Before publishing, inspect the generated files and verify that they export the functions you intended to make public.

Step 5: Understand ES Modules, CommonJS, and UMD

A library may need to support different environments. Choosing output formats depends on the consumers you want to support.