@walrus/rollup

<h1 align="center">
  @walrus/rollup
</h1>

<h2 align="center">
  基于Rollup的零配置打包库
</h2>

## ✨ 特性

- 🚀  快速，默认情况下零配置
- 📦  基于 rollup 进行打包
- 🌈  支持 TypeScript
- 📦  支持 cjs、esm 和 umd 三种格式的打包
- 🎉  支持 lerna
- 🎶  如果需要，很容易使用 Rollup 插件
- 🐚  支持别名设置，默认`@`指向项目`src`目录
- 💅  支持 css、less，支持开启 css modules
- 💻  使用 TypeScript 编写，提供类型定义文件

## 🏗 安装

请使用 `@walrus/rollup-cli` 

```
# npm install
$ npm install @walrus/rollup-cli --save --dev

# yarn install
$ yarn add @walrus/rollup-cli --dev
```

## 🔨 使用

1️⃣ **安装** 按以上步骤按照依赖

2️⃣ **完善项目信息** `package.json`:

```js
{
  "name": "foo",                   // your package name
  "source": "src/foo.js",          // your source code 可选
  "main": "dist/foo.js",           // where to generate the CommonJS/Node bundle 可选
  "module": "dist/foo.module.js",  // where to generate the ESM bundle 可选
  "unpkg": "dist/foo.umd.js",      // where to generate the UMD bundle (also aliased as "umd:main") 可选
  "scripts": {
    "build": "walrus-rollup",        // compiles "source" to "main"/"module"/"unpkg"
  }
}
```

3️⃣ **执行编译** 运行 `npm run build`.

## 📝 配置文件

项目将按照以下顺序读取配置文件

- `build.config.ts`
- `build.config.js`
- `.buildrc.ts`
- `.buildrc.js`

**typescript**

```ts
// .buildrc.ts
import { InputOptions } from '@walrus/rollup';

const config: Config = {
  entries: [
    'src/index.js'
  ]
}

export default config
```

**javascript**

```js
// .buildrc.ts
import { InputOptions } from '@walrus/rollup';

/** @type {import('@walrus/rollup').InputOptions} */
const config: Config = {
  entries: [
    'src/index.js'
  ]
}

export default config
```

## 插件使用

`@walrus/rollup` 支持定制rollup插件，主要通过配置 `plugins` 和 `resolvePlugins` 实现；

```ts
module.exports = {
  plugins: {
    name: true | false | object
  }
}
```

1. 如果包名以`rollup-plugin-`开头，则键应该没有`rollup-plugin-`前缀。
2. 如果包名以`@`开头，请使用完整的包名，内置插件除外。
3. `@svgr/rollup`做了特殊处理，请使用`svgr`。

该值将用作其选项，传递true相当于一个空对象，false用于禁用内置插件。

插件支持通过配置，调整插件的顺序

```ts
// 将插件插入指定插件的前面
beforePosition: string;
// 将插件插入指定插件的后面
afterPosition: string;
```

```ts
module.exports = {
  plugins: {
    postcss: {},
    vue: {},
    typescript2: {
      beforePosition: 'postcss'
    }
  }
}

// 插件顺序如下
// typescript2 - postcss - vue
```

## 📝 配置项: 

### cwd

- 描述: 编译的工作目录
- 类型: `string`
- 默认值: `process.cwd()`

### name

- 描述: UMD 和 IIFE 中公开的名称
- 类型: `string`
- 默认值: 

### entries

- 描述: 打包的入口文件
- 类型: `string[]`
- 默认值: 按照约定进行查找

### formats

- 描述: 打包的格式
- 类型: `('esm' | 'cjs' | 'umd')[]`
- 默认值: `['esm', 'cjs', 'umd']`

### tsconfig

- 描述: 指定`tsconfig.json`文件路径
- 类型: `string`
- 默认值: 默认使用当前工作路径下的`tsconfig.json`

### disableTypeCheck

- 描述: 是否禁用类型检查
- 类型: `boolean`
- 默认值: `false`

### useDefaultTsconfig

- 描述: 是否使用默认的`tsconfig.json`
- 类型: `boolean`
- 默认值: `true`

### findTsconfig

- 描述: 是否向上查找`tsconfig.json`，与`useDefaultTsconfig`互斥
- 类型: `boolean`
- 默认值: `false`

### useConfigFile

- 描述: 是否使用配置文件，设置为`false`则不会读取配置文件
- 类型: `boolean`
- 默认值: `true`

### output

- 描述: 指定输出目录
- 类型: `string`
- 默认值: `dist`

### strict

- 描述: 是否开启严格模式
- 类型: `boolean`
- 默认值: `true`

### compress

- 描述: 是否压缩
- 类型: `boolean`
- 默认值: `true`

### sourcemap

- 描述: 是否生成sourcemap
- 类型: `boolean`
- 默认值: `true`

### banner

- 描述: 配置Banner
- 类型: `string | boolean | object`
- 默认值: `true`

### replace

- 描述: 替换代码配置
- 类型: `object`
- 默认值: `{}`

### cssModules

- 描述: 配置Banner
- 类型: `boolean | object`
- 默认值: `true`

### autoprefixer

- 描述: autoprefixer插件配置
- 类型: `object`
- 默认值: `{}`

### globals

- 描述: umd/iife 包中外部导入所需的变量名对
- 类型: `object`
- 默认值: `{}`

### externals

- 描述: 为 rollup 配置额外的 external
- 类型: `string[]`
- 默认值: `[]`

### target

- 描述: 配置是 node 库还是 browser 库，只作用于语法层
- 类型: `'node' | 'browser'`
- 默认值: `browser`

### filterPackages

- 描述: 过滤处理lerna包
- 类型: `object`
- 默认值: `{ stream: true, showPrivate: false }`

```
{
  /**
   * 是否按照依赖进行排序处理
   * @default true
   */
  stream?: boolean;
  /** 指定包含的包 */
  include?: string[];
  /** 指定排除的包 */
  exclude?: string[];
  /**
   * 是否包含私有的包
   * @default false
   */
  showPrivate?: boolean;
}
```

### alias

- 描述: 别名设置
- 类型: `object | array`
- 默认值: `@` 指向当前工作路径的`src`目录

```ts
// object
{ [find: string]: string }

// array
{
  find: string | RegExp;
  replacement: string;
}[]
```

### postcss

- 描述: rollup-plugin-postcss 配置参数
- 类型: `object`
- 默认值: 

## 🌴 约定

### 关于默认编译入口文件

默认的编译入口文件将按照以下顺序进行查找，这将会满足大部分的场景。

- `src/index.tsx`,
- `src/index.ts`,
- `src/index.jsx`,
- `src/index.js`,
- `index.tsx`,
- `index.ts`,
- `index.jsx`,
- `index.js`

### 配置优先级

配置文件 >> 命令行参数 >> 默认配置

### 关于 dependencies、peerDependencies 和 external

  - cjs 和 esm 格式，dependencies 和 peerDependencies 里的内容会被 external
  - umd 格式，只有 peerDependencies 会被 external