lbundle: Zero-Configuration Library Bundler

1.6.0 verified Thu Apr 23 auth: no javascript

lbundle is a small, zero-configuration bundler specifically designed for NPM libraries, leveraging Rollup.js for bundling and SWC (written in Rust) for fast transpilation. Its core philosophy is to minimize setup by heavily relying on best practices defined within the `package.json` file, using fields like `source`, `main`, `module`, `types`, `unpkg`, and `exports` to determine build inputs and outputs. The current stable version is 1.6.0, with frequent minor releases focusing on bug fixes and feature enhancements, as evidenced by its recent changelog. It differentiates itself by its 'convention over configuration' approach, automatic asset optimization, and robust TypeScript support, making it an ideal choice for library authors seeking a streamlined build process without extensive build toolchain configuration.

Common errors

error Error: Cannot find module 'sass' imported from 'some-file.scss' ↓

cause Sass/SCSS file imported, but `sass` peer dependency is not installed.

fix

Install sass as a development dependency: npm install -D sass or yarn add -D sass.

error Error: Unknown file extension "./src/index.ts" for "./src/index.ts" ↓

cause Typically indicates a misconfiguration in `package.json`'s `source` field or missing `tsconfig.json` setup for `lbundle`.

fix

Ensure source field in package.json points to the correct entry file (e.g., ./src/index.ts) and that TypeScript is correctly configured if using TS files.

error lbundle: command not found ↓

cause The `lbundle` CLI tool is not in your system's PATH or `npx` cannot locate it.

fix

Ensure lbundle is installed as a devDependency and run it via npx lbundle or add lbundle to your package.json scripts (e.g., "build": "lbundle").

Warnings

gotcha lbundle heavily relies on `package.json` fields (`source`, `main`, `module`, `types`, `unpkg`, `exports`). Misconfiguring these fields, or omitting them entirely, will prevent `lbundle` from generating the expected output formats or entry points. ↓

fix Ensure all relevant `package.json` fields are correctly defined according to your desired library output. Consult the `lbundle` documentation for common `package.json` best practices for libraries.

gotcha Asset imports (images, SVGs, etc.) require a TypeScript reference directive (`/// <reference types="lbundle/modules" />`) in your project's type declaration files to ensure type safety and correct resolution during development. ↓

fix Add `/// <reference types="lbundle/modules" />` to your `global.d.ts` or a similar type declaration file, or include `lbundle/modules` in the `types` array of your `tsconfig.json`.

gotcha Styling preprocessor support (Less, Sass, Stylus) depends on corresponding peer dependencies. If you import such files without installing the relevant package, `lbundle` will fail to process them. ↓

fix Install the required peer dependency (e.g., `npm install -D sass` for SCSS files) if you are importing files of that type in your project.

gotcha The `exports` field in `package.json` is crucial for defining how your bundled library is consumed by different environments (ESM, CJS, Node, browser). Incorrectly configuring this field can lead to module resolution issues for consumers. ↓

fix Carefully define the `exports` field to map different entry points and formats to their respective paths (e.g., `./dist/index.mjs` for `import`, `./dist/index.js` for `require`). Validate with tools like `publint`.

Install

npm install lbundle

yarn add lbundle

pnpm add lbundle

Imports

lbundle CLI
wrong
```
import lbundle from 'lbundle'; // This is a CLI tool, not a directly importable function for general use.
```
correct
```
npx lbundle
```
The primary interaction with lbundle is via its command-line interface. Install as a dev dependency and run via `npx` or add to your `package.json` scripts.
Asset Modules Types
wrong
```
import { Asset } from 'lbundle/modules';
```
correct
```
/// <reference types="lbundle/modules" />
```
To enable TypeScript support for asset imports (e.g., `.png`, `.svg` as URLs or React components), add this triple-slash directive to your main TypeScript declaration file (e.g., `src/global.d.ts` or `tsconfig.json` `files` array).
build
wrong
```
const build = require('lbundle').build;
```
correct
```
import { build } from 'lbundle';
await build({ /* config */ });
```
While primarily a CLI tool, `lbundle` exposes a programmatic API for more advanced use cases, allowing direct invocation of its build process within Node.js environments. Use ESM imports for this.

Quickstart

This quickstart demonstrates how to set up `lbundle` using a `package.json` configuration, define an entry point in TypeScript, import various asset types, and prepare your project for bundling with the `lbundle` CLI.

{
  "name": "my-library",
  "version": "1.0.0",
  "source": "./src/index.ts",
  "main": "./dist/index.js",
  "module": "./dist/index.mjs",
  "types": "./dist/index.d.ts",
  "unpkg": "./dist/index.umd.js",
  "sideEffects": false,
  "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"
  },
  "scripts": {
    "build": "lbundle",
    "dev": "lbundle --watch"
  },
  "devDependencies": {
    "lbundle": "^1.6.0"
  }
}

// src/index.ts
import logo from './assets/logo.png';
import { ReactComponent as Icon } from './assets/icon.svg';

export const sayHello = (name: string) => {
  console.log(`Hello, ${name}!`);
  // Example usage of imported assets
  document.body.innerHTML += `<img src="${logo}" alt="Logo" />`;
  const iconContainer = document.createElement('div');
  // In a React context, you'd render <Icon /> directly.
  // For this example, we'll simulate its presence.
  iconContainer.innerHTML = 'SVG Icon placeholder'; 
  document.body.appendChild(iconContainer);
  return `Hello, ${name} with logo and icon!`;
};

// global.d.ts (for TypeScript asset support)
/// <reference types="lbundle/modules" />

// Run the build
// npm install && npm run build