Registry / devops / quickbundle

quickbundle

JSON →
library2.16.0jsnpmunverified

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.

npm install quickbundle
INSTALL
IMPORT
SIG · QUICKBUNDLE
Q
quickbundle
devopsjavascriptv2.16.0
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

Quickbundle CLI
npx quickbundle build
node node_modules/quickbundle build
The primary way to use Quickbundle is via its CLI. `npx` is recommended for running local package executables.
Programmatic `bundle` function
import { bundle } from 'quickbundle';
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.
Compile command
npx quickbundle compile
Used for generating standalone executables, supporting cross-compilation.

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.

import { bundle } from 'quickbundle'; import * as path from 'path'; import * as fs from 'fs/promises'; const entryPoint = path.resolve(__dirname, 'src/index.ts'); const outputDir = path.resolve(__dirname, 'dist'); const outputFile = path.join(outputDir, 'bundle.js'); async function buildMyProject() { try { await fs.mkdir(outputDir, { recursive: true }); console.log(`Bundling ${entryPoint} to ${outputFile}...`); // Quickbundle typically works via package.json config, but for a programmatic example, // one might infer a direct API if exposed. This example assumes a simplified programmatic `bundle`. // In reality, Quickbundle heavily relies on `package.json` configuration for its zero-config approach. // A common setup would involve `package.json`: { "source": "src/index.ts", "main": "dist/bundle.js" } // Then simply `npx quickbundle build`. // For demonstration, simulating a programmatic call, though direct programmatic API details aren't provided. // This would likely involve spawning a child process or having an internal API for such. console.log('Using `npx quickbundle build` as the primary programmatic equivalent...'); const { execa } = await import('execa'); // Using execa for cross-platform command execution const { stdout } = await execa('npx', ['quickbundle', 'build'], { cwd: process.cwd(), // Or the project root stdio: 'inherit' // Stream output to current process }); console.log('Build output:'); console.log(stdout); console.log('Project bundled successfully!'); } catch (error) { console.error('Failed to bundle project:', error); process.exit(1); } } buildMyProject(); // To make this runnable, ensure you have a `package.json` like this in your project root: /* { "name": "my-project", "version": "1.0.0", "type": "module", "source": "src/index.ts", "main": "dist/bundle.js", "scripts": { "build": "quickbundle build" }, "peerDependencies": { "typescript": "^4.7.0 || ^5.0.0" }, "devDependencies": { "quickbundle": "^2.0.0", "typescript": "^5.0.0", "execa": "^8.0.0" } } */ // And a 'src/index.ts' file: /* export const greet = (name: string) => `Hello, ${name}!`; const appDiv: HTMLElement | null = document.getElementById('app'); if (appDiv) { appDiv.innerHTML = `<h1>${greet('Quickbundle User')}</h1>`; } console.log(greet('World from Quickbundle')); */
quickbundle --version
Debug
Known issues
breakingThe `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.
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.
affects: >=2.12.0
gotcha`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.
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.
affects: >=2.0.0
gotcha`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.
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.
affects: >=2.0.0
deprecatedBefore 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.
fix
Upgrade to `quickbundle@2.16.0` or higher to ensure proper support for dynamic imports.
affects: <2.16.0
gotchaWhen 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.
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.
affects: >=2.7.0
Errors
Common errors & fixes
Error: Cannot find module 'quickbundle'
The `quickbundle` package is not installed or the Node.js runtime cannot locate it.
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.
TS1009: Trailing comma not allowed.
Using an unsupported TypeScript syntax feature with an older TypeScript version, or a parsing issue with SWC/Rollup versions `quickbundle` bundles.
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.
quickbundle: command not found
The `quickbundle` executable is not in your system's PATH, or `npx` cannot find it.
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.
Error: Dynamic imports are not supported in this build target.
Attempting to use dynamic imports while building with an older version of `quickbundle` that did not support them, or targeting an incompatible environment.
fix
Upgrade `quickbundle` to version `2.16.0` or newer, which introduced support for dynamic imports. Review your `package.json` `source` and build configurations.
Upgrade
Version history
2.16.0latest on npm
Audit
Dependencies
typescriptrequiredPeer dependency for TypeScript projects, required for type checking and compilation.
Agent activity
2 hits · last 30 days
node
2
Resources
quickbundle — npm install quickbundle · libregistry