{"id":15545,"library":"bit-loader-shimmer","title":"Bit-Loader Shimmer Plugin","description":"The `bit-loader-shimmer` package provides a plugin for `bit-bundler`, enabling detailed control over how non-modular or legacy JavaScript modules are integrated into a modern bundler environment. Currently at version 1.1.0, this package allows developers to define 'shims' for specific modules, dictating their file paths, dependencies (imports), and what they expose to other modules or the global scope (exports). This is particularly useful for handling libraries that expect global variables, require a specific load order, or do not conform to CommonJS or ES module patterns. It offers granular configuration options, such as aliasing imports and exports, linking to global objects, and resolving modules by name or direct path. While a specific release cadence isn't published, the 1.x versioning suggests stability. Its key differentiator lies in its comprehensive API for managing the module environment for legacy scripts, bridging the gap between traditional script inclusion and modular bundling, especially within the `bit-bundler` ecosystem.","status":"maintenance","version":"1.1.0","language":"javascript","source_language":"en","source_url":"https://github.com/MiguelCastillo/bit-loader-shimmer","tags":["javascript","bit-bundler","bit-loader-plugin"],"install":[{"cmd":"npm install bit-loader-shimmer","lang":"bash","label":"npm"},{"cmd":"yarn add bit-loader-shimmer","lang":"bash","label":"yarn"},{"cmd":"pnpm add bit-loader-shimmer","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"This package is a plugin specifically designed for use with bit-bundler.","package":"bit-bundler","optional":false}],"imports":[{"note":"The `shim` function is the default export and should typically be imported as such in ESM contexts.","wrong":"import { shim } from 'bit-loader-shimmer'","symbol":"shim","correct":"import shim from 'bit-loader-shimmer'"},{"note":"CommonJS environments use `require` to import the default exported `shim` function.","symbol":"shim","correct":"const shim = require('bit-loader-shimmer')"},{"note":"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.","symbol":"shim","correct":"import * as shim from 'bit-loader-shimmer'"}],"quickstart":{"code":"const shim = require('bit-loader-shimmer');\nconst path = require('path');\n\nconst shimConfig = shim({\n  // Shim configuration for jQuery, exposing it globally and as an export\n  jquery: {\n    // Use 'name' for module resolution by bit-bundler\n    name: 'jquery/dist/jquery.js',\n    // Define how jQuery exports itself or is made available\n    exports: [{\n      as: '$',\n      name: 'window.$',\n      global: ['$'] // Expose as global $ variable\n    }, {\n      as: 'jQuery',\n      name: 'window.jQuery',\n      global: ['jQuery'] // Expose as global jQuery variable\n    }]\n  },\n  // Shim configuration for Bootstrap, which depends on jQuery\n  bootstrap: {\n    // Specify the direct path to the Bootstrap JavaScript file\n    path: path.resolve('./node_modules/bootstrap/dist/js/bootstrap.js'),\n    // Bootstrap expects jQuery to be available, so we import it\n    imports: [{\n      as: 'jQuery', // Create a local 'jQuery' variable for Bootstrap's scope\n      name: 'jquery' // Refers to the 'jquery' shim defined above\n    }],\n    // If Bootstrap exposes a specific component, e.g., Modal, export it\n    exports: [{\n      as: 'Modal',\n      name: 'window.bootstrap.Modal', // Assuming it attaches to window.bootstrap\n      global: 'bootstrap.Modal'\n    }]\n  },\n  // Example for a simple legacy script that might modify the global scope\n  myLegacyScript: {\n    path: './src/legacy-global-modifier.js'\n    // This script runs, and can be ensured to load at a specific time.\n  }\n});\n\nconsole.log(\"Generated shim configuration:\\n\", JSON.stringify(shimConfig, null, 2));\nconsole.log(\"\\nThis configuration object should be passed to bit-bundler's plugins array.\");\n// Example of how it would be used within bit-bundler (not runnable without bit-bundler setup):\n// const BitBundler = require('bit-bundler');\n// const bundler = new BitBundler({\n//   src: ['./entry.js'],\n//   dest: './bundle.js',\n//   plugins: [shimConfig]\n// });\n// bundler.bundle().then(() => console.log('Bundled with shims!'));","lang":"javascript","description":"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."},"warnings":[{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"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.","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.","error":"ReferenceError: $ is not defined"},{"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.","cause":"The `path` or `name` property within a shim configuration points to an incorrect or non-existent file or an unresolvable module identifier.","error":"Module not found: Can't resolve 'my-library/dist/my-file.js'"},{"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.","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.","error":"Error: Cannot read properties of undefined (reading 'Modal')"}],"ecosystem":"npm"}