Klap JavaScript Bundler

Common errors

• TypeError: Cannot read properties of undefined (reading 'config')

  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.
  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`.

• Error: Cannot find module 'typescript'

  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.
  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.

• SyntaxError: Unexpected token '<' (or similar JSX/ESNext syntax errors)

  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`).
  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.

• ReferenceError: process is not defined (or Buffer is not defined)

  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.
  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.

Warnings

• breaking 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`.
  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.
• deprecated 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.
  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.
• gotcha 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.
  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.
• gotcha 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.
  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.

Install

• npm install klap npm
• yarn add klap yarn
• pnpm add klap pnpm

Imports

• klap CLI commands
  wrong:

  import { build } from 'klap'

  correct:

  npx klap <command> [options]

  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`.
• package.json build scripts
  wrong:

  import { build } from 'klap'; build();

  correct:

  "build": "klap build"

  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.
• Programmatic execution (advanced)
  wrong:

  const klap = require('klap'); klap(['build']);

  correct:

  import klap from 'klap'; klap(['build', './src/index.js']);

  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.

Quickstart

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.

// 1. Initialize a new project with TypeScript and JSX support
// Open your terminal and run:
// npx klap init tsx

// 2. Create your source file (e.g., src/index.tsx)
// This file will be bundled by klap. Klap automatically detects .ts, .tsx, .js, .jsx files.

// src/index.tsx
import React from 'react';

interface GreeterProps {
  name: string;
}

export const Greeter = ({ name }: GreeterProps) => {
  return <h1>Hello, {name}!</h1>;
};

export const sum = (a: number, b: number): number => a + b;

// 3. Add a simple usage example for local development (e.g., examples/app.tsx)
// This file is used for `npm start` and demonstrates library usage, but isn't bundled into the library itself.

// examples/app.tsx
import { Greeter, sum } from '../src'; // Adjust path as needed based on your project structure
import { createRoot } from 'react-dom/client';

const rootElement = document.getElementById('root');
if (rootElement) {
  createRoot(rootElement).render(
    <>
      <Greeter name="Klap User" />
      <p>The sum of 5 and 3 is: {sum(5, 3)}</p>
    </>
  );
} else {
  console.error("Root element not found!");
}

// 4. Run the development server to test your example
// Open your terminal in the project root and run:
// npm start

// 5. Build your library for distribution
// Open your terminal in the project root and run:
// npm run build

// This command will output bundled files (cjs, esm, umd) to the 'dist' directory,
// as configured by the 'main', 'module', and 'browser' fields that 'klap init' sets up in your package.json.