DEV Community: Tierney Cyren

Conditional Exports: Supporting both import and require()

Tierney Cyren — Thu, 17 Jun 2021 02:22:50 +0000

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 supporting 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.

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

Tierney Cyren — Wed, 16 Jun 2021 14:55:55 +0000

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.

Explicit ESM in Node.js with .mjs

Tierney Cyren — Mon, 14 Jun 2021 21:40:43 +0000

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.

The New npm diff Command

Tierney Cyren — Fri, 02 Apr 2021 16:53:41 +0000

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

Tierney Cyren — Fri, 05 Mar 2021 21:59:59 +0000

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 ❤️

Securely Automating npm publish with the New npm Automation Tokens

Tierney Cyren — Fri, 02 Oct 2020 18:06:22 +0000

Today, npm has now 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.

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

Tierney Cyren — Thu, 09 Apr 2020 22:33:13 +0000

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 ${{ github.event.pull_request.head.sha }} # 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 ${{ github.event.pull_request.head.sha }} # 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 ${{ github.event.pull_request.head.sha }}

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: ${{ matrix.os }}
    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 ${{ github.event.pull_request.head.sha }}
    - name: Use Node.js ${{ matrix.node-version }} on ${{ matrix.os }}
      uses: actions/setup-node@v1
      with:
        node-version: ${{ matrix.node-version }}
    - 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.

An Unintentionally Comprehensive Introduction to GitHub Actions CI

Tierney Cyren — Mon, 30 Sep 2019 16:59:04 +0000

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: ${{ matrix.os }}

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 ${{ matrix.node-version }} on ${{ matrix.os }}

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: ${{ matrix.node-version }}

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!

Discuss: GitHub Special Event

Tierney Cyren — Fri, 10 May 2019 14:00:56 +0000

This week GitHub shared that they were planning a GitHub Special Event for... today 😱

The Details

The event is currently planned for 1:30pm PT.
The GitHub team has a special livestream page set up
- This page is using YouTube, which allows you to set reminders for when a scheduled stream goes live if you're signed into YouTube.

What We Know

GitHub is launching a new product (ref)
It's not a Responsive version of GitHub.com or Gist Notifications, since those have both already launched this week (ref, ref)
???

Who to Follow (Twitter)

GitHub: I don't doubt that GitHub's socials will be actively tweeting whatever is happening.
Nat Friedman: Nat is the CEO of GitHub and has been very actively hyping this up. Definitely a good person to follow if you want to catch the messages from the source via a human.
Bryan Clark: Bryan is the individual who invited me to the event and is Director of Product for OSS Maintainers at GitHub. (That's a super awesome title, right?)
Tierney Cyren: That's me! I'll be at the event and would be kidding myself if I were to say I'd be doing anything other than live-tweeting the event while I'm there. Super hyped 😱

What Now?

I figured it would be awesome to kick off a discuss post to keep up with what everyone is thinking about and feeling about the event leading up to it and talk about whatever happens while it's happening.

A few questions I have for y'all to kick things off:

What do you think is going to be shared?
What would you love to see?
Do you think it's something that'll be available today or a longer-term thing?

What Makes Good Developer Tools... Good?

Tierney Cyren — Thu, 02 May 2019 12:20:02 +0000

I've known for a long time that developer tools are the thing I care about in tech – making other developers lives even easier is something I aspire to. Often, though, I wonder if my ideas of what makes developer tools good is also what others think makes developer tools good.

So, I'd like to ask:

What makes your favorite developer tool good?

Would love to hear from you in the comments so I can better understand from your perspective ❤️

The Awesome Features that Just Landed with Node.js v12

Tierney Cyren — Thu, 25 Apr 2019 18:54:59 +0000

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:

// Detect dark theme var iframe = document.getElementById('tweet-1120700101637353473-131'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1120700101637353473&theme=dark" }

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!

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

Tierney Cyren — Mon, 22 Apr 2019 17:01:07 +0000

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!

DEV Community: Tierney Cyren

Conditional Exports: Supporting both import and require()

Setting up Conditional Exports

Consuming a Module that has Conditional Exports

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

Usage of "type": "module"

Why "type": "module"?

The Quick Answer

The Answer With More Context

Explicit ESM in Node.js with .mjs

Why .mjs (and .cjs)?

The Quick Answer

The Answer With Context

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

Securely Automating npm publish with the New npm Automation Tokens

What are Automation Tokens?

How can I Use Automation Tokens?

Looking Forward

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

Jest's Solutions

--changedSince and GitHub Actions CI

An Unintentionally Comprehensive Introduction to GitHub Actions CI

GitHub Actions CI Templates

Dissecting the GitHub Actions YAML for the Templates

What's next?

Discuss: GitHub Special Event

The Details

What We Know

Who to Follow (Twitter)

What Now?

What Makes Good Developer Tools... Good?

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

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

Enter npx

Using npm scripts

Fin

Usage of `"type": "module"`

Why `"type": "module"`?

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

`--changedSince` and GitHub Actions CI