Add debug output format

Author: andrewiggins

CLAUDE.md

@@ -80,6 +80,7 @@ npm run jest -- test/index.test.js
 - **cjs** - CommonJS for Node.js
 - **umd** - Universal Module Definition for CDNs and older environments
 - **iife** - Immediately Invoked Function Expression
+- **debug** - Unminified modern ES2017+ build for debugging (automatically included when `debug` field exists in package.json)
 
 ### Key Subdirectories
 
@@ -126,6 +127,14 @@ npm run jest -- test/index.test.js
 - Only works with es/modern formats
 - Enable with --workers flag
 
+**Debug Format** (src/index.js:109-112, 326, 391, 607-608):
+
+- Automatically included when `debug` field is present in package.json
+- Uses modern ES2017+ compilation (same as modern format)
+- Skips Terser compression/minification for readable debugging output
+- Preserves variable names, whitespace, and code structure
+- Output file specified by `debug` field (e.g., `"debug": "dist/my-lib.debug.js"`)
+
 ### Testing Structure
 
 - **test/index.test.js** - Main test suite

README.md

@@ -14,6 +14,7 @@
   <a href="#setup">Setup</a> ✯
   <a href="#formats">Formats</a> ✯
   <a href="#modern">Modern Mode</a> ✯
+  <a href="#debug">Debug Mode</a> ✯
   <a href="#usage">Usage &amp; Configuration</a> ✯
   <a href="#options">All Options</a>
 </p>
@@ -144,6 +145,36 @@ The `"exports"` field can also be an object for packages with multiple entry mod
 }
 ```
 
+## 🐛 Debug Mode <a name="debug"></a>
+
+Microbundle can generate an **unminified debug build** to help with debugging your library. This is useful when you need to step through your bundled code or investigate issues in production builds.
+
+To enable debug mode, simply add a `"debug"` field to your `package.json`:
+
+```jsonc
+{
+	"name": "foo",
+	"source": "src/index.js",
+	"main": "./dist/foo.js",
+	"module": "./dist/foo.module.js",
+	"debug": "./dist/foo.debug.js", // 👈 Add this field
+	"scripts": {
+		"build": "microbundle"
+	}
+}
+```
+
+When the `debug` field is present, Microbundle will automatically generate an additional unminified bundle with:
+
+- **Modern ES2017+ syntax** (same as the `modern` format - async/await, arrow functions, etc.)
+- **No minification** - readable code with preserved variable names
+- **Preserved comments** - your code comments remain in the output
+- **Proper formatting** - whitespace and indentation maintained
+
+This makes it much easier to debug issues in your library code without needing to map back through source maps.
+
+> 💡 **Tip**: The debug build is automatically included when the `debug` field exists - no need to modify the `--format` flag.
+
 ## 📦 Usage & Configuration <a name="usage"></a>
 
 Microbundle includes two commands - `build` (the default) and `watch`.
@@ -172,7 +203,8 @@ The filenames and paths for generated bundles in each format are defined by the
     "require": "./dist/foo.js",         // CommonJS output bundle
     "default": "./dist/foo.modern.mjs", // Modern ES Modules output bundle
   },
-  "types": "dist/foo.d.ts"              // TypeScript typings
+  "types": "dist/foo.d.ts",             // TypeScript typings
+	"debug": "dist/foo.debug.js"          // Unminified modern bundle for debugging (optional)
 }
 ```
 

src/index.js

@@ -105,6 +105,12 @@ export default async function microbundle(inputOptions) {
 	let formats = (options.format || options.formats).split(',');
 	// de-dupe formats and convert "esm" to "es":
 	formats = Array.from(new Set(formats.map(f => (f === 'esm' ? 'es' : f))));
+
+	// add debug format if pkg.debug is present and not already in the list:
+	if (options.pkg.debug && !formats.includes('debug')) {
+		formats.push('debug');
+	}
+
 	// always compile cjs first if it's there:
 	formats.sort((a, b) => (a === 'cjs' ? -1 : a > b ? 1 : 0));
 
@@ -317,6 +323,7 @@ function getMain({ options, entry, format }) {
 		pkg['umd:main'] || pkg.unpkg || 'x.umd.js',
 		mainNoExtension,
 	);
+	mainsByFormat.debug = replaceName(pkg.debug || 'x.debug.js', mainNoExtension);
 
 	return mainsByFormat[format] || mainsByFormat.cjs;
 }
@@ -378,7 +385,7 @@ function createConfig(options, entry, format, writeMeta) {
 		);
 	}
 
-	const modern = format === 'modern';
+	const modern = format === 'modern' || format === 'debug';
 
 	// let rollupName = safeVariableName(basename(entry).replace(/\.js$/, ''));
 
@@ -586,62 +593,63 @@ function createConfig(options, entry, format, writeMeta) {
 						custom: {
 							defines,
 							modern,
-							compress: options.compress !== false,
+							compress: options.compress !== false && format !== 'debug',
 							targets: options.target === 'node' ? { node: '12' } : undefined,
 							pragma: options.jsx,
 							pragmaFrag: options.jsxFragment,
 							typescript: !!useTypescript,
 							jsxImportSource: options.jsxImportSource || false,
 						},
 					}),
-					options.compress !== false && [
-						terser({
-							compress: Object.assign(
-								{
-									keep_infinity: true,
-									pure_getters: true,
-									// Ideally we'd just get Terser to respect existing Arrow functions...
-									// unsafe_arrows: true,
-									passes: 10,
+					options.compress !== false &&
+						format !== 'debug' && [
+							terser({
+								compress: Object.assign(
+									{
+										keep_infinity: true,
+										pure_getters: true,
+										// Ideally we'd just get Terser to respect existing Arrow functions...
+										// unsafe_arrows: true,
+										passes: 10,
+									},
+									typeof minifyOptions.compress === 'boolean'
+										? minifyOptions.compress
+										: minifyOptions.compress || {},
+								),
+								format: {
+									// By default, Terser wraps function arguments in extra parens to trigger eager parsing.
+									// Whether this is a good idea is way too specific to guess, so we optimize for size by default:
+									wrap_func_args: false,
+									comments: /^\s*([@#]__[A-Z]+__\s*$|@cc_on)/,
+									preserve_annotations: true,
+								},
+								module: modern,
+								ecma: modern ? 2017 : 5,
+								toplevel: modern || format === 'cjs' || format === 'es',
+								mangle:
+									typeof minifyOptions.mangle === 'boolean'
+										? minifyOptions.mangle
+										: Object.assign({}, minifyOptions.mangle || {}),
+								nameCache,
+							}),
+							nameCache && {
+								// before hook
+								options: loadNameCache,
+								// after hook
+								writeBundle() {
+									if (writeMeta && nameCache) {
+										let filename = getNameCachePath();
+										let json = JSON.stringify(
+											nameCache,
+											null,
+											nameCacheIndentTabs ? '\t' : 2,
+										);
+										if (endsWithNewLine) json += EOL;
+										fs.writeFile(filename, json, () => {});
+									}
 								},
-								typeof minifyOptions.compress === 'boolean'
-									? minifyOptions.compress
-									: minifyOptions.compress || {},
-							),
-							format: {
-								// By default, Terser wraps function arguments in extra parens to trigger eager parsing.
-								// Whether this is a good idea is way too specific to guess, so we optimize for size by default:
-								wrap_func_args: false,
-								comments: /^\s*([@#]__[A-Z]+__\s*$|@cc_on)/,
-								preserve_annotations: true,
-							},
-							module: modern,
-							ecma: modern ? 2017 : 5,
-							toplevel: modern || format === 'cjs' || format === 'es',
-							mangle:
-								typeof minifyOptions.mangle === 'boolean'
-									? minifyOptions.mangle
-									: Object.assign({}, minifyOptions.mangle || {}),
-							nameCache,
-						}),
-						nameCache && {
-							// before hook
-							options: loadNameCache,
-							// after hook
-							writeBundle() {
-								if (writeMeta && nameCache) {
-									let filename = getNameCachePath();
-									let json = JSON.stringify(
-										nameCache,
-										null,
-										nameCacheIndentTabs ? '\t' : 2,
-									);
-									if (endsWithNewLine) json += EOL;
-									fs.writeFile(filename, json, () => {});
-								}
 							},
-						},
-					],
+						],
 					options.visualize && visualizer(),
 					// NOTE: OMT only works with amd and esm
 					// Source: https://github.com/surma/rollup-plugin-off-main-thread#config

src/prog.js

@@ -34,7 +34,7 @@ export default handler => {
 		.option('--output, -o', 'Directory to place build files into')
 		.option(
 			'--format, -f',
-			`Only build specified formats (any of ${DEFAULT_FORMATS} or iife)`,
+			`Only build specified formats (any of ${DEFAULT_FORMATS}, debug, or iife)`,
 			DEFAULT_FORMATS,
 		)
 		.option('--watch, -w', 'Rebuilds on any change', false)

test/__snapshots__/index.test.js.snap

@@ -1723,6 +1723,91 @@ exports[`fixtures build custom-source-with-cwd with microbundle 5`] = `
 "
 `;
 
+exports[`fixtures build debug with microbundle 1`] = `
+"Used script: microbundle
+
+Directory tree:
+
+debug
+  dist
+    debug-lib.debug.js
+    debug-lib.debug.js.map
+    debug-lib.esm.mjs
+    debug-lib.esm.mjs.map
+    debug-lib.js
+    debug-lib.js.map
+    debug-lib.umd.js
+    debug-lib.umd.js.map
+  package.json
+  src
+    index.js
+
+
+Build \\"debug-lib\\" to dist:
+328 B: debug-lib.js.gz
+275 B: debug-lib.js.br
+332 B: debug-lib.esm.mjs.gz
+279 B: debug-lib.esm.mjs.br
+415 B: debug-lib.umd.js.gz
+343 B: debug-lib.umd.js.br
+385 B: debug-lib.debug.js.gz
+320 B: debug-lib.debug.js.br"
+`;
+
+exports[`fixtures build debug with microbundle 2`] = `8`;
+
+exports[`fixtures build debug with microbundle 3`] = `
+"// Test debug format with meaningful variable names and modern syntax
+async function fetchUserData(userId) {
+  const response = await fetch(\`/api/users/\${userId}\`);
+  const userData = await response.json();
+  return userData;
+}
+const createGreeting = (name, age) => {
+  const greeting = \`Hello, \${name}! You are \${age} years old.\`;
+  return greeting;
+};
+class UserManager {
+  constructor(initialUsers = []) {
+    this.users = initialUsers;
+    this.count = initialUsers.length;
+  }
+
+  addUser(user) {
+    this.users.push(user);
+    this.count++;
+  }
+
+  async loadUsers() {
+    const allUsers = await Promise.all(this.users.map(u => fetchUserData(u.id)));
+    return allUsers;
+  }
+
+}
+
+export { UserManager, createGreeting, fetchUserData };
+//# sourceMappingURL=debug-lib.debug.js.map
+"
+`;
+
+exports[`fixtures build debug with microbundle 4`] = `
+"var r=function(r){try{return Promise.resolve(fetch(\\"/api/users/\\"+r)).then(function(r){return Promise.resolve(r.json())})}catch(r){return Promise.reject(r)}},e=function(r,e){return\\"Hello, \\"+r+\\"! You are \\"+e+\\" years old.\\"},t=/*#__PURE__*/function(){function e(r){void 0===r&&(r=[]),this.users=r,this.count=r.length}var t=e.prototype;return t.addUser=function(r){this.users.push(r),this.count++},t.loadUsers=function(){try{return Promise.resolve(Promise.all(this.users.map(function(e){return r(e.id)})))}catch(r){return Promise.reject(r)}},e}();export{t as UserManager,e as createGreeting,r as fetchUserData};
+//# sourceMappingURL=debug-lib.esm.mjs.map
+"
+`;
+
+exports[`fixtures build debug with microbundle 5`] = `
+"var e=function(e){try{return Promise.resolve(fetch(\\"/api/users/\\"+e)).then(function(e){return Promise.resolve(e.json())})}catch(e){return Promise.reject(e)}};exports.UserManager=/*#__PURE__*/function(){function r(e){void 0===e&&(e=[]),this.users=e,this.count=e.length}var t=r.prototype;return t.addUser=function(e){this.users.push(e),this.count++},t.loadUsers=function(){try{return Promise.resolve(Promise.all(this.users.map(function(r){return e(r.id)})))}catch(e){return Promise.reject(e)}},r}(),exports.createGreeting=function(e,r){return\\"Hello, \\"+e+\\"! You are \\"+r+\\" years old.\\"},exports.fetchUserData=e;
+//# sourceMappingURL=debug-lib.js.map
+"
+`;
+
+exports[`fixtures build debug with microbundle 6`] = `
+"!function(e,t){\\"object\\"==typeof exports&&\\"undefined\\"!=typeof module?t(exports):\\"function\\"==typeof define&&define.amd?define([\\"exports\\"],t):t((e||self).debugLib={})}(this,function(e){var t=function(e){try{return Promise.resolve(fetch(\\"/api/users/\\"+e)).then(function(e){return Promise.resolve(e.json())})}catch(e){return Promise.reject(e)}};e.UserManager=/*#__PURE__*/function(){function e(e){void 0===e&&(e=[]),this.users=e,this.count=e.length}var r=e.prototype;return r.addUser=function(e){this.users.push(e),this.count++},r.loadUsers=function(){try{return Promise.resolve(Promise.all(this.users.map(function(e){return t(e.id)})))}catch(e){return Promise.reject(e)}},e}(),e.createGreeting=function(e,t){return\\"Hello, \\"+e+\\"! You are \\"+t+\\" years old.\\"},e.fetchUserData=t});
+//# sourceMappingURL=debug-lib.umd.js.map
+"
+`;
+
 exports[`fixtures build default-named with microbundle 1`] = `
 "Used script: microbundle
 

test/fixtures/debug/package.json

@@ -0,0 +1,7 @@
+{
+	"name": "debug-lib",
+	"debug": "dist/debug-lib.debug.js",
+	"scripts": {
+		"build": "microbundle"
+	}
+}

test/fixtures/debug/src/index.js

@@ -0,0 +1,30 @@
+// Test debug format with meaningful variable names and modern syntax
+export async function fetchUserData(userId) {
+	const response = await fetch(`/api/users/${userId}`);
+	const userData = await response.json();
+	return userData;
+}
+
+export const createGreeting = (name, age) => {
+	const greeting = `Hello, ${name}! You are ${age} years old.`;
+	return greeting;
+};
+
+export class UserManager {
+	constructor(initialUsers = []) {
+		this.users = initialUsers;
+		this.count = initialUsers.length;
+	}
+
+	addUser(user) {
+		this.users.push(user);
+		this.count++;
+	}
+
+	async loadUsers() {
+		const allUsers = await Promise.all(
+			this.users.map(u => fetchUserData(u.id)),
+		);
+		return allUsers;
+	}
+}