functions/bundle.mjsjavascript
import * as esbuild from 'esbuild'
import { existsSync, readFileSync } from 'fs'
import { readFile } from 'fs/promises'
import { dest } from 'gulp'
import { builtinModules, createRequire } from 'module'
import path from 'path'
import { PassThrough } from 'stream'
import Vinyl from 'vinyl'
import * as gulpConfig from '../gulp.config.mjs'
import { getBundleConfigs } from './utilities/getBundleConfigs.mjs'
/**
* Resolve one of js-build-tools' own dependencies (a browser shim) to a file path. Resolved from the project first,
* where npm normally hoists it, then from js-build-tools' own install (a nested copy when versions conflict). No
* import.meta here: this file is also compiled to CommonJS (dist/), where import.meta is a syntax error.
* @param {string} request
* @returns {string}
* @private
*/
const resolveShim = (request) => {
const fromProject = createRequire(path.join(process.cwd(), 'package.json'))
try {
return fromProject.resolve(request)
} catch {
return createRequire(fromProject.resolve('js-build-tools')).resolve(request)
}
}
/**
* Browser stand-ins for the Node built-ins that browserify used to provide and that real bundles still reach:
* `path` (json-file-db) and `process` (guarded `typeof process` checks in debug and css-select's dependencies).
* Any other built-in is first looked up as an ordinary package (so a project can install its own shim, e.g.
* `events` or `buffer`), and otherwise becomes an empty object, the way browserify always treated `fs`.
* @type {Object<string, string>}
* @private
*/
const builtinShims = {
path: 'path-browserify',
process: 'process/browser.js'
}
const builtins = new Set(builtinModules)
const emptyNamespace = 'js-build-tools-empty'
/**
* The module injected for a free `process` reference (browserify inserted the same stand-in). esbuild only adds it
* to bundles that actually reference `process`.
* @private
*/
const processInject = 'js-build-tools:process'
const processInjectNamespace = 'js-build-tools-inject'
const processShimImport = 'js-build-tools:process-browser'
const commonJsNamespace = 'js-build-tools-cjs'
/**
* The absolute dist.to when the package.json nearest to it (the one esbuild reads) says `"type": "module"` (see
* browserifyCompat), else null.
* @returns {string|null}
* @private
*/
const commonJsDistRoot = () => {
const distRoot = path.resolve(gulpConfig.get('dist.to'))
for (let directory = distRoot; ; directory = path.dirname(directory)) {
const packageFile = path.join(directory, 'package.json')
if (existsSync(packageFile)) {
return JSON.parse(readFileSync(packageFile, 'utf8')).type === 'module' ? distRoot : null
}
if (path.dirname(directory) === directory) {
return null
}
}
}
/**
* Turn a bundle name into the global it is exposed as, exactly as browserify's `standalone` option (via the umd
* package) did: dashes followed by a lowercase letter are camel-cased, then anything not valid in an identifier is
* dropped, per dot-separated segment. So `matrix-dom` stays `matrix-dom.js` on disk but is `window.matrixDom`.
* @memberOf module:utilities
* @param {string} name
* @returns {string}
* @private
*/
export const toGlobalName = (name) => name.split('.')
.map((segment) => {
const result = segment.replace(/-([a-z])/g, (_, char) => char.toUpperCase()).replace(/[^\w$]+/g, '')
if (!result) {
throw new Error(`Bundle name "${name}" does not give a valid JavaScript identifier`)
}
return result
})
.join('.')
const escapeRegExp = (text) => text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
/**
* Whether browserify's ignore would have matched this import, by the same four rules browserify used: the import
* id itself, the resolved file (entries starting with '.' are resolved against the working directory first), any
* file inside node_modules/<name>/ for an ignored package name, or '/' + the resolved file relative to the working
* directory.
* @param {Array<string>} ignore
* @returns {function(string, string): boolean} (id, resolvedFile) => matched
* @private
*/
const browserifyIgnoreMatcher = (ignore) => {
const entries = new Set(ignore.map((entry) => entry.startsWith('.') ? path.resolve(entry) : entry))
return (id, file) => {
if (entries.has(id) || entries.has(file)) {
return true
}
// Every package the file sits inside (nested node_modules too). browserify only took the first segment of the
// outermost one, so `@scope` matched a whole scope; that still works, and `@scope/name` now matches its package.
const inPackage = file.replace(/\\/g, '/').split('/node_modules/').slice(1).some((part) => {
const [first, second] = part.split('/')
return entries.has(first) || (first.startsWith('@') && entries.has(`${first}/${second}`))
})
return inPackage || entries.has(`/${path.relative(process.cwd(), file).replace(/\\/g, '/')}`)
}
}
/**
* The esbuild plugin that copies what browserify did for module resolution: 'ignore' matches (see
* browserifyIgnoreMatcher) and unshimmed Node built-ins resolve to an empty object, the built-ins listed in
* builtinShims resolve to their browser stand-ins, and a free `process` gets the process stand-in injected.
*
* Also: browserify read every file as CommonJS, esbuild follows package.json "type". js-build-tools' own dist output
* is always CommonJS (Babel), even in a `"type": "module"` project, where esbuild would read it as an ES module and
* leave `exports` undefined. So when commonJsRoot is given, files under it are loaded as CommonJS.
* @param {Array<string>} ignore
* @param {Array<string>} exclude - also applies to Node built-ins, which are otherwise shimmed before esbuild's
* `external` is checked (browserify checked exclude first too)
* @param {string|null} commonJsRoot - absolute dist.to, for a `"type": "module"` project; otherwise null
* @returns {Object} an esbuild plugin
* @private
*/
const browserifyCompat = (ignore, exclude, commonJsRoot) => ({
name: 'js-build-tools-browserify-compat',
setup (build) {
const isIgnored = browserifyIgnoreMatcher(ignore)
const excluded = new Set(exclude)
const emptyModule = (name) => ({ path: name, namespace: emptyNamespace })
const resolveNormally = (args) => build.resolve(args.path, {
kind: args.kind,
resolveDir: args.resolveDir,
importer: args.importer,
pluginData: { browserifyCompat: true }
})
build.onResolve({ filter: new RegExp(`^${escapeRegExp(processInject)}$`) }, () => ({
path: 'process',
namespace: processInjectNamespace
}))
build.onLoad({ filter: /.*/, namespace: processInjectNamespace }, () => ({
contents: `export { default as process } from ${JSON.stringify(processShimImport)}`,
loader: 'js'
}))
// Side-effect free, so a bundle that never reads `process` drops the stand-in entirely
build.onResolve({ filter: new RegExp(`^${escapeRegExp(processShimImport)}$`) }, () => ({
path: resolveShim(builtinShims.process),
sideEffects: false
}))
build.onResolve({ filter: /.*/ }, async (args) => {
if (args.pluginData?.browserifyCompat) {
return undefined
}
if (args.kind !== 'entry-point') {
if (isIgnored(args.path, '')) {
return emptyModule(args.path)
}
const bareName = args.path.replace(/^node:/, '')
if (builtins.has(bareName)) {
if (excluded.has(args.path) || excluded.has(bareName)) {
return { path: args.path, external: true }
}
const installed = args.path.startsWith('node:') ? { errors: [true] } : await resolveNormally(args)
const isFile = !installed.errors.length && installed.namespace === 'file' && path.isAbsolute(installed.path)
// Disabled by the importing package's "browser" field (e.g. postcss: { "fs": false, "path": false }):
// esbuild resolves it to nothing, not a file. The package chose this, so an empty object without a
// warning, before any stand-in, as browserify did.
if (!installed.errors.length && !isFile) {
return emptyModule(bareName)
}
if (builtinShims[bareName]) {
return { path: resolveShim(builtinShims[bareName]) }
}
// A project's own installed package of the same name (a browser shim) wins over an empty object
if (isFile) {
return { path: installed.path }
}
// browserify bundled a real shim for some of these (events, buffer, util...); say so instead of failing
// quietly at runtime. Listing it in browser.ignore makes the empty object deliberate and silences this.
return {
...emptyModule(bareName),
warnings: [{
text: `Node built-in "${args.path}" has no browser version, bundled as an empty object (imported by ` +
`${path.relative(process.cwd(), args.importer)}). Install a browser shim package of the same name, ` +
'or add it to browser.ignore if this is expected.'
}]
}
}
}
if (!ignore.length && !commonJsRoot) {
return undefined
}
const resolved = await resolveNormally(args)
// Unresolvable or excluded: leave it to esbuild, which reports or externalises it as usual
if (resolved.errors.length || resolved.external || resolved.namespace !== 'file') {
return undefined
}
if (args.kind !== 'entry-point' && isIgnored(args.path, resolved.path)) {
return emptyModule(args.path)
}
if (commonJsRoot && resolved.path.startsWith(commonJsRoot + path.sep)) {
return {
path: path.relative(process.cwd(), resolved.path).replace(/\\/g, '/'),
namespace: commonJsNamespace,
pluginData: { file: resolved.path }
}
}
return undefined
})
// The project's own dist files, read outside the 'file' namespace so package.json "type" no longer applies
build.onLoad({ filter: /.*/, namespace: commonJsNamespace }, async ({ pluginData }) => ({
contents: await readFile(pluginData.file, 'utf8'),
loader: 'js',
resolveDir: path.dirname(pluginData.file)
}))
build.onLoad({ filter: /.*/, namespace: emptyNamespace }, () => ({ contents: 'module.exports = {}', loader: 'js' }))
}
})
/**
* Bundle one entry point with esbuild, returning the bundle as a Vinyl file named `<name>.js`.
* @param {{name: string, main: string, ignore: Array<string>, exclude: Array<string>}} bundleConfig
* @returns {Promise<Vinyl>}
* @private
*/
const buildBundle = async ({ name, main, ignore, exclude }) => {
// Either setting may be a single string (an ArrayableSetting), as browserify accepted
const ignoreList = [].concat(ignore || [])
const excludeList = [].concat(exclude || [])
const globalName = toGlobalName(name)
const result = await esbuild.build({
entryPoints: [createRequire(path.join(process.cwd(), 'package.json')).resolve(path.resolve(main))],
bundle: true,
write: false,
outfile: `${name}.js`,
platform: 'browser',
format: 'iife',
globalName,
// browserify only read a package's "browser" and "main" fields, never "module"; keep the same builds
mainFields: ['browser', 'main'],
external: excludeList,
define: { global: 'globalThis' },
inject: [processInject],
// Also reachable through CommonJS, as browserify's UMD wrapper was (the <script> tag global is unchanged)
footer: { js: `if (typeof module === 'object' && module && module.exports) { module.exports = ${globalName} }` },
plugins: [browserifyCompat(ignoreList, excludeList, commonJsDistRoot())],
logLevel: 'silent'
})
result.warnings.forEach(({ text }) => console.warn(`bundle ${name}.js: ${text}`))
return new Vinyl({
cwd: process.cwd(),
base: process.cwd(),
path: path.join(process.cwd(), `${name}.js`),
contents: Buffer.from(result.outputFiles[0].contents)
})
}
/**
* Starting at each bundle's own entry point (dist.main for the primary bundle, or its own
* override from browser.bundles), bundle all the reachable files into a single file per bundle and
* store them in the specified output directory. A project with no browser.bundles entries gets
* exactly the one bundle it always did; each additional entry produces its own separate bundle
* (for example, a render-only variant built from a different entry point than the full bundle).
*
* Bundling is done by esbuild (replacing browserify since 6.9.0), as an IIFE. A bundle's name does
* double duty: it names the output file (name.js) and is also the name its exports are exposed
* under - as a global when loaded with a bare `<script>` tag (camel-cased the way browserify's
* `standalone` option did, so `matrix-dom` is `window.matrixDom`), or as the module when required
* via CommonJS. AMD loaders are no longer supported.
*
* Two escape hatches from browser.config.json keep an unwanted dependency (or a dependency's dependency) out of the
* bundle: 'ignore' replaces it with an empty object (safe when your code never actually calls into it - for example
* a library's default option value you always override with your own) and 'exclude' leaves it out entirely (your
* code must not require it, or provide it another way, such as a separate script tag).
*
* Node built-ins: `path` and `process` get browser stand-ins, any other built-in resolves to a package of the same
* name if the project installs one, otherwise to an empty object.
* @memberOf module:js-build-tools
* @returns {stream.Stream}
*/
export const bundle = () => {
const files = new PassThrough({ objectMode: true })
// One shared dest() for every bundle, not one per bundle - vinyl-fs's dest() races against
// itself (a real "write after end" failure) when two separate dest() streams target the same
// directory concurrently.
const output = files.pipe(dest(gulpConfig.get('browser.to')))
Promise.all(getBundleConfigs().map(buildBundle))
.then((bundles) => {
bundles.forEach((file) => files.write(file))
files.end()
})
.catch((error) => output.emit('error', error))
return output
}