quickbundle 0.0.0-next-6c096f7

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+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
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,164 @@
+<br>
+<div align="center">
+    <h1>📦 Quickbundle</h1>
+    <strong>The zero-configuration transpiler and bundler for the web</strong>
+</div>
+<br>
+<br>
+
+## ✨ Features
+
+Quickbundle allows you to bundle a library in a **quick**, **fast** and **easy** way:
+
+-   Fast build and watch mode powered by Rollup[^1] and SWC[^2].
+-   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).
+
+[^1]: A [module bundler](https://rollupjs.org/) optimized for better tree-shaking processing and seamless interoperability of CommonJS and ESM formats with minimal code footprint.
+
+[^2]: A [TypeScript / JavaScript transpiler](https://swc.rs/) for quicker code processing including TypeScript transpilation, JavaScript transformation, and, minification.
+
+<br>
+
+## 🚀 Quick Start
+
+1️⃣ Install by running:
+
+```bash
+# Npm
+npm install quickbundle
+# Pnpm
+pnpm add quickbundle
+# Yarn
+yarn add quickbundle
+```
+
+2️⃣ Set up your package configuration (`package.json`):
+
+-   When exporting exclusively ESM format:
+
+```jsonc
+{
+	"name": "lib", // Package name
+	"type": "module", // Optional if you want Node-like runtime to process by default `.js` file as ESM modules.
+	"sideEffects": false, // Mark the package as a side-effect-free one to support the consumer dead-code elimination (tree-shaking) process. If your library contains global side effects (ideally, it should be avoided), configure the field to list the files that do have side effects.
+	"exports": {
+		".": {
+			"source": "src/index.ts(x)?", // Source code entry point.
+			"types": "./dist/index.d.ts", // Typing output file (if defined, can increase build time). This condition should always come first after the custom `source` field definition.
+			"default": "./dist/index.mjs", // By default, Quickbundle will always output ESM format for the `default` field (this condition should always come last since it always matches as a generic fallback). However, take care: if both `import` and `default` fields are defined, provide the same file path, as the `import` field export instruction will be the only one considered to define the output file path.
+		},
+		"./otherModulePath": {
+			// ...
+		}
+	}
+	"scripts": {
+		"build": "quickbundle build", // Production mode (optimizes bundle)
+		"watch": "quickbundle watch", // Development mode (watches each file change)
+	},
+	// ...
+}
+```
+
+-   When exporting both CommonJS (CJS) and ECMAScript Modules (ESM) format (please be aware of [dual package hazard risk](https://nodejs.org/api/packages.html#dual-package-hazard)):
+
+```jsonc
+{
+	"name": "lib", // Package name
+	"type": "module", // Optional if you want Node-like runtime to process by default `.js` file as ESM modules.
+	"sideEffects": false, // Mark the package as a side-effect-free one to support the consumer dead-code elimination (tree-shaking) process. If your library contains global side effects (ideally, it should be avoided), configure the field to list the files that do have side effects.
+	"exports": {
+		".": {
+			"source": "src/index.ts(x)?", // Source code entry point.
+			"types": "./dist/index.d.ts", // // Typing output file (if defined, can increase build time). This condition should always come first after the custom `source` field definition.
+			"require": "./dist/index.cjs", // CommonJS output file (matches when the module is loaded via require() consumer side).
+			"import": "./dist/index.mjs", // ESM output file (matches when the package is loaded via import or import() consumer side).
+			"default": "./dist/index.mjs", // By default, Quickbundle will always output ESM format for the `default` field (this condition should always come last since it always matches as a generic fallback). However, take care: if both `import` and `default` fields are defined, provide the same file path, as the `import` field export instruction will be the only one considered to define the output file path.
+		},
+		"./otherModulePath": {
+			// ...
+		}
+	}
+	"scripts": {
+		"build": "quickbundle build", // Production mode (optimizes bundle)
+		"watch": "quickbundle watch", // Development mode (watches each file change)
+	},
+	// ...
+}
+```
+
+3️⃣ Try it by running:
+
+```bash
+# Npm
+npm run build
+# Pnpm
+pnpm build
+# Yarn
+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/stack](https://github.com/adbayb/stack) My opinionated toolbox for JavaScript/TypeScript projects.
+
+<br>
+
+## ✍️ Contribution
+
+We're open to new contributions, you can find more details [here](./CONTRIBUTING.md).
+
+<br>
+
+## 💙 Acknowledgements
+
+-   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").

package/bin/index.mjs

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+
+import { createRequire } from "node:module";
+import { join } from "node:path";
+
+const pkg = createRequire(import.meta.url)("../package.json");
+
+import(join("..", pkg.exports["."].default));

package/dist/index.mjs

@@ -0,0 +1,365 @@
+#!/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 isRecord = (value)=>{
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+};
+
+const build = async (configurations)=>{
+    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({
+                            elapsedTime: 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,
+    standalone: false
+})=>{
+    return getBuildableExports(options).flatMap((buildableExport)=>{
+        return [
+            buildableExport.source && createMainConfig({
+                ...buildableExport,
+                source: buildableExport.source
+            }, options),
+            buildableExport.source && buildableExport.types && createTypesConfig({
+                source: buildableExport.source,
+                types: buildableExport.types
+            })
+        ].filter(Boolean);
+    });
+};
+const getBuildableExports = ({ standalone })=>{
+    if (standalone) {
+        /**
+		 * Entry-point resolution invariants for standalone target (mostly binaries).
+		 */ if (!PKG.source || !PKG.bin) {
+            throw new Error("Invalid package entry points contract. Standalone compilation is enabled but required fields `source` and/or `bin` are missing. Make sure to set them.");
+        }
+        const bin = PKG.bin;
+        return isRecord(bin) ? Object.entries(bin).map((data)=>({
+                require: data[1],
+                source: data[0]
+            })) : [
+            {
+                require: bin,
+                source: PKG.source
+            }
+        ];
+    }
+    /**
+	 * Entry-point resolution invariants for non-standalone target (mostly libraries):
+	 * 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 buildableExportFields = [
+        "default",
+        "import",
+        "require",
+        "types"
+    ];
+    let singleExport = undefined;
+    const output = Object.entries(PKG.exports).map(([field, value])=>{
+        if (isRecord(value)) {
+            return [
+                field,
+                value
+            ];
+        }
+        if ([
+            "source",
+            ...buildableExportFields
+        ].includes(field)) {
+            if (!singleExport) {
+                singleExport = {};
+                singleExport[field] = value;
+                return [
+                    ".",
+                    singleExport
+                ];
+            }
+            singleExport[field] = value;
+        }
+        return undefined;
+    }).reduce((buildableExports, currentExport)=>{
+        if (!currentExport) return buildableExports;
+        const [exportField, exportValue] = currentExport;
+        const conditionalExportFields = Object.keys(exportValue);
+        if (!conditionalExportFields.includes("source")) return buildableExports;
+        const hasAtLeastOneRequiredField = buildableExportFields.some((entryPointField)=>conditionalExportFields.includes(entryPointField));
+        if (hasAtLeastOneRequiredField) {
+            buildableExports.push(exportValue);
+            return buildableExports;
+        }
+        throw new Error(`A \`source\` field is defined without an output defined for the \`${exportField}\` export. Make sure to define at least one conditional entry point (including ${buildableExportFields.map((field)=>`\`${field}\``).join(", ")})`);
+    }, []);
+    if (output.length === 0) {
+        throw new Error("No `source` field is set for the targeted package. If a build step is necessary, make sure to configure at least one `source` field in the package `exports` contract. If not, do not execute quickbundle on this package.");
+    }
+    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
+        }),
+        commonjs(),
+        url(),
+        json(),
+        ...customPlugins
+    ];
+};
+const createMainConfig = (entryPoints, options)=>{
+    const { minification, sourceMaps } = options;
+    const esmInput = entryPoints.import ?? entryPoints.default;
+    if (entryPoints.import && entryPoints.default && entryPoints.import !== entryPoints.default) {
+        throw new Error("Both `import` and `default` export fields have been defined but with different values. To preserve proper `default` field resolution on the consumer side (i.e. to target ESM format), make sure to provide the same file path for both fields.");
+    }
+    const output = [
+        entryPoints.require && {
+            file: entryPoints.require,
+            format: "cjs",
+            inlineDynamicImports: Boolean(options.standalone),
+            sourcemap: sourceMaps
+        },
+        esmInput && {
+            file: esmInput,
+            format: "es",
+            sourcemap: sourceMaps
+        }
+    ].filter(Boolean);
+    return {
+        input: entryPoints.source,
+        output,
+        plugins: getPlugins(nodeResolve(), swc({
+            minify: minification,
+            sourceMaps
+        }))
+    };
+};
+const createTypesConfig = (entryPoints)=>{
+    return {
+        input: entryPoints.source,
+        output: [
+            {
+                file: entryPoints.types
+            }
+        ],
+        plugins: getPlugins(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"
+            ]
+        }), 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)=>{
+    return 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,
+                standalone: false
+            }));
+        }
+    }).task({
+        key: "logInput",
+        label: "Generate report 📝",
+        async handler (context) {
+            return computeBundleSize(context.buildOutput);
+        },
+        skip (context) {
+            return context.buildOutput.length === 0;
+        }
+    }).task({
+        handler (context) {
+            context.logInput.forEach((item)=>{
+                helpers.message([
+                    `${formatSize(item.rawSize)} raw`,
+                    `${formatSize(item.compressedSize)} gzip`
+                ].map((message, index)=>{
+                    return index === 0 ? message : `   ${message}`;
+                }).join("\n"), {
+                    label: `${item.filename} (took ${item.elapsedTime}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 formatSize = (bytes)=>{
+    const kiloBytes = bytes / 1000;
+    return kiloBytes < 1 ? `${bytes} B` : `${kiloBytes.toFixed(2)} kB`;
+};
+
+const watch = (configurations)=>{
+    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)=>{
+    return 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,
+                standalone: false
+            }));
+        }
+    });
+};
+
+const createProgram = (...commandBuilders)=>{
+    const program = termost("The zero-configuration transpiler and bundler for the web");
+    for (const commandBuilder of commandBuilders){
+        commandBuilder(program);
+    }
+};
+createProgram(createBuildCommand, createWatchCommand);

package/package.json

@@ -0,0 +1,70 @@
+{
+  "name": "quickbundle",
+  "version": "0.0.0-next-6c096f7",
+  "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": "bin/index.mjs"
+  },
+  "files": [
+    "bin",
+    "dist"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "source": "./src/index.ts",
+      "default": "./dist/index.mjs"
+    }
+  },
+  "peerDependencies": {
+    "typescript": ">=4.7.0"
+  },
+  "peerDependenciesMeta": {
+    "typescript": {
+      "optional": true
+    }
+  },
+  "dependencies": {
+    "@rollup/plugin-commonjs": "^28.0.1",
+    "@rollup/plugin-json": "^6.1.0",
+    "@rollup/plugin-node-resolve": "^15.3.0",
+    "@rollup/plugin-url": "^8.0.2",
+    "@swc/core": "^1.7.42",
+    "gzip-size": "^7.0.0",
+    "rollup": "^4.24.3",
+    "rollup-plugin-dts": "^6.1.1",
+    "rollup-plugin-node-externals": "^7.1.3",
+    "rollup-plugin-swc3": "^0.12.1",
+    "termost": "^0.18.0"
+  },
+  "devDependencies": {
+    "@types/node": "22.8.5"
+  },
+  "scripts": {
+    "build": "rollup --config ./src/bundler/config.ts --configPlugin rollup-plugin-swc3",
+    "watch": "rollup --watch --config ./src/bundler/config.ts --configPlugin rollup-plugin-swc3"
+  }
+}