pull code

.github/workflows/ci.yml

@@ -53,6 +53,12 @@ jobs:
     - name: JS API Tests
       run: node scripts/js-api-tests.js
 
+    - name: Plugin Tests
+      run: node scripts/plugin-tests.js
+
+    - name: TypeScript Type Definition Tests
+      run: node scripts/ts-type-tests.js
+
     - name: Sucrase Tests
       if: matrix.os == 'ubuntu-latest'
       run: make test-sucrase

CHANGELOG.md

@@ -1,5 +1,120 @@
 # Changelog
 
+## 0.8.2
+
+* Fix the omission of `outbase` in the JavaScript API ([#471](https://github.com/evanw/esbuild/pull/471))
+
+    The original PR for the `outbase` setting added it to the CLI and Go APIs but not the JavaScript API. This release adds it to the JavaScript API too.
+
+* Fix the TypeScript type definitions ([#499](https://github.com/evanw/esbuild/pull/499))
+
+    The newly-released `plugins` option in the TypeScript type definitions was incorrectly marked as non-optional. It is now optional. This fix was contributed by [@remorses](https://github.com/remorses).
+
+## 0.8.1
+
+* The initial version of the plugin API ([#111](https://github.com/evanw/esbuild/pull/111))
+
+    The plugin API lets you inject custom code inside esbuild's build process. You can write plugins in either JavaScript or Go. Right now you can add an "on resolve" callback to determine where import paths go and an "on load" callback to determine what the imported file contains. These two primitives are very powerful, especially in combination with each other.
+
+    Here's a simple example plugin to show off the API in action. Let's say you wanted to enable a workflow where you can import environment variables like this:
+
+    ```js
+    // app.js
+    import { NODE_ENV } from 'env'
+    console.log(`NODE_ENV is ${NODE_ENV}`)
+    ```
+
+    This is how you might do that from JavaScript:
+
+    ```js
+    let envPlugin = {
+      name: 'env-plugin',
+      setup(build) {
+        build.onResolve({ filter: /^env$/ }, args => ({
+          path: args.path,
+          namespace: 'env',
+        }))
+
+        build.onLoad({ filter: /.*/, namespace: 'env' }, () => ({
+          contents: JSON.stringify(process.env),
+          loader: 'json',
+        }))
+      },
+    }
+
+    require('esbuild').build({
+      entryPoints: ['app.js'],
+      bundle: true,
+      outfile: 'out.js',
+      plugins: [envPlugin],
+      logLevel: 'info',
+    }).catch(() => process.exit(1))
+    ```
+
+    This is how you might do that from Go:
+
+    ```go
+    package main
+
+    import (
+      "encoding/json"
+      "os"
+      "strings"
+
+      "github.com/evanw/esbuild/pkg/api"
+    )
+
+    var envPlugin = api.Plugin{
+      Name: "env-plugin",
+      Setup: func(build api.PluginBuild) {
+        build.OnResolve(api.OnResolveOptions{Filter: `^env$`},
+          func(args api.OnResolveArgs) (api.OnResolveResult, error) {
+            return api.OnResolveResult{
+              Path: args.Path,
+              Namespace: "env",
+            }, nil
+          })
+
+        build.OnLoad(api.OnLoadOptions{Filter: `.*`, Namespace: "env"},
+          func(args api.OnLoadArgs) (api.OnLoadResult, error) {
+            mappings := make(map[string]string)
+            for _, item := range os.Environ() {
+              if equals := strings.IndexByte(item, '='); equals != -1 {
+                mappings[item[:equals]] = item[equals+1:]
+              }
+            }
+            bytes, _ := json.Marshal(mappings)
+            contents := string(bytes)
+            return api.OnLoadResult{
+              Contents: &contents,
+              Loader: api.LoaderJSON,
+            }, nil
+          })
+      },
+    }
+
+    func main() {
+      result := api.Build(api.BuildOptions{
+        EntryPoints: []string{"app.js"},
+        Bundle:      true,
+        Outfile:     "out.js",
+        Plugins:     []api.Plugin{envPlugin},
+        Write:       true,
+        LogLevel:    api.LogLevelInfo,
+      })
+
+      if len(result.Errors) > 0 {
+        os.Exit(1)
+      }
+    }
+    ```
+
+    Comprehensive documentation for the plugin API is not yet available but is coming soon.
+
+* Add the `outbase` option ([#471](https://github.com/evanw/esbuild/pull/471))
+
+    Currently, esbuild uses the lowest common ancestor of the entrypoints to determine where to place each entrypoint's output file. This is an excellent default, but is not ideal in some situations. Take for example an app with a folder structure similar to Next.js, with js files at `pages/a/b/c.js` and `pages/a/b/d.js`. These two files correspond to the paths `/a/b/c` and `/a/b/d`. Ideally, esbuild would emit `out/a/b/c.js` and `out/a/b/d.js`. However, esbuild identifies `pages/a/b` as the lowest common ancestor and emits `out/c.js` and `out/d.js`. This release introduces an `--outbase` argument to the cli that allows the user to choose which path to base entrypoint output paths on. With this change, running esbuild with `--outbase=pages` results in the desired behavior. This change was contributed by [@nitsky](https://github.com/nitsky).
+
 ## 0.8.0
 
 **This release contains backwards-incompatible changes.** Since esbuild is before version 1.0.0, these changes have been released as a new minor version to reflect this (as [recommended by npm](https://docs.npmjs.com/misc/semver)). You should either be pinning the exact version of `esbuild` in your `package.json` file or be using a version range syntax that only accepts patch upgrades such as `^0.7.0`. See the documentation about [semver](https://docs.npmjs.com/misc/semver) for more information.

Makefile

@@ -11,11 +11,11 @@ npm/esbuild-wasm/wasm_exec.js:
 
 # These tests are for development
 test:
-	make -j5 test-go vet-go verify-source-map end-to-end-tests js-api-tests
+	make -j6 test-go vet-go verify-source-map end-to-end-tests js-api-tests plugin-tests ts-type-tests
 
 # These tests are for release ("test-wasm" is not included in "test" because it's pretty slow)
 test-all:
-	make -j6 test-go vet-go verify-source-map end-to-end-tests js-api-tests test-wasm
+	make -j7 test-go vet-go verify-source-map end-to-end-tests js-api-tests plugin-tests ts-type-tests test-wasm
 
 # This includes tests of some 3rd-party libraries, which can be very slow
 test-extra: test-all test-preact-splitting test-sucrase bench-rome-esbuild test-esprima test-rollup
@@ -44,6 +44,12 @@ js-api-tests: cmd/esbuild/version.go | scripts/node_modules
 	cd npm/esbuild && npm version "$(ESBUILD_VERSION)" --allow-same-version
 	node scripts/js-api-tests.js
 
+plugin-tests: cmd/esbuild/version.go | scripts/node_modules
+	node scripts/plugin-tests.js
+
+ts-type-tests: | scripts/node_modules
+	node scripts/ts-type-tests.js
+
 cmd/esbuild/version.go: version.txt
 	node -e 'console.log(`package main\n\nconst esbuildVersion = "$(ESBUILD_VERSION)"`)' > cmd/esbuild/version.go
 

cmd/esbuild/main.go

@@ -46,6 +46,8 @@ Options:
 
 Advanced options:
   --version                 Print the current version and exit (` + esbuildVersion + `)
+  --outbase=...             The base path used to determine entry point output
+                            paths (for multiple entry points)
   --sourcemap=inline        Emit the source map with an inline data URL
   --sourcemap=external      Do not link to the source map with a comment
   --sourcefile=...          Set the source file for the source map (for stdin)