Skip to main content

Small zero-configuration bundler build on top of Rollup.js and SWC for NPM libraries

Works with
This package works with Bun
This package works with Node.js
This package works with Deno
JSR Score
76%
Published
2 weeks ago (1.3.1)

lbundle

GitHub Actions Workflow Status NPM Version NPM Downloads NPM License JSR Version GitHub Repo stars

Small zero-configuration bundler build on top of Rollup.js and SWC for NPM libraries

🚀 Motivation

There is always this repeated pattern for creating a library while following best practices that you need to maintain across all of your libraries, but then I thought maybe creating a library for bundling libraries is a good idea.

💾 install

NPM registry

# npm
npm i -D lbundle

# yarn
yarn add -D lbundle

# pnpm
pnpm i -D lbundle

# bun
bun i -D lbundle

JSR registry

# deno
deno add -D @mrii/lbundle

# jsr
npx jsr add -D @mrii/lbundle

🔧 Usage

package.json

This bundler heavily relay on your package.json best practices.

{
  "source": "./src/index.ts", // your source code entry
  "main": "./dist/index.js", // cjs entry
  "module": "./dist/index.mjs", // esm entry

  "types": "./dist/index.d.ts", // declaration entry

  "unpkg": "./dist/index.umd.js", // umd entry
  // "unpkg": "./dist/index.amd.js", // or as amd
  // "unpkg": "./dist/index.iife.js", // or as iife

  "bin:source": "./src/cli.ts", // your source code bin entry
  "bin": "./dist/cli.js", // bin entry

  "sideEffects": false, // enable tree shaking for your library code, also useful for users bundlers

  // the bundler will check for for different extension to bundle different formats
  "exports": {
    ".": {
      "default": "./dist/index.js",
      "node": "./dist/index.js",
      "require": "./dist/index.js",
      "import": "./dist/index.mjs",
      "types": "./dist/index.d.ts"
    },
    "./index.css": "./dist/index.css",
    "./package.json": "./package.json"
  }
}

CLI

Just call lbundle binary

lbundle

And That's it, it will generate the bundle for you at the target directory.

✨ Features

  • 🤩 all in 1: supports bundling your library and binary into all known formats (esm, cjs, umd, amd and iife), and generate declarations files as well.
  • 🚀 fast: it uses rust to compile source code into target env.
  • 🍙 bun: can be used with bunx --bun lbundle to speed up the bundling even more.
  • 🌲 tree shaking: it will preserve your file structure (for cjs and esm formats) so bundlers can exclude unused code easily.
  • 🎮 typescript: it supports bundling typescript code out of the box (make sure have typescript installed).
  • 🎯 JSX: supports JSX transformation out of the box (make sure have react and react-dom installed).
  • 💅 styles: it support all kind of style files:
    • css, pcss, sss: out of the box.
    • scss, sass: just install sass.
    • less: just install less.
    • styl, stylus: just install stylus.
  • 🍇 CSS modules: all styles files support CSS modules by just appending .module. before the file extension.
  • 🗺️ path alias: supports TS path and baseUrl transformation.
  • 📤 auto externals: look for your dependencies and peerDependencies and exclude them from the bundle.
  • 🪛 json: supports importing json files in your code.
  • 📦 polyfills: supports adding polyfills to the bundle if you're using latest ES features (make sure to have core-js installed)

🛣️ Roadmap

  • bundling into UMD and AMD formats.
  • reading exports field and generate extra output according to it.
  • vue jsx transformation.
  • extending SWC and Rollup config.
  • useful logs.
  • schema validation and useful errors.
  • bundle info.
  • watch mode.
  • more options.
    • single entry instead of preserved modules.
    • JSX transformation options.
    • ...
  • tests (partially done).
  • CI.
  • changelog.
  • contributors.

🧰 API

// esm
import { lbundle } from 'lbundle';

// cjs
const { lbundle } = require('lbundle');

// deno
import { lbundle } from '@mrii/lbundle';

await lbundle({
  /* options */
});

🔍 Options

key cli default description version
cwd ---cwd, -c "." root dir path of your lib 1.0.0
Built and signed on
GitHub Actions
View transparency log

Add Package

deno add @mrii/lbundle

Import symbol

import * as mod from "@mrii/lbundle";

Add Package

npx jsr add @mrii/lbundle

Import symbol

import * as mod from "@mrii/lbundle";

Add Package

yarn dlx jsr add @mrii/lbundle

Import symbol

import * as mod from "@mrii/lbundle";

Add Package

pnpm dlx jsr add @mrii/lbundle

Import symbol

import * as mod from "@mrii/lbundle";

Add Package

bunx jsr add @mrii/lbundle

Import symbol

import * as mod from "@mrii/lbundle";