Registry / web-framework / babel-plugin-universal-import

babel-plugin-universal-import

library3.1.3jsnpmunverified

Babel plugin that transforms dynamic import() calls into universal imports with chunk name magic comments, designed for use with react-universal-component and extract-css-chunks-webpack-plugin. Current stable version is 3.1.3 (v4.x exists but with breaking changes). Release cadence is sporadic; last v3 release was 2018-10-01, last v4 release 2020-04-15. Key differentiator: automatically generates chunk names, resolve paths, and CSS chunk loading boilerplate. Requires webpack 4+ and Babel 7+. Alternative to manual webpack magic comment management.

web-framework

npm install babel-plugin-universal-import

github ↗package ↗

INSTALL

IMPORT

SIG · BABEL-PLUGIN-UNIVE

babel-plugin-universal-import

web-frameworkjavascriptv3.1.3

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

default (plugin registration)

✓ { "plugins": ["universal-import"] }

✗ { "plugins": [["universal-import", "someOption"]] }

No options are accepted in Babel config. Plugin is auto-detected in .babelrc or babel.config.js.

universalImport (helper)

✓ import universalImport from 'babel-plugin-universal-import/universalImport.js'

✗ const universalImport = require('babel-plugin-universal-import/universalImport')

Helper is ESM-only; require may cause webpack critical dependency warnings.

react-universal-component (companion)

✓ import universal from 'react-universal-component'

✗ import { universal } from 'react-universal-component'

Default export, not named. Required if using the universal() wrapper pattern.

Setup Babel plugin and use with react-universal-component for automatic code splitting with chunk naming.

// .babelrc { "plugins": ["universal-import"] } // app.js import universal from 'react-universal-component'; const AsyncPage = universal(import('./Page')); // AsyncPage can now be used as a component // It will automatically split into a separate chunk with chunkName 'Page'

Debug

Known issues

breakingChunk names are no longer generated as directory structures (e.g., 'components/component' becomes 'components-component')

fix

Update any hardcoded chunk references to use hyphens instead of slashes.

affects: >=2.0.0 <3.0.0

breakingPlugin no longer renames chunks to dashed format; expects magic comments to be preserved as-is

fix

If upgrading from v3, remove any custom chunk renaming logic; let webpack handle names via magic comments.

affects: >=4.0.0

deprecatedv3 is the last stable release supporting Babel 7; v4 is available but has breaking changes

fix

Pin to 3.1.3 if stable; evaluate v4 breaking changes before upgrading.

affects: >=3.1.3 <4.0.0

gotchaWebpack critical dependency warning: 'the request of a dependency is an expression'

fix

Upgrade to 3.0.2+ which uses constant string paths for helper to avoid warnings.

affects: <3.0.2

gotchaDynamic import paths (template strings) may cause incorrect chunk naming if not used with magic comment '[request]'

fix

Ensure dynamic imports use `webpackChunkName: '[request]'` inside import() comments.

affects: >=3.0.0

gotchaPlugin does not support Babel 6; requires Babel 7+

fix

Upgrade to Babel 7 or use v2.x (which supports Babel 6 but with fewer features).

affects: >=3.0.0

Errors

Common errors & fixes

WARNING in ./node_modules/babel-plugin-universal-import/universalImport.js 33:18-37 Critical dependency: the request of a dependency is an expression

Using require() to import the helper, causing webpack to treat the import as dynamic.

fix

Use ESM import: `import universalImport from 'babel-plugin-universal-import/universalImport.js'`

Error: [BABEL] unknown plugin "universal-import"

Plugin not installed or not registered in Babel config correctly.

fix

Run `npm install babel-plugin-universal-import` and add 'universal-import' to plugins array.

Module not found: Can't resolve 'babel-plugin-universal-import/universalImport.js'

Using wrong import path or helper not available in early v1/v2.

fix

Upgrade to v3+ which includes the helper. Import from 'babel-plugin-universal-import/universalImport.js'.

Upgrade

Version history

3.1.3latest on npm

Audit

Dependencies

webpackoptionalPeer dependency; plugin generates webpack-specific chunk loading code

Agent activity

9 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/faceyspacey/babel-plugin-universal-import ↗

packagehttps://www.npmjs.com/package/babel-plugin-universal-import ↗