{"id":15774,"library":"quickbundle","title":"Quickbundle","description":"Quickbundle is a zero-configuration transpiler and bundler for web projects, currently at version 2.16.0. It aims to simplify the build process by allowing developers to define build artifacts directly in `package.json`. The library boasts fast build and watch modes, leveraging powerful underlying tools such as Rollup and SWC. It supports various module formats (CJS, ESM), loaders for JavaScript, TypeScript, JSX, JSON, and Images, and includes TypeScript declaration file bundling. A key differentiator is its ability to compile and cross-compile standalone executables for environments without Node.js. The project has a frequent release cadence, with minor and patch updates often occurring multiple times a month, primarily focused on dependency updates and feature enhancements like dynamic import support.","status":"active","version":"2.16.0","language":"javascript","source_language":"en","source_url":"ssh://git@github.com/adbayb/quickbundle","tags":["javascript","library","bundle","build","compiler","transpiler","module","fast","esbuild"],"install":[{"cmd":"npm install quickbundle","lang":"bash","label":"npm"},{"cmd":"yarn add quickbundle","lang":"bash","label":"yarn"},{"cmd":"pnpm add quickbundle","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency for TypeScript projects, required for type checking and compilation.","package":"typescript","optional":false}],"imports":[{"note":"The primary way to use Quickbundle is via its CLI. `npx` is recommended for running local package executables.","wrong":"node node_modules/quickbundle build","symbol":"Quickbundle CLI","correct":"npx quickbundle build"},{"note":"While primarily a CLI tool, it's common for bundlers to expose a programmatic API. The documentation shows `source` in `package.json` pointing to an entry, implying `quickbundle` orchestrates the build. An explicit programmatic API is not detailed in the available snippet but is a common pattern for bundlers.","symbol":"Programmatic `bundle` function","correct":"import { bundle } from 'quickbundle';"},{"note":"Used for generating standalone executables, supporting cross-compilation.","symbol":"Compile command","correct":"npx quickbundle compile"}],"quickstart":{"code":"import { bundle } from 'quickbundle';\nimport * as path from 'path';\nimport * as fs from 'fs/promises';\n\nconst entryPoint = path.resolve(__dirname, 'src/index.ts');\nconst outputDir = path.resolve(__dirname, 'dist');\nconst outputFile = path.join(outputDir, 'bundle.js');\n\nasync function buildMyProject() {\n  try {\n    await fs.mkdir(outputDir, { recursive: true });\n    console.log(`Bundling ${entryPoint} to ${outputFile}...`);\n\n    // Quickbundle typically works via package.json config, but for a programmatic example,\n    // one might infer a direct API if exposed. This example assumes a simplified programmatic `bundle`.\n    // In reality, Quickbundle heavily relies on `package.json` configuration for its zero-config approach.\n    // A common setup would involve `package.json`: { \"source\": \"src/index.ts\", \"main\": \"dist/bundle.js\" }\n    // Then simply `npx quickbundle build`.\n\n    // For demonstration, simulating a programmatic call, though direct programmatic API details aren't provided.\n    // This would likely involve spawning a child process or having an internal API for such.\n    console.log('Using `npx quickbundle build` as the primary programmatic equivalent...');\n    const { execa } = await import('execa'); // Using execa for cross-platform command execution\n    const { stdout } = await execa('npx', ['quickbundle', 'build'], { \n      cwd: process.cwd(), // Or the project root\n      stdio: 'inherit' // Stream output to current process\n    });\n    \n    console.log('Build output:');\n    console.log(stdout);\n    console.log('Project bundled successfully!');\n  } catch (error) {\n    console.error('Failed to bundle project:', error);\n    process.exit(1);\n  }\n}\n\nbuildMyProject();\n\n// To make this runnable, ensure you have a `package.json` like this in your project root:\n/*\n{\n  \"name\": \"my-project\",\n  \"version\": \"1.0.0\",\n  \"type\": \"module\",\n  \"source\": \"src/index.ts\",\n  \"main\": \"dist/bundle.js\",\n  \"scripts\": {\n    \"build\": \"quickbundle build\"\n  },\n  \"peerDependencies\": {\n    \"typescript\": \"^4.7.0 || ^5.0.0\"\n  },\n  \"devDependencies\": {\n    \"quickbundle\": \"^2.0.0\",\n    \"typescript\": \"^5.0.0\",\n    \"execa\": \"^8.0.0\"\n  }\n}\n*/\n\n// And a 'src/index.ts' file:\n/*\nexport const greet = (name: string) => `Hello, ${name}!`;\n\nconst appDiv: HTMLElement | null = document.getElementById('app');\nif (appDiv) {\n  appDiv.innerHTML = `<h1>${greet('Quickbundle User')}</h1>`;\n}\n\nconsole.log(greet('World from Quickbundle'));\n*/","lang":"typescript","description":"This quickstart demonstrates how to set up and run a build using `quickbundle` for a TypeScript project, primarily showing its CLI usage which is the recommended zero-config approach."},"warnings":[{"fix":"Review your build scripts and any programmatic usage of `quickbundle` when upgrading to `2.12.0` or later. Consult the official GitHub repository for detailed migration steps if issues arise.","message":"The `quickbundle@2.12.0` release included an \"Update binary contract\". While specifics aren't detailed in the changelog, changes to a binary contract can potentially break existing programmatic integrations or custom build scripts that rely on its internal workings or specific CLI output formats.","severity":"breaking","affected_versions":">=2.12.0"},{"fix":"Always test your builds thoroughly after updating `quickbundle`. Pin your `quickbundle` version (`\"quickbundle\": \"~2.x.x\"` or `\"quickbundle\": \"2.x.x\"`) if stability is critical for your project, and only update after verifying compatibility.","message":"`quickbundle` frequently updates its internal dependencies like Rollup, SWC, and esbuild. While this keeps it modern and performant, it might introduce subtle behavioral changes or regressions between minor versions if these underlying tools have breaking changes in their own updates.","severity":"gotcha","affected_versions":">=2.0.0"},{"fix":"Ensure that a compatible version of `typescript` is installed as a `devDependency` in your project. If you encounter TypeScript-related errors, try updating your `typescript` package to match `quickbundle`'s peer dependency requirements.","message":"`quickbundle` relies on a peer dependency for `typescript` (`^4.7.0 || ^5.0.0`). Incorrect or missing TypeScript versions in your project can lead to compilation errors or unexpected behavior.","severity":"gotcha","affected_versions":">=2.0.0"},{"fix":"Upgrade to `quickbundle@2.16.0` or higher to ensure proper support for dynamic imports.","message":"Before version 2.16.0, `quickbundle` did not officially support building dynamic imports. While this has been added in `2.16.0`, relying on older versions for projects with dynamic imports could lead to build failures or unexpected output.","severity":"deprecated","affected_versions":"<2.16.0"},{"fix":"For `compile` mode, simplify your dependency graph where possible. Ensure your main entry point and critical dependencies are compatible with a CommonJS output. Carefully test the generated executable in your target environment.","message":"When using `quickbundle compile` for standalone executables, the source code must not rely on external dependencies that cannot be bundled, and the bundled code must ultimately use the CommonJS module system. While `quickbundle` attempts to address this by bundling all dependencies and outputting CJS in compile mode, complex dependency graphs or specific Node.js API usages might still cause issues.","severity":"gotcha","affected_versions":">=2.7.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Run `npm install quickbundle` (or `pnpm add quickbundle`, `yarn add quickbundle`) in your project's root directory. Ensure that `node_modules` is present and accessible, or use `npx` to execute the CLI directly.","cause":"The `quickbundle` package is not installed or the Node.js runtime cannot locate it.","error":"Error: Cannot find module 'quickbundle'"},{"fix":"Check your `tsconfig.json` for `target` settings. Update your `typescript` peer dependency to match `quickbundle`'s requirements. Review `quickbundle`'s changelog for specific updates to SWC or Rollup that might affect parsing behavior.","cause":"Using an unsupported TypeScript syntax feature with an older TypeScript version, or a parsing issue with SWC/Rollup versions `quickbundle` bundles.","error":"TS1009: Trailing comma not allowed."},{"fix":"Use `npx quickbundle [command]` to run the command via the local `node_modules/.bin` directory. If you want to use `quickbundle` globally, install it with `npm install -g quickbundle`, though `npx` is generally preferred.","cause":"The `quickbundle` executable is not in your system's PATH, or `npx` cannot find it.","error":"quickbundle: command not found"},{"fix":"Upgrade `quickbundle` to version `2.16.0` or newer, which introduced support for dynamic imports. Review your `package.json` `source` and build configurations.","cause":"Attempting to use dynamic imports while building with an older version of `quickbundle` that did not support them, or targeting an incompatible environment.","error":"Error: Dynamic imports are not supported in this build target."}],"ecosystem":"npm"}