Skip to content

Commit bafbf70

Browse files
Add notes about separate bundles (#1348)
--------- Co-authored-by: Augustine Kim <[email protected]>
1 parent 5eaf63b commit bafbf70

File tree

1 file changed

+30
-2
lines changed

1 file changed

+30
-2
lines changed

packages/lit-dev-content/site/docs/v3/ssr/authoring.md

Lines changed: 30 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -42,16 +42,44 @@ if (isServer) {
4242
}
4343
```
4444
45-
For more complex uses cases, consider utilizing [conditional exports](https://nodejs.org/api/packages.html#conditional-exports) in Node that specifically match for `"node"` environments so you could have different code depending on whether the module is being imported for use in Node or in the browser. Users would get the appropriate version of the package depending on whether it was imported from Node or the browser. Export conditions are also supported by popular bundling tools like [rollup](https://github.com/rollup/plugins/tree/master/packages/node-resolve#exportconditions) and [webpack](https://webpack.js.org/configuration/resolve/#resolveconditionnames) so users can bring in the appropriate code for your bundle.
45+
### Conditional exports
46+
47+
For more complex uses cases, consider utilizing [conditional exports](https://nodejs.org/api/packages.html#conditional-exports) that specifically match for `"node"` environments so you could have different code depending on whether the module is being imported for use in Node or in the browser. Users would get the appropriate version of the package depending on whether it was imported from Node or the browser. Export conditions are also supported by popular bundling tools like [rollup](https://github.com/rollup/plugins/tree/master/packages/node-resolve#exportconditions) and [webpack](https://webpack.js.org/configuration/resolve/#resolveconditionnames) so users can bring in the appropriate code for your bundle.
48+
49+
An example configuration might look like below:
50+
```json
51+
// package.json
52+
{
53+
"name": "my-awesome-lit-components",
54+
"exports": {
55+
"./button.js": {
56+
"node": "./button-node.js",
57+
"default": "./button.js"
58+
}
59+
}
60+
}
61+
```
62+
63+
The Node entrypoint file can be made manually, or you might use a bundler to generate those.
64+
65+
### Bundlers
4666
4767
{% aside "warn" %}
4868
49-
Don't bundle Lit into published components.
69+
Avoid bundling Lit inline into published components if possible.
5070
5171
Because Lit packages use conditional exports to provide different modules to Node and browser environments, we strongly discourage bundling `lit` into your packages being published to NPM. If you do, your bundle will only include `lit` modules meant for the environment you bundled, and won't automatically switch based on environment.
5272
5373
{% endaside %}
5474
75+
If you are using a bundler like ESBuild or Rollup to transform your code, you can mark packages as _external_ so they will not be bundled into your component. ESBuild has a [`packages`](https://esbuild.github.io/api/#packages) option to externalize all dependencies, or you can mark only `lit` and related packages in the [external](https://esbuild.github.io/api/#external) option. Similarly, Rollup also has an equivalent ["external"](https://rollupjs.org/configuration-options/#external) configuration option.
76+
77+
If you must bundle Lit library code into your component (e.g. for distribution via a CDN), we recommended creating two entrypoints: one for the browser, and one for Node. Bundlers will have options to either select a target platform like browser or Node, or allow you to explicitly specify the export condition used for resolving modules.
78+
79+
For example, ESBuild has the [`platform`](https://esbuild.github.io/api/#platform) option, and in Rollup you can provide `"node"` to `@rollup/plugin-node-resolve`'s [`exportConditions`](https://github.com/rollup/plugins/tree/master/packages/node-resolve#exportconditions) option.
80+
81+
These entrypoints for browser and Node targets must then be specified in your component library's `package.json` file. See [Conditional exports](#conditional-exports) for more details.
82+
5583
## Lifecycle
5684
5785
Only certain lifecycle callbacks are run during server-side rendering. These callback generate the initial styling and markup for the component. Additional lifecycle methods are called client-side during hydration and during runtime after the components are hydrated.

0 commit comments

Comments
 (0)