rollup-plugin-web-worker-loader
v1.6.1
Published
Rollup plugin to handle Web Workers
Downloads
52,972
Readme
rollup-plugin-web-worker-loader
Rollup plugin to handle Web Workers.
Can inline the worker code or emit a script file using code-splitting. Handles Worker dependencies and can emit source maps. Worker dependencies are added to Rollup's watch list. Supports bundling workers for Node.js environments
Getting started
yarn add rollup-plugin-web-worker-loader --dev
Add the plugin to your rollup configuration:
import webWorkerLoader from 'rollup-plugin-web-worker-loader';
export default {
entry: 'src/index.js',
plugins: [
webWorkerLoader(/* configuration */),
],
format: 'esm',
};
Bundle the worker code using the RegEx pattern specified in the plugin's configuration.
By default you can add the prefix web-worker:
to your imports:
// here we use the default pattern but any RegEx can be configured
import DataWorker from 'web-worker:./DataWorker';
const dataWorker = new DataWorker();
dataWorker.postMessage('Hello World!');
Configuration
The plugin responds to the following configuration options:
webWorkerLoader({
targetPlatform?: string, // The platform workers should be built for, can be 'auto', 'browser', 'node' or 'base64'.
// specifying a target platform other than 'auto' reduces the amount of loader code.
// The `base64` options forces inline and the import results on a base64 string that
// encodes the worker's source code. NOTE: The string does not include a mime type.
// 'auto' detectes the target platform and selects between 'browser` and 'node'.
// Default: 'auto'
pattern?: RegEx, // A RegEx instance describing the pattern that matches the files to import as
// web workers. If capturing groups are present, the plugin uses the contents of the
// last capturing group as the path to the worker script. Default: /web-worker:(.+)/
extensions?: string[], // An array of strings to use as extensions when resolving worker files.
// Default: ['.js']
sourcemap?: boolean, // When inlined, should a source map be included in the final output. Default: false
inline?: boolean, // Should the worker code be inlined (Base64). Default: true
forceInline?: boolean, // *EXPERIMENTAL* when inlined, forces the code to be included every time it is imported
// useful when using code splitting: Default: false
external?: string[], // *EXPERIMENTAL* override rollup resolution of external module IDs
// useful to inline external dependencies in a worker blob. Default: undefined
preserveSource?: boolean, // When inlined and this option is enabled, the full source code is included in the
// built file, otherwise it's embedded as a base64 string. Default: false
preserveFileNames?: boolean, // When code splitting is used (`inline === false`) the input worker file names are
// preserved, if duplicates are found `-n` is appended to the file names.
// Default: false
enableUnicodeSupport?: boolean, // When inlined in Base64 format, this option enables unicode support (UTF16). This
// flag is disabled by default because supporting UTF16 doubles the size of the final
// payload. Default: false
outputFolder?: string, // When code splitting is used (`inline: false`), folder in which the worker scripts
// should be written to. Default: '' (same as build output folder)
loadPath?: string, // This option is useful when the worker scripts need to be loaded from another folder.
// Default: ''
plugins?: Array, // An array of extra plugins to use while compiling the worker code. Used to apply
// transformations to the worker code and not the main code (i.e. minify)
// NOTE: these plugins be added to the rollop process on top of the plugins in the
// default configuration.
// Default: []
skipPlugins?: Array, // Plugin names to skip for web worker build
// Default: [ 'liveServer', 'serve', 'livereload' ]
})
TypeScript
An example project that uses this plugin with TypeScript can be found here
Notes
WARNING: To use code-splitting for the worker scripts, Rollup v1.9.2 or higher is required. See https://github.com/rollup/rollup/issues/2801 for more details.
The sourcemap
configuration option is ignored when inline
is set to false
, in that case the project's sourcemap configuration is inherited.
loadPath
is meant to be used in situations where code-splitting is used (inline = false
) and the entry script is hosted in a different folder than the worker code.
Setting targetPlatform
to 'base64'
will ignore the inline
option and will always inline the resulting code.
Roadmap
- [x] Bundle file as web worker blob
- [x] Support for dependencies using
import
- [x] Include source map
- [x] Configuration options to inline or code-split workers
- [ ] ~~Provide capability checks and fallbacks~~ DROPPED (all modern environments support workers)
- [ ] ~~Avoid code duplication~~ DROPPED (there are better solutions for this purpose)