npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@vercel/webpack-asset-relocator-loader

v1.7.3

Published

Asset relocation loader used in ncc for performing Node.js builds while emitting and relocating any asset references.

Downloads

1,109,229

Readme

Asset Relocator Loader for Webpack

Build Status codecov

Asset relocation loader used in ncc for performing Node.js builds while emitting and relocating any asset references.

Usage

Installation

npm i -g @vercel/webpack-asset-relocator-loader

Usage

Add this loader as a Webpack plugin for any JS files.

Any .node files included will also support binary relocation.

{
  target: "node",
  output: {
    libraryTarget: "commonjs2"
  },
  module: {
    rules: [
      {
        // For node binary relocations, include ".node" files as well here
        test: /\.(m?js|node)$/,
        // it is recommended for Node builds to turn off AMD support
        parser: { amd: false },
        use: {
          loader: '@vercel/webpack-asset-relocator-loader',
          options: {
            // optional, base folder for asset emission (eg assets/name.ext)
            outputAssetBase: 'assets',
            // optional, restrict asset emissions to only the given folder.
            filterAssetBase: process.cwd(),
            // optional, permit entire __dirname emission
            // eg `const nonAnalyzable = __dirname` can emit everything in the folder
            emitDirnameAll: false,
            // optional, permit entire filterAssetBase emission
            // eg `const nonAnalyzable = process.cwd()` can emit everything in the cwd()
            emitFilterAssetBaseAll: false,
            // optional, custom functional asset emitter
            // takes an asset path and returns the replacement
            // or returns false to skip emission
            customEmit: (path, { id, isRequire }) => false | '"./custom-replacement"',
            // optional, a list of asset names already emitted or
            // defined that should not be emitted
            existingAssetNames: [],
            wrapperCompatibility: false, // optional, default
            // build for process.env.NODE_ENV = 'production'
            production: true, // optional, default is undefined
            cwd: process.cwd(), // optional, default
            debugLog: false, // optional, default
          }
        }
      }
    ]
  }
}

Assets will be emitted using emitAsset, with their references updated in the code by the loader to the new output location.

Asset Permissions and Symlinks

Asset symlinks and permissions are maintained in the loader, but aren't passed to Webpack as emit doesn't support these.

This information can be obtained from the loader through the API calls getAssetMeta() and getSymlinks():

const relocateLoader = require('webpack-asset-relocator-loader');

webpack({...}).run((err, stats) => {
  const assetMeta = relocateLoader.getAssetMeta();
  const symlinks = relocateLoader.getSymlinks();
});

They will always contain the most recent build state.

Caching

When using Webpack 5 caching, asset permissions need to be maintained through their own cache, and the public path needs to be injected into the build.

To ensure these cases work out, make sure to run initAssetCache in the build, with the options.outputAssetBase argument:

const relocateLoader = require('webpack-asset-relocator-loader');

webpack({
  // ...

  plugins: [
    {
      apply(compiler) {
        compiler.hooks.compilation.tap("webpack-asset-relocator-loader", compilation => {
          relocateLoader.initAssetCache(compilation, outputAssetBase);
        });
      }
    }
  ]
});

How it Works

Asset Relocation

Assets are detected using static analysis of code, based on very specific triggers designed for common Node.js workflows to provide build support for a very high (but not perfect) level of compatibility with existing Node.js libraries.

  • process.cwd(), __filename, __dirname, path.*(), require.resolve are all statically analyzed when possible.
  • File emissions for exact asset paths
  • Whole directory asset emissions for exact directory paths
  • Wildcard asset emissions for variable path expressions

When an asset is emitted, the pure expression referencing the asset path is replaced with a new expression to the relocated asset and the asset emitted. In the case of wildcard emission, the dynamic parts of the expression are maintained.

Binary Relocation

Node binary loading conventions cover the following triggers for binary relocations:

  • require('bindings')(...)
  • nbind.init(..)
  • node-pre-gyp include patterns

Any shared libraries loaded by these binaries will also be emitted as well.

Node.js Compatibility Features

In addition to asset relocation, this loader also provides a couple of compatibility features for Webpack Node.js builds as part of its analysis.

These include:

  • require.main === module checks are retained for the entry point being built.
  • options.wrapperCompatibility: Automatically handles common AMD / Browserify wrappers to ensure they are properly built by Webpack. See the utils/wrappers.js file for the exact transformations currently provided.
  • require.resolve support in the target environment, while also supporting emission in the build environment.
  • Dynamic require statements are analyzed to exact paths wherever possible, and when not possible to analyze, turned into dynamic requires in the target environment.