browserize
Converts simple node.js modules into ES6 modules.
What it is
What it does
browserize
turns this:
module {}
const extra = 'EXTRA'moduleexports = extra
into this:
{} const extra = 'EXTRA'
main
Recognizes references to browserize
turns this:
module { return true }
const main = moduleexports = extra: main
into this:
{ return true }
This relies on identical names for the default export in both files.
Merges constants and Variables
browserize
turns this:
const common = 'CONSTANT'module { return common }
const common = 'CONSTANT'moduleexports = extra: common
into this:
const common = 'CONSTANT' { return common }
and this:
let common = 'VARIABLE'module { return common }
let common = 'VARIABLE'moduleexports = extra: common
into this:
let common = 'VARIABLE' { return common } common = 'VARIABLE'
NOTE: Since
browserize
cannot know ifcommon
gets changed inmain.js
, it leaves the assignment in place. If the variable is not assigned in the second file, the declaration is removed.
What it does not
browserize
does not:
- check if the result will run in a browser
- transform
require
s intoimport
s - bundle dependencies àla Webpack/Rollup
- transpile anything other than JavaScript, like CoffeeScript (it might work by coincidence, but there's no support for that)
When to use
browserize
is made for small packages without runtime dependencies that should run both in node.js and in the browser.
When not to use
If your package has any dependency, it's probably complex enough to warrant babel, webpack, or some such. Use that instead.
If you need to transpile anything, like CoffeScript or TypeScript, your tooling for that should cover you.
How to use it
NOTE: If you want to interpolate imports, you need to use the node API. This feature is currently not available for the CLI.
node API
You can import either browserize
or browserize/fs
, depending on how you will use it.
browserize
takes an options object with three optional entries:
main
: a string containing the main/default exportnamed
: a string containing the named exportsimports
: a key/value store that maps import paths to replacement values
browserize/fs
takes an options object with three optional entries:
main
: the file where the main/default export is found, defaults toindex.js
, set tonull
for no default exportnamed
: where to find the named exports, defaults tonull
imports
: a key/value store that maps import paths to replacement file pathsoutput
: where to write the ESM file, defaults to themain
ornamed
filename with the extension.mjs
And that is it.
Examples
The simplest form
const browserizeFS =
This reads index.js
and writes the equivalent index.mjs
, and that's it.
Handling in-memory files
const fs = const browserize = const main = fs
Turns the content of main.js
into its ESM version.
This is mainly useful if you want to integrate with a build setup using in-memory files, like gulp
.
browserize/fs
covers
The most complex case const browserizeFS =
This includes named exports, sets custom paths for everything, and interpolates an import into both import files.
Replacing imports
build.js |
|
---|---|
src/main.js |
|
src/constant.js |
|
result |
|
Using this feature, you can extract constants for common use in node files and still have an ESM file without dependencies.
IMPORTANT: The keys are matched verbatim, so
imports:{'./x':'X'}
will do nothing forrequire('./x.js')
.
NOTE: This only works for simple values, like strings and arrays, not functions or classes.
CLI
npx browserize [--no-default|-x]
The CLI passes the given arguments through to the underlying node API, and works through browserize/fs
.
Examples
The simplest form
npx browserize
This reads index.js
and writes the equivalent index.mjs
, and that's it.
Adding named exports
npm browserize -n helper-functions
This reads index.js
and helper-functions.js
, then transforms and concatenates them, and finally writes the result to index.mjs
.
browserize
covers
The most complex case npx browserize class-name.jsx helper-functions.js dist/browser-magic.js
This includes named exports and sets custom paths for everything.
Requirements
browserize
is a simple tool and has a few simple requirements:
module.exports
Each source file must contain exactly one assignment to Good
moduleexports = {}
moduleexports = key1: helper1 key2: helper2
Bad
exportskey1 = helper1exportskey2 = helper2
While valid, browserize
does not know how to transform this.
moduleexports = export1moduleexports = export2
This is not useful anyway.
windowmyStuff = {}
This is not a module.
The default export must be declared without a newline between the assignment operator and the exported item
Good
moduleexports = {}
moduleexports =
Bad
moduleexports = {}
While this is valid in node.js, it will lead to an invalid ESM file.
The named exports must be declared as an object literal
Good
moduleexports = helper1 helper2
moduleexports = helper1 helper2
Bad
moduleexportshelper1 = helper1moduleexportshelper2 = helper2
While this is valid in node.js, browserize
does not understand it.
This is too complex, and has no real benefit over the object literal.
The named exports must use shorthand syntax
Good
moduleexports = helper1 helper2
Bad
moduleexports = helper1: helper1 helper2: helper2
moduleexports = key1: helper1 key2: helper2
While this is valid in node.js, it will lead to an invalid ESM file.