babel-plugin-qunit-lazy-imports

1.2.0 verified Sat Apr 25 auth: no javascript

A Babel plugin that transforms ES module imports in QUnit test files into lazy imports inside beforeEach hooks, enabling on-demand loading of test dependencies. Current stable version is 1.2.0. Released as needed on GitHub by NullVoxPopuli. Key differentiator: designed for Vite-based QUnit projects to reduce initial bundle size by deferring module loading, with support for include/exclude patterns via startsWith and matches options. Requires @babel/core as a peer dependency and Node.js ^20.11 or >=22. Minimal plugin with no runtime dependencies, focused solely on QUnit test transformation.

Common errors

error Cannot find module 'babel-plugin-qunit-lazy-imports' ↓

cause Package not installed or not in node_modules.

fix

Run: npm add babel-plugin-qunit-lazy-imports --save-dev

error Error: [BABEL] unknown: Plugin module:babel-plugin-qunit-lazy-imports requires @babel/core@^7.0.0 but was loaded with @babel/core@6.x. ↓

cause Incompatible @babel/core version.

fix

Upgrade @babel/core to ^7.0.0: npm upgrade @babel/core

error TypeError: startsWith.filter is not a function ↓

cause startsWith option is not an array.

fix

Change startsWith to an array, e.g., startsWith: ['my-app/']

Warnings

breaking Option 'startsWith' must be an array of strings; passing a single string causes runtime error. ↓

fix Use an array: startsWith: ['my-app/'] instead of startsWith: 'my-app/'

gotcha Plugin only transforms imports that match startsWith or matches patterns; all other imports remain as static imports, which may cause unexpected synchronous loading. ↓

fix Ensure all imports you want to be lazy are covered by the patterns; add additional patterns as needed.

gotcha Lazy imports are hoisted to a single beforeEach hook per module (suite). If your test file has multiple module() calls, imports from different suites may be loaded before the suite runs due to hoisting. ↓

fix Consider splitting test files with different suites into separate files, or manually manage lazy imports.

deprecated v1.0.0 initial release uses 'module:' prefix which is not compatible with some Babel configurations; no actual deprecation yet. ↓

fix Use 'module:babel-plugin-qunit-lazy-imports' in babel.config.js; for .babelrc, omit the 'module:' prefix.

Install

npm install babel-plugin-qunit-lazy-imports

yarn add babel-plugin-qunit-lazy-imports

pnpm add babel-plugin-qunit-lazy-imports

Imports

default

wrong

plugins: [['babel-plugin-qunit-lazy-imports', ...]]

correct

module.exports = {
  plugins: [
    ['module:babel-plugin-qunit-lazy-imports', { startsWith: ['my-app/'] }]
  ]
};

Use 'module:' prefix when using babel.config.js in Node.js; not needed in .babelrc or when using require directly.

default
```
const plugin = require('babel-plugin-qunit-lazy-imports');
```
CommonJS require works; no default import in ESM because the plugin does not export a named symbol.

plugin options

wrong

{
  "plugins": [
    ["babel-plugin-qunit-lazy-imports", { startsWith: 'my-app/' }]
  ]
}

correct

[
  'module:babel-plugin-qunit-lazy-imports',
  { startsWith: ['my-app/'], matches: [/.*\.lazy\..*/] }
]

startsWith must be an array of strings; matches must be an array of RegExp. Both options are optional but at least one must be provided.

Quickstart

Shows basic setup with babel.config.js and example transformation of imports into lazy beforeEach imports.

// Install: npm add babel-plugin-qunit-lazy-imports --save-dev

// babel.config.js
module.exports = {
  plugins: [
    [
      'module:babel-plugin-qunit-lazy-imports',
      {
        // Transform imports starting with 'my-app/' into lazy imports
        startsWith: ['my-app/'],
        // Also match any import matching regex (optional)
        matches: [/.*\.lazy\..*/],
      },
    ],
  ],
};

// Before transformation:
// import { foo } from 'my-app/foo';
// import { bar } from 'some-other-lib';
// import { baz } from './baz.lazy';

// After transformation:
// let foo, bar, baz;
// module('...', function(hooks) {
//   hooks.beforeEach(async function() {
//     const mod1 = await import('my-app/foo');
//     foo = mod1.foo;
//     const mod2 = await import('./baz.lazy');
//     baz = mod2.baz;
//   });
// });
// Note: only imports matching startsWith or matches are transformed