Forem: Mike E

What are dist-tags in npm?

Mike E — Thu, 21 Dec 2023 16:18:30 +0000

Recently I had a need to use dist-tags tags when publishing a package with npm. It unfortunately took longer than I would have liked to fully understand it conceptually, so I thought I'd put this document together to provide all the information someone would need to get started.

What are dist-tags?

dist-tags or distribution tags are an optional way to provide an alias for a package that you are publishing. They are not to be confused with Git tags. Here is npm's documentation on dist-tags.

How do you add a dist-tag when publishing a package?

When you publish a package, you can add a dist-tag by including the --tag option followed by the dist-tag you'd like to use. If you do not include the --tag option, (meaning you just run npm publish), the dist-tag latest will be used by default.

Here is an example where we publish a package with the stable dist-tag:



npm publish --tag stable

An important takeaway is that using the stable dist-tag (or any dist-tag other than latest) not only associates that alias with the version of that package, but it results in the package NOT being marked as latest:

As it turns out, this describes my original need for dist-tags. I had to publish a version of a package for a previous major version and needed to ensure the version of the package I was publishing was not going to be considered the latest.

How do dist-tags come into play with installing a package?

We are all familiar with how to install a specific version of a package. We'd do something like this:



npm install some-package@3.2.0

Similarly, we can also target a specific Git tag when installing a package. Like this:



npm install some-package@v3.2.0

Just as we can target a specific package version or Git tag, we can also target a specific dist-tag like this:



npm install some-package@beta

This is why when you want to upgrade a package to the latest version, you run the following command:



npm install some-package@latest

You are simply telling npm: "Install the package with the latest dist-tag."

What values can I use for a dist-tag?

There are certain dist-tags that it seems the industry has standardized on like beta, canary, and next, but you can use almost any value that makes sense for your project. Other than latest, no tag has any special significance to npm itself.

The only restrictions are that dist-tags share a namespace with versions and Git tags so your dist-tag cannot match one of those. You will actually get an error if you try to publish a package that appears to be a semantic version (eg. 3.2.0) or tag (v3.2.0).

Tricking Dependabot into allowing multiple update configs for one package ecosystem

Mike E — Mon, 02 Oct 2023 14:30:58 +0000

Dependabot can be limiting in the way you can configure it in the dependabot.yml file. There was a certain manner in which I wanted to configure Dependabot to automatically create updates which would seem unachievable based on documentation, but I was able to find a way to "trick" Dependabot into allowing it.

The Goal

The way I wanted to configure Dependabot was to have PRs created for the following scenarios:

All security updates.
Major and minor version updates for any packages in my private registry.

Here is a configuration that allows for PRs for security updates to (the open-pull-requests-limit: 0 line does that), but does nothing for goal #2 above:

version: 2
updates:
  - package-ecosystem: 'npm'
    directory: '.'
    schedule:
      interval: 'daily'
    open-pull-requests-limit: 0

Here is a configuration that allows for major and minor version updates for my private registry, but does nothing for goal #1 above:

version: 2
registries:
  mycompany:
    type: npm-registry
    url: 'https://npm.pkg.github.com'
updates:
  - package-ecosystem: 'npm'
    directory: '/'
    registries:
      - 'mycompany'
    schedule:
      interval: 'daily'
    allow:
      - dependency-name: '@mycompany/*'
    ignore:
      - dependency-name: '@mycompany/*'
        update-types: ['version-update:semver-patch']

The Problem

The configuration above will allow PRs for version updates for @mycompany dependencies to be created for major and minor version bumps. Great! The problem, however, is that this filters out all security updates. I could get the security updates by removing the allow and ignore options, but then I'd get all version updates which I don't want.

This problem occurs because Dependabot only allows one update configuration per package-ecosystem (documentation). Actually, to be accurate, it only allows for one update configuration per package-ecosystem-directory combination. This allows for different configurations for different packages in a mono repo.

The Solution

When trying to find a solution for this limitation so I could get the Dependabot behavior I was seeking, I focused on how I could have multiple update configurations for the npm package-ecosystem while continuing to target the root directory in both configs (since I don't have a mono repo). Ultimately, I was able to leverage different strings that end up resolving to the root directory when the workflow executes.

The default root path that you see in Dependabot documentation is / which, in Linux, represents the "root" of the filesystem. Linux also supports . which represents the current directory in the file system. I tested and confirmed both end up targeting the root of my codebase. This allows for two update configurations for the npm package-ecosystem being allowed, successfully targeting the root directory.

Here was my final dependabot.yml config:

version: 2
registries:
  mycompany:
    type: npm-registry
    url: 'https://npm.pkg.github.com'
updates:
  # npm packages for @mycompany major and minor updates only
  - package-ecosystem: 'npm'
    directory: '/'
    registries:
      - 'mycompany'
    schedule:
      interval: 'daily'
    allow:
      - dependency-name: '@mycompany/*'
    ignore:
      - dependency-name: '@mycompany/*'
        update-types: ['version-update:semver-patch']
  # npm packages for security updates only
  - package-ecosystem: 'npm'
    directory: '.'
    schedule:
      interval: 'daily'
    open-pull-requests-limit: 0

How to inspect transient DOM elements

Mike E — Mon, 17 Jul 2023 15:04:21 +0000

There are certain situations in web applications where a UI element will appear/disappear from the screen and it is challenging to inspect it. This typically occurs when an element's presence in the DOM is based on focus or hover state which changes when you attempt to inspect it. In this article, I'll cover a couple ways to overcome this.

The OK way

An easy way to inspect an element which may be satisfactory in many situations is to use setTimeout() in combination with debugger; to effectively freeze the DOM, allowing you to then inspect anything at your leisure. The debugger; statement (documented here) invokes the Javascript debugger and completely pauses execution. When used in the callback of a setTimeout() timer, you can "schedule" the DOM to freeze after you've gotten the UI ready for inspection.

Here is a CodeSandbox example where you can play around with this technique. In this example, if you click on the <input>, an options menu will appear. If our goal was to inspect one of the options in the menu, we'd have to contend with the fact that the menu disappears when we click anywhere outside of the menu.

To test this solution, open up the Developer Tools and add the following code to the Console tab:

setTimeout(() => { debugger; }, 3000)

Once we submit this command in the console, you'll have three seconds to open the menu, before the execution is paused and the DOM is frozen.

One drawback of this approach is the DOM is completely frozen. This means that if we wanted to do something like check the hover behavior on one of the options menu, we couldn't.

The better way

A better way is to leverage Chrome's "Emulate a focused page" option in Developer Tools. You can quickly enable this option by using Chrome's command palette by pressing Control+Shift+P on Windows/Linux or Command+Shift+P on Mac. Once open, start typing "Emulate a focused page" or "emfo" for short.

Once enabled, you can hit the "Select an element in the page to inspect it" button in Developer Tools.

Lastly, click on the options menu or one of the options. You'll notice that the menu does not disappear and you can even see hover styles.

How to inspect files packaged by webpack before they are emitted

Mike E — Thu, 30 Jun 2022 20:30:34 +0000

I recently had a need to inspect files in my front-end project that are packaged by webpack before they were emitted. In my pursuit to accomplish this an elegant and robust manner, I came across webpack hooks which are an exceedingly powerful way to tap into the inner workings of webpack.

What is webpack?

webpack is a module bundler for JavaScript. Front-end applications contain many types of assets such as JavaScript, (HOPEFULLY) Typescript, JSON, HTML, CSS, and images. webpack (after you've configure it to process files in a certain manner) will generate static assets, representing your applications modules so that they can be interpreted by a browser.

What are webpack hooks?

A "hook" in software development is a place in code that allows you to tap into a module to either provide different behavior or to react when something happens. webpack provides the following types of hooks:

How about an example?

For an example scenario, let's pretend we want to make sure that, when we build our application, no file is outputted that contains the string MY_SUPER_SECRET. Perhaps we want to do this to provide a last line of defense from a developer including a sensitive value in our code and we want to prevent webpack from even compiling it. If that string is detected, we'd like webpack to:

throw an error.
not emit any files at any point during the build.

To do this, let's look at the shouldEmit compiler hook. This hook is called before assets are emitted and will allow us to error out and not emit assets if our validation fails.

To start, let's create a new plugin class and add it to the plugins block of our webpack.config:

// src/webpack.config.ts
import { AssetValidatorPlugin } from './plugins/asset-validator-plugin';

module.exports= {
    entry: {...},
    module:{...},
    plugins: [
        new AssetValidatorPlugin(),
        ...
    ]
};

Note that, while I've defined my plugin in a separate class/file, you could include it in your webpack.config inline.

Now, let's take a look at the plugin:

// src/plugins/asset-validator-plugin.ts
import * as webpack from 'webpack';

export class AssetValidatorPlugin {
  apply(compiler: webpack.Compiler) {
    compiler.hooks.shouldEmit.tap('AssetValidatorPlugin', (compilation: webpack.compilation.Compilation) => {
      this.validateAssets(compilation);
    });
  }

  public validateAssets(compilation: webpack.compilation.Compilation) {
    const assets = Object.entries(compilation.assets);
    const regex = new RegExp('MY_SUPER_SECRET', 'g');

    // Loop through each asset and check to see if it contains any sensitive strings
    for (let i = 0; i < assets.length; i++) {
      const [fileName] = assets[i];
      const asset = compilation.getAsset(fileName);
      const source = asset.source.source();
      const contents = convertSourceToString(source);
      const matches = contents.match(regex);

      if (matches) {
        throw new Error(
          "Our tool has identified the presence of the string 'MY_SUPER_SECRET' in your compiled code. Compilation has been aborted."
        );
      }
    }

    return true;
  }
}

// This function is only needed because asset.source.source() can be a string or ArrayBuffer
const convertSourceToString = (source: string | ArrayBuffer): string => {
  if (typeof source === 'string') {
    return source;
  } else {
    return new TextDecoder().decode(source);
  }
};

So, let's review what is included our plugin. We've defined our plugin class and, within, are able to tap into the compiler.hooks.shouldEmit hook. In the hook callback, we simply call a validateAssets() function we've defined which loops through all assets that are part of the compilation and use regular expression matching to see if the string exists. We throw an error if it does, short-circuiting the compilation and not emitting any files. If it doesn't contain our special string, we'll return true, compilation will continue, emitting the packaged files as expected.

If you have a need to pass any parameters to your plugin, that can easily be accomplished by defining a constructor in your plugin class like this:

constructor(options: MyPluginOptions) {
    this.options = options;
}

Conclusion

Hopefully you now have a better understanding of webpack hooks and how you can leverage them to provide additional behavior when your application's assets are packaged.