Supporting multiple Javascript environments

Evan K — Fri, 25 Jul 2025 00:01:09 +0000

I've been working on a small utility that I've recently published to npm, and my goal with it was to target both a Node.js and a browser environment.

In order to accomplish this, I picked up a tool that I've been loathe to touch since the last time I used it, roughly a decade ago — Babel.

What's wrong with Babel?

While I wouldn't actually say there's something wrong with Babel, it does (necessarily) involve lots of complexity. It can be an absolute nightmare to configure, depending on your build process(es).

For this relatively simple project, within the space of a week and a half, I wrote, then threw away and rewrote my babel build configuration several times until I was satisfied with the end result.

Then why use a transpiler at all?

When used correctly, a build process that involves transpilation can strike the sweet spot where you're able to use the latest ECMAScript features while maintaining backward compatibility with a variety of target environments.

In my case, I wanted to be able to write my source code using ES Modules that enjoy widespread browser support, while compiling down to the CommonJS module system that's still widely used in Node.js.

Show, don't tell

Full disclaimer: while this is the result of a lot of trial and error, I don't claim to have met any standard of best practices, and would recommend you do your own homework. Decide what best meets your needs, rather than just following my (or anyone else's) example.

Start to finish, my build process consists of a some nested npm run scripts and a decent amount of bash:

dist: kicks off additional run scripts per build target
- build-browser: prepares the browser distributable by way of...
  - concat-browser: concatenates a few source files together into a single build-main-browser.mjs script
  - transpile-browser: runs babel on said script with the .babelrc.esm.json config and an output filename
- build-node: prepares the node distributable by way of...
  - concat-node: concatenates a few source files together into a single build-main-node.mjs script
  - transpile-node: runs babel on said script with the .babelrc.cjs.json config and an output filename
  - bash snippet that copies import.mjs for ESM export/import support on top of the transpiled CJS

This produces:

a browser targeted script in lib/ with the original ES Module exports, leveraging a browserslist query for which browser features to transpile support for
a Node v20 targeted script in dist/ transpiled down to CommonJS, with an additional script to tack on ES Module exports

You can see the result on npm, if you're interested.

Stringifying Errors: A Uniquely Javascript Problem

Evan K — Sun, 29 Sep 2024 00:30:13 +0000

Exception handling, like most things in the Javascript world, is...complicated.

What is or isn't supported may vary widely between client (browser) and server (NodeJS), and further even from one browser to another.

If you're not too familiar already, this is a great guide to all things Javascript error handling.

The short version goes like this:

Exception handling typically involves throwing and catching exceptions, either synchronously (in a try...catch block) or asynchronously (with Promise.prototype.catch).
Javascript provides a standard built-in Error class for you to use, either directly or with extending sub-classes.
The standard Error class comes with useful but not-always-supported (and so not-always-used) features like the stack and cause properties.
The throw statement allows you to throw a user-defined exception, which is notably not required to be an Error object.

The Error class

Error objects are great, but the biggest headache around handling them typically involves stringifying or serializing them, as is evident from this NodeJS console example:

> new Error('a problem occurred').toString()
'Error: a problem occurred'
> JSON.stringify( new Error('a problem occurred') )
'{}'

The error object in question — an instance of the Error class — supports conversion to a string via its toString method. This produces (essentially) a concatenation of the name and message, omitting the stack and any other instance properties. Sometimes this is good, as you just want to know what broke but not necessarily where.

Serialization to JSON is decidedly unhelpful, returning an empty object.

Logging to different destinations

For debugging and most logging purposes, the built-in console.log method prints a friendly and verbose summation of any error directly to stdout (in NodeJS), or to the web console (in browser):

And if instead you need it printed to stderr, look no further than the console.error method.

Well, what if you need to log an error somewhere else? To a file, a database table, a third party logging utility, etc.

You might wonder if there's a way to capture this same output from the console to a string variable, and in NodeJS you technically could. It is not simple, however, and one approach requires another console instance and some trickery with streams.

Streams give me anxiety, so I went another way.

Enter `loggable-error`

A little over two kilobytes of javascript, with zero runtime package dependencies and a single default export.

It produces a string approximate to what console.log would print — an Error object expanded to constructor name, message and stack, with any other instance properties in an object notation:

import stringify from 'loggable-error';

class CustomError extends Error {
    constructor(message, options) {
        super(message, options);
        this.extra = options?.extra;
    }
}

try {
    throw new Error(
        'testing one two three',
        {
            cause: new CustomError(
                'the actual root cause',
                {
                    extra: {
                        message: 'some extra debugging info',
                        values: [ 3.14, 42, null ]
                    }
                }
            )
        }
    );
} catch(e) {
    process.stdout.write(
        stringify(e)
    );
}
/* =>
Error: testing one two three
    at file:///home/jdoe/test.js:11:11
    at ModuleJob.run (node:internal/modules/esm/module_job:222:25)
    at async ModuleLoader.import (node:internal/modules/esm/loader:316:24)
    at async asyncRunEntryPointWithESMLoader (node:internal/modules/run_main:123:5) {
  [cause]: CustomError: the actual root cause
      at file:///home/jdoe/test.js:14:20
      at ModuleJob.run (node:internal/modules/esm/module_job:222:25)
      at async ModuleLoader.import (node:internal/modules/esm/loader:316:24)
      at async asyncRunEntryPointWithESMLoader (node:internal/modules/run_main:123:5) {
    [extra]: {"message":"some extra debugging info","values":[3.14,42,null]}
  }
}
*/

As shown above, it also handles error objects nested as properties with recursive calls to itself, indenting them at the appropriate level.

You've got `options`

Because different situations call for different formatting, the exported function accepts a second options object, allowing you to toggle display of stack traces and control the initial indentation:

// shown here with the default options
stringify(e, { depth: 0, stack: true });

That's all, folks!

The goal here was to keep it simple, but if you have issues or feature requests, I'd love to hear them.

DEV Community: Evan K