async?

boolean

(Optional) Whether the source should be loaded asynchronously or not.

background?

LayerOptions

(Optional) The options of the background layer.

bundlePath?

string

(Optional) The bundle path resolved against the runtime public path.

Prefer this over url when the bundle should follow the active publicPath. The runtime will load it with publicPath + bundlePath, which keeps external bundle resolution aligned with the current build output without hard-coding an absolute URL into the generated runtime code.

libraryName?

string | string[]

(Optional) The name of the library. Same as https://webpack.js.org/configuration/externals/\#string.

By default, the library name is the same as the externals key. For example:

The config

ExternalsLoadingPlugin({
  externals: {
    lodash: {
      url: '……',
    }
  }
})

Will generate the following webpack externals config:

externals: {
  lodash: 'lynx[Symbol.for("__LYNX_EXTERNAL_GLOBAL__")].lodash',
}

If one external bundle contains multiple modules, should set the same library name to ensure it's loaded only once. For example:

ExternalsLoadingPlugin({
  externals: {
    lodash: {
      libraryName: 'Lodash',
      url: '……',
    },
    'lodash-es': {
      libraryName: 'Lodash',
      url: '……',
    }
  }
})

Will generate the following webpack externals config:

externals: {
  lodash: 'lynx[Symbol.for("__LYNX_EXTERNAL_GLOBAL__")].Lodash',
  'lodash-es': 'lynx[Symbol.for("__LYNX_EXTERNAL_GLOBAL__")].Lodash',
}

You can pass an array to specify subpath of the external. Same as https://webpack.js.org/configuration/externals/\#string-1. For example:

ExternalsLoadingPlugin({
  externals: {
    preact: {
      libraryName: ['ReactLynx', 'Preact'],
      url: '……',
    },
  }
})

Will generate the following webpack externals config:

externals: {
  preact: 'lynx[Symbol.for("__LYNX_EXTERNAL_GLOBAL__")].ReactLynx.Preact',
}

mainThread?

LayerOptions

(Optional) The options of the main-thread layer.

retries?

number

(Optional) The number of additional attempts when fetching the external bundle times out (response.code === -2).

timeout?

number

(Optional) The wait time in milliseconds.

url?

string

(Optional) The final bundle URL to fetch directly at runtime.

Use this when the external bundle is hosted outside the current build output, such as on a CDN. If both url and bundlePath are provided, url takes precedence because it is already the fully resolved address.