quickbundle 1.2.0 → 2.1.0

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2021 Ayoub Adib
+Copyright (c) Ayoub Adib
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,7 +1,7 @@
 <br>
 <div align="center">
     <h1>📦 Quickbundle</h1>
-    <strong>The zero-configuration bundler powered by ESBuild</strong>
+    <strong>The zero-configuration transpiler and bundler for the web</strong>
 </div>
 <br>
 <br>
@@ -10,17 +10,16 @@
 
 Quickbundle allows you to bundle a library in a **quick**, **fast** and **easy** way:
 
--   Fast build and watch mode thanks to [esbuild](https://esbuild.github.io/)
--   Zero configuration: define the build artifacts in your `package.json` and you're all set!
--   Support of multiple module formats including `cjs` & `esm`
--   JavaScript, TypeScript, JSX, CSS, JSON, Image and Text support following [esbuild support](https://esbuild.github.io/content-types/)
--   TypeScript declaration file (`.d.ts`) generation with bundling support
--   Bundling can be done for several platform targets including `browser` or `node`
--   Optimized build with automatic dependency inclusion (`peerDependencies` and `dependencies` are not bundled in the final output)
+-   Fast build and watch mode powered by [Rollup module bundler](https://rollupjs.org/) and [SWC transpiler](https://swc.rs/).
+-   Zero configuration: define the build artifacts in your `package.json`, and you're all set!
+-   Support of `cjs` & `esm` module formats output.
+-   Support of several loaders including JavaScript, TypeScript, JSX, JSON, and Images.
+-   TypeScript's declaration file (`.d.ts`) bundling.
+-   Automatic dependency inclusion (`peerDependencies` and `dependencies` are not bundled in the final output, `devDependencies` are unless they're not imported).
 
 <br>
 
-## 🚀 Quickstart
+## 🚀 Quick Start
 
 1️⃣ Install by running:
 
@@ -38,15 +37,19 @@ yarn add quickbundle
 ```jsonc
 {
 	"name": "lib", // Package name
-	"source": "src/index.ts", // Source code entrypoint
-	"main": "./dist/index.cjs", // CommonJS output file
-	"module": "./dist/index.mjs", // ESM output file
-	"types": "./dist/index.d.ts", // Typing output file (if defined, can increase build time)
-	"platform": "node", // Platform target (optional, by default "browser")
+	"exports": {
+		".": {
+			"source": "src/index.ts(x)?", // Source code entrypoint
+			"types": "./dist/index.d.ts", // Typing output file (if defined, can increase build time)
+			"import": "./dist/index.mjs", // ESM output file
+			"require": "./dist/index.cjs" // CommonJS output file
+		}
+	}
 	"scripts": {
 		"build": "quickbundle build", // Production mode (optimizes bundle)
 		"watch": "quickbundle watch", // Development mode (watches each file change)
-	}
+	},
+	// ...
 }
 ```
 
@@ -63,21 +66,62 @@ yarn build
 
 <br>
 
+## 👨‍🍳 Patterns
+
+### Optimize the build output
+
+By default, Quickbundle does the following built-in optimizations during the bundling process:
+
+-   Include, in the build output, only the code that is effectively imported and used in the source code. Setting the `sideEffects` package.json field to `false` marks the package as a side-effect-free one and helps Quickbundle to safely prune unused exports.
+-   [Identify and annotate](https://rollupjs.org/configuration-options/#treeshake-annotations) side-effect-free code (functions, ...) to enable a fine-grained dead-code elimination process later consumer side. For example, if a consumer uses only one library API, build output annotations added by Quickbundle allow the consumer's bundler remove all other unused APIs.
+
+However, Quickbundle doesn't minify the build output. Indeed, in general, **if the build targets a library (the most Quickbundle use case)**, minification is not necessary since enabling it can introduce some challenges:
+
+-   Reduce the build output discoverability inside the `node_modules` folder (minified code is an obfuscated code that can be hard to read for code audit/debugging purposes).
+-   Generate suboptimal source maps for the bundled library, as the consumer bundler will generate source maps based on the already minified library build (transformed code, mangled variable names, etc.).
+-   Risk of side effects with double optimizations (producer side and then consumer side).
+
+Popular open source libraries ([Vue](https://unpkg.com/browse/vue@3.4.24/dist/), [SolidJS](https://unpkg.com/browse/solid-js@1.8.17/dist/), [Material UI](https://unpkg.com/browse/@material-ui/core@4.12.4/), ...) do not provide minified builds as the build optimization is sensitive to the consumer context (e.g. environment targets (browser support), ...) and needs to be fully owned upstream (i.e. consumer/application-side).
+
+However, for non-library targets or if you would like to minify the build output on your side anyway, Quickbundle still provides the ability to enable the minification via:
+
+```bash
+quickbundle build --minification
+quickbundle watch --minification
+```
+
+### Enable source maps generation
+
+By default, source maps are not enabled but Quickbundle still provides the ability to enable it via:
+
+```bash
+quickbundle build --source-maps
+quickbundle watch --source-maps
+```
+
+Enabling source map generation is needed only if a build is [obfuscated (minified)](#optimize-the-build-output) for debugging-easing purposes. It generally pairs with the [`minification` flag](#optimize-the-build-output).
+
+<br>
+
 ## 🤩 Used by
 
--   [@adbayb/scripts](https://github.com/adbayb/stack) My opinionated toolbox for JavaScript/TypeScript projects
+-   [@adbayb/stack](https://github.com/adbayb/stack) My opinionated toolbox for JavaScript/TypeScript projects.
+
+<br>
+
+## ✍️ Contribution
 
-Contribution welcomed! 🤗
+We're open to new contributions, you can find more details [here](./CONTRIBUTING.md).
 
 <br>
 
 ## 💙 Acknowledgements
 
--   The backend is powered by [ESBuild](https://github.com/evanw/esbuild) to make blazing-fast builds. A special shoutout to its author [Evan Wallace](https://github.com/evanw) and [all contributors](https://github.com/evanw/esbuild/graphs/contributors).
+-   The backend is powered by [Rollup](https://github.com/rollup/rollup) and its plugin ecosystem (including [SWC](https://github.com/swc-project/swc)) to make blazing-fast builds. A special shoutout to all contributors involved.
 -   The zero-configuration approach was inspired by [microbundle](https://github.com/developit/microbundle). A special shoutout to its author [Jason Miller](https://github.com/developit) and [all contributors](https://github.com/developit/microbundle/graphs/contributors).
 
 <br>
 
 ## 📖 License
 
-[MIT](./LICENSE "License MIT")
+[MIT](./LICENSE "License MIT").

package/dist/index.js

@@ -0,0 +1,308 @@
+#!/usr/bin/env node
+import { helpers, termost } from 'termost';
+import { gzipSize } from 'gzip-size';
+import { rollup, watch as watch$1 } from 'rollup';
+import commonjs from '@rollup/plugin-commonjs';
+import json from '@rollup/plugin-json';
+import { nodeResolve } from '@rollup/plugin-node-resolve';
+import url from '@rollup/plugin-url';
+import { createRequire } from 'node:module';
+import { join } from 'node:path';
+import dts from 'rollup-plugin-dts';
+import externals from 'rollup-plugin-node-externals';
+import { swc } from 'rollup-plugin-swc3';
+import { readFile as readFile$1 } from 'node:fs/promises';
+
+const onLog = (_, log)=>{
+    if (log.message.includes("Generated an empty chunk")) return;
+};
+
+const build = async (configurations)=>{
+    var _process_env;
+    (_process_env = process.env).NODE_ENV ?? (_process_env.NODE_ENV = "production");
+    const output = [];
+    for (const config of configurations){
+        const initialTime = Date.now();
+        const bundle = await rollup({
+            ...config,
+            onLog
+        });
+        if (config.output) {
+            const outputEntries = Array.isArray(config.output) ? config.output : [
+                config.output
+            ];
+            const promises = [];
+            for (const outputEntry of outputEntries){
+                const outputFilename = outputEntry.file ?? outputEntry.dir;
+                if (!outputFilename) {
+                    throw new Error("Misconfigured file entry point. Make sure to define an `import`, `require`, or `default` field.");
+                }
+                promises.push(new Promise((resolve, reject)=>{
+                    bundle.write(outputEntry).then(()=>{
+                        resolve({
+                            elapedTime: Date.now() - initialTime,
+                            filename: outputFilename
+                        });
+                    }).catch(reject);
+                }));
+            }
+            output.push(...await Promise.all(promises));
+        }
+    }
+    return output;
+};
+
+const CWD = process.cwd();
+
+const require = createRequire(import.meta.url);
+const PKG = require(join(CWD, "./package.json"));
+const createConfigurations = (options = {
+    minification: false,
+    sourceMaps: false
+})=>{
+    /**
+	 * Entry-point resolution:
+	 * Following the [package entry-point specification](https://nodejs.org/api/packages.html#package-entry-points),
+	 * whenever an export object is defined, it take precedence over other classical entry-point fields
+	 * (such as main, module, and types defined at the root package.json level).
+	 */ if (PKG.main ?? PKG.module ?? PKG.types ?? !PKG.exports) {
+        throw new Error("Invalid package entry points contract. Use the recommended [`exports` field](https://nodejs.org/api/packages.html#package-entry-points) instead and, for TypeScript-based projects, update the `tsconfig.json` file to resolve it properly (`moduleResolution` must be set to `Bundler` (or `NodeNext`)).");
+    }
+    const outputEntryPointFields = [
+        "import",
+        "require",
+        "types"
+    ];
+    const output = Object.entries(PKG.exports).flatMap(([name, entryPoints])=>{
+        if (typeof entryPoints === "string") return [];
+        const entryPointKeys = Object.keys(entryPoints);
+        if (entryPointKeys.includes("source")) {
+            const hasAtLeastOneRequiredField = outputEntryPointFields.some((field)=>entryPointKeys.includes(field));
+            if (!hasAtLeastOneRequiredField) {
+                throw new Error(`A \`source\` field is defined without a provided \`${name}\` module entry point. Make sure to define at least one entry point (including ${outputEntryPointFields.join(", ")})`);
+            }
+        }
+        return [
+            entryPoints.source && createMainConfig({
+                ...entryPoints,
+                source: entryPoints.source
+            }, options),
+            entryPoints.source && entryPoints.types && createTypesConfig({
+                source: entryPoints.source,
+                types: entryPoints.types
+            })
+        ].filter(Boolean);
+    });
+    if (output.length === 0) {
+        throw new Error("No `source` field is set for the targetted package. If a build step is necessary, make sure to configure at least one `source` field in the package `exports` contract.");
+    }
+    return output;
+};
+const getPlugins = (...customPlugins)=>{
+    return [
+        externals({
+            builtins: true,
+            deps: true,
+            /**
+			 * As they're not installed consumer side, `devDependencies` are declared as internal dependencies (via the `false` value)
+			 * and bundled into the dist if and only if imported and not listed as `peerDependencies` (otherwise, they're considered external).
+			 */ devDeps: false,
+            optDeps: true,
+            peerDeps: true
+        }),
+        nodeResolve({
+            /**
+			 * The `exports` conditional fields definition order is important in the `package.json file`.
+			 * To be resolved first, `types` field must always come first in the package.json exports definition.
+			 * @see https://devblogs.microsoft.com/typescript/announcing-typescript-4-7/#package-json-exports-imports-and-self-referencing.
+			 */ exportConditions: [
+                "types"
+            ]
+        }),
+        commonjs(),
+        url(),
+        json(),
+        ...customPlugins
+    ];
+};
+const createMainConfig = (entryPoints, options)=>{
+    const { minification, sourceMaps } = options;
+    const output = [
+        entryPoints.require && {
+            file: entryPoints.require,
+            format: "cjs",
+            sourcemap: sourceMaps
+        },
+        entryPoints.import && {
+            file: entryPoints.import,
+            format: "es",
+            sourcemap: sourceMaps
+        }
+    ].filter(Boolean);
+    return {
+        input: entryPoints.source,
+        output,
+        plugins: getPlugins(swc({
+            minify: minification,
+            sourceMaps
+        }))
+    };
+};
+const createTypesConfig = (entryPoints)=>{
+    return {
+        input: entryPoints.source,
+        output: [
+            {
+                file: entryPoints.types
+            }
+        ],
+        plugins: getPlugins(dts({
+            compilerOptions: {
+                incremental: false
+            },
+            respectExternal: true
+        }))
+    };
+};
+// eslint-disable-next-line import/no-default-export
+createConfigurations();
+
+const readFile = readFile$1;
+
+const createCommand = (program, input)=>{
+    return program.command(input).option({
+        key: "minification",
+        name: "minification",
+        description: "Enable minification",
+        defaultValue: false
+    }).option({
+        key: "sourceMaps",
+        name: "source-maps",
+        description: "Enable source maps generation",
+        defaultValue: false
+    });
+};
+
+const createBuildCommand = (program)=>{
+    createCommand(program, {
+        name: "build",
+        description: "Build the source code (production mode)"
+    }).task({
+        key: "buildOutput",
+        label: "Bundle assets 📦",
+        async handler (context) {
+            return build(createConfigurations({
+                minification: context.minification,
+                sourceMaps: context.sourceMaps
+            }));
+        }
+    }).task({
+        key: "logInput",
+        label: "Generate report 📝",
+        async handler (context) {
+            return computeBundleSize(context.buildOutput);
+        },
+        skip (context) {
+            return context.buildOutput.length === 0;
+        }
+    }).task({
+        handler (context) {
+            const padding = context.logInput.map((item)=>item.rawSize).reduce((pad, currentRawSize)=>{
+                return Math.max(pad, String(currentRawSize).length);
+            }, 0) + 2;
+            context.logInput.forEach((item)=>{
+                helpers.message([
+                    `${item.rawSize.toString().padStart(padding)} B raw`,
+                    `${item.compressedSize.toString().padStart(padding)} B gz`
+                ], {
+                    label: `${item.filename} (took ${item.elapedTime}ms)`,
+                    type: "information"
+                });
+            });
+        },
+        skip (context) {
+            return context.buildOutput.length === 0;
+        }
+    });
+};
+const computeBundleSize = async (buildOutput)=>{
+    const computeFileSize = async (buildItemOutput)=>{
+        const content = await readFile(buildItemOutput.filename);
+        const gzSize = await gzipSize(content);
+        return {
+            ...buildItemOutput,
+            compressedSize: gzSize,
+            rawSize: content.byteLength
+        };
+    };
+    return Promise.all(buildOutput.map(async (item)=>computeFileSize(item)));
+};
+
+const watch = (configurations)=>{
+    var _process_env;
+    (_process_env = process.env).NODE_ENV ?? (_process_env.NODE_ENV = "development");
+    const watcher = watch$1(configurations.map((config)=>({
+            ...config,
+            onLog
+        })));
+    let startDuration;
+    console.clear();
+    watcher.on("event", async (event)=>{
+        switch(event.code){
+            case "START":
+                {
+                    startDuration = Date.now();
+                    clearLog(`Build in progress...`, {
+                        type: "information"
+                    });
+                    return;
+                }
+            case "BUNDLE_END":
+                await event.result.close();
+                break;
+            case "END":
+                {
+                    const duration = Date.now() - startDuration;
+                    clearLog(`Build done in ${duration}ms (at ${new Date().toLocaleTimeString()})`, {
+                        type: "success"
+                    });
+                    return;
+                }
+            case "ERROR":
+                {
+                    const { error } = event;
+                    clearLog(`${String(error)}`, {
+                        type: "error"
+                    });
+                    console.error("\n", error);
+                    return;
+                }
+        }
+    });
+};
+const clearLog = (...input)=>{
+    console.clear();
+    helpers.message(...input);
+};
+
+const createWatchCommand = (program)=>{
+    createCommand(program, {
+        name: "watch",
+        description: "Watch and rebuild on any code change (development mode)"
+    }).task({
+        handler (context) {
+            watch(createConfigurations({
+                minification: context.minification,
+                sourceMaps: context.sourceMaps
+            }));
+        }
+    });
+};
+
+const createProgram = (...commandBuilders)=>{
+    const program = termost("The zero-configuration bundler powered by ESBuild");
+    for (const commandBuilder of commandBuilders){
+        commandBuilder(program);
+    }
+};
+createProgram(createBuildCommand, createWatchCommand);

package/package.json

@@ -1,146 +1,60 @@
 {
-	"name": "quickbundle",
-	"version": "1.2.0",
-	"author": {
-		"name": "Ayoub Adib",
-		"email": "adbayb@gmail.com",
-		"url": "https://twitter.com/adbayb"
-	},
-	"repository": {
-		"type": "git",
-		"url": "git@github.com:adbayb/quickbundle.git"
-	},
-	"license": "MIT",
-	"keywords": [
-		"library",
-		"bundle",
-		"build",
-		"compiler",
-		"transpiler",
-		"module",
-		"fast"
-	],
-	"bin": {
-		"quickbundle": "bin/index.js"
-	},
-	"files": [
-		"bin"
-	],
-	"main": "bin/index.js",
-	"scripts": {
-		"prepublishOnly": "pnpm verify && pnpm build",
-		"prestart": "pnpm build",
-		"start": "bin/index.js",
-		"clean": "rm -rf bin",
-		"build": "tsc && chmod +x bin/index.js",
-		"watch": "tsc -w",
-		"release": "semantic-release",
-		"verify": "pnpm lint & tsc --noEmit",
-		"fix": "pnpm lint --fix",
-		"lint": "eslint . --ignore-path .gitignore",
-		"format": "prettier . --ignore-path .gitignore --ignore-path .prettierignore --write"
-	},
-	"dependencies": {
-		"dts-bundle-generator": "8.0.1",
-		"esbuild": "0.17.18",
-		"gzip-size": "6.0.0",
-		"termost": "0.9.0",
-		"threads": "1.7.0",
-		"typescript": ">=4.0.0"
-	},
-	"devDependencies": {
-		"@adbayb/eslint-config": "0.14.0",
-		"@adbayb/prettier-config": "0.14.0",
-		"@adbayb/ts-config": "0.14.0",
-		"@commitlint/cli": "17.6.3",
-		"@commitlint/config-conventional": "17.6.3",
-		"@semantic-release/git": "10.0.1",
-		"@types/node": "18.15.11",
-		"eslint": "8.40.0",
-		"husky": "4.3.8",
-		"lint-staged": "13.2.2",
-		"prettier": "2.8.8",
-		"semantic-release": "21.0.2",
-		"vitest": "0.31.0"
-	},
-	"packageManager": "pnpm@8.1.1",
-	"engines": {
-		"node": ">= 16.13.1"
-	},
-	"commitlint": {
-		"extends": [
-			"@commitlint/config-conventional"
-		]
-	},
-	"prettier": "@adbayb/prettier-config",
-	"eslintConfig": {
-		"extends": "@adbayb"
-	},
-	"husky": {
-		"hooks": {
-			"pre-commit": "lint-staged",
-			"commit-msg": "commitlint -E HUSKY_GIT_PARAMS"
-		}
-	},
-	"lint-staged": {
-		"**/*.{js,jsx,ts,tsx}": [
-			"pnpm lint"
-		],
-		"**/*.{json,md,mdx,html,css}": [
-			"pnpm format"
-		]
-	},
-	"release": {
-		"branches": [
-			"main"
-		],
-		"ci": false,
-		"plugins": [
-			[
-				"@semantic-release/commit-analyzer",
-				{
-					"releaseRules": [
-						{
-							"breaking": true,
-							"release": "major"
-						},
-						{
-							"revert": true,
-							"release": "patch"
-						},
-						{
-							"type": "feat",
-							"release": "minor"
-						},
-						{
-							"type": "fix",
-							"release": "patch"
-						},
-						{
-							"type": "perf",
-							"release": "patch"
-						},
-						{
-							"type": "refactor",
-							"release": "patch"
-						},
-						{
-							"type": "chore",
-							"scope": "deps",
-							"release": "patch"
-						}
-					]
-				}
-			],
-			"@semantic-release/release-notes-generator",
-			"@semantic-release/npm",
-			[
-				"@semantic-release/git",
-				{
-					"message": "chore(release): ${nextRelease.version}\n\n${nextRelease.notes}"
-				}
-			],
-			"@semantic-release/github"
-		]
-	}
-}
+  "name": "quickbundle",
+  "version": "2.1.0",
+  "description": "The zero-configuration transpiler and bundler for the web",
+  "author": {
+    "name": "Ayoub Adib",
+    "email": "adbayb@gmail.com",
+    "url": "https://twitter.com/adbayb"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git@github.com:adbayb/quickbundle.git",
+    "directory": "quickbundle"
+  },
+  "license": "MIT",
+  "keywords": [
+    "library",
+    "bundle",
+    "build",
+    "compiler",
+    "transpiler",
+    "module",
+    "fast",
+    "esbuild",
+    "swc",
+    "microbundle"
+  ],
+  "bin": {
+    "quickbundle": "dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "source": "./src/index.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "@rollup/plugin-commonjs": "^28.0.0",
+    "@rollup/plugin-json": "^6.1.0",
+    "@rollup/plugin-node-resolve": "^15.3.0",
+    "@rollup/plugin-url": "^8.0.2",
+    "gzip-size": "^7.0.0",
+    "rollup": "^4.24.0",
+    "rollup-plugin-dts": "^6.1.1",
+    "rollup-plugin-node-externals": "^7.1.3",
+    "rollup-plugin-swc3": "^0.12.1",
+    "termost": "^0.14.0"
+  },
+  "devDependencies": {
+    "@types/node": "20.16.11"
+  },
+  "scripts": {
+    "build": "rollup --config ./src/bundler/config.ts --configPlugin rollup-plugin-swc3 && chmod +x ./dist/index.js",
+    "watch": "rollup --watch --config ./src/bundler/config.ts --configPlugin rollup-plugin-swc3"
+  }
+}

package/bin/bundler/bundler.d.ts

@@ -1,2 +0,0 @@
-export declare const build: () => Promise<any[]>;
-export declare const watch: (onWatch: (type: "loading" | "result", error?: string) => void) => Promise<void>;