# @rhao/vite-toolkit

> Toolkit of vite

Latest version **2.0.0** (published 2024-01-10) · MIT license · 0 weekly downloads

## Install

```sh
npm install @rhao/vite-toolkit
pnpm add @rhao/vite-toolkit
yarn add @rhao/vite-toolkit
bun add @rhao/vite-toolkit
```

## Health

**Score 25/100 (F)** — status: abandoned.

Positive: has types; esm support; no vulnerabilities.

Warnings: low downloads.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 2.0.0 |
| Published | 2024-01-10 |
| First published | 2023-08-22 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | >=14 |
| Dependencies | 2 |
| Unpacked size | 184.9 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 1 |
| Author | RayHao |
| Maintainers | lei-hh |
| Keywords | toolkit, tools, vite, utils |

## Links

- npm: https://www.npmjs.com/package/@rhao/vite-toolkit
- Repository: https://github.com/l246804/vite-toolkit
- Issues: https://github.com/l246804/vite-toolkit/issues
- npm.io page: https://npm.io/package/@rhao/vite-toolkit

## Dependencies (2)

- [debug](https://npm.io/package/debug.md) ^4.3.4
- [@rhao/types-base](https://npm.io/package/@rhao/types-base.md) ^0.2.1

## Alternatives

- [lodash.assign](https://npm.io/package/lodash.assign.md) — 2.3M weekly downloads
- [lodash.chunk](https://npm.io/package/lodash.chunk.md) — 1.8M weekly downloads
- [react-native-ios-utilities](https://npm.io/package/react-native-ios-utilities.md) — 138.5K weekly downloads
- [@technically/lodash](https://npm.io/package/@technically/lodash.md) — 50.9K weekly downloads
- [@fluid-topics/ft-icon](https://npm.io/package/@fluid-topics/ft-icon.md) — 20.6K weekly downloads

## Recent versions

- 2.0.0 (latest) — 2024-01-10
- 1.0.0 — 2023-12-24
- 0.2.1 — 2023-11-14
- 0.2.0 — 2023-11-10
- 0.1.1 — 2023-10-27
- 0.1.0 — 2023-10-25
- 0.0.5 — 2023-08-23
- 0.0.4 — 2023-08-23
- 0.0.3 — 2023-08-23
- 0.0.2 — 2023-08-23
- 0.0.1 — 2023-08-22

## README

# `@rhao/vite-toolkit`

`vite` 配置工具包。

## 功能清单

- [x] 检查运行环境
- [x] 解析环境变量，支持 `JS` 原生数据类型
- [x] 环境变量挂载至 `process.env`
- [x] 转换开发服务器代理配置

## 示例

解析并挂载全局环境变量

> 注意：当允许将加载的环境变量挂在至 `process.env` 时，非 `string` 类型的数据将被 `JSON.stringify` 序列化为字符串！

```ts
// global.d.ts 定义全局类型文件
declare global {
  // 定义 vite 环境变量
  declare interface ViteEnv {
    VITE_APP_TITLE: string
    VITE_APP_TIMEOUT: number
  }

  // 推荐挂载至单一变量
  const __ENV__: ViteEnv
}

export {}
```

```shell
# .env.development
# 应用标题
VITE_APP_TITLE=应用标题
# 应用接口默认超时时间
VITE_APP_TIMEOUT=5000
# 应用代理
VITE_APP_PROXY=[{prefix: '/api', target: 'http://127.0.0.1:5555'}]
```

```ts
// vite.config.ts
import { defineConfig } from 'vite'
import { createToolkit } from '@rhao/vite-toolkit'

export default defineConfig((configEnv) => {
  const toolkit = createToolkit<ViteEnv>(configEnv, { allowMountToProcessEnv: true })

  /**
   * {
   *   VITE_APP_TITLE: '应用标题',
   *   VITE_APP_TIMEOUT: 5000,
   *   VITE_APP_PROXY: [{ prefix: '/api', target: 'http://127.0.0.1:5555' }]
   * }
   */
  const env = toolkit.loadEnv()

  return {
    // ...
    server: {
      // 根据环境变量转换服务代理配置
      proxy: toolkit.transformProxy(env.VITE_APP_PROXY),
    },

    define: {
      // 扁平化并挂载至全局环境变量
      ...toolkit.flattenEnv(env)
    }
  }
})
```

## 多文件共享唯一实例

用于在 `vite.config.ts` 中创建全局唯一工具实例，在其他文件中能够直接获取，避免繁琐的传递。

```ts
// vite.config.ts
import { defineConfig } from 'vite'
import { Toolkit } from '@rhao/vite-toolkit'

export default defineConfig((configEnv) => {
  const toolkit = Toolkit.createInstance<ViteEnv>(configEnv, { allowMountToProcessEnv: true })

  /**
   * {
   *   VITE_APP_TITLE: '应用标题',
   *   VITE_APP_TIMEOUT: 50000,
   *   VITE_APP_PROXY: [{ prefix: '/api', target: 'http://127.0.0.1:5555' }]
   * }
   */
  const env = toolkit.loadEnv()

  return {
    // ...
    define: {
      // 扁平化并挂载至全局环境变量
      ...toolkit.flattenEnv(env)
    }
  }
})
```

```ts
// plugin.ts
import { Toolkit } from '@rhao/vite-toolkit'

export function createPlugins() {
  const toolkit = Toolkit.getInstance<ViteEnv>()

  console.log(toolkit?.isDev())

  return [
    // ...
  ]
}
```

## 客户端使用

> 由于 `define` 提供的 `__ENV__` 会在编译时以字面量形式代替，当 `__ENV__` 是对象类型，多次使用会被硬编码进源码中，所以推荐使用提供的 `flattenEnv` 将环境变量扁平化后再挂载，可以达到完美效果。

> 由于 `define` 无法定义非 `.` 操作符的属性名，所以 `env` 需避免使用以数字开头或包含非字母、数字、下划线字符的属性名（`1name, a-1, $b`等）！

### 直接使用

```ts
// 编译前
// 第一次
console.log(__ENV__.VITE_APP_TITLE)

// 第二次
console.log(__ENV__.VITE_APP_TITLE)

// 编译后
// 第一次
console.log({ VITE_APP_TITLE: '应用标题', VITE_APP_TIMEOUT: 50000, VITE_APP_PROXY: [{ prefix: '/api', target: 'http://127.0.0.1:5555' }] }.VITE_APP_TITLE)

// 第二次
console.log({ VITE_APP_TITLE: '应用标题', VITE_APP_TIMEOUT: 50000, VITE_APP_PROXY: [{ prefix: '/api', target: 'http://127.0.0.1:5555' }] }.VITE_APP_TITLE)
```

### 扁平化环境变量

```ts
// vite.config.ts

export default defineConfig((configEnv) => {
  const toolkit = createToolkit(configEnv)
  const env = toolkit.loadEnv()
  return {
    // ...
    define: {
      ...toolkit.flattenEnv(env, '__ENV__')
    }
  }
})
```

```ts
// 编译前
// 第一次
console.log(__ENV__.VITE_APP_TITLE)

// 第二次
console.log(__ENV__.VITE_APP_TITLE)

// 编译后
// 第一次
console.log('应用标题')

// 第二次
console.log('应用标题')
```

## 迁移至 v1.x

- `flattenEnv()` 不再支持非普通对象类型数据的深度扁平化属性。

## 迁移至 v2.x

- `modeMapping` 被移除
- `getMode`、`eqMode` 更改使用方式
- `isDev`、`isProd` 更改实现方式

---
_Source: https://npm.io/package/@rhao/vite-toolkit · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._
