Bit-Bundler Source Map Extraction Plugin

Common errors

• Sourcemap files named 'null.map' generated in current working directory.

  cause The `bit-bundler` bundle operation was executed without a `dest` (destination) file path specified, causing `bit-bundler-extractsm` to misinterpret the output target.
  fix Ensure that `Bitbundler.bundle` is always called with a valid `dest` option, like `dest: 'out.js'`. For `bit-bundler-extractsm` versions prior to `2.1.2`, this was a known bug; upgrading to `2.1.2` or newer resolves the underlying issue.

• Source map file not generated or extracted (e.g., 'out.js.map' is missing).

  cause Either no upstream `bit-bundler` plugin (e.g., `bit-bundler-minifyjs`, Babel plugin) is configured to produce source maps, or `bit-bundler-extractsm` is explicitly disabled in the bundler configuration.
  fix Confirm that your bundling pipeline includes a plugin that generates source maps and that `bit-bundler-extractsm` is placed after it in the `bundler` array. Also, ensure `bit-bundler-extractsm` is not configured to `false` for the affected bundle or split.

Warnings

• gotcha When `bit-bundler-extractsm` is used without a `dest` option for the main bundle, it might incorrectly generate sourcemap files named `null.map` in `process.cwd()`.
  Fix: Ensure that your `Bitbundler.bundle` call always specifies a `dest` path for the main output bundle. Upgrade to version `2.1.2` or higher to fix this bug automatically.
• gotcha `bit-bundler-extractsm` requires another bundler plugin (like `bit-bundler-minifyjs`) to actually generate source maps in the first place. If no source maps are being produced by prior steps in the pipeline, `extractsm` will have nothing to extract.
  Fix: Verify that a plugin preceding `bit-bundler-extractsm` in the `bundler` array (e.g., `bit-bundler-minifyjs`) is configured to generate source maps. Consult the documentation for other `bit-bundler` plugins to ensure they are outputting source maps.
• gotcha To remove sourcemaps from a bundle or a specific bundle split, `bit-bundler-extractsm` must be configured with `false` or an object specifying `false` for named splits. Misconfiguration can lead to unexpected source map generation or removal.
  Fix: To remove all source maps, use `['bit-bundler-extractsm', false]`. For specific bundle splits, provide an object like `['bit-bundler-extractsm', { vendor: false }]` where `vendor` is the name of the bundle split.

Install

• npm install bit-bundler-extractsm npm
• yarn add bit-bundler-extractsm yarn
• pnpm add bit-bundler-extractsm pnpm

Imports

• Bitbundler
  wrong:

  import Bitbundler from 'bit-bundler';

  correct:

  var Bitbundler = require("bit-bundler");

  The core `bit-bundler` library is typically imported via CommonJS `require()` in environments where this plugin is most often used, as shown in the README examples.
• Plugin Registration String
  wrong:

  import { extractsm } from 'bit-bundler-extractsm';

  correct:

  bundler: ["bit-bundler-extractsm"]

  `bit-bundler-extractsm` is registered as a plugin by its package name string within `bit-bundler`'s configuration array, not via a direct JavaScript import or require statement into user code.
• Direct Module Reference (Rare)
  wrong:

  import * as extractsmModule from 'bit-bundler-extractsm';

  correct:

  const extractsmModule = require('bit-bundler-extractsm');

  While the module can technically be `require()`d, `bit-bundler-extractsm` is almost exclusively used as a named plugin string within `bit-bundler`'s configuration rather than directly invoking functions from `extractsmModule` in user code.

Quickstart

This example demonstrates how to use `bit-bundler-extractsm` with `bit-bundler` and `bit-bundler-minifyjs` to bundle `in.js` into `out.js` and extract its source map into a separate `out.js.map` file.

const Bitbundler = require("bit-bundler");
const path = require("path");
const fs = require("fs");

// Create a dummy in.js file for the example
const inJsContent = `
// in.js
console.log('Hello from in.js');
const add = (a, b) => a + b;
console.log('Sum:', add(1, 2));
// This line is often generated by tools like Babel or TypeScript, or explicitly added by minifiers.
//# sourceMappingURL=data:application/json;charset=utf-8;base64,eyJ2ZXJzaW9uIjozLCJzb3VyY2VzIjpbImluLmpzIl0sIm5hbWVzIjpbImNvbnNvbGUiLCJsb2ciLCJhZGQiLCJhIiwiYiJdLCJtYXBwaW5ncyI6IkFBQUE7QUFDQUEsUUFBQUMsR0FBRCxDQUFLLGtCQUFMLENBQUw7QUFDQSxNQUFNQyxHQUFHLENBQUNDLEVBQUQsRUFBU0MsQ0FBVCxDQUFELEdBQWdCRCxDQUFDLEdBQUVDLENBQXJCO0FBQ0FILFFBQUFDLGdBQWdCLENBQUNFLFdBQVdDLENBQUMsQ0FBQyxDQUFFLENBQUMsQ0FBRCxDQUFZLENBQVAsQ0FBckI7QUFDQTtBQUxBIiwic291cmNlc0NvbnRlbnQiOlsiLy8gaW4uanNcbmNvbnNvbGUubG9nKCdIZWxsbyBmcm9tIGluLmpzJyk7XG5jb25zdCBhZGQgPSAocmEsIGIpID0+IGEgKyBiO1xuY29uc29sZS5sb2coJ1N1bTogJywgYWRkKDEsIDIpKTtcbi8vIHRoaXMgaW5saW5lIHNvdXJjZW1hcCBpcyBmb3IgZGVtb25zdHJhdGlvbiBwdXJwb3Nlcywgbm90gCBhIGNhbm9uaWNhbCBzb3VyY2VtYXAgZm9ybWF0XG4jIyMgc291cmNlTWFwZmluZ1VSTA1pbi5qcy5tYXAgYnkgYmFzZTY0IGVuY29kaW5nIGEgZHVubXkgc291cmNlbWFwXG4ifV0sImZpbGUiOiJpbi5qcyJ9
`;
const inJsPath = path.join(__dirname, 'in.js');
fs.writeFileSync(inJsPath, inJsContent.trim());

const outJsPath = path.join(__dirname, 'out.js');
const outMapPath = path.join(__dirname, 'out.js.map');

// Clean up previous outputs if they exist
if (fs.existsSync(outJsPath)) fs.unlinkSync(outJsPath);
if (fs.existsSync(outMapPath)) fs.unlinkSync(outMapPath);

console.log('Starting bundling process...');
Bitbundler.bundle({
  src: inJsPath,
  dest: outJsPath
}, {
  bundler: [
    // bit-bundler-minifyjs is often used to generate the source map that extractsm will then process
    "bit-bundler-minifyjs",
    "bit-bundler-extractsm"
  ]
}).then(() => {
  console.log(`Bundle created at ${outJsPath}`);
  console.log(`Source map extracted to ${outMapPath}`);
  console.log('Verification: out.js should reference out.js.map, and out.js.map should exist.');
  
  // Clean up dummy in.js after bundling
  fs.unlinkSync(inJsPath);
}).catch(err => {
  console.error('Bundling failed:', err);
  // Ensure cleanup even on error
  if (fs.existsSync(inJsPath)) fs.unlinkSync(inJsPath);
  if (fs.existsSync(outJsPath)) fs.unlinkSync(outJsPath);
  if (fs.existsSync(outMapPath)) fs.unlinkSync(outMapPath);
});

// To run this example:
// 1. Ensure you have Node.js installed.
// 2. npm install bit-bundler bit-bundler-minifyjs bit-bundler-extractsm
// 3. Save the code above as 'bundle.js'
// 4. Run: node bundle.js