{"id":14659,"library":"klap","title":"Klap JavaScript Bundler","description":"Klap is a zero-configuration, zero-dependency bundler designed for small to medium-sized JavaScript packages. It simplifies the build process by leveraging standard `package.json` entries (`source`, `main`, `module`, `browser`) to define multiple output targets, including CommonJS, ESM, and UMD. Despite its \"zero dependency\" marketing claim, it internally integrates and orchestrates established tools such as Rollup, Babel, and TypeScript to provide modern JavaScript syntax transforms, JSX support (for frameworks like React, Styled Components, and Emotion), and TypeScript compilation. The current stable version is 7.0.11, though the last significant update to the main GitHub repository was in May 2021, suggesting a maintenance or stable state rather than active, frequent development. Key differentiators include built-in minification, gzip size tracking, and a development server, offering an opinionated, complete build pipeline with minimal setup for library authors.","status":"maintenance","version":"7.0.11","language":"javascript","source_language":"en","source_url":"https://github.com/osdevisnot/klap","tags":["javascript"],"install":[{"cmd":"npm install klap","lang":"bash","label":"npm"},{"cmd":"yarn add klap","lang":"bash","label":"yarn"},{"cmd":"pnpm add klap","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"Klap's primary interface is its Command Line Interface (CLI). Direct JS/TS imports of specific commands like 'build' are not supported or intended for typical usage. Users interact by executing commands via `npx` or `npm run`.","wrong":"import { build } from 'klap'","symbol":"klap CLI commands","correct":"npx klap <command> [options]"},{"note":"The recommended and most common way to integrate klap into a project's build process is by defining `klap` commands within npm/yarn scripts in `package.json`. This ensures proper context and execution.","wrong":"import { build } from 'klap'; build();","symbol":"package.json build scripts","correct":"\"build\": \"klap build\""},{"note":"While possible for advanced use cases, direct programmatic import of the `klap` package is not its primary design. Klap is an ESM package, meaning `require()` is incorrect in modern Node.js environments without specific loader configurations or transpilation.","wrong":"const klap = require('klap'); klap(['build']);","symbol":"Programmatic execution (advanced)","correct":"import klap from 'klap'; klap(['build', './src/index.js']);"}],"quickstart":{"code":"// 1. Initialize a new project with TypeScript and JSX support\n// Open your terminal and run:\n// npx klap init tsx\n\n// 2. Create your source file (e.g., src/index.tsx)\n// This file will be bundled by klap. Klap automatically detects .ts, .tsx, .js, .jsx files.\n\n// src/index.tsx\nimport React from 'react';\n\ninterface GreeterProps {\n  name: string;\n}\n\nexport const Greeter = ({ name }: GreeterProps) => {\n  return <h1>Hello, {name}!</h1>;\n};\n\nexport const sum = (a: number, b: number): number => a + b;\n\n// 3. Add a simple usage example for local development (e.g., examples/app.tsx)\n// This file is used for `npm start` and demonstrates library usage, but isn't bundled into the library itself.\n\n// examples/app.tsx\nimport { Greeter, sum } from '../src'; // Adjust path as needed based on your project structure\nimport { createRoot } from 'react-dom/client';\n\nconst rootElement = document.getElementById('root');\nif (rootElement) {\n  createRoot(rootElement).render(\n    <>\n      <Greeter name=\"Klap User\" />\n      <p>The sum of 5 and 3 is: {sum(5, 3)}</p>\n    </>\n  );\n} else {\n  console.error(\"Root element not found!\");\n}\n\n// 4. Run the development server to test your example\n// Open your terminal in the project root and run:\n// npm start\n\n// 5. Build your library for distribution\n// Open your terminal in the project root and run:\n// npm run build\n\n// This command will output bundled files (cjs, esm, umd) to the 'dist' directory,\n// as configured by the 'main', 'module', and 'browser' fields that 'klap init' sets up in your package.json.\n","lang":"typescript","description":"This quickstart demonstrates how to initialize a TypeScript project with JSX support using `npx klap init tsx`, create a simple React component and a utility function, set up a local development server for testing, and finally build the library for distribution. It showcases `klap`'s zero-config approach for common library development patterns, particularly for React-based packages."},"warnings":[{"fix":"Carefully review your bundled output after upgrading to v7.0.0+ if your library targets Node.js environments or uses Node.js global variables. Adjust your code or `klap` configuration if unexpected behavior or runtime errors occur due to changed global polyfills.","message":"Version 7.0.0 introduced a breaking change by replacing an unmaintained `nodeGlobals` plugin with a well-maintained alternative. This may alter the compile output if your code previously relied on specific Node.js global variable polyfills being replaced by `klap`.","severity":"breaking","affected_versions":">=7.0.0"},{"fix":"Evaluate the project's long-term viability for your needs. If continuous updates, robust community support, or bleeding-edge feature compatibility are critical, consider alternative, more actively maintained bundlers.","message":"The `klap` project appears to be in maintenance mode, with the last significant update to the main repository (v7.0.11) occurring in May 2021. While the tool remains functional for many use cases, new features, active bug fixes for recently discovered issues, or updates to keep pace with modern JavaScript ecosystem changes may not be consistently provided.","severity":"deprecated","affected_versions":">=7.0.0"},{"fix":"Be aware that major version upgrades of `klap` are most likely to incorporate significant updates to these internal dependencies. Review `klap`'s changelog carefully for details on underlying tool versions and their potential impact.","message":"Despite marketing itself as 'zero dependency,' `klap` internally relies on significant tools like Rollup, Babel, and TypeScript. This means that changes or breaking updates in these underlying tools, or their specific versions integrated within `klap`, can indirectly affect your build process or output. The 'zero dependency' claim primarily refers to your project's *runtime* dependencies, not `klap`'s build-time tooling.","severity":"gotcha","affected_versions":">=3.2.0"},{"fix":"Ensure your entry point file has the correct `.ts` or `.tsx` extension. For advanced TypeScript configurations, you might need to simplify your `tsconfig.json` to align with `klap`'s conventions or consider a bundler that offers more explicit TypeScript configuration options.","message":"Klap's automatic TypeScript detection works by expecting `.ts` or `.tsx` file extensions. For complex TypeScript setups, specific `tsconfig.json` paths, stricter rules, or advanced compiler options may not be fully configurable or respected by `klap`'s zero-config philosophy, potentially leading to unexpected compilation errors or warnings.","severity":"gotcha","affected_versions":">=6.1.3"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Ensure your `package.json` includes valid `source`, `main`, `module`, and `browser` entries, even if you intend to only output a subset of formats. Running `npx klap init` is the recommended way to generate a correct minimal `package.json`.","cause":"The `package.json` file is missing required fields like `source`, `main`, `module`, or `browser`, or they are misconfigured, preventing `klap` from determining input/output paths.","error":"TypeError: Cannot read properties of undefined (reading 'config')"},{"fix":"Install TypeScript as a development dependency: `npm install --save-dev typescript`. Verify your Node.js version is compatible with the installed `klap` and `typescript` versions. Using `npx klap init ts` or `npx klap init tsx` should prompt for its installation.","cause":"When building a TypeScript project, the `typescript` package is either not installed as a `devDependency`, or `klap` cannot locate it within your project's node_modules.","error":"Error: Cannot find module 'typescript'"},{"fix":"For React/JSX projects, initialize with `npx klap init tsx`. Ensure your source files containing JSX or other advanced syntax have the correct `.jsx` or `.tsx` (for TypeScript with JSX) extension, as `klap` relies on these for automatic detection and transformation.","cause":"Attempting to bundle JSX syntax or modern ESNext features without `klap` being properly configured for them (e.g., `klap init tsx` was not used, or the input file has a `.js` extension instead of `.jsx` or `.tsx`).","error":"SyntaxError: Unexpected token '<' (or similar JSX/ESNext syntax errors)"},{"fix":"Review your code for direct usage of Node.js globals. If they are necessary for browser compatibility, you might need to manually provide polyfills or ensure your code is environment-aware. This error is more prevalent after upgrading to v7.0.0 due to the change in the `nodeGlobals` plugin.","cause":"Your bundled code (intended for a browser environment) references Node.js global objects like `process` or `Buffer`, and `klap`'s v7.0.0 breaking change might have affected how these globals are polyfilled or replaced.","error":"ReferenceError: process is not defined (or Buffer is not defined)"}],"ecosystem":"npm"}