fix #140: add "--metafile" for JSON metadata

CHANGELOG.md

@@ -2,6 +2,35 @@
 
 ## Unreleased
 
+* Add the `--metafile` flag ([#140](https://github.com/evanw/esbuild/issues/140))
+
+    Pass `--metafile=meta.json` to write metadata about the build to the file `meta.json`. This includes information such as which files are in the bundle, what other files a given file depends on, and how much of each file ended up in the bundle. This is similar to the [stats option in Webpack](https://webpack.js.org/api/stats/).
+
+    The format looks like this:
+
+    ```ts
+    interface Metadata {
+      inputs: {
+        [path: string]: {
+          bytes: number
+          imports: {
+            path: string
+          }[]
+        }
+      }
+      outputs: {
+        [path: string]: {
+          bytes: number
+          inputs: {
+            [path: string]: {
+              bytesInOutput: number
+            }
+          }
+        }
+      }
+    }
+    ```
+
 * Shorten numeric literals ([#122](https://github.com/evanw/esbuild/issues/122))
 
     Certain numeric literals now use shorter representations in the generated JavaScript code. For example, `123400000` is now written out as `1234e5`.

README.md

@@ -248,6 +248,7 @@ Advanced options:
   --error-limit=...         Maximum error count or 0 to disable (default 10)
   --log-level=...           Disable logging (info, warning, error)
   --resolve-extensions=...  A comma-separated list of implicit extensions
+  --metafile=...            Write metadata about the build to a JSON file
 
   --trace=...           Write a CPU trace to this file
   --cpuprofile=...      Write a CPU profile to this file

cmd/esbuild/main.go

@@ -56,6 +56,7 @@ Advanced options:
   --error-limit=...         Maximum error count or 0 to disable (default 10)
   --log-level=...           Disable logging (info, warning, error)
   --resolve-extensions=...  A comma-separated list of implicit extensions
+  --metafile=...            Write metadata about the build to a JSON file
 
   --trace=...           Write a CPU trace to this file
   --cpuprofile=...      Write a CPU profile to this file
@@ -268,6 +269,14 @@ func parseArgs(fs fs.FS, rawArgs []string) (argsObject, error) {
 			}
 			args.bundleOptions.ModuleName = value
 
+		case strings.HasPrefix(arg, "--metafile="):
+			value := arg[len("--metafile="):]
+			file, ok := fs.Abs(value)
+			if !ok {
+				return argsObject{}, fmt.Errorf("Invalid metadata file: %s", arg)
+			}
+			args.bundleOptions.AbsMetadataFile = file
+
 		case strings.HasPrefix(arg, "--outfile="):
 			value := arg[len("--outfile="):]
 			file, ok := fs.Abs(value)
@@ -498,6 +507,9 @@ func parseArgs(fs fs.FS, rawArgs []string) (argsObject, error) {
 		if args.logOptions.LogLevel == logging.LevelNone {
 			args.logOptions.LogLevel = logging.LevelWarning
 		}
+		if args.bundleOptions.AbsMetadataFile != "" {
+			return argsObject{}, fmt.Errorf("Cannot generate metadata when writing to stdout")
+		}
 
 		// Forbid the "file" loader since stdout only allows one output file
 		for _, loader := range args.bundleOptions.ExtensionToLoader {