Bundlex JavaScript Bundler

Common errors

• Cannot find module 'some-module' or its corresponding type declarations.

  cause The bundler failed to resolve an import path, likely due to incorrect relative paths, a missing `node_modules` dependency, or a misconfigured alias.
  fix Verify the import path is correct and the module exists. For `node_modules`, ensure it's installed. If using aliases, consider a custom `infoExtractor` with `createBundler` to handle alias resolution.

• SyntaxError: Cannot use import statement outside a module

  cause The bundled output is in ES Module format, but it's being executed in a CommonJS context (e.g., Node.js without `"type": "module"` in `package.json` or an older Node version).
  fix Ensure your Node.js project's `package.json` contains `"type": "module"` or ensure your runtime environment supports ESM. Bundlex's primary output is ESM, so direct CJS output options may not be available.

Warnings

• gotcha Bundlex primarily targets ESM output for modern JavaScript environments. While it processes CJS modules as inputs, the default output format is typically ESM. Direct CommonJS 'require()' calls in the bundled output for external modules might not function as expected without a transpilation step or specific configuration for Node.js environments.
  Fix: Configure your project to use ES modules (`"type": "module"` in package.json) or ensure your target environment supports ESM. For Node.js, consider a custom bundler function with `createBundler` if specific CJS output or advanced external module handling is required.
• gotcha Relative path resolution within the bundler can sometimes be tricky, especially when dealing with nested directories or alias configurations. Bundlex resolves paths relative to the importing file unless explicitly configured otherwise.
  Fix: Always use clear relative or absolute paths. For complex projects, consider implementing a custom 'infoExtractor' with `createBundler` to handle path aliases or advanced module resolution strategies tailored to your project structure.
• gotcha The `jsBundler.on('change', ...)` listener monitors file system changes for files included in the bundle graph. However, it might not automatically trigger a *re-bundle* operation; it merely notifies your application. You are responsible for re-invoking the `jsBundler()` function (or your custom bundler) upon receiving a 'change' event to generate an updated output.
  Fix: When using the `change` listener, implement logic within your callback to explicitly re-run the `jsBundler()` function with the entry file path to generate an updated bundle.

Install

• npm install bundlex npm
• yarn add bundlex yarn
• pnpm add bundlex pnpm

Imports

• jsBundler
  wrong:

  const jsBundler = require('bundlex').jsBundler;

  correct:

  import { jsBundler } from 'bundlex';

  The primary function for bundling files. Bundlex is ESM-first; CommonJS require() may not be supported directly.
• createBundler

  import { createBundler } from 'bundlex';

  Used to create custom bundler instances with specific info extractor and bundler logic.
• InfoExtractor, Bundler

  import type { InfoExtractor, Bundler } from 'bundlex';

  TypeScript types for defining custom bundler logic. Essential for strong typing when using `createBundler`.

Quickstart

Demonstrates basic bundling of TypeScript files and how to set up a file change listener using `jsBundler`.

import { jsBundler } from 'bundlex';
import path from 'path';
import fs from 'fs/promises';

// Define temporary files for the demo
const entryFile = path.resolve('./temp-entry.ts');
const depFile = path.resolve('./temp-dependency.ts');

async function runBundlexQuickstart() {
  // Create dummy files for bundling
  await fs.writeFile(depFile, `export const message = "Hello from dependency!";`);
  await fs.writeFile(entryFile, `
    import { message } from './temp-dependency';
    console.log(message);
    console.log("This is the main entry point.");
  `);

  console.log('Starting Bundlex quickstart...');

  try {
    // Set up a listener for file changes
    jsBundler.on('change', (changedPath: string) => {
      console.log(`[Bundlex Watch] Detected change in: ${changedPath}.`);
      console.log('Re-bundling logic would typically go here...');
    });

    // Bundle the entry file
    const bundledContent = await jsBundler(entryFile);

    console.log('\n--- Bundled Output (truncated) ---');
    console.log(bundledContent.slice(0, 500) + '\n...'); // Display first 500 characters

    // Simulate a file change to trigger the listener
    await new Promise(resolve => setTimeout(resolve, 50)); // Small delay
    await fs.appendFile(depFile, `\n// Added content to trigger change on ${Date.now()}`);
    console.log('\nSimulated file change. Check for listener output above.');

  } catch (error) {
    console.error('Bundlex quickstart failed:', error);
  } finally {
    // Clean up temporary files
    await fs.unlink(entryFile).catch(() => {});
    await fs.unlink(depFile).catch(() => {});
    console.log('\nCleaned up temporary files.');
  }
}

runBundlexQuickstart();