js-build-tools 5.3.2 → 5.5.0

package/functions/bundle.mjs

@@ -1,10 +1,22 @@
 import browserify from 'browserify'
 import { dest } from 'gulp'
+import mergeStream from 'merge-stream'
 import * as gulpConfig from '../gulp.config.mjs'
 import source from 'vinyl-source-stream'
+import { getBundleConfigs } from './utilities/getBundleConfigs.mjs'
 
 /**
- * Starting at the distribution entry point, bundle all the files into a single file and store them in the specified output directory.
+ * 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).
+ *
+ * A bundle's name does double duty: it names the output file (name.js) and, via browserify's
+ * `standalone` option, is also the name its exports are exposed under - as a global when loaded
+ * with a bare <script> tag, or as the module when required via CommonJS/AMD. Without this, a
+ * bundle built from a real entry point (one that actually exports something) builds successfully
+ * but exposes nothing a consumer can reach.
  *
  * 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
@@ -13,18 +25,20 @@ import source from 'vinyl-source-stream'
  * @memberOf module:js-build-tools
  * @returns {stream.Stream}
  */
-export const bundle = () => {
-  const bundler = browserify(gulpConfig.get('dist.main'))
-  const ignore = gulpConfig.get('browser.ignore')
-  const exclude = gulpConfig.get('browser.exclude')
-  if (ignore && ignore.length) {
-    bundler.ignore(ignore)
-  }
-  if (exclude && exclude.length) {
-    bundler.exclude(exclude)
-  }
-  return bundler
-    .bundle()
-    .pipe(source(`${gulpConfig.get('browser.name')}.js`))
-    .pipe(dest(gulpConfig.get('browser.to')))
-}
+export const bundle = () => mergeStream(
+  getBundleConfigs().map(({ name, main, ignore, exclude }) => {
+    const bundler = browserify(main, { standalone: name })
+    if (ignore && ignore.length) {
+      bundler.ignore(ignore)
+    }
+    if (exclude && exclude.length) {
+      bundler.exclude(exclude)
+    }
+    return bundler
+      .bundle()
+      .pipe(source(`${name}.js`))
+  })
+  // 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, which every additional bundle's own dest() call otherwise would.
+).pipe(dest(gulpConfig.get('browser.to')))

package/functions/bundle.test.mjs

@@ -1,4 +1,5 @@
 import fs from 'fs'
+import path from 'path'
 import * as setUp from './test-helpers/setUp.mjs'
 import { bundle } from './bundle.mjs'
 import { countMatches } from 'test-filesystem'
@@ -66,6 +67,82 @@ describe('bundle', () => {
         done()
       })
   })
+
+  test('exposes browser.name as the standalone export, reachable by a real consumer', done => {
+    const destPath = gulpConfig.get('browser.to')
+    const bundledFile = `${destPath}/${gulpConfig.get('browser.name')}.js`
+    expect.assertions(2)
+    bundle()
+      .on('finish', () => {
+        // A UMD bundle (browserify's `standalone` option) resolves to its CommonJS branch when
+        // required like this, and to a `window.<browser.name>` global when loaded via a bare
+        // <script> tag in a real browser - both paths hit the same exported value.
+        const resolved = path.resolve(bundledFile)
+        delete require.cache[resolved]
+        const loaded = require(resolved)
+        expect(typeof loaded.file1).toBe('function')
+        expect(typeof loaded.file2).toBe('function')
+        done()
+      })
+      .on('error', error => done(error))
+  })
+})
+
+describe('bundle with additional bundles', () => {
+  const renderOnlyFileContents = 'const file1 = require(\'./sources/file1\')\n' +
+    '\n' +
+    'module.exports = {\n' +
+    '  file1,\n' +
+    '}\n'
+
+  afterEach(() => gulpConfig.set('browser.bundles', []))
+
+  test('produces one file per additional bundle, each from its own entry point', done => {
+    const distPath = gulpConfig.get('dist.to')
+    const renderOnlyMain = `${distPath}/renderOnly`
+    fs.writeFileSync(`${renderOnlyMain}.js`, renderOnlyFileContents)
+    gulpConfig.set('browser.bundles', [{ name: 'renderOnly', main: renderOnlyMain }])
+
+    const destPath = gulpConfig.get('browser.to')
+    const primaryFile = `${destPath}/${gulpConfig.get('browser.name')}.js`
+    const renderOnlyFile = `${destPath}/renderOnly.js`
+    expect.assertions(4)
+    bundle()
+      .on('finish', () => {
+        // The primary bundle is unaffected - still built from dist.main, still has both files.
+        const primaryContents = fs.readFileSync(primaryFile).toString()
+        expect(primaryContents).toContain('Hello from file1')
+        expect(primaryContents).toContain('Good-bye from file2')
+
+        // The additional bundle came from its own entry point - file1 only, never file2.
+        const renderOnlyContents = fs.readFileSync(renderOnlyFile).toString()
+        expect(renderOnlyContents).toContain('Hello from file1')
+        expect(renderOnlyContents).not.toContain('Good-bye from file2')
+        done()
+      })
+      .on('error', error => done(error))
+  })
+
+  test('an additional bundle exposes its own name as its standalone export', done => {
+    const distPath = gulpConfig.get('dist.to')
+    const renderOnlyMain = `${distPath}/renderOnly`
+    fs.writeFileSync(`${renderOnlyMain}.js`, renderOnlyFileContents)
+    gulpConfig.set('browser.bundles', [{ name: 'renderOnly', main: renderOnlyMain }])
+
+    const destPath = gulpConfig.get('browser.to')
+    const renderOnlyFile = `${destPath}/renderOnly.js`
+    expect.assertions(2)
+    bundle()
+      .on('finish', () => {
+        const resolved = path.resolve(renderOnlyFile)
+        delete require.cache[resolved]
+        const loaded = require(resolved)
+        expect(typeof loaded.file1).toBe('function')
+        expect(loaded.file2).toBeUndefined()
+        done()
+      })
+      .on('error', error => done(error))
+  })
 })
 
 describe('bundle ignore / exclude', () => {

package/functions/bundleLint.mjs

@@ -1,12 +1,18 @@
 import { dest, src } from 'gulp'
 import * as gulpConfig from '../gulp.config.mjs'
 import { standardLint } from './partials/standardLint.mjs'
+import { getBundleConfigs } from './utilities/getBundleConfigs.mjs'
 
 /**
- * Applies Standard code style linting to bundled file.
+ * Applies Standard code style linting to every bundled file (the primary bundle, plus any
+ * additional ones from browser.bundles). The lint step itself never varies per bundle, so this is
+ * one shared src()/dest() pipeline fed every bundle's filename at once, rather than one pipeline
+ * per bundle - gulp's src()/dest() both accept an array of paths natively.
  * @memberOf module:js-build-tools
  * @returns {stream.Stream}
  */
-export const bundleLint = () => src(`${gulpConfig.get('browser.to')}/${gulpConfig.get('browser.name')}.js`)
+export const bundleLint = () => src(
+  getBundleConfigs().map(({ name }) => `${gulpConfig.get('browser.to')}/${name}.js`)
+)
   .pipe(standardLint({ fix: true }))
   .pipe(dest(gulpConfig.get('browser.to')))

package/functions/bundleLint.test.mjs

@@ -62,4 +62,24 @@ describe('bundleLint', () => {
         done()
       })
   }, 10000)
+
+  test('lints every additional bundle too, not just the primary one', done => {
+    const browserPath = gulpConfig.get('browser.to')
+    const renderOnlyFile = `${browserPath}/renderOnly.js`
+    fs.writeFileSync(renderOnlyFile, lintableContents)
+    gulpConfig.set('browser.bundles', [{ name: 'renderOnly' }])
+    expect.assertions(2)
+    bundleLint()
+      .on('finish', () => {
+        const lintedContents = fs.readFileSync(renderOnlyFile).toString()
+        expect(countMatches(lintedContents, '"')).toEqual(0)
+        expect(countMatches(lintedContents, ';')).toEqual(0)
+        gulpConfig.set('browser.bundles', [])
+        done()
+      })
+      .on('error', error => {
+        console.error('Encountered error', error)
+        done(error)
+      })
+  }, 10000)
 })

package/functions/bundleMinify.mjs

@@ -1,9 +1,16 @@
 import * as gulpConfig from '../gulp.config.mjs'
 import { minifyFor } from './partials/minifyFor.mjs'
+import { getBundleConfigs } from './utilities/getBundleConfigs.mjs'
 
 /**
- * Creates the minified bundle file.
+ * Creates the minified file for every bundle (the primary bundle, plus any additional ones from
+ * browser.bundles). The minify step itself never varies per bundle, so this is one shared
+ * src()/dest() pipeline (inside minifyFor) fed every bundle's filename at once, rather than one
+ * pipeline per bundle - gulp's src() accepts an array of paths natively.
  * @memberOf module:js-build-tools
  * @returns {*}
  */
-export const bundleMinify = () => minifyFor(`${gulpConfig.get('browser.to')}/${gulpConfig.get('browser.name')}.js`, gulpConfig.get('browser.to'))
+export const bundleMinify = () => minifyFor(
+  getBundleConfigs().map(({ name }) => `${gulpConfig.get('browser.to')}/${name}.js`),
+  gulpConfig.get('browser.to')
+)

package/functions/bundleMinify.test.mjs

@@ -7,9 +7,31 @@ const gulpConfig = testHelpers.gulpConfig
 jest.mock('./partials/minifyFor.mjs', () => ({ minifyFor: jest.fn(() => Promise.resolve(true)) }))
 
 describe('bundleMinify', () => {
-  test('calls minifyFor with configurations', () => {
+  afterEach(() => {
+    gulpConfig.set('browser.bundles', [])
+    minifyFor.mockClear()
+  })
+
+  test('calls minifyFor with the primary bundle', () => {
     expect.assertions(1)
     bundleMinify()
-    expect(minifyFor).toHaveBeenCalledWith(`${gulpConfig.get('browser.to')}/${gulpConfig.get('browser.name')}.js`, gulpConfig.get('browser.to'))
+    expect(minifyFor).toHaveBeenCalledWith(
+      [`${gulpConfig.get('browser.to')}/${gulpConfig.get('browser.name')}.js`],
+      gulpConfig.get('browser.to')
+    )
+  })
+
+  test('calls minifyFor once, with every additional bundle included in the same array', () => {
+    gulpConfig.set('browser.bundles', [{ name: 'renderOnly' }])
+    expect.assertions(2)
+    bundleMinify()
+    expect(minifyFor).toHaveBeenCalledTimes(1)
+    expect(minifyFor).toHaveBeenCalledWith(
+      [
+        `${gulpConfig.get('browser.to')}/${gulpConfig.get('browser.name')}.js`,
+        `${gulpConfig.get('browser.to')}/renderOnly.js`
+      ],
+      gulpConfig.get('browser.to')
+    )
   })
 })

package/functions/utilities/getBundleConfigs.mjs

@@ -0,0 +1,29 @@
+import * as gulpConfig from '../../gulp.config.mjs'
+
+/**
+ * Build the full list of bundles to produce for this project: the primary bundle (browser.name /
+ * dist.main / browser.ignore / browser.exclude, exactly as before browser.bundles existed) plus
+ * any additional bundles from browser.bundles - each falling back to the primary's main / ignore /
+ * exclude whenever its own isn't given, so a render-only (or any other variant) bundle only has to
+ * specify what's actually different about it.
+ * @memberOf module:utilities
+ * @returns {Array<{name: string, main: string, ignore: Array, exclude: Array}>}
+ */
+export const getBundleConfigs = () => {
+  const primary = {
+    name: gulpConfig.get('browser.name'),
+    main: gulpConfig.get('dist.main'),
+    ignore: gulpConfig.get('browser.ignore'),
+    exclude: gulpConfig.get('browser.exclude')
+  }
+  const additional = gulpConfig.get('browser.bundles') || []
+  return [
+    primary,
+    ...additional.map((bundleConfig) => ({
+      name: bundleConfig.name,
+      main: bundleConfig.main || primary.main,
+      ignore: bundleConfig.ignore || primary.ignore,
+      exclude: bundleConfig.exclude || primary.exclude
+    }))
+  ]
+}

package/gulp.config.mjs

@@ -60,6 +60,20 @@ import { fileExists } from 'test-filesystem'
  * @property {ArrayableSetting} exclude - Module names or file paths left out of the bundle entirely; requiring one at
  * runtime throws unless something else provides it (for example a script tag loading it separately). See
  * browserify's b.exclude(file).
+ * @property {Array<module:gulpConfig~AdditionalBundleConfig>} bundles - Additional bundles to produce alongside the
+ * primary one (name/dist.main/ignore/exclude above) - for example a render-only variant built from a different
+ * entry point than the full bundle. Empty by default: a project that never sets this gets exactly the one bundle it
+ * always did.
+ */
+/**
+ * One additional bundle - everything but `name` falls back to the primary bundle's own value when omitted, so an
+ * additional bundle only has to specify what's actually different about it.
+ * @typedef {Object<string, Setting>} module:gulpConfig~AdditionalBundleConfig
+ * @property {StringSetting} name - The name for this bundle's output file and standalone export - must be unique
+ * among all of a project's bundles.
+ * @property {StringSetting} [main] - This bundle's own entry point. Falls back to dist.main when omitted.
+ * @property {ArrayableSetting} [ignore] - This bundle's own ignore list. Falls back to browser.ignore when omitted.
+ * @property {ArrayableSetting} [exclude] - This bundle's own exclude list. Falls back to browser.exclude when omitted.
  */
 /**
  * Configurations for building the node distribution files.
@@ -150,6 +164,7 @@ import { readFileSync } from 'fs'
 
 const setDefaults = {
   browser: {
+    bundles: [],
     enabled: true,
     exclude: [],
     from: 'dist/**/*.js',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "js-build-tools",
-  "version": "5.3.2",
+  "version": "5.5.0",
   "description": "Standardised build process with gulp.",
   "main": "gulpfile.base.js",
   "exports": {
@@ -68,6 +68,7 @@
     "jest": "^30.5.2",
     "jest-environment-jsdom": "^30.5.2",
     "jsdoc-to-markdown": "^9.1.3",
+    "merge-stream": "^2.0.0",
     "postcss": "^8.5.28",
     "regenerator-runtime": "^0.14.1",
     "sass": "^1.105.0",