repository·master·Indexed 27 days ago
https://github.com/developit/microbundleA zero-configuration bundler for tiny JavaScript libraries powered by Rollup. It automatically produces optimized CJS, ESM, and UMD bundles from a single source file, including a 'modern' bundle for browsers supporting <script type="module">. It supports TypeScript, CSS Modules, Module Workers, and can be used via CLI or as a programmatic asynchronous function.
--visualize flag to generate a stats.html file at build time. This file provides a visual representation of your bundle's composition using rollup-plugin-visualizer.Microbundle is a zero-configuration bundler that uses your package.json to determine source files and output locations.
To set up a standard build, define the following keys:
source: Your entry point file.main: The CommonJS (CJS) bundle location.module: The ES Modules (ESM) bundle location.unpkg: The Universal Module Definition (UMD) bundle location.exports: Defines how the package is exported, enabling modern ESM support and subpath exports.Add a build script to run the bundler and a dev script to watch for changes.
{
"name": "foo",
"type": "module",
"source": "src/foo.js",
"exports": {
"require": "./dist/foo.cjs",
"default": "./dist/foo.modern.js"
},
"main": "./dist/foo.cjs",
"module": "./dist/foo.module.js",
"unpkg": "./dist/foo.umd.js",
"scripts": {
"build": "microbundle",
"dev": "microbundle watch"
}
}Microbundle provides two primary commands for bundling:
microbundle (or microbundle build): Bundles your code once and exits.microbundle watch: Bundles your code and automatically re-bundles whenever files change.Microbundle automatically determines which dependencies to inline based on your package.json.
Microbundle can bundle Module Workers for esm and modern formats.
new Worker(new URL('./worker.js', import.meta.url), { type: 'module' });--workers flag.To reduce bundle size, you can rename internal object properties or class members. This is enabled by creating a mangle.json file or adding a "mangle" property to your package.json.
You can use a regular expression to control which properties are mangled.
{
"mangle": {
"regex": "^_"
}
}Microbundle supports importing CSS via import "./foo.css".
.css file in the output directory.--css inline flag to import CSS as a string: import css from './foo.css';..module.css are treated as modules by default..css files as modules, use --css-modules true.--no-css-modules or --css-modules false.--css-modules "[name]_[hash:base64:7]" using naming conventions.To use TypeScript, point the input to a .ts file via the CLI or the source key in package.json.
Best Practices:
"module": "ESNext" and "target": "ESNext" in your tsconfig.json to match Microbundle's internal configuration.files or include array in tsconfig.json."include": ["node_modules/microbundle/index.d.ts"] to your tsconfig.json..d.ts files are visible to projects using moduleResolution: 'NodeNext', add a types key to your package.json's exports mapping.Use the --define option to inject or replace constants.
--define KEY=VALUE.@: --define @assign=Object.assign.Install microbundle as a development dependency using npm.
npm i -D microbundleModern Mode outputs a modern bundle designed for browsers that support <script type="module">. This bundle preserves modern JavaScript features (like async/await, arrow functions, and destructuring) using Babel's "bugfixes" mode. This results in smaller and faster bundles compared to the standard esm output.
To enable Modern Mode, include an exports field in your package.json pointing to the modern bundle (typically with a .mjs or .modern.js extension).
{
"main": "./dist/foo.umd.js",
"module": "./dist/foo.module.mjs",
"exports": "./dist/foo.modern.mjs",
"scripts": {
"build": "microbundle src/foo.js"
}
}Microbundle uses package.json properties to define the bundling workflow.
source property defines the entry module.main, umd:main, module, and exports properties define the paths for generated bundles.name field. You can override this with amdName in package.json or the --name CLI flag.Note for {"type":"module"} packages: If your package is an ES Module package, you must change the extension for CommonJS bundles to .cjs.
{
"source": "src/index.js", // input
"main": "dist/foo.js", // CommonJS output bundle
"umd:main": "dist/foo.umd.js", // UMD output bundle
"module": "dist/foo.mjs", // ES Modules output bundle
"exports": {
"types": "./dist/foo.d.ts", // TypeScript typings for NodeNext modules
"require": "./dist/foo.js", // CommonJS output bundle
"default": "./dist/foo.modern.mjs", // Modern ES Modules output bundle
},
"types": "dist/foo.d.ts"
}publishConfig property in package.json to override configuration specifically for production/publishing, allowing you to use different entry points or output paths for development (e.g., for Jest).