asbundle: Minimalistic CommonJS Bundler

2.7.0 · maintenance · verified Sun Apr 19

asbundle (current stable version 2.7.0) is a focused JavaScript bundler designed to convert single ES Module or CommonJS source files into a lightweight, optimized CommonJS bundle, primarily for browser environments. It serves as a companion to `ascjs` and utilizes `babylon` for parsing, automatically transforming ES2015+ modules into CommonJS when necessary. Its core differentiators include its minimalistic design, aiming for simplicity over feature breadth, and its ability to produce small, minifier-friendly bundles that do not rely on a global `require` or runtime dependency resolution. It prioritizes compatibility with downstream tools like Babel and UglifyJS, supports both relative file paths and `node_modules` package resolution, and reproduces a modern CommonJS environment ideal for web browsers. It explicitly avoids replacing comprehensive bundlers like Webpack or Rollup, focusing solely on `import`/`export` transpilation. The package was last published 5 years ago, suggesting a maintenance or stable status with infrequent updates.

Common errors

```
Error: Cannot find module 'some-npm-package' from 'path/to/your-file.js'
```
cause The module specified in a `require()` or `import` statement could not be resolved. This often indicates a missing `node_modules` dependency or an unresolvable path.

fix Ensure the required package is installed via `npm install <package-name>` or `yarn add <package-name>`. Verify the module path is correct relative to the importing file or resolvable from `node_modules`.
```
Error: Cannot find module 'fs' from 'path/to/your-file.js'
```
cause A Node.js core module (like `fs`, `path`, `http`) is being required, but `asbundle` does not include these in the browser-targeted bundle. It attempts to resolve them as regular files/packages, which fails.

fix If the bundle is for the browser, remove or replace usage of Node.js core modules with browser-compatible alternatives. If it's a Node.js target, `asbundle` might not be the right tool or you need to ensure the module is externalized.

Warnings

gotcha Node.js core modules (e.g., `fs`, `path`, `http`) are not bundled by `asbundle`. If your source code requires these modules and the bundle is intended for a browser environment, `asbundle` will throw an error if it cannot resolve them as local files or installed packages.
Fix: Refactor code to avoid Node.js core modules in browser bundles or use browser-compatible alternatives/shims for those functionalities.
gotcha `asbundle` inherits constraints from `ascjs`, its underlying transformer. This means dynamic `require` calls (e.g., `require(variable)`) are not supported and will lead to bundling failures or incorrect output. All `require` statements must be statically analyzable.
Fix: Ensure all `require` statements use static string literals for module paths. Avoid any form of dynamic module loading that `asbundle` cannot resolve at build time.
gotcha `ascjs` (and thus `asbundle`) does not fully support mixing CommonJS `module.exports`/`exports.property` syntax with ES Module `export default` in the same file. This can lead to unpredictable behavior or errors during transformation.
Fix: Maintain a consistent module syntax (either CommonJS or ES Modules) within each source file. Avoid hybrid module patterns where both `module.exports` and `export default` are present.

Install

npm install asbundle npm
yarn add asbundle yarn
pnpm add asbundle pnpm

Imports

asbundle
wrong:
```
import asbundle from 'asbundle';
```
correct:
```
const asbundle = require('asbundle');
```
asbundle itself is distributed as a CommonJS module, so direct ES Module `import` syntax will result in a runtime error. Use `require` for programmatic access.

Quickstart

Demonstrates programmatic usage of `asbundle` to transform an ES Module entry point (`main.js`) and its dependency (`module.js`) into a single CommonJS compatible string, then logs the result.

const asbundle = require('asbundle');
const fs = require('fs');
const path = require('path');

// Create dummy source files for the example to be runnable
const tempDir = path.join(__dirname, 'temp_asbundle_example');
fs.mkdirSync(tempDir, { recursive: true });

fs.writeFileSync(path.join(tempDir, 'main.js'), `
import func, {a, b} from './module.js';
const val = 123;
export default function test() {
  console.log('asbundle');
};
export {func, val};
    `);
fs.writeFileSync(path.join(tempDir, 'module.js'), `
export const a = 1, b = 2;
export default function () {
  console.log('module');
};
    `);

async function bundleExample() {
  try {
    const sourceFileName = path.join(tempDir, 'main.js');
    const bundleContent = await asbundle(sourceFileName);

    console.log('Generated bundle content:\n');
    console.log(bundleContent);

    // Clean up temporary files
    fs.unlinkSync(path.join(tempDir, 'main.js'));
    fs.unlinkSync(path.join(tempDir, 'module.js'));
    fs.rmdirSync(tempDir);
    console.log('\nTemporary files cleaned up.');

  } catch (error) {
    console.error('Bundling failed:', error.message);
    // Ensure cleanup even on error
    if (fs.existsSync(path.join(tempDir, 'main.js'))) fs.unlinkSync(path.join(tempDir, 'main.js'));
    if (fs.existsSync(path.join(tempDir, 'module.js'))) fs.unlinkSync(path.join(tempDir, 'module.js'));
    if (fs.existsSync(tempDir)) fs.rmdirSync(tempDir);
  }
}

bundleExample();

view raw JSON →