Package and Module Configuration in LWR on Node.js
Do you want to add dependencies to your project? What about customizing LWR’s module support? Read on to discover how.
You can also check out the Configure Your Project page for other configuration options.
Your initial project’s package.json file looks something like this, with both the lwr and the lwc packages included as dependencies:
LWR projects are standard npm packages, so you can add other project dependencies with typical package manager toolchains such as npm or Yarn. (The examples that follow use npm, but the general guidance applies equally.)
For example, to add a package dependency you could use:
And then add the import to your component source code, and you’d be done:
If you want to add an LWC package dependency to your project, that requires one more step. Read on for details.
To add an LWC package as a dependency to your project is only slightly more complicated than the general case.
LWC packages are Lightning web components that someone else created and made distributable for reuse. If you’re curious about including an LWC package in your project, search the npm package registry for “LWC” or “Lightning Web Components” and discover what’s on offer. If you're interested in distributing your own Lightning web components, check out Package and Distribute LWC OSS Components (video) or Distribute Your Component Using npm.
As before, to add a package, you first add the dependency to your project using npm.
npm updates your project’s package.json file to include the lightning-base-components package dependency:
Next, for LWC you must also add a directory module record to your LWC configuration in lwr.config.json.
The LWC documentation has more details on how LWC module resolution works, as does this blog post.
The LWR server is based on a plugin model. In addition to the core LWR server, as a project owner you can also plug in new capabilities into the server using providers. With module provider plugins, you can customize LWR's module support by exposing different sources for available ES modules.
LWR provides a set of default module providers that support the common sources of modules, such as static filesystem modules or packaged LWCs. For example, the @lwrjs/app-service package has the module provider to bootstrap LWR web applications.
| Module Provider Plugin | Description |
|---|---|
| @lwrjs/lwc-module-provider | Support for filesystem-based LWC Modules exposed via LWC Module Resolution |
| @lwrjs/npm-module-provider | Support for Filesystem-based NPM Pkg exposed ES Modules |
| @lwrjs/app-service/moduleProvider | Support for LWR Application Bootstrap Component Modules |
You also have the option to include other, optional module providers. This flexibility keeps the runtime small for the simplest use cases while supporting extensibility for more complex applications. You could use an optional module provider for dynamic view generation modules, other @salesforce/ scoped modules, or 3rd-party generated module providers.
The @lwrjs/label-module-provider package is an example of an optional module provider that exposes the capability of scoped module labels (for example, @salesforce/label/*) support. If you want to support/consume these labels in your application, you can include it, but it's not required.
To add a module provider to your project, first, install the package as a dependency to your project using npm.
For example, to install the LWR Static Labels module provider:
Then add the module provider plugin to your lwr.config.json file:
Because the moduleProviders array overwrites the LWR defaults, when you use moduleProviders you must explicitly include the default module providers owned by LWR, as shown in the preceding example.
Your application components can now statically import labels sourced from JSON files in your project’s $rootDir/src/labels directory:
You can add module records to lwr.config.json from any of these sources:
- Alias module record: A file path where a module can be resolved.
- Directory module record: A folder path where modules can be resolved.
- npm package module record: An npm package that exposes one or more modules.
For example:
The order of the array matters. LWR iterates through the modules array and uses the first module that matches the requested module specifier.