unpkg-bundler Client-Side ESBuild Bundler

0.0.12 · active · verified Tue Apr 21

unpkg-bundler is a client-side JavaScript library (current version 0.0.12) designed for in-browser code transpilation and bundling, with a unique capability to dynamically fetch and load npm packages directly from unpkg.com. It leverages esbuild internally for high-performance bundling and supports both ES modules (ESM) and CommonJS (CJS) syntax, as well as TypeScript and TSX with React code. The library's core differentiator is its ability to operate without filesystem access, making it ideal for browser-based development environments, interactive code editors, or learning platforms that need to execute user-provided code with npm dependencies on the fly. Its release cadence is currently irregular, typical for projects in early development.

Common errors

```
TypeError: (0 , unpkg_bundler__WEBPACK_IMPORTED_MODULE_0__.bundle) is not a function
```
cause Attempting to import `bundle` as a named export when it is a default export in an ESM context (common with bundlers like Webpack/Vite).

fix Change `import { bundle } from 'unpkg-bundler';` to `import bundle from 'unpkg-bundler';`.
```
SyntaxError: await is only valid in async functions and the top level bodies of modules
```
cause Using `await bundle(...)` outside of an `async` function or a top-level `await` context.

fix Wrap the call to `bundle` in an `async` function, e.g., `const createBundle = async () => { const { code, err } = await bundle(modules); };`.
```
ReferenceError: require is not defined
```
cause Trying to use CommonJS `require` in an ES module environment (e.g., in a browser or a Node.js module configured as `type: "module"`).

fix For ESM, use `import bundle from 'unpkg-bundler';`. For CommonJS, use `const bundle = require('unpkg-bundler/lib/cjs');`.

Warnings

gotcha The package is in early development (v0.0.12) and APIs might change frequently without following strict semantic versioning practices.
Fix: Review release notes carefully for updates and consider pinning exact versions in production environments to avoid unexpected changes.
gotcha The `bundle` function is asynchronous and must be awaited within an `async` context to correctly retrieve results. Forgetting `await` will result in a Promise object instead of the bundled code.
Fix: Ensure calls to `bundle()` are prefixed with `await` and are contained within an `async` function or a top-level `await` context.
gotcha `unpkg-bundler` is designed for client-side use without filesystem access. It cannot resolve local file paths or perform operations requiring Node.js-specific modules (like `fs`).
Fix: Ensure all input code is provided as a string, and dependencies are resolved via `unpkg.com` or are self-contained within the input string.
gotcha CommonJS users importing the package via `require()` must specify the CommonJS entry point at `'unpkg-bundler/lib/cjs'`, as the default package entry is an ES module.
Fix: Use `const bundle = require('unpkg-bundler/lib/cjs');` for CommonJS environments.
gotcha The `bundle` function is a default export. Attempting to destructure it as a named import (e.g., `import { bundle } from 'unpkg-bundler';`) will result in `undefined` or a runtime error.
Fix: Always import `bundle` as a default import: `import bundle from 'unpkg-bundler';`.

Install

npm install unpkg-bundler npm
yarn add unpkg-bundler yarn
pnpm add unpkg-bundler pnpm

Imports

bundle
wrong:
```
import { bundle } from 'unpkg-bundler';
const bundle = require('unpkg-bundler');
```
correct:
```
import bundle from 'unpkg-bundler';
```
The main `bundle` function is a default export. For CommonJS environments, explicitly import from `unpkg-bundler/lib/cjs`. The primary package entry point is ESM.

Quickstart

Demonstrates bundling a React component, including automatic fetching of `react` and `react-dom` from `unpkg.com`, and shows how to execute the resulting bundled code in a browser environment.

import bundle from 'unpkg-bundler';

// React component code to be bundled.
// unpkg-bundler will automatically fetch React and ReactDOM from unpkg.
const reactCode = `
import React from 'react';
import ReactDOM from 'react-dom';

const App = () => {
  return (
    <div style={{ fontFamily: 'sans-serif', textAlign: 'center' }}>
      <h1>Hello from unpkg-bundler!</h1>
      <h2>This code was bundled and transpiled on the client-side.</h2>
      <p>It automatically fetched React and ReactDOM from unpkg.com.</p>
    </div>
  );
};

// Typically, you'd render this into an existing DOM element.
// For this quickstart, we'll just demonstrate the bundling output.
const rootElement = document.createElement('div');
rootElement.id = 'root';
document.body.appendChild(rootElement);

ReactDOM.render(<App />, rootElement);
`;

const runBundle = async () => {
  console.log('Bundling React code...');
  const { code, err } = await bundle(reactCode);

  if (err) {
    console.error('Bundling error:', err);
    return;
  }

  console.log('Bundle successful. Executing code...');
  // To execute in a browser, you can create a <script> tag or use eval.
  // Be cautious with eval in production due to security implications.
  // For demonstration:
  try {
    // This will execute the bundled code directly in the current scope.
    // In a real application, you might inject it into an iframe for isolation.
    new Function(code)();
    console.log('Code executed successfully. Check the document body for the React app.');
  } catch (executionError) {
    console.error('Error executing bundled code:', executionError);
  }
};

runBundle();

view raw JSON →