From 49fcf83c9c54933749a549d324002c93870dcc4f Mon Sep 17 00:00:00 2001 From: Konnor Rogers Date: Tue, 18 Feb 2025 17:01:19 -0500 Subject: [PATCH 1/2] Add notes of caution about `sideEffects` key in `package.json` Hi there! I stumbled on your guide today on Bluesky and noticed the note about "sideEffects". While it currently says its "needed", im here to provide some feedback on how `sideEffects` has burned me. Feel free to close, but heres a blog post I made with some links to various broken packages as a result of using the `sideEffects` key. https://www.konnorrogers.com/posts/2023/the-shoelace-side-effect-scavenger-hunt ( you can ignore everything after the linked github issues) --- README.md | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 269dd9e..16b3c2a 100644 --- a/README.md +++ b/README.md @@ -871,7 +871,12 @@ import 'ui-library/includes/button.js'; import 'ui-library/includes/alert.js'; ``` -The `package.json` needs to have a `sideEffects` property that explicitly lists all side effect files provided by the library package. This entry enables build tooling like Rollup and Webpack to optimize tree shaking while ensuring the side effects are included correctly in the final application bundle. +Some libraries such as Rollup or Webpack can optimize treeshaking of the above "side effects", by setting a `"sideEffects"` property in your `package.json`. While it can improve package size and dead code elimination, it also can sometimes cause the bundler to skip various optimizations and checks and wrongfully treeshake code that is actually used. It is error prone and difficult to keep up to date, and in some cases, you may not even realize you have sideEffects. All that to say, if you're going to use it, make sure you're properly testing it in various bundlers. + +More reading on sideEffects: + + + 🚧 **Warning**: Side effect isolation is required for [Scoped Element Registries](https://github.com/webcomponents/polyfills/tree/master/packages/scoped-custom-element-registry) From a5d9bae332836e6b82b69b1e9c835020aadac601 Mon Sep 17 00:00:00 2001 From: Konnor Rogers Date: Tue, 18 Feb 2025 19:12:04 -0500 Subject: [PATCH 2/2] Update README.md --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 16b3c2a..fcd68b2 100644 --- a/README.md +++ b/README.md @@ -871,7 +871,7 @@ import 'ui-library/includes/button.js'; import 'ui-library/includes/alert.js'; ``` -Some libraries such as Rollup or Webpack can optimize treeshaking of the above "side effects", by setting a `"sideEffects"` property in your `package.json`. While it can improve package size and dead code elimination, it also can sometimes cause the bundler to skip various optimizations and checks and wrongfully treeshake code that is actually used. It is error prone and difficult to keep up to date, and in some cases, you may not even realize you have sideEffects. All that to say, if you're going to use it, make sure you're properly testing it in various bundlers. +Some bundlers such as Rollup or Webpack can optimize treeshaking of the above "side effects", by setting a `"sideEffects"` property in your `package.json`. While it can improve package size and dead code elimination, it also can sometimes cause the bundler to skip various optimizations and checks and wrongfully treeshake code that is actually used. It is error prone and difficult to keep up to date, and in some cases, you may not even realize you have sideEffects. All that to say, if you're going to use it, make sure you're properly testing it in various bundlers. More reading on sideEffects: