babel-plugin-universal-import

3.1.3 verified Sat Apr 25 auth: no javascript maintenance

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.

Common errors

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

cause 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 Error: [BABEL] unknown plugin "universal-import" ↓

cause 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.

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

cause 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'.

Warnings

breaking Chunk 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.

breaking Plugin 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.

deprecated v3 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.

gotcha Webpack 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.

gotcha Dynamic 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.

gotcha Plugin 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).

Install

npm install babel-plugin-universal-import

yarn add babel-plugin-universal-import

pnpm add babel-plugin-universal-import

Imports

default (plugin registration)
wrong
```
{
  "plugins": [["universal-import", "someOption"]]
}
```
correct
```
{
  "plugins": ["universal-import"]
}
```
No options are accepted in Babel config. Plugin is auto-detected in .babelrc or babel.config.js.

universalImport (helper)

wrong

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

correct

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

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

react-universal-component (companion)
wrong
```
import { universal } from 'react-universal-component'
```
correct
```
import universal from 'react-universal-component'
```
Default export, not named. Required if using the universal() wrapper pattern.

Quickstart

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'