Tierney Cyren

My 🔥 First Experience Attending TC39

2019-04-15T00:00:00Z

A few weeks ago I had the opportunity to attend TC39, the ECMA technical committee that defines the ECMAScript specification, for the first time. As a first-timer, the experience wasn't what I expected and I want to share what it was like being there. I'd like to share that experience with y'all 💖

What the heck is TC39

TC39 is a Technical Committee (hence TC) under ECMA International that defines the ECMAScript standard – better known as JavaScript. There's a pretty good article outlining what the differences between the two are over on FreeCodeCamp.

tl;dr: TC39 builds the specification that browser engines implement that lets you run JavaScript.

Terminology

I wanted to build a tiny list of terminology because there is a lot of words that are commonly used in the meetings. Trying to interpret the terminology while also keeping up with the discussions was a challenge. Going into the meeting, I knew none of the terminology. Over three days I ended up catching on. In the rest of this article, I'll be using some of these terms – I wanted to put them up front so y'all will be able to refer to them 💖

Proposal: A proposal is a suggested addition to ECMAScript. For example, import() and BigInt are both proposals. You can find the full list of proposals on GitHub.
Stages: The mechanism that TC39 uses to advance proposals. I would argue this is a consensus mechanism, though others may disagree. You can find the entire staging process in the process document.
Plenary: The part of the meeting in which proposals are being discussed. Effectively, when everyone is in the room discussing proposals.
Normative: Typically brought up in the context of "normative changes", when something is normative it's a requirement in the spec that's not reflected correctly. A "normative change" is a change that is intended to resolve such an issue. Basically, they're bugs in the spec. See @allenwb's comment on this post for more context!
Delegate: An individual representing a member (members are corporate entities) of ECMA International.
Invited Expert: Someone who is invited by the Secretariat General (a role currently held by Istvan Sebestyen – you can see the job description here) or a member or of TC39 (as far as I can tell?) as a domain expert. They are not delegates themselves.

Expectation vs. Reality

What were my expectations going in?

In the context of the plenary session, I was expecting was an extremely high barrier in terms of a computer science education and in terms of understanding how specifications work. That is not my background, so I was... nervous about that expectation.

As an extension of that expectation, I was confident that I wasn't going to be able to contribute to the meeting much at all – I was expecting to observe the meeting to figure out if there was a path to meaningful contributions for me.

How did my expectations stack up to reality?

In reality, the technical barrier was a lot lower than my expectations. There was a lot I didn't understand, but that mostly seemed to stem from not being familiar with the specification and how certain parts of it work – less of a "you're not coming from a computer-science background" and more of a "you're not familiar with this specific context." I know I can catch up on context, but I don't think I can reasonably catch up on a comp-sci degree.

This isn't to say that a computer science background wouldn't be helpful (it absolutely would), but I'm not feeling left out because I don't have one. There is a tremendous amount of work that can be done with other skills. Technical writing, reviewing, contributor onboarding, and even experience with JavaScript as a developer of any level are all traits that are appreciated in the meetings and in work on GitHub.

Additionally, I was surprised that there were multiple paths to non-trivial contributions that weren't just technical contributions. Just like any good open-source project, TC39 seemed to value non-code contributions. I now realize how... silly my expectation of not being able to contribute was because the vast majority of the work done in TC39 isn't actually about writing code. There is absolutely code written (see, for example, the Realms proposal, which has a shim, examples, and other bits of code) but an immense amount of the work seems to be writing docs, building consensus, and other work to help surface both the specification and the processes via which the specification are built.

I was incredibly happy to be able to assist with meeting minutes – of which there were roughly two dozen pages written on each of the three days. As someone with ADHD, it was awesome to be able to follow along with the discussion by typing out what I was hearing (this personally helps me commit information to memory more easily) and work with 1-2 other people at a time on getting content into the minutes as a team. Additionally, there were several points when I hit a limit of being able to focus on the discussions, and I was able to spin out at those points and focus on something else. Everyone who was working on the minutes was incredibly friendly, and I felt like that contribution was valued – something I'd 100% not expected out of the first meeting.

Timeline

TC39 meetings span three days. I'm not sure what the plan usually is, but this meeting was Tuesday, Wednesday, and Thursday. I assume they intentionally put it in the middle of the week so delegates can travel and attend on their work-week, rather than forcing them to travel over the weekends.

Let's dig into what each day looked like in terms of what happened in plenary and planned activities.

Day 1:

Plenary session:
- Started with What seemed to me to be boilerplate kickoff presentations (some metrics reporting about the spec
- Some high level "normative" presentations
- Advancement of a few non-controversial proposals through the stages
After plenary, there was a first-timers meetup, led by Aki Rose Braun – one of the TC39 co-chairs.
- I found it helpful to identify who else was also at the meeting for the first time (a few people from Netflix, IBM, GitHub, and of course myself from Microsoft).
- This meetup provided a space for me to get the vast majority of my questions answered!

Day 2:

Plenary session:
- Discussions of the more meaty/controversial proposals started.
  - Multiple people told me this would be how it went on Day 1.
  - The proposals discussed were all at various stages – 1, 2, and 3.
    - I'd not expected this much diversity in the levels of maturity of each proposal, but it was exciting to see how the conversations were slightly different at each stage.
    - One of the biggest takeaways from this experience was that certain types of concerns only come up at certain stages, and some concerns can be ignored until a proposal reaches a given stage.
  - One or two discussions went into overtime and had additional time allotted to them later so we could continue working through the other proposals.
Ended with a dinner for the entire attending membership (and invited experts) of TC39.

Day 3:

Plenary session:
- Almost identical in structure to Day 2.
- Major difference that I noticed in this meeting – not sure if this is standard practice – was that the the proposals for features that typically get a lot of attention from the broader JavaScript ecosystem were on Day 3, as opposed to the features that get less widespread attention.
Ended with the Modern JavaScript: /runtimes/ meetup that was organized by Myles Borins.

There were a few constants between all the days:

Breakfast and lunch were provided by the venue each day.
There was about an hour for lunch, and several 5-15 minute breaks throughout the day.
Individuals – myself included – dropped out often to attend meetings or complete their normal work that they needed to do. Plenty of space was available to do this, and it wasn't looked down upon at all.
Each night, some tangent of attendees ended up going out to grab dinner as a group whether or not there was something officially planned.

Something I'd not expected in any way was the hallway track – during lunches, breaks, and at the dinners I attended, I had many excellent discussions with people who I'd not met before. Everyone was incredibly warm and welcoming – probably more so because I was a first-time attendee.

Also worth noting that this specific meeting was graciously hosted in the Google NYC offices, thanks to Myles Borins and the cast of JavaScript Googlers in NYC.

Takeaways

Even though I'd come in with few expectations, the entire experience broke the mold that I thought it would fit in.

Every single delegate that I talked to was extremely encouraging of new participants, absolutely following the same structure and practices that I've come to expect from open-source projects – straying from how I'd assumed standards bodies operated in general. My unique personal background was valued. I was warmly welcomed and gently encouraged to contribute however I felt comfortable. The kind of non-technical work that I end up doing – documentation, first-timer onboarding, and context building – is something the group is looking to do more of.

One of the threads that were brought up each day in various ways was engagement with the broader JavaScript community – not as a question, but more as a value. Much as my assumptions about standards bodies were challenged by work that's already been completed around encouraging new delegates and their participation, I'm extraordinarily happy to see that the individuals who represent TC39's membership care about this and are holding it more like a core value and less as "something we should probably do", as I assumed.

Overall, the experience was different than anything else I've ever done in terms of technology and community. I fairly confident I'm going to continue participating as a delegate, and see how I can meaningfully contribute to processes, community, and the spec itself.

Using npx and npm scripts to Reduce the Burden of Developer Tools

2019-04-22T00:00:00Z

On Friday, I was working on a workshop-ified version of Step by Step Express for Flawless Hacks in Brooklyn.

In the workshop-ified version, I've modified each step so there is an app.js and an app.complete.js so that attendees could start with a clean slate from the previous step and know what they're aiming for to complete in the step that they're working on.

I figured there was probably a tool on npm that would allow me to lower the barrier even further to let attendees/users know what they need to do to complete the step and check their code against app.complete.js if their code isn't doing what they think it is.

After a bit of searching, I was able to find Pretty Diff, which exposes a CLI tool that allows you to diff two files, and show the difference in the console.

I tested the CLI a bit after globally installing it and was able to figure out that because of how I structured the changes (app.js and app.complete.js in each folder in addition to each folder having its own package.json), I was able to use the same command for every single step:

diff source:"app.js" diff:"app.complete.js"

Awesome! I found a tool that will hopefully lower the barrier to finding success with the code that they'll be writing. There's only one problem: they'll need the CLI to be installed for the above command to work. That sounds like a fantastic way to increase the barrier to entry and waste time on tooling that was intended to improve the experience, not take away from it 😱

Enter npx

Luckily, there's this excellent tool that everyone who has a modern version of npm installed already has: npx.

In case you're not familiar, npx is a CLI that the npm team ships which automagically executes a CLI from a module on the npm registry. Ideally, most modules will only ship one top-level command – for those modules, you can simply run npx <module name> and the command will be executed.

In our case, we're looking to run the prettydiff module and pass the diff command. Luckily, npx makes this super easy:

npx prettydiff diff source:"app.js" diff:"app.complete.js"

Workshop attendees can 100% run this in any of the steps' directories and they'll be able to see a diff of the before/after!

Awesome! I've found a workable solution... that is 58 characters long and has some weird syntax that may be difficult to remember for everyone. It works, but it's not necessarily ideal. Luckily, we can make it even easier.

Using npm scripts

npm scripts are a super handy utility in our toolbelt that makes repetitive tasks and long commands easy. Awesomely, you can use npx inside of npm scripts – meaning you can use any CLI on npm to do work in your project without ever needing to actually install it. This is fantastic for build steps, productivity tools, and (in our case) diffing code.

In my case, I added a diff command to my package.json:

  "scripts": {
    "lint": "standard",
    "diff": "npx prettydiff diff source:\"app.js\" diff:\"app.complete.js\""
  },

Now, instead of needing to write out npx prettydiff diff source:"app.js" diff:"app.complete.js" attendees of my workshop can just type npm run diff and the command will execute 🤗

Fin

I love npx and think npx + npm scripts is a super powerful combination that allows end-users of our JavaScript code to reduce the cognitive load of repetitive commands that aid their workflow. I wanted to share this quick example of how I've used it in hopes of enabling others to focus more on code rather than getting caught up on workflows ✨

If you've got any questions about npx, npm scripts, or anything else I've talked about in this article, please don't hesitate to ask in the comments – more than happy to answer any questions you may have!

The Awesome Features that Just Landed with Node.js v12

2019-04-25T00:00:00Z

This week, we saw the release of Node.js v12, the next Node.js release line that will become LTS. I wanted to go through the various posts that went out and the changelog and condense the information into an easily consumable digest of what's new in Node.js v12.x to share with everyone. 💖

The 🔥 Changes

Let's dig into some of the most important and remarkable changes that have landed in v12.0.0!

New ES Modules, who dis

With the release of Node.js v12.0.0, we see the introduction of a new implementation of ES Modules in Node.js. 🎉

Note: ES Modules features are still Experimental and as such should not be used in production code until they are finalized.

At release, this new implementation has replaced the previous implementation behind the --experimental-modules flag. This is intended to help get the new implementation out there and tested so the project can get feedback. If all goes well (🤞), this can ship unflagged once Node.js v12 goes LTS in October!

Up front, I want to say this is going to be a tl;dr. If you're interested in a deeper dive into the new hotness around ESM in Node.js, please check out the blog post by the Modules Team on Medium.

Previous implementation

Many of the previous implementation's features carried over. This includes ES2015 import statements, various kinds of export, Node.js export support on all core modules, WIP imports for CommonJS, very WIP loader API, and explicit ESM parsing if the .mjs file extension is present.

New implementation features

These features are 100% new with the enhancements the Modules Team has been working on, and are available behind the --experimental-modules flag in Node.js v12.0.0.

Import and export syntax in .js files
- there was lots of feedback that Node.js needs to provide a way to use import/export in .js files.
- Two different solutions were implemented for this (keep reading!)
Support for "type": "module" in package.json
- If this is detected, Node.js will treat all .js files in your project as ES Modules.
- If you still have CommonJS files, you can rename them with the .cjs file extension, which will tell Node.js to parse them as CommonJS explicitly
- An --input-type flag for cases like --eval and STDIN

Current WIP Features

These features are currently being worked on by the Modules team and are either implemented but are likely going to change or are being worked on but did not ship in Node.js v12.0.0.

JSON imports
- Currently does not work, but is being actively worked on.
import and require interop
- ️️⚠️ The Modules Team has requested that you do not publish ES Modules that can be used in Node.js until it's been resolved. I assume that modules published before this is resolved will likely break.
Module Loaders
- ⚠️ Very WIP
- A first implementation of the --loader API has shipped, but it's going to be improved upon and, as such, change.
A simpler way to require in ES Modules code.
- The current implementation is a bit heavy-handed. The Modules team is working on lowering the barrier.
Package path maps
- This would allow for less verbose imports in certain situations
Automatic entry point module type detection
- Effectively, static analysis that would allow Node.js to figure out if a module is a CommonJS module or an ES Module.

Quick ESM Examples

If you're interested in seeing what ESM in Node.js looks like, you can check out two repos I pushed out yesterday:

simple-esm – an example of what ESM in Node.js looks like with the current ESM implementation
simple-esm-usage – an example of how you could use ESM modules from npm in Node.js if the current implementation were to ship unchanged (it's going to be changing, so this is more theory than practice)

I'm planning to keep these repos (and the version of simple-esm published to npm) both up-to-date as the ESM implementation changes both for my own understanding and as a community resource to have a minimum viable example of ESM in Node.js.

V8 7.4

This release included a major V8 upgrade, jumping forward several releases to the most recent version of V8 at time of release. This upgrade includes a plethora of really fantastic enhancements. I'm personally most interested in Zero-cost Async Stack Traces, but there are a plethora of additional enhancements that are better outlined by Mathias Bynens from the V8 team:

https://twitter.com/mathias/status/1120700101637353473

TLS 1.3

Next up, we have official TLS 1.3 support. This is an incredible improvement to previous TLS versions, and I'm super excited that it's now supported in a release line that'll be going LTS! Thankfully, this is a backward compatible change thanks to the underlying implementation in OpenSSL 1.1.1. Additionally, it's mentioned in the PR that it should be backported to other LTS release lines.

If you're curious about the awesome parts of TLS 1.3, I recommend this blog post from the IETF.

Worker Threads

This is the first LTS release line that will include the currently-experimental work on Worker Threads. This release has removed the need to run Worker Threads with a flag, hopefully lowering the barrier to more widespread usage of the tool for parallelizing work in Node.js.

If you're interested in trying out Worker Threads today, there are a few resources you can use to get started:

Built-in Heap Snapshotting

In this release, we also see built-in heap snapshotting adapted from the heapdump module on npm. This is exposed via v8.getHeapSnapshot() and returns a readable stream.

Other Notable Changes and Improvements

Core Dependencies:
- Upgraded to OpenSSL 1.1.1b (nodejs/node#26327)
- Upgraded to ICU 63 (nodejs/node#25852)
  - There is also currently an open PR to further update to ICU 64.2
Node.js has started using llhttp as its default parser (nodejs/node#24730)
Invalid main entries in package.json will now throw an error (nodejs/node#26823)
node --debug is now EOL – use node --inspect instead (nodejs/node#25828)
TLS 1.0 and 1.1 are now disabled by default (nodejs/node#23814)

Fin

Hopefully this overview of the new release is helpful to you! If you've got any questions about the new features that've shipped, when you can start expecting to use ESM in Node.js, or anything else about Node.js v12 I'm happy to be a resource for you to hopefully find the answers you're looking for!

An Unintentionally Comprehensive Introduction to GitHub Actions CI

2019-10-02T00:00:00Z

We're currently approaching GitHub Actions v2 shipping publicly for everyone to use. I'm personally super excited about this because it means I don't need to configure an external service to run my CI – I can slap in some YAML, and I'm off with a cross-platform (!) CI system with multiple versions of Node.js installed.

For me, that's bliss. No need to go to an external site; everything is very neatly contained. That said, when I've used other CI services in the past (primarily Travis CI and Azure Pipelines) I've generally just copy/pasted someone else's CI configuration from the beginning and then tweaked it with additional context.

This time though, there's minimal prior context. During the beta of Actions v2, GitHub has published a few different CI templates that I could copy/paste certain parts from. However, there are a few standards I hold all of my projects to:

npm install should pass on the latest versions of all operating systems
npm test should pass on the latest versions of all operating systems
npm install and npm test should succeed without fail on all currently supported Node.js versions

This ends up meaning I have a matrix of anywhere from 9 (3 versions multiplied by three operating systems) to 12 (4 versions multiplied by three operating systems) CI runs on every project at any time. I've found that the implementation of how to achieve this varies greatly depending on the CI system.

Given that there's not going to be a massive amount of prior art on release, I figured I'd begin building out some comprehensive templates so at launch people will have something to easily copy/paste and then tweak to suit their exact needs.

GitHub Actions CI Templates

After working on adding GitHub Actions CI to good-first-issue, I figured I should probably abstract the CI file into a repo, so it's a bit more accessible.

As such, last night, I built out GitHub Actions CI Templates. Initially, I shipped it with a single template that covered my needs around Node.js and npm, but as of about an hour ago I've added two additional templates: Node.js and Yarn, and Node.js and pnpm.

If you'd like to check out the templates, they're all relatively straightforward as far as YAML goes:

Node.js Cross-Platform:
- Runs builds on:
  - Ubuntu (Latest),
  - Windows (Latest),
  - macOS (Latest)
- Using all versions of Node.js that are currently supported by the Node.js project,
- Using npm install and npm test.
Node.js Cross-Platform (using Yarn)
- Runs builds on:
  - Ubuntu (Latest),
  - Windows (Latest),
  - macOS (Latest)
- Using all versions of Node.js that are currently supported by the Node.js project,
- Using yarn install and yarn test.
Node.js Cross-Platform (using pnpm):
- Runs builds on:
  - Ubuntu (Latest),
  - Windows (Latest),
  - macOS (Latest)
- Using all versions of Node.js that are currently supported by the Node.js project.
- Using pnpm install and pnpm test.

Dissecting the GitHub Actions YAML for the Templates

The templates all follow a relatively similar structure. I figured I'd walk you through each line of code of the Node.js Cross-Platform file to help ensure that they're understandable to you. Let's go line by line, with code on the top and the description on the bottom:

name: Node.js Cross-platform CI (using Yarn)

The above line is the title of the entire CI script, as it'll show up in the Actions tab of the GitHub repo.

Relevant docs:

Workflow syntax docs - name

on: [push]

The above line indicates the trigger for a run. For most CI cases, [push] will be ideal since you want it to run every time you push code to the repo or to a PR.

Relevant docs:

jobs:

Workflows are composed of one or more jobs. This line is an indicator that we've got multiple jobs to be run.

Relevant docs:

Workflow syntax docs - jobs
Usage limits, for context on limits around jobs

  build:

This one is the job_id of our specific job. Since we're running a build, I named this build but this specific name has no semantic meaning inside of GitHub Actions CI itself.

Relevant docs:

Workflow syntax docs - jobs.<job_id>

    runs-on: $

This is a required property, which tells the CI run what kind of machine it should be running on. In our case, we've added some complexity by adding a matrix of operating systems that need to be built against. That said, the context of the matrix gets hoisted, and we can use that context here.

One key thing to note from the docs:

Each job runs with a fresh instance of the virtual environment specified in by runs-on.

Meaning, every job is running a clean instance of whatever OS is selected. This is table stakes for CI, but it's always useful to keep it in mind. ❤️

Relevant docs:

Workflow syntax docs - jobs.<job_id>.runs-on
Virtual environments for GitHub Actions, which lists all the possible supported values for this property

    strategy:

Having a strategy line is the way to begin defining a matrix of environments to run your builds in.

Relevant docs:

Workflow syntax docs - jobs.<job_id>.strategy

      matrix:

The tl;dr of a matrix is that it's the set of all the pieces of context you'll want to run against. The most straightforward matrix is one row – for example, multiple Node.js versions on a single platform.

A simple matrix:

ubuntu-latest
Node.js 8
Node.js 10
Node.js 12

That said, JavaScript and Node.js applications are effectively run on all three of the major operating systems in the world as a part of developer workflows. Often, we'll want to run on the three major operating systems to ensure that there are no unexpected platform-specific bugs that are going to occur – especially in open source when there are very few direct paths to end-users. Luckily, a matrix makes this relatively straightforward.

By adding in multiple operating systems, our matrix gets more complex:

ubuntu-latest	macos-latest	windows-latest
Node.js 8	Node.js 8	Node.js 8
Node.js 10	Node.js 10	Node.js 10
Node.js 12	Node.js 12	Node.js 12

But... that's only the latest versions of each platform. What about older versions that we may often need to support? Well, it turns out that we can also use older versions of each platform in GitHub Actions CI, which could even further complicate the matrix:

ubuntu-latest	ubuntu-16.04	macos-latest	macOS-10.14	windows-latest	windows-2016
Node.js 8	Node.js 8	Node.js 8	Node.js 8	Node.js 8	Node.js 8
Node.js 10	Node.js 10	Node.js 10	Node.js 10	Node.js 10	Node.js 10
Node.js 12	Node.js 12	Node.js 12	Node.js 12	Node.js 12	Node.js 12

And this is currenlty a downtime for Node.js builds. Half of the year (every year) there are 4 supported release lines, which would look more like this:

ubuntu-latest	ubuntu-16.04	macos-latest	macOS-10.14	windows-latest	windows-2016
Node.js 8	Node.js 8	Node.js 8	Node.js 8	Node.js 8	Node.js 8
Node.js 10	Node.js 10	Node.js 10	Node.js 10	Node.js 10	Node.js 10
Node.js 12	Node.js 12	Node.js 12	Node.js 12	Node.js 12	Node.js 12
Node.js 13	Node.js 13	Node.js 13	Node.js 13	Node.js 13	Node.js 13

A matrix is super useful in helping us programmatically define such a list without actually having to define each of these contexts individually. This utility mostly comes when you start adding more platforms and versions, but thankfully the overhead of doing that is incredibly low from the configuration side of things (see the following sections for more context)

Relevant docs:

Workflow syntax docs - jobs.<job_id>.strategy.matrix

        os: [ubuntu-latest, windows-latest, macOS-latest]

The above is effectively a variable that we're assigning to the matrix, which can be dynamically called. In our case, we're just saying that the os variable on matrix (so matrix.os) is going to be each of these. The how is still a bit magic to me, but... it works, seemingly by iterating over each of them when they're called. When used in conjunction with another variable (like node-version), they're iterated over to create something like the tables above effectively.

Relevant docs:

Virtual environments for GitHub Actions, which is where you can find information about all of the operating systems currently available.

        node-version: [8.x, 10.x, 12.x]

Another variable where we're going to define the Node.js versions we'd want to be running.

Relevant docs:

actions/setup-node – the GitHub Action we pass versions to, which defines the acceptable syntax for versions
Software in virtual environments for GitHub Actions
– an exhaustive list of software available in each virtual environment (OS) by default

    steps:

Each job contains a set of steps. This specific line is where we indicate that we're going to begin defining the steps.

Relevant docs:

Workflow syntax docs - jobs.<job_id>.steps

    - uses: actions/checkout@v1

Tells our workflow that we're going to be using the GitHub Action that can be found at actions/checkout which maps to the GitHub org/repo at [gihub.com/actions/checkout]. It's also worth noting that @v1 which is a tagged and released version that can be found in the GitHub Releases for the repo.

Relevant docs:

actions/checkout, an action that checks out your repository to $GITHUB_WORKSPACE in the virtual environment.
Workflow syntax docs - jobs.<job_id>.steps.uses

    - name: Use Node.js $NaN on $

The name to display for the job in the UIs that it's rendered within, given the various variables that we've inserted using matrix.

Note: There seems to be a bug where this does not render properly – instead of rendering as a tagged template literal, the Actions UI renders as a string.

Relevant docs:

Workflow syntax docs - jobs.<job_id>.name

      uses: actions/setup-node@v1

Defines an external action – in this case, the [github.com/actions/setup-node] action at version 1.x.x (as released via the GitHub repo). In our case, this is an action that provides a super handy interface to install arbitrary versions of Node.js other than the version that comes baked into the VMs that are provided. My guess is that this will be a default action for anyone who is running JavaScript or Node.js builds simply because it handles so much for you by default.

It's worth noting that actions consumed with uses: can be sourced from within the same repository, from a public repository, and from a Docker image published to Docker Hub.

Relevant docs:

      with:

This is a map (my assumption is that this is a map in the sense of YAML's definition of a map) of the parameters defined in the action. In our case, actions/setup-node needs a version to run with.

Relevant docs:

Workflow syntax docs - jobs.<job_id>.steps.with

        node-version: $NaN

The actions/setup-node action needs a version of Node.js to run, via the node-version: property. Since we named the variable for Node.js versions in our Matrix node-versions, we're able to pass matrix.node-version to the node-version: property.

Relevant docs:

    - name: npm install and test

We're again defining the name of a job. In this case, there's no dynamic information since the commands we're going to be running are pretty static.

I use npm install and npm test, but your applications may vary in install/build/test/ci commands – my recommendation for this is to tweak both the title and the actual commands, so it's extremely clear what's being run.

Relevant docs:

Workflow syntax docs - jobs.<job_id>

      run: |
        npm install
        npm test

This is an interesting set of lines for those unfamiliar with YAML. We start with using a run property for the job, which allows us to run any command on the system. In our case, we're going to use this to run npm install and npm test... but those are two different commands, that need to be run separately. The pipe (|) is a tool defined in the YAML spec as Literal Style. In our case, it allows us to write multiple lines that execute independently without having to use multiple run: commands or multiple jobs. Basically, it's shorthand that enables use to be looser in how we're able to build out our file.

Note: It may be worth using npm ci rather than npm install to install dependencies, given that npm ci was tailor-made for CI environments. You can find more details on npm ci in the official documentation.

Relevant docs:

      env:

Allows us to set up environment variables in our virtual environments with relative ease.

Relevant docs:

Workflow syntax docs - jobs.<job_id>.steps.env

        CI: true

This one is a personal preference, and also happens to be the default for the simplest Node.js workflow suggested by GitHub. Simply sets an environment variable that can be easily picked up on by various tools. GitHub

Relevant docs:

Virtual environments for GitHub Actions – Environment Variables

What's next?

Currently, GitHub Actions CI is in a semi-public beta as a part of GitHub Actions v2 – they've invited a bunch of folks who applied to use it. That said, if you feel like this is a repeat of what happened when GitHub Actions initially shipped last year, you'll be happy to know that in the GitHub Special Event in which GitHub Actions CI and GitHub Actions v2 were shared, Nat Friedman said that GitHub Actions CI and GitHub Actions v2, along with GitHub Package Registry, is shipping to everyone on November 13th – the first day of GitHub Universe.

So, in just over a month from the date of publishing this article, you'll be able to start using GitHub Actions CI on any and every public project for free. 🎉

If you've got any questions or comments about what I've talked about in this post, or if there's more you'd like to learn about GitHub Actions CI or GitHub Actions v2, I'd be more than happy to see if I can either answer your questions in the comments directly, make good free and public repos that can help give you answers, or write more posts on the subject if you'd find that helpful!

Jest and the `--changedSince` flag in GitHub Actions CI

2020-04-09T00:00:00Z

Recently, I've been working a lot more with GitHub Actions - both writing actions and creating CI pipelines for projects. Last week I picked up a project I started a bit ago: the nodejs/examples repository.

Note: The examples repository is still in its early stages. As such, there's still a bunch of WIP work we're doing - we've intentionally not talked a bunch publicly about it yet. That said, if you're interested in helping, feel free to reach out to me on Twitter or the OpenJS Slack ❤️

The goal of this repository is to be home to a bunch of distinct and well-tested examples of real-world Node.js that go beyond "hello, world!". This means there's hopefully going to be a boatload of distinct projects in there.

This structure presents a challenge when trying to be straightforward for new contributions; specifically, it's a barrier to run a full test suite for many projects when someone submitting a PR only needs to see the results of the one they've worked on.

Jest's Solutions

Jest has a super handy --onlyChanged feature that only tells you what has changed in the current repository. This is super duper handy, but the functionality is slightly unclear in one way: does it diff with master or just with the previous commit? It does indeed seem to be the latter (though I could totally be wrong!), which is not particularly helpful in the case of PRs with multiple commits.

As such, I looked through the flags that Jest exposes and found the --changedSince flag which compares the current work with a different branch. Since - in the case of nodejs/examples - master will always be a source of truth, this is perfect for the use case of potentially having multiple commits while still wanting to run only the tests relevant to a proposed change.

`--changedSince` and GitHub Actions CI

Previously, the --onlyChanged flag worked flawlessly with GitHub Actions CI. When trying to simply change from --onlyChanged to --changedSince, the CI build immediately nuked itself with the following command:

  ● Test suite failed to run

    fatal: bad revision '^master'

This was bizarre to me since the test was working completely fine on my machine (shocker, I know). Upon investigating, this is a git error and not a Jest error - Jest is merely acting as a courier for that error.

It turns out that the actions/checkout GitHub Action does not checkout your full repository, but only the code relevant to the PR. As such, master as a branch did not exist. Further, my specific use case of wanting to have master in the run but have the PR branch checked out is not particularly well supported by actions/checkout at present since it is somewhat of an edge case (though I did open an issue to request it).

While the examples are helpful, they don't solve my somewhat complex but not over the top use case. Layer on that I'm not super excellent with git, and you have a challenging mixture.

I reached out to Shelley Vohr, who's extremely talented with git (amongst many other things) and explained what I was facing. She suggested that I'd need to go one step beyond what the actions/checkout repo recommended:

git fetch --no-tags --prune --depth=1 origin +refs/heads/*:refs/remotes/origin/* # fetches all branches

... and needed to checkout master with the following command:

git checkout -b master # -b creates and checks out a new branch

... and then switch back to the PR branch. Luckily, GitHub provides that data in the YAML config:

git checkout $ # checks out the SHA of the HEAD from the PR

This was all able to be combined as a part of a run property in the YAML for the step, which runs whatever commands are passed to it:

    - uses: actions/checkout@v2
    - run: |
        git fetch --no-tags --prune --depth=1 origin +refs/heads/*:refs/remotes/origin/* # fetches all branches
        git checkout -b master # -b creates and checks out a new branch
        git checkout $ # checks out the SHA of the HEAD from the PR

However, that's a rather bulky git fetch that can potentially artificially increase the build times as more branches are added to the repo. As such, I figured I should try to cut it down to just what I needed. After a bit of searching around, I found the git fetch <remote> <branch> structure. Since I know I'll always want to use master, this was a pretty easy change (while also ditching --prune since it seems potentially useless in this case):

    - uses: actions/checkout@v2
    - run: |
        git fetch --no-tags --depth=1 origin master
        git checkout -b master
        git checkout $

In addition to all this YAML CI config, I also included a new npm script called test:changedsince which is a handy shortcut for the Jest command I want to run:

  "scripts": {
    "test": "jest --coverage",
    "test:changedsince": "jest --changedSince=master --coverage",
    "lint": "standard"
  },

This new npm script took the place of the previous test:onlychanged npm script in my final GitHub Actions CI YAML config, seen below. Note: if you copy-paste this config into your own CI, you'll need ensure that you have jest as a devDependency so it's installed on your CI build.

name: tests(push) - install, lint, test:changedsince

on: [push]

jobs:
  build:
    runs-on: $
    strategy:
      matrix:
        os: [ubuntu-latest, windows-latest, macOS-latest]
        node-version: [10.x, 12.x]
    steps:
    - uses: actions/checkout@v2
    - run: |
        git fetch --no-tags --depth=1 origin master
        git checkout -b master
        git checkout $
    - name: Use Node.js $NaN on $
      uses: actions/setup-node@v1
      with:
        node-version: $NaN
    - name: npm install
      run: npm install
      env:
        CI: true 
    - name: npm run test:changedsince
      run: jest --changedSince=master --coverage
      env:
        CI: true

Now, this seems to be working perfectly - it'll diff changes between the current PR's HEAD and master, running only the tests that are different across all commits and not just between the most recent commit and the one prior.

Securely Automating npm publish with the New npm Automation Tokens

2020-10-02T00:00:00Z

Today, npm has shipped automation tokens 🎉

Previously, if you wanted to automatically publish an npm module from CI/CD you had a choice - have 2FA turned off and allow publishing via a token or have 2FA turned on and build a custom tool to allow you to input a 2FA code when your CI/CD is trying to publish.

This was a challenging system since it made users choose between smooth DX or security. This has been impactful historically - there have been cases (for example, the eslint-scope incident) where maintainers' accounts were hijacked and impactful modules were compromised since they didn't have 2FA for user publishes turned on.

Since 2FA on publish was introduced, folks in the ecosystem have been asking for the ability to have some way to automatically publish modules from CI while also having 2FA for user-publishes turned on.

Today, the npm team delivered one of the proposed solutions: automation tokens.

What are Automation Tokens?

Automation tokens are effectively publish tokens that a user can create to publish a module from an automated process. They skip the OTP (one-time password) check and ship it.

Say, for example, that you're the maintainer of a module called good-first-issue. Instead of having to pull good-first-issue locally and publish after opening up your 2FA app and typing in the OTP, you could instead set up your favorite CI - GitHub Actions CI, CircleCI, Travis, or whatever else - to automatically publish whenever certain conditions are met. Semantic Release is a pretty wonderful example of this kind of automation.

This has the obvious benefit of streamlining workflows and reducing maintainer burden. It also helps reduce risk - in pulling down and publishing or having to build a custom publishing system both have their own additional levels of potential risk. With automation tokens, we can now pretty easily just ship code where we build it.

How can I Use Automation Tokens?

To publish with Automation Tokens today, you'll want to do a few things to get going.

First, to actually publish to a module with an automation token, you'll need to update the module's Settings. Specifically, you'll need to change the module's Publishing Access from whatever it was previously (either Two-factor authentication is not required or Require two-factor authentication to publish) to the new option, Require two-factor authentication or automation tokens.

Once you've updated that, you'll now be able to use Automation Tokens for publishing that module.

To get an automation token, you'll want to head over to your user settings. From that, you'll open up the Access Tokens page and then create a new token. When you start the token creation flow, you'll have the option to select Automation. Once you do, click Generate Token and you'll be shown the token once - copy it, and you're all set.

Looking Forward

There are a handful of use cases where this current implementation is extremely useful - specifically, my perspective is that it's most useful where you're an individual maintainer with a limited set of projects.

That said, this is the first step in the right direction for more granular controls for all kinds of maintainers to securely manage their modules with a good DX while being as secure as possible. In speaking with the npm team, they're exploring further iteration in this space that I'm super excited for.

The New npm diff Command

2021-04-02T00:00:00Z

With the recent release of npm@7, we've gotten a few neat new features in npm.

One of the ones that I imagine can go under the radar for most folks is the npm diff command. It's a relatively... advanced command that has immense potential utility.

Preface

There's a few things we should establish as baseline assumptions before digging in.

First, I'm going to be talking about a "local version" and a "remote version".

The local version will be a module in your current working directory - so, if I wanted to diff my local liblice module with the remote published version, I'd need to have that on disk and either have it as my current working directory or pass it as a path to the command. For the sake of this article, we're going to assume anytime we're diffing a local version it's in the current working directory.

The remote version will be one that's on your default registry. For the vast majority of folks, this will be the default npm registry (a.k.a. https://registry.npmjs.com). However, if you're trying to diff a module published to an alternative registry (say, an internal corporate registry) or if you've changed your default registry to a mirror or internal cache, that would be the registry the remote version would be checking. This is some super nice flexibility that comes free with the diff command that enables some pretty nice theoretical advanced workflows.

Diffing the Local Version with the Latest Remote Version

The raw command will diff the local version of a module with the remote version. This is particularly useful for module maintainers, contributors, and those floating local patches on a module (to patch a security vulnerability, for example).

npm diff

This will output all differences between the local version and the remote version. With a single change (replacing pass with return) in README.md to use a better word, here's an example of what output would look like:

$ npm diff
diff --git a/README.md b/README.md
index v1.1.0..v1.1.0 100644
--- a/README.md
+++ b/README.md
@@ -10,7 +10,7 @@
 
 ## Usage
 
-temporalts can pass all Node.js LTS release line temporal information, or the temporal information for a _specific_ release line.
+temporalts can return all Node.js LTS release line temporal information, or the temporal information for a _specific_ release line.
 
 ### `temporalts()`

Diffing Individual Local File(s) with the Latest Remote Version

If you've made more than a single tiny change to your module, diffing a single file from the local version with the remote version.

# the general structure
npm diff [...paths]

# specific examples
npm diff README.md
npm diff /lib/handler.js
npm diff SECURITY.md /public/index.html

Instead of getting a diff for all files, you'll only get diffs for any paths you passed. If you passed a single path, you'll get a single diff; if you passed multiple, you'll get multiple.

This functionality can be particularly useful in a handful of cases: generating changelogs, checking how something works in the currently published version, or even as a prepublish check to make sure you're only shipping changes you intended to ship.

Diffing Local Version with a Specific Remote Version

Similar to Diffing the Local Version with the Latest Remote Version, you can diff your local version of a module with the remote version, but with any specific version.

npm diff --diff=<version>

As an example, here's an excerpt from running npm diff --diff=1.0.1 on temporalts@1.1.0. There's a single version between these two - v1.0.1 was also published, and we're able to compare what we currently have with a previous version that's not @latest. There's a few uses for this, like checking what's changed in a module while upgrading, changelog authoring, or pre-publish change validation (especially if you're using files in package.json to limit which files you're publishing).

We can also diff forward - for example, if I were to publish temporalts@2.0.0, I'd be able to diff between v1.1.0 and v2.0.0. This is useful, particularly if you're looking forward for upgrades or at pre-release versions.

$ npm diff --diff==1.0.0                                                                                
diff --git a/examples/12.js b/examples/12.js
deleted file mode 100644
index v1.0.0..v1.1.0 
--- a/examples/12.js
+++ b/examples/12.js
@@ -1,12 +0,0 @@
-const temporalts = require('../')
-
-async function prettyPrint () {
-  const version = 'v12'
-  const data = await temporalts(version)
-
-  console.log()
-  console.log(`We are ${data.currentPercentOfLTSLifeSpanWithoutDecimal}% through the lifespan of the Node.js ${version} LTS release line.\n${data.currentPercentOfLTSLifeSpanAsProgressBar} `)
-  console.log()
-}
-
-prettyPrint()
\ No newline at end of file
diff --git a/helpers/fetchSchedule.js b/helpers/fetchSchedule.js
index v1.0.0..v1.1.0 100644
--- a/helpers/fetchSchedule.js
+++ b/helpers/fetchSchedule.js
@@ -12,4 +12,4 @@
   }
 }
 
-module.exports = fetchSchedule
+module.exports.fetchSchedule = fetchSchedule
diff --git a/index.js b/index.js
index v1.0.0..v1.1.0 100644
--- a/index.js
+++ b/index.js
@@ -1,3 +1,3 @@
-const lts = require('exports/lts.js')
+const lts = require('./exports/lts.js')

[... more file diffs, dropped for length]

Diffing Individual Local File(s) with a Specific Remote Version

As an extension of Diffing Local Version with a Specific Remote Version, you can also pass in a single file to diff.

# the general structure
npm diff --diff=<version> [...paths]

# specific examples
npm diff --diff=<version> README.md
npm diff --diff=<version> /lib/handler.js
npm diff --diff=<version> SECURITY.md /public/index.html

As an example, if we diff index.js:

$ npm diff --diff==1.0.0 index.js
diff --git a/index.js b/index.js
index v1.0.0..v1.1.0 100644
--- a/index.js
+++ b/index.js
@@ -1,3 +1,3 @@
-const lts = require('exports/lts.js')
+const lts = require('./exports/lts.js')
 
 module.exports = lts

Diffing Two Remote Versions

There is also a very valid reason you may want to diff two versions of the same module you've got that aren't locally stored. npm diff allows you to do this with package identifiers (a.k.a. pkg-identifier) which is something along the lines of package@semver-range - so, for example, node@12.10.0, fastify@latest, babel@7.0.0-rc.1, and npm@7.

# the general structure
npm diff --diff=<pkg-identifier> --diff=<pkg-identifier>

# specific example
npm diff --diff=gatsby@2.32.3 --diff=gatsby@latest

If we try to run the latter command - comparing a slightly older version of Gatsby to the latest version - we'll get about 19mb of diff output at time of publishing (the latest version of Gatsby is presently gatsby@3.2.0 if you'd like to try to reproduce this output exactly). Unfortunately, that's far too much to include in a blog post, but you should try running it yourself.

As with any actively developed module - or any sufficiently modified module from one package identifier to another - this diff will only get bigger as the maintainers published newer and newer versions, making more changes.

Diffing Individual Files from Two Remote Versions

As with previous npm diff commands, you can pass in individual files or paths to filter your diff's output and you'll get just a diff for that file or path.

# the general structure
npm diff --diff=<pkg-identifier> --diff=<pkg-identifier>

# specific examples
npm diff --diff=fastify@3.13.0 --diff=fastify@latest package.json
npm diff --diff=fastify@3.13.0 --diff=fastify@latest /lib/errors.js
npm diff --diff=fastify@3.13.0 --diff=fastify@latest README.md /lib/context.js

Here's what the output for the first command there looks like:

$ npm diff --diff=fastify@3.13.0 --diff=fastify@latest package.json
diff --git a/package.json b/package.json
index v3.13.0..v3.14.1 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "fastify",
-  "version": "3.13.0",
+  "version": "3.14.1",
   "description": "Fast and low overhead web framework, for Node.js",
   "main": "fastify.js",
   "type": "commonjs",
@@ -177,7 +177,7 @@
     "abstract-logging": "^2.0.0",
     "ajv": "^6.12.2",
     "avvio": "^7.1.2",
-    "fast-json-stringify": "^2.2.1",
+    "fast-json-stringify": "^2.5.2",
     "fastify-error": "^0.3.0",
     "fastify-warning": "^0.2.0",
     "find-my-way": "^4.0.0",

Useful Flags

The npm diff command also provides some helpful flags to limit the diff output to only relevant changes, depending on your goal.

--diff-ignore-all-space: Ignores all changes that are exclusively space. Extremely useful for limiting changes to only what matters, especially after linter runs.
--diff-name-only: Limits outputs to only filenames of files with changes for the command. Extremely useful for getting an overview of what's changed and figuring out which files to drill down into.

Markdown Link Checking in GitHub with Actions

2021-05-05T00:00:00Z

Having been a part of the Node.js project since the io.js 1.0 announcement, one of the things I've grown extremely familiar with is how untouched Markdown documents that are supposed to provide a foundation can rot over time.

More specifically, a project on GitHub can slightly tweak how it operates every now and then. Those changes might not be enough to justify a documentation change since they're not meaningfully different enough.

If enough of these pile up you can end up with some blind spots on how your foundational documents haven't kept up with the times. This can often be remedied by manual inspection, but even then there's things that you might miss.

One of those things I've often missed when doing that manual inspection is broken links. Specifically, if a file is moved at some point but all references to it aren't updated you end up in a situation where those references point to a 404.

I've also had a handful of experiences with external links to smaller sites die because they decided to completely redesign the site and its structure... and if we're honest, I've only noticed those when I've really tried to find things that are broken. I'm sure others who are less familiar with that documentation have hit them more often.

Various forms of link rot like this are something that I've struggled to fight with different tooling for years. Now, thankfully, I've found the exact setup I've always wanted.

Linkinator and GitHub Actions

A friend, Justin Beckwith, published a tool that serves both as a CLI and a module called Linkinator some time ago that focused on finding broken links within HTML sites. He extended it to work with Markdown relatively recently as well.

He also published a Linkinator GitHub Action that consumes Linkinator as a module and uses that to cleanly integrate with GitHub repositories.

Even more recently, he added the retry functionality from the module to the Action.

With retry and the foundation of the rest of the work Justin's put into Linkinator, my problems with Markdown link rot in GitHub have now been entirely solved.

Let's get into how.

Markdown Link Rot Begone: Using the Action

The first space I've set up Linkinator is in the Node.js Community Committee repo via #658. Specifically, this PR adds the Linkinator GitHub Action and fixes all (but one, which has been fixed in a different unmerged PR) broken links in the repository. As it turns out, there were quite a few... including some in very notable places, like the README.

The setup is pretty standard for a single purpose GitHub Action. There's some pretty decent documentation of the expected YAML on GitHub's Docs site. I'll walk through each line with you:

Setting up Triggers

To start, we set up the triggers for the Action. The first line will always be on: but from there you can do a lot.

In this specific case, I've set it up to run on push to the default branch (thanks to the handy $default-branch macro, it doesn't matter what the name is!), on PRs (this could be more verbose to run less often), and on workflow_dispatch which allows us to run it manually via the GitHub Actions UI if we want to.

on:
  push:
    branches:
      - $default-branch
  pull_request:
  workflow_dispatch:

The Name

Next, we have the name which is what will appear in the GitHub UI. In this case, I just went with Linkinator CI but you can change this to whatever you'd like.

name: Linkinator CI

The Job

The beginning of the jobs section is, again, relatively standard. We include the jobs property under which we start defining the work that'll be done.

In this case, we name the (only!) step linkinator since I like to try to keep to as small yet as descriptive of a job name as is possible.

Then, we tell Actions to run this on ubuntu-latest and add the property steps to start defining what we're going to do in the job.

From there, we then we declare that we want to use the actions/checkout action which by default checks out the repo this is running in and sets things up nicely for us.

jobs:
  linkinator:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2

Next, we're going to actually include the linkinator step. We call the Linkinator action from Justin's repo directly. We also pass a few of Linkinator's inputs via the with property:

paths: we're specifically checking for all markdown files in the project, recursively with globbing.
markdown: asserting to Linkinator that we're specifically looking for markdown files (as opposed to HTML files).
retry: for GitHub repos that have links to GitHub this is super important - if we get timed out because of a rate limit, the Action will respectfully retry until they get a non-rate-limited response.

      - uses: JustinBeckwith/linkinator-action@v1
        with:
          paths: "**/*.md"
          markdown: true
          retry: true

The Whole Configuration

Putting all of that together, we get the following:

on:
  push:
    branches:
      - $default-branch
  pull_request:
  workflow_dispatch:
name: Linkinator CI
jobs:
  linkinator:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: JustinBeckwith/linkinator-action@v1
        with:
          paths: "**/*.md"
          markdown: true
          retry: true

By popping this as a new file into ./github/workflows/ (say, ./github/workflows/linkinator.yml) and pushing it to your repo, you'll start getting link checks on every push and PR plus whenever you want to manually run it.

Genuinely happy with this solution and I hope it helps someone else as much as it's (going to be) helping me ❤️

Explicit ESM in Node.js with .mjs

2021-06-16T00:00:00Z

A while ago, Node.js introduced support for ECMAScript Modules (ESM). ESM is the standardized modules implementation that's been built-in to JavaScript. This differs rather significantly from CommonJS (CJS), which is the module system that Node.js has shipped with for over a decade that make them relatively incompatible.

There are a number of different components of Node.js that have been intentionally structured to allow you to use standard (as in, how the ECMAScript Specification defines it) ESM by default and extend/augment that experience if you'd like to.

Today, I want to get into one of the baisc elements of ESM in Node.js: the .mjs and .cjs extensions.

Why `.mjs` (and `.cjs`)?

The Quick Answer

The straightforward answer to this is that having different file extensions allows you to be explicit in how you want to run your code - .mjs will always be run as ESM, .cjs will always be run as CommonJS.

The Answer With Context

Because of the differences in how ESM and CommonJS work, Node.js runs them differently by default. This results in the runtime needing an indicator about which way you want to run your code - as ESM or as CommonJS.

There's three different ways that this indicator could be expressed: explicitly, implicitly, and by default.

To not break over a decade of projects and over a million modules that are expecting to Just Work, the default the project landed on was CommonJS - sensible, especially when you consider millions of lines of code and multitudes of applications already running in this way.

The way to explicitly assert that the code you're running is ESM and should be run as such is to just use the .mjs file extension (which, if you're concerned, is also supported in web browsers as long as the Content-Type: text/javascript header is sent and is actually recommended by V8). The official overview of this is documented in the determining module system section of the Node.js Packages documentation.

When you use .mjs, Node.js knows that you've written ESM and will parse your JavaScript as such. The same is true for .cjs - Node.js knows that .cjs should run as CommonJS, and will parse your JavaScript as CommonJS.

Implicit ESM in Node.js with "type": "module"

2021-06-16T00:00:00Z

Continuing the Node.js ESM content, I'd like to talk about the comparitively straightforward alternative to using .mjs to get your Node.js applications to run as ECMAScript Modules (ESM) rather than CommonJS: including "type": "module" in your package.json.

Usage of `"type": "module"`

Let's assume we've started with the following package.json for a zero (production) dependency application:

{
  "name": "apollo-lunar-module",
  "version": "0.0.1",
  "description": "A simple, fast, nice lunar lander module",
  "main": "index.js",
  "scripts": {
    "lint": "standard"
  },
  "author": "Tierney Cyren <hello@bnb.im> (https://bnb.im/)",
  "license": "MIT",
  "devDependencies": {
    "standard": "^16.0.3"
  }
}

To have implicit ESM - that is, have our .js files parsed as ESM - we' need to make the following change:

{
  "name": "apollo-lunar-module",
  "version": "0.0.1",
  "description": "A simple, fast, nice lunar lander module",
  "main": "index.js",
+ "type": "module",
  "scripts": {
    "lint": "standard"
  },
  "author": "Tierney Cyren <hello@bnb.im> (https://bnb.im/)",
  "license": "MIT",
  "devDependencies": {
    "standard": "^16.0.3"
  }
}

This specifically tells Node.js to parse your .js files under this package.json as ESM. Otherwise, by default (or when you use "type": "commonjs"), Node.js will parse your .js files as CommonJS. There's a few things to note:

Node.js specifically looks for the closest package.json to determine whether or not to parse .js as ESM or CommonJS.

"Closest" is important here. If there's a package.json that's closer to .js files than your project's package.json, and it does not have "type": "module" (or a dual export, which is out of the scope of this post), CommonJS will be used for those .js files. The most common/obvious example of this is the code within your /node_modules/ that may not be ESM, and shouldn't be parsed as such.

Further, it's worth noting that explicitly using .cjs overrides "type": "module". This is extremely useful if you're converting a codebase from CommonJS to ESM.

Why `"type": "module"`?

The Quick Answer

For you, the user, the straightforward answer to this is that using "type": "module" is a better developer experience than having to explicitly use .mjs in every single JavaScript file in your project if you're going to have a non-trivial number of files.

The Answer With More Context

Using "type": "module" is often going to be a better developer experience for maintainers for a number of reasons:

It minimizes manual changes and potential mistakes, allowing a single line of text to control parsing.
It makes migrating from CommonJS to ESM easier.
- It depends on how you'd like to do it, but one strategy is to chunk out work of converting your applications to ESM one bit at a time by setting "type": "module" and converting all the CommonJS code to use the .cjs file extension.
It allows ecosystem tooling to quickly determine if your projects are using ESM or not.
- Note that JSON modules (and therefore importing package.json) are only supported behind the --experimental-json-modules flag. It does seem that necessary proposals to streamline this seem to be making pretty decent progress through the relevant standards processes.

Conditional Exports: Supporting both import and require()

2021-06-17T00:00:00Z

Now that we've both gone over how to make Node.js implicitly and explicitly parse your code as ESM, we can get into some of the more meaty and interesting bits of ESM in Node.js.

To me, one of the most interesting features is Conditional Exports. With conditional exports, you can have a single module export both ESM (allowing it to be imported, with all the features of import that you'd expect) and CommonJS (allowing it to be require()ed.)

From a broader perspective, this is an amazing tool for transition. Whether you're a maintainer of an open-source module or charged with supporting1 internal end-users on an SDK with a long support cycle, this helps ease the shock of going from CommonJS to ESM, or simply helps you support both use cases for as long as your consumers require.

Setting up Conditional Exports

Let's take the package.json we used in the Implicit ESM article, and exapand on that:

{
  "name": "apollo-lunar-module",
  "version": "0.0.1",
  "description": "A simple, fast, nice lunar lander module",
  "main": "index.js",
  "type": "module",
+ "exports": {
+   "import": "./main.js",
+   "require": "./main.cjs"
+ },
  "scripts": {
    "lint": "standard"
  },
  "author": "Tierney Cyren <hello@bnb.im> (https://bnb.im/)",
  "license": "MIT",
  "devDependencies": {
    "standard": "^16.0.3"
  }
}

You can see we've added the following code:

{
  // ...
  "exports": {
    "import": "./main.js", // doesn't have to be `main`
    "require": "./main.cjs" // doesn't have to be `main`
  }
  // ...
}

You should note that we've got "type": "module" in our package.json, meaning that .js will be interpreted as ESM and to use CommonJS in this module, we'll need to use the .cjs extension.

The utility of having both ESM and CommonJS in the same project becomes apparent here. We're now able to enable both ESM and CommonJS users to consume our package without having to install a different module.

Now, it is worth noting that you can't just copy/paste your code from main.js into main.cjs - you'll actually need to make it work as CommonJS code, which probably also means figuring out how to support both use cases in both export styles. If you'd like a solid example of how to do this for realsies, Myles Borins built node-osc and has a rollup configuration that does ESM to CommonJS conversion for this exact use case. Additionally, there are a number of codemods that exist (and I've apparently signed myself up to work on yet another codemod for this) that can help with this.

Consuming a Module that has Conditional Exports

Thankfully, conditional exports were built in such a way that they're largely invisible to end-users of your module with one caveat.

The caveat: if your end-users are somehow consuming the same module both as ESM and as CommonJS, the instance is of the ESM and CommonJS versions are not the same. Both ESM and CommonJS have been built so the instance is shared, but in the case of using both the instance will not be the same. For most folks this likely won't be problematic for a number of reasons, but it is still a possibility. The most likely way this'll surface is through you using a conditionally exported module one way and a dependency in node_modules using it a different way.

Outside of that, you'd use modules with conditional exports however you would normally.

Let's take the example of apollo-lunar-module that we've been using:

npm install apollo-lunar-module

To use it in ESM:

import * as lander from "apollo-lunar-module"

And if we wanted to import (hypothetical) named exports from main.js with ESM:

import { abortGuidancePanel } from "apollo-lunar-module"
import { plssCondensateContainerAssy } from "apollo-lunar-module"
import { crewLog } from "apollo-lunar-module"

To use it in CommonJS:

const lander = require("apollo-lunar-module")

And, again, if we wanted to consume (hypothetical) named exports, exposed by main.cjs:

const { abortGuidancePanel } = require("apollo-lunar-module")
const { plssCondensateContainerAssy } = require("apollo-lunar-module")
const { crewLog } = require("apollo-lunar-module")

Either way, as an end-user, conditional exports make support for ESM or for CommonJS effectively invisible to those who are using your modules the other way. This ends up creating a pretty wonderful solution for end-users, enabling maintainers to ensure they're supporting both ESM and CommonJS consumers if they want to.

is-mdm: MDM detection in Node.js

2025-10-30T00:00:00Z

Last night, I was looking at Lobste.rs and saw that the top post was a blog post from LGUG2Z about MDM detection, using Rust. The post heavily implied that this could be used for ensuring butts-in-seats (hands-on-keyboards?) licenses are being followed - you can use your imagination on how detecting MDM would connect to that.

The scripts looked pretty simple, so I thought it'd be fun to implement in JavaScript. I know no Rust, and am definitely a bit rusty since I was laid off a few months ago. In the past week I've been asked 6 times what I've worked on while not employed, which I've found... weird but understandable I guess. This seemed like a way to at least derust a little bit.

It seemed like The Node Way to make it a package, so I've published a zero-tests (PRs welcome) package to npm called is-mdm that checks both macOS and Windows for MDM enrollment.

Using `is-mdm`

Quick usage, it's pretty simple. Install with npm install is-mdm and then:

const isMdm = require('is-mdm')

isMdm() // true if MDM is detected, otherwise it'll return false

Under the Hood of `is-mdm`

Basically, I converted the Rust version from the blog post and then added conditional checking of platforms through Node.js's provided process.platform.

The macOS check is pretty straightforward - it uses the exact command from the blog post:

function isMdmMacOS() {
	let enrolled = true; // let's assume we're managed and correct ourselves if we prove we're not

	const command = spawnSync("/usr/bin/profiles", [
		"status",
		"-type",
		"enrollment",
	]).stdout.toString();

	if (
		command.includes("Enrolled via DEP: No") &&
		command.includes("MDM enrollment: No")
	) {
		enrolled = false;
	}

	return enrolled;
}

The Windows version does the same thing, using the exact same command linked in the blog post:

function isMdmWindows() {
	let enrolled = true; // let's assume we're managed and correct ourselves if we prove we're not

	const command = spawnSync("dsregcmd", ["/status"]).stdout.toString();

	if (!command.includes("MdmUrl")) {
		enrolled = false;
	}

	return enrolled;
}

and I've wrapped them both in a function that checks the platform and exported that function as the module:

function isMdm() {
	if (process.platform === "darwin") {
		return isMdmMacOS();
	}

	if (process.platform === "win32") {
		return isMdmWindows();
	}
}

Both functions do default to expecting that the device is MDM'ed unless it's proven that they're not - I think this is reasonable but if people want to tell me I'm wrong and I should do it differently, I'm open to that.

Honestly, I expect nobody to ever use this but I like the name in the style of is-even and is-odd and it was a fun lil process to publish a module that does something outside of what I normally look at.

As a fun aside, I have Copilot installed in VS Code because it's been a minute since I've used this computer, and while writing this it keeps suggesting that node-mdm-detector exists and is a package that I've written is-mdm as an alternative for. I searched it on Google, and Google's AI header section also thinks node-mdm-detector exists. It doesn't. I'm perpetually amazed at how bad literally every AI tool is.

Tierney Cyren

My 🔥 First Experience Attending TC39

What the heck is TC39 #

Terminology #

Expectation vs. Reality #

What were my expectations going in? #

How did my expectations stack up to reality? #

Timeline #

Day 1: #

Day 2: #

Day 3: #

Takeaways #

Using npx and npm scripts to Reduce the Burden of Developer Tools

Enter npx #

Using npm scripts #

Fin #

The Awesome Features that Just Landed with Node.js v12

The 🔥 Changes #

New ES Modules, who dis #

Previous implementation #

New implementation features #

Current WIP Features #

Quick ESM Examples #

V8 7.4 #

TLS 1.3 #

Worker Threads #

Built-in Heap Snapshotting #

Other Notable Changes and Improvements #

Fin #

An Unintentionally Comprehensive Introduction to GitHub Actions CI

GitHub Actions CI Templates #

Dissecting the GitHub Actions YAML for the Templates #

What's next? #

Jest and the `--changedSince` flag in GitHub Actions CI

Jest's Solutions #

--changedSince and GitHub Actions CI #

Securely Automating npm publish with the New npm Automation Tokens

What are Automation Tokens? #

How can I Use Automation Tokens? #

Looking Forward #

The New npm diff Command

Preface #

Diffing the Local Version with the Latest Remote Version #

Diffing Individual Local File(s) with the Latest Remote Version #

Diffing Local Version with a Specific Remote Version #

Diffing Individual Local File(s) with a Specific Remote Version #

Diffing Two Remote Versions #

Diffing Individual Files from Two Remote Versions #

Useful Flags #

Markdown Link Checking in GitHub with Actions

Linkinator and GitHub Actions #

Markdown Link Rot Begone: Using the Action #

Setting up Triggers #

The Name #

The Job #

The Whole Configuration #

Explicit ESM in Node.js with .mjs

Why .mjs (and .cjs)? #

The Quick Answer #

The Answer With Context #

Implicit ESM in Node.js with "type": "module"

Usage of "type": "module" #

Why "type": "module"? #

The Quick Answer #

The Answer With More Context #

Conditional Exports: Supporting both import and require()

Setting up Conditional Exports #

Consuming a Module that has Conditional Exports #

is-mdm: MDM detection in Node.js

Using is-mdm #

Under the Hood of is-mdm #

What the heck is TC39

Terminology

Expectation vs. Reality

What were my expectations going in?

How did my expectations stack up to reality?

Timeline

Day 1:

Day 2:

Day 3:

Takeaways

Enter npx

Using npm scripts

Fin

The 🔥 Changes

New ES Modules, who dis

Previous implementation

New implementation features

Current WIP Features

Quick ESM Examples

V8 7.4

TLS 1.3

Worker Threads

Built-in Heap Snapshotting

Other Notable Changes and Improvements

Fin

GitHub Actions CI Templates

Dissecting the GitHub Actions YAML for the Templates

What's next?

Jest's Solutions

`--changedSince` and GitHub Actions CI

What are Automation Tokens?

How can I Use Automation Tokens?

Looking Forward

Preface

Diffing the Local Version with the Latest Remote Version

Diffing Individual Local File(s) with the Latest Remote Version

Diffing Local Version with a Specific Remote Version

Diffing Individual Local File(s) with a Specific Remote Version

Diffing Two Remote Versions

Diffing Individual Files from Two Remote Versions

Useful Flags

Linkinator and GitHub Actions

Markdown Link Rot Begone: Using the Action

Setting up Triggers

The Name

The Job

The Whole Configuration

Why `.mjs` (and `.cjs`)?

The Quick Answer

The Answer With Context

Usage of `"type": "module"`

Why `"type": "module"`?

The Quick Answer

The Answer With More Context

Setting up Conditional Exports

Consuming a Module that has Conditional Exports

Using `is-mdm`

Under the Hood of `is-mdm`