v 1 r t l
💻
Daniel Berner
💻
Tom Julius
💻
Marcus Lindblom
💻
## :sparkles: Features
- :tada: **zero config**: bundle your library using only a `package.json`
- :boom: **zero config**: typescript support (just rename `*.js` to `*.ts`)
- :star2: **zero config**: code transforms using babel macros
- :rainbow: **zero config**: code generation using babel plugin codegen
- :rocket: **zero dependency**: uses [gcc-style bundling](https://www.npmjs.com/package/@vercel/ncc).
- :octopus: creates **tiny bundles** for multiple output formats `cjs`, `esm` and `umd`
- :fire: **Modern JS** syntax with class properties, async/await, and generators
- :zap: Built in Minification and Gzip Size Tracking
- :cyclone: Built in development server for quick prototyping.
- :confetti_ball: Supports **`react`**, **`styled-components`** and **`emotion`** out of the box.
### :muscle: Powered By
- [rollup](https://rollupjs.org) - Next-generation ES module bundler
- [babel](https://babeljs.io) - The compiler for next generation JavaScript
- [typescript](https://www.typescriptlang.org/) - Typed JavaScript at Any Scale.
## :plate_with_cutlery: Usage
First, initialize your project using `klap init`:
```bash
npx klap init
```
**Prefer Typescript ?** initialize using `ts` argument:
```bash
npx klap init ts
```
**Want to use JSX with Typescript?** `init` using `tsx` argument:
```bash
npx klap init tsx
```
The `init` command will create a minimal `package.json` with `source`, `main`, `module` and `browser` entries and the `build`, `watch` and `start` scripts.
```jsonc
{
"name": "...",
"version": "0.0.0",
"files": [ "dist" ],
"source": "src/sum.js", # source file of your package
"main": "dist/sum.cjs.js", # commonjs bundle target
"module": "dist/sum.esm.js", # esm bundle target
"browser": "dist/sum.js", # umd bundle target
"scripts": {
"build": "klap build", # bundle your package
"watch": "klap watch", # bundle your package and watch for changes
"start": "klap start", # start a development server
},
"devDependencies": {
"klap": "3.2.0" # klap as dev dependency
}
}
```
> Note: Dropping `pkg.main` will disable `cjs` output, also applies to `esm` and `umd` outputs.
Then use `npm run` or `yarn` to invoke npm scripts as you normally would.
> See [examples](examples) for common use cases using `klap`.
### :anger: Granular Control
`klap` uses sensible defaults for most part. However, as needed, use below properties in `package.json` to fine tune `klap`. You can also use `cli flags` to control config options for `klap`.
| option | cli flag(s) | description | default |
| ----------------- | ---------------------- | ---------------------------------------------- | ------------------------------------------------------------- |
| `source` | -s --source | source file to compile and bundle | `src/index.js` |
| `cjs` | -c --cjs | the output file for common js format | pkg.main |
| `esm` | -e --esm | the output file for esm format | pkg.module |
| `umd` | -u --umd | the output file for umd format | pkg.browser |
| `types` | -t --types | the output file for type definitions | pkg.types |
| `browserslist` | -b --browserslist | browserslist compatible compilation target | `last 2 versions modern browsers if usage is greater than 1%` |
| `klap.name` | -n --name | package name for `umd` bundles | sanitized `pkg.name` |
| `klap.port` | -p --port | port for development server | `1234` |
| `klap.example` | --example | location of index js/ts file for start command | `public/index.js` or `pkg.source` |
| `klap.fallback` | --fallback | location of index html file for start command | `public/index.html` |
| `klap.target` | --target | target for development server (`umd, es`) | `es` |
| `klap.sourcemap` | --no-sourcemap | sourcemaps for builds | `true` |
| `klap.minify` | --no-minify | minification for builds | `true` |
| `klap.runtime` | --runtime | the runtime for new JSX transform | `react` |
| `klap.pragma` | --pragma | the JSX Pragma for classic runtime | `react` |
| `klap.pragmaFrag` | --pragmaFrag | JSX Fragment pragma | `react` |
| `klap.usets` | --usets | use typescript compiler for the project | `false` |
| `klap.globals` | | global names for umd bundles | `{}` |
> `--usets` allows the library code to use typescript features not supported by `@babel/preset-typescript`. See [const-enums](examples/const-enums) example to enable usage of const enums.
## :clinking_glasses: License
**klap** is licensed under the [MIT License](http://opensource.org/licenses/MIT).
Documentation is licensed under [Creative Common License](http://creativecommons.org/licenses/by/4.0/).
Created with ❤️ by [@osdevisnot](https://github.com/osdevisnot) and [all contributors](https://github.com/osdevisnot/klap/graphs/contributors).
## :sparkles: Contributors
Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)):
v 1 r t l 💻 |
Daniel Berner 💻 |
Tom Julius 💻 |
Marcus Lindblom 💻 |