esbuild-plugin-filelastmodified

2.0.4 verified Fri May 01 auth: no javascript

An esbuild plugin that exports the last modified timestamp of specific files during the build process. Version 2.0.4 is the latest stable release, with no known breaking changes since v2.0.0. It returns a Unix timestamp (milliseconds) for requested files, integrated as a virtual module. Differentiator: simple, focused utility for cache busting or build-time file info without manual file system reads.

Common errors

error Error: The plugin "fileLastModifiedPlugin" doesn't have a `setup` function. ↓

cause Importing the wrong export or using an outdated import pattern.

fix

Use the correct import: import { fileLastModifiedPlugin } from 'esbuild-plugin-filelastmodified'

error Cannot find module 'esbuild-plugin-filelastmodified' ↓

cause Package not installed or missing from dependencies.

fix

Run npm install esbuild-plugin-filelastmodified --save-dev

Warnings

gotcha Plugin expects the virtual module import path to start with the namespace prefix (default 'filemod:') — if you change the namespace, adjust imports accordingly. ↓

fix Ensure the import path matches the namespace configuration, e.g., 'my-ns:./file.js' if namespace is 'my-ns'.

gotcha Timestamps are in milliseconds (Unix time); if you need seconds, divide by 1000. ↓

fix Use Math.floor(timestamp / 1000) to get seconds.

gotcha The plugin only watches files included in the esbuild build graph (via import statements). Files not imported anywhere will not have their timestamps tracked. ↓

fix Import the files you need timestamps for, even if they are not directly used in code.

gotcha Changes to the monitored files will cause esbuild to rebuild only if those files are actually part of the build (i.e., imported). The plugin does not add files to the build graph automatically. ↓

fix Explicitly import any file you need timestamps for to ensure rebuilds trigger.

Install

npm install esbuild-plugin-filelastmodified

yarn add esbuild-plugin-filelastmodified

pnpm add esbuild-plugin-filelastmodified

Imports

fileLastModifiedPlugin

wrong

const fileLastModifiedPlugin = require('esbuild-plugin-filelastmodified')

correct

import { fileLastModifiedPlugin } from 'esbuild-plugin-filelastmodified'

CommonJS require works as it also exports a default; prefer named import for clarity.

fileLastModifiedPlugin

wrong

const fileLastModifiedPlugin = require('esbuild-plugin-filelastmodified').default

correct

const { fileLastModifiedPlugin } = require('esbuild-plugin-filelastmodified')

No default export, destructure directly.

fileLastModifiedPlugin

wrong

import { fileLastModifiedPlugin } from 'esbuild-plugin-filelastmodified'

correct

import fileLastModifiedPlugin from 'esbuild-plugin-filelastmodified'

Default import also works since both named and default exports point to the same function.

FileLastModifiedPluginOptions

import type { FileLastModifiedPluginOptions } from 'esbuild-plugin-filelastmodified'

Type-only import for TypeScript users.

Quickstart

Shows how to set up the esbuild plugin and use virtual module imports to get file modification timestamps.

import { build } from 'esbuild';
import { fileLastModifiedPlugin } from 'esbuild-plugin-filelastmodified';

await build({
  entryPoints: ['src/app.js'],
  bundle: true,
  outfile: 'dist/out.js',
  plugins: [
    fileLastModifiedPlugin({
      filter: /^.*\.json$/,
      namespace: 'filemod',
    }),
  ],
});

// In your entry point, import the virtual module to get timestamps:
import { 'filemod:./data.json' as timestamps };
// timestamps will be an object mapping file paths to last modified timestamps (Unix ms).