babel-plugin-transform-globals

babel-plugin-transform-globals is a Babel plugin that lets you transform global variables in JavaScript. This can be helpful when working with scripts that make assumptions about what is in the global variable space.

1window.addEventListener('click', {
2  document.body.appendChild(
3    document.createElement('div')
4  )
5})
6
7/* becomes (with replace: 'browser') */
8
9window.addEventListener('click', {
10  window.document.body.appendChild(
11    window.document.createElement('div')
12  )
13})
14
15/* becomes (with import: { './my-dom': { window: 'default', document: 'document' }) */
16
17import window, { document } from './my-dom'
18
19window.addEventListener('click', {
20  document.body.appendChild(
21    document.createElement('div')
22  )
23})

Usage

Add babel-plugin-transform-globals to your project:

1npm install babel-plugin-transform-globals --save-dev

Add babel-plugin-transform-globals to your Babel configuration:

1// babel.config.js
2module.exports = {
3  plugins: [
4    'transform-globals'
5  ]
6}

Alternative, configure transformations within your Babel configuration:

1module.exports = {
2  plugins: [
3    ['transform-globals', {
4
5      /* replace global variables */
6
7      replace: {
8        // transform global `varA` into `replaceVarA`
9        varA: 'replaceVarA',
10        // transform global `varB` into `nest.replaceVarB`
11        varB: 'nest.replaceVarB'
12      },
13
14      /* import global variables (ES Modules) */
15
16      import: {
17        'module-import-a': {
18          // when `importVarA` is global,
19          // write `import importVarA = from 'module-import-a'`
20          importVarA: 'default'
21        },
22        'module-import-b': {
23          // when `importVarB` is global,
24          // write `import { altName as importVarB } from 'module-import-b'`
25          importVarB: 'altName'
26        },
27        'module-import-c': {
28          // when `importVarC` and `importVarD` are global,
29          // write `import importVarC, { altName as importVarD } from 'module-import-c'`
30          importVarC: 'default',
31          importVarD: 'altName'
32        }
33      },
34
35      /* require global variables (CommonJS) */
36
37      require: {
38        'module-require-a': {
39          // when `requireVarA` is global,
40          // write `const requireVarA = require('module-require-a')`
41          requireVarA: 'default'
42        },
43        'module-require-b': {
44          // when `requireVarB` is global,
45          // write `const { altName: requireVarB } = require('module-require-b')`
46          requireVarB: 'altName'
47        },
48        'module-require-c': {
49          // when `requireVarC` and `requireVarD` are global,
50          // write `const requireVarC = require('module-require-c')` and
51          // write `const { altName: requireVarB } = requireVarC`
52          requireVarC: 'default',
53          requireVarD: 'altName'
54        }
55      }
56    }]
57  ]
58}

Options

replace

The replace option defines an object of global variable names and the variables that will replace them.

1/* would transform `window.addEventListener` into `__window.addEventListener` */
2/* would transform `document.createElement` into `__window.document` */
3{
4  replace: {
5    'document': 'window.document',
6    'window': '__window'
7  }
8}

The replace option accepts the keyword browsers to automatically prefix global browser variables with window.

1/* would transform `document` into `window.document` */
2/* would transform `HTMLElement` into `window.HTMLElement` */
3{
4  replace: 'browser'
5}

import

The import option defines an object of modules conditionally imported when one of their global variable names are referenced.

1/* on `window.addEventListener` prefix `import window from './dom'` */
2/* on `document.createElement` prefix `import { document } from './dom'` */
3/* on `Node.prototype` prefix `import { __Node as Node } from './dom'` */
4/* on all prefix `import window, { document, __Node as Node } from './dom'` */
5{
6  import: {
7    './dom': {
8      'document': 'document',
9      'Node': '__Node',
10      'window': 'default'
11    }
12  }
13}

require

The require option defines an object of modules conditionally required when one of their global variable names are referenced.

1/* on `window.addEventListener` prefix `const window = require('./dom')` */
2/* on `document.createElement` prefix `const { document } = require('./dom')` */
3/* on `Node.prototype` prefix `const { __Node: Node } = require('./dom')` */
4/* on all prefix `const window = require('./dom'); const { document, __Node: Node } = window` */
5{
6  require: {
7    './dom': {
8      'document': 'document',
9      'Node': '__Node',
10      'window': 'default'
11    }
12  }
13}