The browser field is provided by a module author as a hint to javascript bundlers or component tools when preparing modules for client side us.
Below are common terms used in the rest of the document
This is a non-dom based javascript execution environment. It usually only contains the base javascript language spec libraries and objects along with modules to communicate with OS features (available through commonjs require).
This is a browser execution environment. It may provide additional built in objects exposed in the global namespace. It is a specialized execution environment which provides builtin capabilities beyond the base javascript language spec.
A require system for specifying which modules or files a particular file uses.
A tool which takes a plain javascript package and creates client usable files. It may include, but is not limited to: replacing modules or files with client versions (since the client may already provide the functionality), merging all the dependencies into a single file, etc.
Metadata information about a module.
The use of a bundler to create a file(s) suitable for running on a client.
When a javascript module is prepared for use on a client there are two major concerns: certain features are already provided by the client, and certain features are not available. Features provided by a client can include http requests, websockets, dom manipulation. Features not available would include tcp sockets, system disk IO.
The browser field is where the module author can hint to the bundler which elements (other modules or source files) need to be replaced when packaging.
When you specify a single string for the browser field, it will replace main and be the module entry point.
"browser": "./browser/specific/main.js"Whenever another module requires your module by name, the bundler will load javascript from ./browser/specific/main.js instead of the typical main field entry point (or index.js by default).
In many cases, there is a large amount of code which is applicable to both client and server. If is easier to just replace some files instead of craeting a completely new entry point. To do this, just specify an object versus a single string.
When using an object. The left hand side (key) is the name of a module or file you wish to replace and the right side is the replacement.
"browser": {
"module-a": "./shims/module-a.js",
"./server/only.js": "./shims/server-only.js"
}Now when you package your code, uses of module-a will be replaced with code from ./shims/module-a.js versus the module code itself and anytime ./server/only.js is used, it will be replaced with ./shims/server-only.js
If a module you depend on already includes a browser field, then you don't have to do anything special. Whenever you require that module, the bundler SHOULD use the hint provided by the module. The ws module is an example of this behavior.
Using the browser field in package.json allows a module author to clearly articulate which files are innapropriate for client use and provide alternatives. It allows the module code (and subsequently dependants on the module) to not use preprocessor hacks, source code changes, or runtime detection hacks to identify which code is appropriate when creating a client bound package.
- If your module is pure javascript and can run in both client and server environments, then you do not need a browser field.
- The
browserfield is located in thepackage.jsonfile as it provides metadata in the form of a hint to bundlers about what files you have indicated are targeted for the client. It allows your source code to remain clean and free of hacks. - Consider that the client environment as the special case as it exposes objects into the global space to provide certain features and limits others.