Skip to content

Commit 07ce4dc

Browse files
chenjiahanchenjiahan
committed
docs: add API reference
1 parent f8385c6 commit 07ce4dc

4 files changed

Lines changed: 222 additions & 0 deletions

File tree

‎website/docs/en/guide/_meta.json‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,11 @@
1313
"name": "configuration",
1414
"label": "Configuration"
1515
},
16+
{
17+
"type": "file",
18+
"name": "api-reference",
19+
"label": "API reference"
20+
},
1621
{
1722
"type": "dir-section-header",
1823
"name": "cli",

‎website/docs/en/guide/api-reference.mdx‎

Lines changed: 106 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,106 @@
1+
# API reference
2+
3+
Rstack provides a unified configuration API and re-exports the public APIs of Rsbuild, Rslib, Rstest, and Rslint through dedicated subpaths. Prefer these subpaths to direct imports from each tool's core package so that dependency entry points and tool versions remain aligned with Rstack.
4+
5+
## Import paths
6+
7+
| Import path | Contents | Use case |
8+
| ------------------------ | ------------------------------------------------- | --------------------------------------- |
9+
| `rstack` | Rstack configuration API | Register tool configurations |
10+
| `rstack/app` | Public APIs from `@rsbuild/core` | Build applications and extend Rsbuild |
11+
| `rstack/lib` | Public APIs from `@rslib/core` | Build libraries and extend Rslib |
12+
| `rstack/test` | Public APIs from `@rstest/core` | Write tests and configure test projects |
13+
| `rstack/lint` | Public APIs from `@rslint/core` | Use Rslint presets and plugins |
14+
| `rstack/types` | Project types shared by Rsbuild and Rslib | Type application and library sources |
15+
| `rstack/test/globals` | Global Rstest API declarations | Enable global test API types |
16+
| `rstack/test/importMeta` | `ImportMeta` declaration for `import.meta.rstest` | Type in-source tests |
17+
18+
## Main entry point
19+
20+
### `define`
21+
22+
Import `define` from `rstack` to register tool configurations in `rstack.config.ts`; see [Configuration APIs](./configuration#configuration-apis) for details.
23+
24+
## Re-exports
25+
26+
The tool-specific subpaths below re-export the public APIs from their corresponding core packages. Using these Rstack entry points keeps dependency entry points and tool versions aligned with the toolchain integrated by Rstack.
27+
28+
### `rstack/app`
29+
30+
`rstack/app` re-exports all public APIs from `@rsbuild/core`, including APIs for creating and controlling Rsbuild instances.
31+
32+
```ts
33+
import { createRsbuild, mergeRsbuildConfig } from 'rstack/app';
34+
```
35+
36+
For details, see the [Rsbuild core APIs](https://rsbuild.rs/api/javascript-api/core).
37+
38+
### `rstack/lib`
39+
40+
`rstack/lib` re-exports all public APIs from `@rslib/core`, including APIs for creating Rslib instances and merging Rslib configurations.
41+
42+
```ts
43+
import { createRslib, mergeRslibConfig } from 'rstack/lib';
44+
```
45+
46+
For details, see the [Rslib core APIs](https://rslib.rs/api/javascript-api/core).
47+
48+
### `rstack/test`
49+
50+
`rstack/test` re-exports all public APIs from `@rstest/core`, including APIs for defining tests, writing assertions, mocking modules, and merging test configurations.
51+
52+
```ts
53+
import { describe, expect, test } from 'rstack/test';
54+
```
55+
56+
See the [Rstest runtime API](https://rstest.rs/api/runtime-api/) for test APIs and the [Rstest core APIs](https://rstest.rs/api/javascript-api/rstest-core) for configuration helpers.
57+
58+
### `rstack/lint`
59+
60+
`rstack/lint` re-exports all public APIs from `@rslint/core`, including JavaScript and TypeScript presets and framework plugins.
61+
62+
```ts
63+
import { js, reactPlugin, ts } from 'rstack/lint';
64+
```
65+
66+
For details about the available presets and plugins, see [Rslint rules and presets](https://rslint.rs/config/rules-and-presets).
67+
68+
## TypeScript types
69+
70+
These type-only entry points add ambient declarations to a TypeScript project. Add only the entries your project needs to [`compilerOptions.types`](https://www.typescriptlang.org/tsconfig/#types) in `tsconfig.json`.
71+
72+
### `rstack/types`
73+
74+
`rstack/types` provides project-level declarations shared by Rsbuild and Rslib, including types for `import.meta.env` and static asset imports. Use it in place of `@rsbuild/core/types` or `@rslib/core/types`.
75+
76+
```json title="tsconfig.json"
77+
{
78+
"compilerOptions": {
79+
"types": ["rstack/types", "node"]
80+
}
81+
}
82+
```
83+
84+
### `rstack/test/globals`
85+
86+
`rstack/test/globals` declares Rstest APIs such as `test`, `expect`, and lifecycle hooks as globals. Add it when tests use these APIs without explicit imports.
87+
88+
```json title="tsconfig.json"
89+
{
90+
"compilerOptions": {
91+
"types": ["rstack/test/globals", "node"]
92+
}
93+
}
94+
```
95+
96+
### `rstack/test/importMeta`
97+
98+
`rstack/test/importMeta` augments `ImportMeta` with the optional `rstest` property, enabling `import.meta.rstest` in in-source tests.
99+
100+
```json title="tsconfig.json"
101+
{
102+
"compilerOptions": {
103+
"types": ["rstack/test/importMeta", "node"]
104+
}
105+
}
106+
```

‎website/docs/zh/guide/_meta.json‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,11 @@
1313
"name": "configuration",
1414
"label": "配置"
1515
},
16+
{
17+
"type": "file",
18+
"name": "api-reference",
19+
"label": "API 参考"
20+
},
1621
{
1722
"type": "dir-section-header",
1823
"name": "cli",

‎website/docs/zh/guide/api-reference.mdx‎

Lines changed: 106 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,106 @@
1+
# API 参考 \{#api-reference}
2+
3+
Rstack 提供统一的配置 API，并通过专用子路径重导出 Rsbuild、Rslib、Rstest 和 Rslint 的公开 API。建议优先从这些子路径导入，以统一依赖入口，并确保 API 与 Rstack 集成的工具版本保持一致。
4+
5+
## 导入路径 \{#import-paths}
6+
7+
| 导入路径 | 内容 | 使用场景 |
8+
| ------------------------ | ----------------------------------------- | ------------------------ |
9+
| `rstack` | Rstack 配置 API | 注册各项工具配置 |
10+
| `rstack/app` | `@rsbuild/core` 的公开 API | 构建应用及扩展 Rsbuild |
11+
| `rstack/lib` | `@rslib/core` 的公开 API | 构建库及扩展 Rslib |
12+
| `rstack/test` | `@rstest/core` 的公开 API | 编写测试及配置测试项目 |
13+
| `rstack/lint` | `@rslint/core` 的公开 API | 使用 Rslint 预设和插件 |
14+
| `rstack/types` | Rsbuild 与 Rslib 共用的项目类型 | 为应用和库的源码提供类型 |
15+
| `rstack/test/globals` | Rstest 全局 API 声明 | 启用全局测试 API 类型 |
16+
| `rstack/test/importMeta` | `import.meta.rstest` 的 `ImportMeta` 声明 | 为源码内测试提供类型 |
17+
18+
## 主入口 \{#main-entry-point}
19+
20+
### `define`
21+
22+
从 `rstack` 导入 `define`，用于在 `rstack.config.ts` 中注册各项工具配置；详细用法请参阅[配置 API](./configuration#configuration-apis)。
23+
24+
## 重导出 \{#re-exports}
25+
26+
以下工具子路径均会重导出对应 core 包的公开 API。通过这些 Rstack 入口导入，可以让依赖入口和工具版本与 Rstack 集成的工具链保持一致。
27+
28+
### `rstack/app`
29+
30+
`rstack/app` 重导出 `@rsbuild/core` 的全部公开 API，包括用于创建和控制 Rsbuild 实例的 API。
31+
32+
```ts
33+
import { createRsbuild, mergeRsbuildConfig } from 'rstack/app';
34+
```
35+
36+
具体用法请参阅 [Rsbuild 核心 API](https://rsbuild.rs/zh/api/javascript-api/core)。
37+
38+
### `rstack/lib`
39+
40+
`rstack/lib` 重导出 `@rslib/core` 的全部公开 API，包括用于创建 Rslib 实例和合并 Rslib 配置的 API。
41+
42+
```ts
43+
import { createRslib, mergeRslibConfig } from 'rstack/lib';
44+
```
45+
46+
具体用法请参阅 [Rslib 核心 API](https://rslib.rs/zh/api/javascript-api/core)。
47+
48+
### `rstack/test`
49+
50+
`rstack/test` 重导出 `@rstest/core` 的全部公开 API，包括用于定义测试、编写断言、模拟模块和合并测试配置的 API。
51+
52+
```ts
53+
import { describe, expect, test } from 'rstack/test';
54+
```
55+
56+
测试 API 请参阅 [Rstest 运行时 API](https://rstest.rs/zh/api/runtime-api/)，配置辅助 API 请参阅 [Rstest 核心 API](https://rstest.rs/zh/api/javascript-api/rstest-core)。
57+
58+
### `rstack/lint`
59+
60+
`rstack/lint` 重导出 `@rslint/core` 的全部公开 API，包括 JavaScript 和 TypeScript 预设以及框架插件。
61+
62+
```ts
63+
import { js, reactPlugin, ts } from 'rstack/lint';
64+
```
65+
66+
可用的预设和插件请参阅 [Rslint 规则和预设](https://rslint.rs/config/rules-and-presets)。
67+
68+
## TypeScript 类型 \{#typescript-types}
69+
70+
以下纯类型入口用于为 TypeScript 项目补充环境类型声明。请仅将项目需要的入口添加到 `tsconfig.json` 的 [`compilerOptions.types`](https://www.typescriptlang.org/tsconfig/#types) 中。
71+
72+
### `rstack/types`
73+
74+
`rstack/types` 提供 Rsbuild 与 Rslib 共用的项目级类型声明，包括 `import.meta.env` 和静态资源导入的类型。请使用该入口替代 `@rsbuild/core/types` 或 `@rslib/core/types`。
75+
76+
```json title="tsconfig.json"
77+
{
78+
"compilerOptions": {
79+
"types": ["rstack/types", "node"]
80+
}
81+
}
82+
```
83+
84+
### `rstack/test/globals`
85+
86+
`rstack/test/globals` 提供 `test`、`expect` 和生命周期钩子等 Rstest API 的全局声明。测试代码无需显式导入这些 API 时，请添加该入口。
87+
88+
```json title="tsconfig.json"
89+
{
90+
"compilerOptions": {
91+
"types": ["rstack/test/globals", "node"]
92+
}
93+
}
94+
```
95+
96+
### `rstack/test/importMeta`
97+
98+
`rstack/test/importMeta` 为 `ImportMeta` 增加可选的 `rstest` 属性，使源码内测试可以使用 `import.meta.rstest`。
99+
100+
```json title="tsconfig.json"
101+
{
102+
"compilerOptions": {
103+
"types": ["rstack/test/importMeta", "node"]
104+
}
105+
}
106+
```

0 commit comments

Comments
 (0)