Bit-Loader Shimmer Plugin

Common errors

• ReferenceError: $ is not defined

  cause A shimmed module (e.g., Bootstrap) expects jQuery's '$' global to be available, but the jQuery shim either wasn't processed or didn't correctly expose '$' to the global scope or to subsequent shims.
  fix Ensure the shim for jQuery (or similar dependency) is loaded before the dependent module and that its `exports` configuration correctly includes `global: ['$']` (and potentially `name: 'window.$'`) to make the variable available.

• Module not found: Can't resolve 'my-library/dist/my-file.js'

  cause The `path` or `name` property within a shim configuration points to an incorrect or non-existent file or an unresolvable module identifier.
  fix Verify the `path` property contains the correct, absolute, or relative-to-config-file path to the shimmed file. If using `name`, ensure the module is installed and its main entry point or sub-path is correctly specified according to Node.js resolution rules.

• Error: Cannot read properties of undefined (reading 'Modal')

  cause A downstream module attempts to import a named export (e.g., `Modal`) from a shimmed module, but the shim's `exports` configuration did not correctly define and expose that specific property.
  fix Review the `exports` array for the shimmed module, ensuring that the `as`, `name`, and `global` properties correctly map the internal variable or global object property to the desired export name.

Warnings

• gotcha Incorrectly configured `imports` or `exports` can lead to runtime errors, undefined globals, or modules not receiving their expected dependencies. Complex interactions with global objects require careful setup.
  Fix: Carefully trace expected global names and module dependencies. Use the `as` property for local aliases within the shimmed module's scope and `global` for managing properties on the `window` or global object. Validate loading order and variable availability.
• gotcha Shimming large, monolithic libraries with many internal dependencies can be brittle and difficult to maintain. The shim configuration might not fully capture the library's internal loading mechanisms.
  Fix: Prioritize using modern, modular versions of libraries when available. Use shimming primarily for smaller, isolated legacy scripts, or to bridge specific global dependencies for otherwise modular code. Consider refactoring legacy code if shimming becomes overly complex.
• gotcha Relative paths specified in the `path` option are resolved relative to the bit-bundler configuration file, not necessarily the current working directory or the shimmed module itself.
  Fix: Always use `path.resolve()` with `__dirname` or absolute paths for clarity and reliability, especially when dealing with module paths that might be ambiguous, or use the `name` option for modules resolvable via npm or similar registries.

Install

• npm install bit-loader-shimmer npm
• yarn add bit-loader-shimmer yarn
• pnpm add bit-loader-shimmer pnpm

Imports

• shim
  wrong:

  import { shim } from 'bit-loader-shimmer'

  correct:

  import shim from 'bit-loader-shimmer'

  The `shim` function is the default export and should typically be imported as such in ESM contexts.
• shim

  const shim = require('bit-loader-shimmer')

  CommonJS environments use `require` to import the default exported `shim` function.
• shim

  import * as shim from 'bit-loader-shimmer'

  This pattern imports the entire module as a namespace object, which can be useful in some bundler configurations or when explicit default import is not desired.

Quickstart

This quickstart demonstrates how to configure `bit-loader-shimmer` to handle legacy libraries like jQuery and Bootstrap, managing their imports, exports, and global interactions within a `bit-bundler` setup.

const shim = require('bit-loader-shimmer');
const path = require('path');

const shimConfig = shim({
  // Shim configuration for jQuery, exposing it globally and as an export
  jquery: {
    // Use 'name' for module resolution by bit-bundler
    name: 'jquery/dist/jquery.js',
    // Define how jQuery exports itself or is made available
    exports: [{
      as: '$',
      name: 'window.$',
      global: ['$'] // Expose as global $ variable
    }, {
      as: 'jQuery',
      name: 'window.jQuery',
      global: ['jQuery'] // Expose as global jQuery variable
    }]
  },
  // Shim configuration for Bootstrap, which depends on jQuery
  bootstrap: {
    // Specify the direct path to the Bootstrap JavaScript file
    path: path.resolve('./node_modules/bootstrap/dist/js/bootstrap.js'),
    // Bootstrap expects jQuery to be available, so we import it
    imports: [{
      as: 'jQuery', // Create a local 'jQuery' variable for Bootstrap's scope
      name: 'jquery' // Refers to the 'jquery' shim defined above
    }],
    // If Bootstrap exposes a specific component, e.g., Modal, export it
    exports: [{
      as: 'Modal',
      name: 'window.bootstrap.Modal', // Assuming it attaches to window.bootstrap
      global: 'bootstrap.Modal'
    }]
  },
  // Example for a simple legacy script that might modify the global scope
  myLegacyScript: {
    path: './src/legacy-global-modifier.js'
    // This script runs, and can be ensured to load at a specific time.
  }
});

console.log("Generated shim configuration:\n", JSON.stringify(shimConfig, null, 2));
console.log("\nThis configuration object should be passed to bit-bundler's plugins array.");
// Example of how it would be used within bit-bundler (not runnable without bit-bundler setup):
// const BitBundler = require('bit-bundler');
// const bundler = new BitBundler({
//   src: ['./entry.js'],
//   dest: './bundle.js',
//   plugins: [shimConfig]
// });
// bundler.bundle().then(() => console.log('Bundled with shims!'));