Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add notes about separate unbundled bundles for ESbuild #1348

Merged
merged 2 commits into from
Jul 15, 2024
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
32 changes: 30 additions & 2 deletions packages/lit-dev-content/site/docs/v3/ssr/authoring.md
Original file line number Diff line number Diff line change
Expand Up @@ -42,16 +42,44 @@ if (isServer) {
}
```

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.
### Conditional exports

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.

An example configuration might look like below:
```json
// package.json
{
"name": "my-awesome-lit-components",
"exports": {
"./button.js": {
"node": "./button-node.js",
"default": "./button.js"
}
}
}
```

The Node entrypoint file can be made manually, or you might use a bundler to generate those.

### Bundlers

{% aside "warn" %}

Don't bundle Lit into published components.
Avoid bundling Lit inline into published components if possible.

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.

{% endaside %}

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.

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.

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.

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.

## Lifecycle

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.
Expand Down
Loading