Put the knife down and take a green herb, dude. (c) Ruffin Bailey 2001-2021

NOTE: Snowpack is obsolete at this point, which makes this post, um, less useful.

If you've been working with JavaScript for a while, you'll know that things have changed from the day when the code end users saw in production was the same code you hacked with your hands. Though I might prefer the days of Vanilla.js, it's gotten nearly impossible to hold a job without knowing how to transpile code.

If you're still on the Vanilla side of the chart, transpiling JavaScript code is when you take a recent version of JavaScript, or, more properly, ECMAscript, and essentially compile it into an older, more compatible version. Transpiling is a "source-to-source" compilation, from one programming language (or version) to another, so to speak.

Maybe you want to use "farts" or "fat arrow functions" where you can exchange this code...

function (x) {
    return x + 1;
}

... with the shorthand...

(x) => x + 1;

Or maybe you want to use shorthand property definitions, which turns this:

var o = {
  a: a,
  b: b,
  c: c
};

... into...

let o = {a, b, c};

Or maybe you just want to use let and const instead of being limited to var.

Or, even better, maybe you want to use TypeScript, which is a great idea, bringing along the bug-squashing safety of strong-typing without sacrificing the abilty to go full dynamic when you need it.

You get the point. JavaScript keeps adding features (as does TypeScript), but older browsers won't magically support all of them. You need to turn your cutting-edge code into something [insert lowest common denominator based on your browser requirements] can run.

That's transpilation. Even if you're not going to transpile something, you need to be aware of how it works so that you can pick the right tools for your projects.

I'll probably make a video at some point, but I would like to quickly get down the steps I think I'd take when moving from a vanilla, es5-compatible JavaScript codebase.

Notes, warnings, and caveats

Why target your transpilation for es5? es5 is the latest version IE supports, as a benchmark. es6 requires more modern browsers. Luckily requirements to support IE seem to be going the way of the dinosaur.

That said, I haven't (yet) run into a situation where a transpiler balks at targeting es5. That is, why not include IE if transpiling to something newer buys me nothing? Everything I can do in es6 I can, thanks to some insane transpiler shimming, do in es5.

Warning: This is not going to be a howto, I'm afraid, but a command recipe for those who already kind of know what they're doing.

It's also not a really nuanced recipe. For instance, when you run npm init, you probably don't want to use the -y flag and should instead pick a specific license. For some reason, using the -y flag means you'll pick "ISC", "a permissive free software license published by the Internet Software Consortium" instead of "UNLICENSED" for your project, and "UNLICENSED" is what the docs say to use for copyrighted code.

So use at your own risk.

And to be overly clear, this is for browser development, not server-side node dev, natch.

Recipe to move es5 codebase to modern JS (with snowpack, webpack, & babel)

Here's the 10,000' view:

Use Snowpack to transpile your TypeScript into modern JavaScript.
Use webpack to fold your modern JavaScript into a single file.
Use babel to transpile your modern JavaScript into es5 compliant code.
(Use some node code, called by your build process, to link to that single es5 page from your starting html.)

Here are the specific steps:

Ensure you've got node installed globally
- The node install will include installing npm.
- If you know you will need to swap to different versions of node for different projects (as in you know you have some older ones that won't work in the latest version of node), google nvm ("node version manager").
  - You should, however, know if this applies to you.
  - (If this is your first transpilation project, different versions of node don't apply. Yet.)
Navigate to an es5 code base.
In the home directory of the codebase, run npm i -y
- See caveat about licensing, above.
Now run npm install -D snowpack
- Snowpack is a development tool only imo.
- It is not a conventional transpiler so much as a package manager.
- snowpack's goal is to allow you to develop in a browser that supports whatever version of JavaScript you want to program in (vs. deploy) quickly.
- It does, however, support compiling TypeScript on the fly. That and the more deliberate management of libraries are the biggest gains snowpack buys for me.
"Port" your existing es5 to TypeScript by changing all JavaScript files' extensions from .js to .ts
- TypeScript is a superscript of JavaScript, so that's all you have to do.
- On macOS, you can use this command:
  - find . -iname "*.js" -exec bash -c 'mv "$0" "${0%\.js}.ts"' {} \;
- I've got a PowerShell script to do this somewhere, but until I find it, try these answers.
Add a snowpack.config.js file to the root directory.
- I'm glossing over a lot here. See below the receipe for an example snowpack config.
Add "start": "snowpack dev" to your package.json's scripts collection
Install webpack as a "dev dependency" for your project with npm install -D webpack-cli
- Example webpack config is below.
Add this build command to your package.json's scripts collection:
- "build": "snowpack build && webpack"
- Here, snowpack is going to compile your TypeScript into JavaScript.
- Then webpack is going to take the compiled JavaScript and pack it into a single index.js file.
- Hang in there. We're getting to the transpilation.
npm install --save-dev babel-loader @babel/core
- We're using Babel to transpile the code.
- Up until this point, we needed a modern browser that understood our untranspiled code.
- Not a big deal as you develop, but potentially a very big deal before releasing.
Add this command to package.json:
- "launderIndexHtml": "node ./buildscripts/build.js"
Add build.js to your project's home directory using the template, below.
Edit package.json's build command to include this new build command:
- "build": "snowpack build && webpack && npm run launderIndexHtml",
- Why didn't we just start with that for our build command? Idk. This recipe is too tutorial-ly, I suppose.

Suggested initial `snowpack.config.js`

/*global module */
module.exports = {
    mount: {
        public: { url: "/", static: true },
        app: "/",
    },
    buildOptions: {
        out: "./dist",
    },
    devOptions: {
        open: "brave",
    },
};

Why does this open Brave when in devOptions.open? Well, I like to have a browser dedicated to testing and Canary wasn't an option snowpack supported at the time of this writing, strangely enough.

Suggested initial `webpack.config.js`

/*eslint-disable */
const path = require("path");
module.exports = {
    entry: "./dist/index.js",
    output: {
        filename: "./index.js",
        path: path.resolve(__dirname, "dist"),
    },
    module: {
        rules: [
            {
                test: /\.(js)$/,
                exclude: /node_modules/,
                use: ["babel-loader"],
            },
        ],
    },
    resolve: {
        extensions: ["*", ".js"],
    },
};

Custom `build.js` script

/* eslint-env node */
// We need to do two things after we've compiled our TypeScript with snowpack,
// transpiled into es5 with babel, and bundled & minified with webpack:
// 1. Update index.html to load our minified es5 file as-is, not as a module.
// 2. Get rid of the source we bundled into our webpack output.
var fs = require("fs");
var indexLoc = "./dist/index.html";
fs.readFile(indexLoc, "utf8", function (err, data) {
    if (err) {
        return console.log(err);
    }
    var result = data.replace('script type="module" src="./index.js"', 'script src="./index.js"');
    // var result = data.replace(/script type="module" src="./index.js"/, 'script src="./index.js"');
    fs.writeFile(indexLoc, result, "utf8", function (errWrite) {
        if (errWrite) {
            return console.log(errWrite);
        }
    });
});
function getDirectories(path) {
    return fs.readdirSync(path).filter(function (file) {
        return fs.statSync(path + "/" + file).isDirectory();
    });
}
var foldersToKeep = ["lib", "css", "assets"];
getDirectories("./dist").forEach((x) => {
    if (foldersToKeep.indexOf(x) === -1) {
        fs.rmdirSync("./dist/" + x, { recursive: true });
    }
});

Labels: howto, javascript, transpilation, typescript

I noticed today I've been using TypeScript for years and really haven't blogged about it at all. I guess that's not surprising; it essentially does exactly what it says it does: Turns the Wild West of fully dynamic JavaScript development into a strongly-typed, well-controlled arena.

I love doing dynamic stuff with JavaScript (a dynamic language provides for a very particular set of mental challenges), but for the most part, aside from massaging payloads to and from servers (so when we jump concerns from, eg, client to API), it's A Very Bad Idea to go full dynamic. And that means I love TypeScript. It takes some of the silly putty of JavaScript and puts it into the hard Lego blocks of C#, if I can reuse an interview answer I gave once upon a time...

The use case

But as I prepare a large and reasonably mature .NET MVC/AngularJS codebase [sic] for TypeScript, I ran back into the age old issue of how to expose my exports. Is there a way to import an entire directory of files easily? No, not really, no there's not.

The usual shorthand for doing this is to import from barrel files. And that's probably the way to go to start, creating multiple child barrels per folder and exposing them in an uber-barrel at the top. We have scores of AngularJS files to move to TypeScript, and currently have a <script> import per file (no, literally a line of <script> per AngularJS source file) in the main cshtml page, all generated by a giant .NET MVC's bundle config. Ewww. So we cut each folder into its own import and import the parent barrel in the index.html equivalent.

_{(I'd mistakenly thought the bundles were log files, I think as in logrolling, another term I tend to remember in concept but forget the term, though with the growing importance of elections, I'm doing better remembering now.)}

What's a barrel?

Here's a decent description of the advantage of barrels from a self-titled TypeScript Book on github.com:

Without a barrel, a consumer would need three import statements:

import { Foo } from '../demo/foo';
import { Bar } from '../demo/bar';
import { Baz } from '../demo/baz';

You can instead add a barrel demo/index.ts containing the following:

// demo/index.ts
export * from './foo'; // re-export all of its exports
export * from './bar'; // re-export all of its exports
export * from './baz'; // re-export all of its exports

Now the consumer can import what it needs from the barrel:

import { Foo, Bar, Baz } from '../demo'; // demo/index.ts is implied

Here's another source that give or take explains my use case:

Since we are using many components in app.routing.module.ts file, we must import their reference for .component.ts and .module.ts files. A general import statements would looks like this:

import { DashboardComponent } from './dashboard/dashboard.component';
import { LoginComponent } from './login/login.component';
import { SignUpComponent } from './sign-up/sign-up.component';
import { AccountOverviewComponent } from './dashboard/account/account-overview/account-overview.component';
import { AccountSecurityComponent } from './dashboard/account/account-security/account-security.component';
import { CartOverviewComponent } from './dashboard/cart/cart-overview/cart-overview.component';
import { CartItemDetailsComponent } from './dashboard/cart/cart-item-details/cart-item-details.component';
import { CartComponent } from './dashboard/cart/cart/cart.component';
import { ProductComponent } from './dashboard/products/product/product.component';
import { ProductsDetailsComponent } from './dashboard/products/products-details/products-details.component';
import { ProductsOverviewComponent } from './dashboard/products/products-overview/products-overview.component';
import { DashboardModule } from './dashboard/dashboard.module';
import { AccountModule } from './dashboard/account/account.module';
import { CartModule } from './dashboard/cart/cart.module';
import { LoginModule } from './login/login.module';
import { SignUpModule } from './sign-up/sign-up.module';
import { ProductsModule } from './dashboard/products/products.module';

...

Typescript module resolution picks up index.ts file from folder name if it is there and try to import packages.

In this file, we can export all folder specific components and modules. For example, consider index.ts file inside products folder:

export * from './product/product.component';
export * from './products-details/products-details.component';
export * from './products-overview/products-overview.component';
export * from './products.module';

...

Here are the complete import statement[s] using index.ts file approach

import { AccountOverviewComponent, AccountSecurityComponent, AccountModule } from './dashboard/account';
import { CartComponent, CartOverviewComponent, CartItemDetailsComponent, CartModule } from './dashboard/cart';
import { ProductComponent, ProductsDetailsComponent, ProductsOverviewComponent, ProductsModule } from './dashboard/products';
import { DashboardComponent, DashboardModule } from './dashboard';
import { LoginComponent, LoginModule } from './login'
import { SignUpModule, SignUpComponent } from './sign-up';

Looks neat and simple, [doesn't] it?

The evil side of barrels: Circular dependencies

As I got ready to put our AngularJS files into barrels for the TypeScript port, I recalled that thar be dragons in the barrel file. But I couldn't remember what it was, precisely.

Turns out it's that importing and exporting indiscriminately can run you into circular dependencies.

Here's a decent explanation:

Barrel File Caveats

Although its is not directly related to barrel files i-e circular dependency. Circular dependency occurs when a Module A somehow imports itself.

B imports A, C imports B

At the end of the day Module A imports itself

Make sure you don’t get into this kind of trouble especially when using Barrel files.

And because everyone and their brother says circular dependencies, but don't actually explain where it'd happen, here's one real-world example of this issue:

From nestjs.com:

WARNING

A circular dependency might also be caused when using "barrel files"/index.ts files to group imports. Barrel files should be omitted when it comes to module/provider classes. For example, barrel files should not be used when importing files within the same directory as the barrel file, i.e. cats/cats.controller should not import cats to import the cats/cats.service file. For more details please also see this github issue.

The linked GitHub issue:

alexandr2110pro commented on Oct 9, 2018:

Minimal reproduction of the problem with instructions

Not sure. We've got nearly 50 modules and all are working fine.
And most of them actually use AuthModule as you might guess.

Only this one, that I've created recently can't load. Any ideas on what am I doing wrong? :)

The begrudging fix:

alexandr2110pro commented on Oct 11, 2018:

So in the end, nothing has changed... I didn't remove/change the code. I've just moved 2 functions from separate files to the test file body. That's it!
And of course, the imports in the test file changed:
/* <...> */
import {
  createAccessToken,
  createAccount,
  createUser,
  // findOneInvitation,  <-- was here when I had an exception
  // findOneAccount,     <-- was here when I had an exception
  E2ETestingContainer,
  E2ETestingModulesFactory,
  findOneRole,
  findOneUser,
  FixtureLoader,
  FixtureLoaderConfig,
  JEST_E2E_TIMEOUT,
  MongooseFixturesService,
} from '../../testing';
/* <...> */
@kamilmysliwiec
I think we can close the issue if you want.
But if somebody can tell me what the hell is going on here, I'd greatly appreciate that!

The explanation:

kamilmysliwiec commented on Oct 16, 2018:

I would suggest omitting barrel files when it comes to module's providers/module class OR using them very carefully (for example, even if you create a barrel, you shouldn't use it from within the same module itself [only from outside] and when circular dependency may potentially appear).

Wait, huh?

I'm not going to swear I get it. I think there might be some interaction with dependency injection.

See this blog post on class declarations not hoisting in JavaScript and how order matters. I think a similar issue is illustrated (as in literally illustrated with a flowchart) here, but doesn't mention barrels.

See also this reddit post [sic] that lays out a circular dependency setup for related objects reasonably well.

Another real world use case. And here's some jive on circular references in general, elementary stuff, but perhaps useful.

From github.com:

Desired functionality.
An option to ignore these kind of circular deps
A => barrel => A

I think that's it in a nutshell. Something in the indiscriminately broad barrel is importing/exporting the same thing that started the chain. I'm suspicious it's actually A => barrel => Lots of difficult to follow dependencies => A, but you get the idea. If you import a barrel that could contain something used in the same library, you can easily get a circular dependency. Instead, you should roll the barrel in one directly only, never using it within your own self-contained module, only exposing its contents to use in another app that imports it.

And that makes sense with the original example of having helper functions that blow up. If your object imports helper functions and models that also use the helper functions you could be entering a world of pain. Though I'm still not 100% convinced. More like 50% sure I smell something.

And here's the bottom line from an anonymous poster:

Anonymous says:
January 3, 2021 at 12:10 pm
@lasimone just don’t use barrels within same module. Use relative imports.

Wait a minute. Didn't the Angular.io style guide used to encourage barrels?

Yes, yes it did. But though it originally encouraged them, the Angular style guide now doesn't mention barrels. This change used to be described on the Angular changelog page, but isn't there any more.

As of today, anyhow, you can find an archive of the warning here, if you're curious:

"Style Guide" with NgModules (2016-09-27)
StyleGuide explains recommended conventions for Angular modules (NgModule). Barrels now are far less useful and have been removed from the style guide; they remain valuable but are not a matter of Angular style.

Looks like you can find the history of this style guide here now, and here's what the style guide used to say about using barrels:

Create and Import Barrels

Style 04-10

Consider creating a file that imports, aggregates, and re-exports items. We call this technique a barrel.

Consider naming this barrel file index.ts.

Why? A barrel aggregates many imports into a single import.

Why? A barrel reduces the number of imports a file may need.

Why? A barrel provides a consistent pattern to import everything exported in the barrel from a folder.

Why? This is consistent with a pattern from Node, which imports the index.js|ts file from a folder.

Why? A barrel shortens import statements.

And that's the belated history of barrel file use for importing JavaScript/TypeScript files.

Btw, is anyone else going crazy with the new font choices at StackOverflow? Why did you sell, Joel? I hope you're enjoying your hats of money. ;^D

Labels: javascript, noteToSelf, typescript

Add p/React to any legacy client codebase

State & Events Up

Step 1: How I chose React

Notes, warnings, and caveats

Recipe to move es5 codebase to modern JS (with snowpack, webpack, & babel)

Suggested initial `snowpack.config.js`

Suggested initial `webpack.config.js`

Custom `build.js` script

The use case

What's a barrel?

The evil side of barrels: Circular dependencies

Barrel File Caveats

Minimal reproduction of the problem with instructions

Wait, huh?

Desired functionality.

Wait a minute. Didn't the Angular.io style guide used to encourage barrels?

"Style Guide" with NgModules (2016-09-27)

Create and Import Barrels

Style 04-10

Too Many Tools.

Why a Pattern?

Unraveling a Promise

Unraveling a Promise with a `finally`

Promise wrapping

TL;DR

Add p/React to any legacy client codebase

State & Events Up

Step 1: How I chose React

Notes, warnings, and caveats

Recipe to move es5 codebase to modern JS (with snowpack, webpack, & babel)

Suggested initial snowpack.config.js

Suggested initial webpack.config.js

Custom build.js script

The use case

What's a barrel?

The evil side of barrels: Circular dependencies

Barrel File Caveats

Minimal reproduction of the problem with instructions

Wait, huh?

Desired functionality.

Wait a minute. Didn't the Angular.io style guide used to encourage barrels?

"Style Guide" with NgModules (2016-09-27)

Create and Import Barrels

Style 04-10

Too Many Tools.

Why a Pattern?

Unraveling a Promise

Unraveling a Promise with a finally

Promise wrapping

TL;DR

Suggested initial `snowpack.config.js`

Suggested initial `webpack.config.js`

Custom `build.js` script

Unraveling a Promise with a `finally`