Authoring Libraries | webpack

Aside from applications, webpack can also be used to bundle JavaScript libraries. The following guide is meant for library authors looking to streamline their bundling strategy.
Let's assume that we are writing a small library, webpack-numbers, that allows users to convert the numbers 1 through 5 from their numeric representation to a textual one and vice-versa, e.g. 2 to 'two'.
The basic project structure would look like this:
Initialize the project with npm, then install webpack, webpack-cli, and lodash as development dependencies:
We install lodash as a devDependency because we will initially bundle it into our library. Since it is included in the final output, consumers of our library won't need to install it themselves.
Let's start with this basic webpack configuration:
In the above example, we're telling webpack to bundle src/index.js into dist/webpack-numbers.js.
When bundling a library, it is recommended to generate source maps. Source maps allow consumers of your library to debug your original source code rather than the minified bundle. This can be done using the devtool option:
Using 'source-map' as the devtool value generates a separate .map file alongside your bundle. Make sure to also publish this .map file so consumers can use it for debugging.
So far everything should be the same as bundling an application, and here comes the different part – we need to expose exports from the entry point through output.library option.
We exposed the entry point as webpackNumbers so users can use it through script tag:
However it only works when it's referenced through script tag, it can't be used in other environments like CommonJS, AMD, Node.js, etc.
As a library author, we want it to be compatible in different environments, i.e., users should be able to consume the bundled library in multiple ways listed below:
CommonJS module require:
Let's update the output.library option with its type set to 'umd':
Now webpack will bundle a library that can work with CommonJS, AMD, and script tag.
Note that the library setup is tied to the entry configuration. For most libraries, specifying a single entry point is sufficient. While multi-part libraries are possible, it is more straightforward to expose partial exports through an index script that serves as a single entry point. Using an array as an entry point for a library is not recommended.
Now, if you run npx webpack, you will find that a largish bundle is created. If you inspect the file, you'll see that lodash has been bundled along with your code. To avoid bundling lodash and bloating our library, we can configure webpack to treat it as an external module. Since we are no longer bundling it, the consumer will need to provide it. Therefore, you should move lodash from devDependencies to dependencies (or peerDependencies) so package managers will install it automatically for consumers of your library.
This can be done using the externals configuration:
This means that your library expects a dependency named lodash to be available in the consumer's environment.
For libraries that use several files from a dependency:
You won't be able to exclude them from the bundle by specifying library in the externals. You'll either need to exclude them one by one or by using a regular expression.
Optimize your output for production by following the steps mentioned in the production guide. Let's also add the path to your generated bundle as the package's main field in with the package.json
Or, to add it as a standard module as per this guide:
The key main refers to the standard from package.json, and module to a proposal to allow the JavaScript ecosystem upgrade to use ES2015 modules without breaking backwards compatibility.
The module property should point to a script that utilizes ES2015 module syntax but no other syntax features that aren't yet supported by browsers or node. This enables webpack to parse the module syntax itself, allowing for lighter bundles via tree shaking if users are only consuming certain parts of the library.
Now you can publish it as an npm package and find it at unpkg.com to distribute it to your users.
To expose stylesheets associated with your library, import the CSS from your entry and let webpack's built-in CSS support extract it — the emitted .css file is named by output.cssFilename, and users consume and load it as they would any other stylesheet.
Copyright OpenJS Foundation and webpack contributors. All rights reserved. The OpenJS Foundation has registered trademarks and uses trademarks. For a list of trademarks of the OpenJS Foundation, please see our Trademark Policy and Trademark List. Trademarks and logos not indicated on the list of OpenJS Foundation trademarks are trademarks™ or registered® trademarks of their respective holders. Use of them does not imply any affiliation with or endorsement by them.
The OpenJS Foundation | Terms of Use | Privacy Policy | Bylaws | Code of Conduct | Trademark Policy | Trademark List | Cookie Policy