Bundle a TypeScript library with Bili
Tags: typescript, javascript, bili, rollup
Published: 2019-03-19 13:57:37

---
title: Bundle a TypeScript library with Bili
published: true
description: 
tags: 
- typescript
- javascript
- bili
- rollup
---


[Bili](https://bili.egoist.sh) is a bundler built on the top of [Rollup](https://rollupjs.org), it can be really convenient if you wanna bundle your library in multiple formats, nowadays it's pretty common to build a JavaScript library that works in CommonJS, UMD and ES Modules.

Bili also works with TypeScript seamlessly, this post will walk you through creating a simple TypeScript library.

## Get Started

Let's get started by creating a new project to learn how to use TypeScript with Bili:

```bash
mkdir my-lib
cd my-lib
yarn init -y # Create a package.json
yarn add bili --dev
```

Next install TypeScript related dependencies:

```bash
yarn add typescript rollup-plugin-typescript2 --dev
```

We will use [rollup-plugin-typescript2](https://github.com/ezolenko/rollup-plugin-typescript2) instead of the official [rollup-plugin-typescript](https://github.com/rollup/rollup-plugin-typescript) because the latter does not perform type-checking during compilation.

Now Bili will automatically use rollup-plugin-typescript2 if you're building a `.ts` file.

## TypeScript Config

To let TypeScript perform proper type-checking, a `tsconfig.json` is necessary, you can create one by running the TypeScript compiler with `--init` flag:

```bash
yarn tsc --init
```

Feel free to tweak the options in `tsconfig.json` to suit your needs.

## Bundle in Multiple Formats

We will create a `src/index.ts` in `my-lib`:

```bash
# Create src/index.ts
mkdir src
echo "export default 42" > src/index.ts
# Bundle it in CommonJS and ESM format
# Omit `--format <format>` to bundle in CommonJS only
yarn bili src/index.ts --format cjs --format esm
```

Then `src/index.ts` will be bundled to `dist/index.js`:

```js
'use strict';

var index = 42;

module.exports = index;
```

And `dist/index.mjs`:

```js
var index = 42;

export default index;
```


It's recommended to add `dist` (generated by Bili) and `.rpt2_cache` (generated by rollup-plugin-typescript2) in `.gitignore` file.

## Generate Declaration Files

To generate corresponding `.d.ts` files for files in `src` folder, first you need to enable `compilerOptions.declaration` in your `tsconfig.json`:

```json
{
  "compilerOptions": {
    "declaration": true
  }
}
```

Then create `bili.config.ts` to configure TypeScript to include `src` folder only:

```ts
import { Config } from 'bili'

const config: Config = {
  plugins: {
    typescript2: {
      // Override the config in `tsconfig.json`
      tsconfigOverride: {
        include: ['src']
      }
    }
  },

  // Let's take this opportunity to move the CLI flags here as well
  input: 'src/index.ts',
  output: {
    format: ['cjs', 'esm']
  }
}

export default config
```

Note that we didn't set `include: ['src']` in `tsconfig.json` directly, because in most cases your editor like VS Code will use that file by default and you don't want other files like `./my-lib/test/index.test.ts` to be excluded.

Finally let's run `yarn bili` and the declaration file will be generated to `dist/index.d.ts`:

```typescript
declare const _default: 42;
export default _default;
```

## Configure package.json

```json
{
  "name": "my-lib",
  "main": "dist/index.js",
  "module": "dist/index.mjs"
  "types": "dist/index.d.ts",
  "files": ["dist"],
  "scripts": {
    "build": "bili",
    "prepublishOnly": "npm run build"
  }
}
```

Now you can publish it on npm and the types can be found when others are using it.

Check out https://github.com/egoist/objql for a simple real-world TypeScript library.

## Related Links

- [Contributing to Bili on GitHub](https://github.com/egoist/bili)
- [JavaScript/TypeScript in Bili](https://bili.egoist.sh/#/recipes/javascript)
- [Following the author of Bili on Twitter](https://twitter.com/_egoistlily)
- [Making a donation to keep Bili alive](https://patreon.com/egoist)