Build sytem: allow customization of some build options (such as global name) to NPM consumers (#13685)

* Build system: translate exports (and not just imports) from .ts files

* add global options

* contain use of 16010PREBID_GLOBAL16010 macro

* allow custom global / defineGlobal

* allow distUrlBase customization

* allow extensionless import

* update README

* fix eslint config

* consistent quotes

* remove useless comment

Author: dgirardi

README.md

@@ -24,7 +24,7 @@ Prebid.js is open source software that is offered for free as a convenience. Whi
 ## Usage (as a npm dependency)
 
 **Note**: versions prior to v10 required some Babel plugins to be configured when used as an NPM dependency -
-refer to [v9 README](https://github.com/prebid/Prebid.js/blob/9.43.0/README.md).
+refer to [v9 README](https://github.com/prebid/Prebid.js/blob/9.43.0/README.md). See also [customize build options](#customize-options)
 
 ```javascript
 import pbjs from 'prebid.js';
@@ -56,6 +56,37 @@ declare global {
 }
 ```
 
+<a id="customize-options"></a>
+
+### Customize build options
+
+If you're using Webpack, you can use the `prebid.js/customize/webpackLoader` loader to set the following options:
+
+| Name | Type | Description | Default | 
+| ---- | ---- | ----------- | ------- |
+| globalVarName | String | Prebid global variable name | `"pbjs"` | 
+| defineGlobal | Boolean | If false, do not set a global variable | `true` | 
+| distUrlBase |  String | Base URL to use for dynamically loaded modules (e.g. debugging-standalone.js) | `"https://cdn.jsdelivr.net/npm/prebid.js/dist/chunks/"` |
+
+For example, to set a custom global variable name:
+
+```javascript
+// webpack.conf.js
+module.exports = {
+  module: {
+    rules: [
+      {
+        loader: 'prebid.js/customize/webpackLoader',
+        options: {
+          globalVarName: 'myCustomGlobal'
+        }
+      },
+    ]
+  }
+}
+```
+
+
 <a name="Install"></a>
 
 ## Install

customize/buildOptions.mjs

@@ -0,0 +1,49 @@
+import path from 'path'
+import validate from 'schema-utils'
+
+const boModule = path.resolve(import.meta.dirname, '../dist/src/buildOptions.mjs')
+
+export function getBuildOptionsModule () {
+  return boModule
+}
+
+const schema = {
+  type: 'object',
+  properties: {
+    globalVarName: {
+      type: 'string',
+      description: 'Prebid global variable name. Default is "pbjs"',
+    },
+    defineGlobal: {
+      type: 'boolean',
+      description: 'If false, do not set a global variable. Default is true.'
+    },
+    distUrlBase: {
+      type: 'string',
+      description: 'Base URL to use for dynamically loaded modules (e.g. debugging-standalone.js)'
+    }
+  }
+}
+
+export function getBuildOptions (options = {}) {
+  validate(schema, options, {
+    name: 'Prebid build options',
+  })
+  const overrides = {}
+  if (options.globalVarName != null) {
+    overrides.pbGlobal = options.globalVarName
+  }
+  ['defineGlobal', 'distUrlBase'].forEach((option) => {
+    if (options[option] != null) {
+      overrides[option] = options[option]
+    }
+  })
+  return import(getBuildOptionsModule())
+    .then(({ default: defaultOptions }) => {
+      return Object.assign(
+        {},
+        defaultOptions,
+        overrides
+      )
+    })
+}

customize/webpackLoader.mjs

@@ -0,0 +1,8 @@
+import { getBuildOptions, getBuildOptionsModule } from './buildOptions.mjs'
+
+export default async function (source) {
+  if (this.resourcePath !== getBuildOptionsModule()) {
+    return source
+  }
+  return `export default ${JSON.stringify(await getBuildOptions(this.getOptions()), null, 2)};`
+}

eslint.config.js

@@ -60,6 +60,7 @@ module.exports = [
       // do not lint build-related stuff
       '*.js',
       'metadata/**/*',
+      'customize/**/*',
       ...jsPattern('plugins'),
       ...jsPattern('.github'),
     ],
@@ -99,7 +100,7 @@ module.exports = [
       'comma-dangle': 'off',
       semi: 'off',
       'no-undef': 2,
-      'no-console': 'error',      
+      'no-console': 'error',
       'space-before-function-paren': 'off',
       'import/extensions': ['error', 'ignorePackages'],
       'no-restricted-syntax': [

gulp.precompilation.js

@@ -15,17 +15,21 @@ const {buildOptions} = require('./plugins/buildOptions.js');
 // do not generate more than one task for a given build config - so that `gulp.lastRun` can work properly
 const PRECOMP_TASKS = new Map();
 
-function babelPrecomp({distUrlBase = null, disableFeatures = null, dev = false} = {}) {
+function getDefaults({distUrlBase = null, disableFeatures = null, dev = false}) {
   if (dev && distUrlBase == null) {
     distUrlBase = argv.distUrlBase || '/build/dev/'
   }
+  return {
+    disableFeatures: disableFeatures ?? helpers.getDisabledFeatures(),
+    distUrlBase: distUrlBase ?? argv.distUrlBase,
+    ES5: argv.ES5
+  }
+}
+
+function babelPrecomp({distUrlBase = null, disableFeatures = null, dev = false} = {}) {
   const key = `${distUrlBase}::${disableFeatures}`;
   if (!PRECOMP_TASKS.has(key)) {
-    const babelConfig = require('./babelConfig.js')({
-      disableFeatures: disableFeatures ?? helpers.getDisabledFeatures(),
-      prebidDistUrlBase: distUrlBase ?? argv.distUrlBase,
-      ES5: argv.ES5
-    });
+    const babelConfig = require('./babelConfig.js')(getDefaults({distUrlBase, disableFeatures, dev}));
     const precompile = function () {
       // `since: gulp.lastRun(task)` selects files that have been modified since the last time this gulp process ran `task`
       return gulp.src(helpers.getSourcePatterns(), {base: '.', since: gulp.lastRun(precompile)})
@@ -173,9 +177,23 @@ function generateGlobalDef(options) {
   }
 }
 
+function generateBuildOptions(options = {}) {
+  return function (done) {
+    options = buildOptions(getDefaults(options));
+    import('./customize/buildOptions.mjs').then(({getBuildOptionsModule}) => {
+      const dest = getBuildOptionsModule();
+      if (!fs.existsSync(path.dirname(dest))) {
+        fs.mkdirSync(path.dirname(dest), {recursive: true});
+      }
+      fs.writeFile(dest, `export default ${JSON.stringify(options, null, 2)}`, done);
+    })
+  }
+
+}
+
 function precompile(options = {}) {
   return gulp.series([
-    gulp.parallel(['ts', generateMetadataModules]),
+    gulp.parallel(['ts', generateMetadataModules, generateBuildOptions(options)]),
     gulp.parallel([copyVerbatim, babelPrecomp(options)]),
     gulp.parallel([publicModules, generateCoreSummary, generateModuleSummary, generateGlobalDef(options)])
   ]);

libraries/riseUtils/index.js

@@ -14,6 +14,8 @@ import {BANNER, NATIVE, VIDEO} from '../../src/mediaTypes.js';
 import {config} from '../../src/config.js';
 import {ADAPTER_VERSION, DEFAULT_CURRENCY, DEFAULT_TTL, SUPPORTED_AD_TYPES} from './constants.js';
 
+import {getGlobalVarName} from '../../src/buildOptions.js';
+
 export const makeBaseSpec = (baseUrl, modes) => {
   return {
     version: ADAPTER_VERSION,
@@ -367,7 +369,7 @@ export function generateGeneralParams(generalObject, bidderRequest, adapterVersi
 
   const generalParams = {
     wrapper_type: 'prebidjs',
-    wrapper_vendor: '$$PREBID_GLOBAL$$',
+    wrapper_vendor: getGlobalVarName(),
     wrapper_version: '$prebid.version$',
     adapter_version: adapVer,
     auction_start: bidderRequest.auctionStart,

modules/adagioRtdProvider.js

@@ -31,6 +31,8 @@ import { _ADAGIO, getBestWindowForAdagio } from '../libraries/adagioUtils/adagio
 import { getGptSlotInfoForAdUnitCode } from '../libraries/gptUtils/gptUtils.js';
 import { getBoundingClientRect } from '../libraries/boundingClientRect/boundingClientRect.js';
 
+import {getGlobalVarName} from '../src/buildOptions.js';
+
 /**
  * @typedef {import('../modules/rtdModule/index.js').RtdSubmodule} RtdSubmodule
  * @typedef {import('../modules/rtdModule/index.js').adUnit} adUnit
@@ -446,7 +448,7 @@ function storeRequestInAdagioNS(bid, config) {
       bidderRequestsCount,
       ortb2: ortb2Data,
       ortb2Imp: ortb2ImpData,
-      localPbjs: '$$PREBID_GLOBAL$$',
+      localPbjs: getGlobalVarName(),
       localPbjsRef: getGlobal(),
       organizationId,
       site

modules/amxBidAdapter.js

@@ -17,6 +17,8 @@ import { getStorageManager } from '../src/storageManager.js';
 import { fetch } from '../src/ajax.js';
 import { getGlobal } from '../src/prebidGlobal.js';
 
+import {getGlobalVarName} from '../src/buildOptions.js';
+
 const BIDDER_CODE = 'amx';
 const storage = getStorageManager({ bidderCode: BIDDER_CODE });
 const SIMPLE_TLD_TEST = /\.com?\.\w{2,4}$/;
@@ -343,7 +345,7 @@ export const spec = {
       trc: fbid.bidRequestsCount || 0,
       tm: isTrue(testMode),
       V: '$prebid.version$',
-      vg: '$$PREBID_GLOBAL$$',
+      vg: getGlobalVarName(),
       i: testMode && tagId != null ? tagId : getID(loc),
       l: {},
       f: 0.01,
@@ -551,7 +553,7 @@ export const spec = {
           U: getUIDSafe(),
           re: ref,
           V: '$prebid.version$',
-          vg: '$$PREBID_GLOBAL$$',
+          vg: getGlobalVarName(),
         };
       }
 

modules/amxIdSystem.js

@@ -14,6 +14,8 @@ import {getStorageManager} from '../src/storageManager.js';
 import {MODULE_TYPE_UID} from '../src/activities/modules.js';
 import {domainOverrideToRootDomain} from '../libraries/domainOverrideToRootDomain/index.js';
 
+import {getGlobalVarName} from '../src/buildOptions.js';
+
 const NAME = 'amxId';
 const GVL_ID = 737;
 const ID_KEY = NAME;
@@ -117,7 +119,7 @@ export const amxIdSubmodule = {
 
       v: '$prebid.version$',
       av: version,
-      vg: '$$PREBID_GLOBAL$$',
+      vg: getGlobalVarName(),
       us_privacy: usp,
       am: getBidAdapterID(),
       gdpr: consent.gdprApplies ? 1 : 0,

modules/gamAdServerVideo.js

@@ -26,6 +26,8 @@ import {DEFAULT_GAM_PARAMS, GAM_ENDPOINT, gdprParams} from '../libraries/gamUtil
 import { vastLocalCache } from '../src/videoCache.js';
 import { fetch } from '../src/ajax.js';
 import XMLUtil from '../libraries/xmlUtils/xmlUtils.js';
+
+import {getGlobalVarName} from '../src/buildOptions.js';
 /**
  * @typedef {Object} DfpVideoParams
  *
@@ -74,7 +76,7 @@ export const VAST_TAG_URI_TAGNAME = 'VASTAdTagURI';
  */
 export function buildGamVideoUrl(options) {
   if (!options.params && !options.url) {
-    logError(`A params object or a url is required to use $$PREBID_GLOBAL$$.adServers.gam.buildVideoUrl`);
+    logError(`A params object or a url is required to use ${getGlobalVarName()}.adServers.gam.buildVideoUrl`);
     return;
   }