Feature: Add Option to Skip Initial Build in Watch Mode

[clicktodev]

Problem

When running a development script like the following:

"dev": "npm run build && concurrently \"npm run build --watch\" \"npm run serve\""

  await esbuild.build({
    watch: {
      skipFirstBuild: true
    },
  )}

the watch mode (npm run build:watch) starts immediately and triggers a build on the first run. This can cause issues in cases where:

1. The serve command starts before the initial build is complete.
2. The doc folder (or equivalent) does not exist prior to the build, leading to a 404 error when the serve command runs.

Currently, there is no built-in way to skip the initial run in watch mode and only trigger builds on subsequent file changes.

Use Case

Developers often need to ensure that the doc folder (or other build artifacts) is present before starting the server. For example:

1. npm run build ensures that the doc folder exists.
2. npm run build:watch watches for changes and rebuilds as needed.
3. npm run serve serves the doc folder but should not start before the first build is complete.

Without the ability to skip the first build in watch mode, there is a race condition between the build and serve commands, causing issues for the user.

Proposed Solution

Introduce an option or flag (e.g., --skip-first-build) for the watch mode to skip the initial execution and only run on subsequent file changes.

Example:

  await esbuild.build({
    watch: true,
    skipFirstBuild: true
  )}

This would:

1. Start watching files immediately.
2. Only trigger a rebuild when changes are detected, skipping the initial run.

Workaround

Currently, developers must rely on custom scripts or tools to handle this, which adds unnecessary complexity. For example:

• Writing scripts that conditionally skips the first build.

https://stackoverflow.com/questions/42495826/webpack-watch-with-skip-initial-build

Benefits

• Simplifies the development workflow by avoiding race conditions.
• Reduces the need for custom workarounds or scripts.
• Provides a more intuitive experience for users running common dev setups.

Additional Context

This feature would be especially useful for projects where build artifacts are required before serving, such as:

• Static site generators
• Projects using bundlers or transpilers
• Applications with a multi-step build process

Thank you for considering this feature request!

[evanw]

I'm looking at other watch mode issues at the moment due to #4178. One reason why this isn't straightforward to do is that esbuild's watch mode is deliberately precise instead of conservative, meaning it only watches files that affect the build (instead of watching all files under a given directory tree). However, that means esbuild needs to do an initial build to know what files are in the build before it begins watching them.

[clicktodev]

So it's not feasible due to how esbuild works? I created a similar request to the nodejs built-in watcher but I doubt that will be available anytime soon