How to tell rsbuild when to hash, and when not to hash?

[binarykitchen]

Hello - I'm running multiple environments: Local, Delivery, Test and Production.

On Test and Production, NODE_ENV is set to PROD. But For Local and Delivery, it's DEV.

But I want rsbuild to amend content hashes to all assets for every environment except LOCAL. How to configure this best?

For now, I wrote this code, but I am not happy about it, and wonder if you have better ideas or suggestions for this scenario?

const FILE_NAME_HASH = "[contenthash:10]";
const NON_LOCAL_FILENAME = {
  js: `[name].${FILE_NAME_HASH}.js`,
  css: `[name].${FILE_NAME_HASH}.css`,
  svg: `[name].${FILE_NAME_HASH}.svg`,
  font: `[name].${FILE_NAME_HASH}[ext]`,
  wasm: `${FILE_NAME_HASH}.module.wasm`,
  image: `[name].${FILE_NAME_HASH}[ext]`,
  media: `[name].${FILE_NAME_HASH}[ext]`,
  assets: `[name].${FILE_NAME_HASH}[ext]`,
};

function getClientOutput() {
  const output = {
    distPath: {
      root: wwwDir,
    },
    target: "web" as const,
  };

  if (isLocal()) {
    return output;
  }

  return {
    distPath: output.distPath,
    target: output.target,
    filename: NON_LOCAL_FILENAME,
    copy: output.copy,
  };
}

[binarykitchen]

Under notes at https://github.com/web-infra-dev/rsbuild/blob/main/website/docs/en/config/output/filename-hash.mdx#notes you mention

By default, the filename in development mode does not include a hash.

Can I somehow override this behaviour and configure this myself?

[chenjiahan]

You only need to customize JS and CSS filenames:

const NON_LOCAL_FILENAME = {
  js: `[name].${FILE_NAME_HASH}.js`,
  css: `[name].${FILE_NAME_HASH}.css`,
};

Other assets already respect output.filenameHash in dev mode.

[binarykitchen]

Thanks @chenjiahan

I already have this code in place:

const FILE_NAME_HASH = "[contenthash:10]"; // <-- Hard code? Bad idea, should follow rsbuild standards

const NON_LOCAL_FILENAME = { // <-- Hard code UI assets? Bad idea, should check which UI assets rsbuild supports.
  js: `[name].${FILE_NAME_HASH}.js`,
  css: `[name].${FILE_NAME_HASH}.css`,
  svg: `[name].${FILE_NAME_HASH}.svg`,
  font: `[name].${FILE_NAME_HASH}[ext]`,
  wasm: `${FILE_NAME_HASH}.module.wasm`,
  image: `[name].${FILE_NAME_HASH}[ext]`,
  media: `[name].${FILE_NAME_HASH}[ext]`,
  assets: `[name].${FILE_NAME_HASH}[ext]`,
};

Three problems:

• What is your default content hash? You're not exporting it. Its length changed from 8 to 10 recently during your update to v2. Please export it.
• UI assets come in many ways, JS, CSS, SVG, font, Wasm etc ... how do we know which ones rsbuild supports and hashes them? This information (export) is also missing. Pretend you add sound, "wav" later, I will miss it out in my build.
• My initial question, when to hash, when not to hash, independently of NODE_ENV, hasn't been answered yet ...

[chenjiahan]

• We probably should not export the internal default hash template as a public constant. If users customize output.filename, they should explicitly choose the hash format they want.
• You do not need to enumerate all asset types. Currently, only JS and CSS have mode-dependent default filename hash behavior. Other assets already follow output.filenameHash by default.
• More precisely, this behavior is based on Rsbuild mode, not directly on NODE_ENV. NODE_ENV only affects the default value of mode when mode is not explicitly configured. See "Default" in https://rsbuild.rs/config/output/filename#outputfilename

[binarykitchen]

I see. Thanks for explaining.

You do not need to enumerate all asset types. Currently, only JS and CSS have mode-dependent default filename hash behavior. Other assets already follow output.filenameHash by default.

Ok, let's not export internals. Agree.

More precisely, this behavior is based on Rsbuild mode, not directly on NODE_ENV. NODE_ENV only affects the default value of mode when mode is not explicitly configured. See "Default" in rsbuild.rs/config/output/filename#outputfilename

I see. I wonder, is there a callback function to adjust output.filename based on other environments, not just NODE_ENV?
If you run a business, have a local, dev, test, delivery, acceptance and live servers to test properly with QA staff ...

... you will want to fine-tune what assets to hash, what assets to cache and which one not, while seeing stack traces for some, while sticking to defaults whatever is not defined.

For example, you have this for local development using HMR:

// Development mode
const devDefaultFilename = {
  html: '[name].html',
  js: '[name].js',
  css: '[name].css',
  svg: '[name].[contenthash:10].svg',
  ...
};

What if I set up a new Test server, also running on NODE_ENV = DEV. This for QA tests, while I still want to any full error stack trace:

// Test mode
const testDefaultFilename = {
  html: '[name].html', // <-- Okay, that one is an exception, do not hash index.html
  js: '[name].[contenthash:10].js',
  css: '[name].[contenthash:10].css',
  svg: '[name].[contenthash:10].svg',
  ...
};

This is not possible right now, unfortunately.

Related code:
https://github.com/web-infra-dev/rsbuild/blob/main/packages/core/src/types/config.ts

I understand, this is a tricky question:

Currently, only JS and CSS have mode-dependent default filename hash behavior. Other assets already follow output.filenameHash by default.

Fair enough. This makes sense for most simple set-ups, but when you run multiple servers and environments, it would be good to finetune this further.

Mode (NODE_ENV) !== Servers / Environment

[chenjiahan]

I don’t think a callback is necessary here.

For different environments, you can configure different values under environments directly, instead of making filenameHash depend on a callback.

About true vs 'always': true needs to keep the current behavior: add filename hash after a production build. 'always' would mean adding JS/CSS filename hash in all modes, including development mode.

For format, it is already configurable today via output.filenameHash: string, for example:

export default {
  output: {
    filenameHash: 'contenthash:16',
  },
};

So format would just be the object-form equivalent of the existing string usage.

[binarykitchen]

Ok then, let's give it a try that way. Then I will see how it goes and can provide more feedback afterwards.

[chenjiahan]

The object-format config has been added in v2.0.4, see: https://rsbuild.rs/config/output/filename-hash#always-enable-hash

[binarykitchen]

Nice. That worked:

output: {
  distPath: {
    root: wwwDir,
  },
  target: "web",
  filenameHash: {
    enable: isLocal() ? false : "always",
  },
},

The tip on your documentation ...

Enabling filename hash in development mode may cause HMR to fail, especially for CSS files.

... is fair. I just want to add, that I run multiple servers under multiple environments. Some remote servers are still run under DEV mode but without HMR. Enabling DEV mode on remote servers gives us QA testers more possibilities and ways to investigate bugs, that's why.

Really appreciate it when rsbuild allows customisations like these for unusual setups. Thank you 🥇

[chenjiahan]

Thanks for the feedback! Glad it helped.