release notes

CHANGELOG.md

@@ -57,6 +57,36 @@
 
     This fix was contributed by [@lbwa](https://github.com/lbwa).
 
+* Plugins can now specify `sideEffects: false` ([#1009](https://github.com/evanw/esbuild/issues/1009))
+
+    The default path resolution behavior in esbuild determines if a given file can be considered side-effect free (in the [Webpack-specific sense](https://webpack.js.org/guides/tree-shaking/#mark-the-file-as-side-effect-free)) by reading the contents of the nearest enclosing `package.json` file and looking for `"sideEffects": false`. However, up until now this was impossible to achieve in an esbuild plugin because there was no way of returning this metadata back to esbuild.
+
+    With this release, esbuild plugins can now return `sideEffects: false` to mark a file as having no side effects. Here's an example:
+
+    ```js
+    esbuild.build({
+      entryPoints: ['app.js'],
+      bundle: true,
+      plugins: [{
+        name: 'env-plugin',
+        setup(build) {
+          build.onResolve({ filter: /^env$/ }, args => ({
+            path: args.path,
+            namespace: 'some-ns',
+            sideEffects: false,
+          }))
+          build.onLoad({ filter: /.*/, namespace: 'some-ns' }, () => ({
+            contents: `export default self.env || (self.env = getEnv())`,
+          }))
+        },
+      }],
+    })
+    ```
+
+    This plugin creates a virtual module that can be generated by importing the string `env`. However, since the plugin returns `sideEffects: false`, the generated virtual module will not be included in the bundle if all of the imported values from the module `env` end up being unused.
+
+    This feature was contributed by [@chriscasola](https://github.com/chriscasola).
+
 ## 0.12.6
 
 * Improve template literal lowering transformation conformance ([#1327](https://github.com/evanw/esbuild/issues/1327))