isentinel

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

isentinel Preferences

isentinel 偏好设置

Opinionated tooling and patterns for roblox-ts development.

针对roblox-ts开发的指导性工具链与编码模式。

Quick Summary

快速概览

Category	Preference
Package Manager	pnpm (bun as optional runtime)
Language	TypeScript (strict + extra checks)
TypeScript Config	@isentinel/tsconfig
Linting	@isentinel/eslint-config (no Prettier)
Testing	Jest-roblox, TDD approach
Git Hooks	husky + lint-staged
Commits	Conventional Commits

分类	偏好设置
包管理器	pnpm（bun可作为可选运行时）
语言	TypeScript（严格模式 + 额外检查）
TypeScript 配置	@isentinel/tsconfig
代码检查	@isentinel/eslint-config（无需Prettier）
测试	Jest-roblox，测试驱动开发（TDD）方式
Git 钩子	husky + lint-staged
提交规范	Conventional Commits

Package Manager (pnpm)

包管理器（pnpm）

Use pnpm as the package manager. Can use bun as runtime for scripts.

使用pnpm作为包管理器。可使用bun作为脚本运行时。

@antfu/ni

Use

@antfu/ni

for unified package manager commands (It auto-detects the package manager (pnpm/npm/yarn/bun) based on lockfile):

Command	Description
`ni`	Install dependencies
`ni <pkg>`	Add dependency
`ni -D <pkg>`	Add dev dependency
`nr <script>`	Run script
`nu`	Upgrade dependencies
`nun <pkg>`	Uninstall dependency
`nci`	Clean install
`nlx <pkg>`	Execute package

使用

@antfu/ni

统一包管理器命令（它会根据锁文件自动检测包管理器（pnpm/npm/yarn/bun））：

命令	描述
`ni`	安装依赖
`ni <pkg>`	添加依赖
`ni -D <pkg>`	添加开发依赖
`nr <script>`	运行脚本
`nu`	升级依赖
`nun <pkg>`	卸载依赖
`nci`	干净安装（重新安装）
`nlx <pkg>`	执行包命令

TypeScript

Use

@isentinel/tsconfig

with the roblox preset. Strict mode plus additional checks:

```
exactOptionalPropertyTypes
```
```
noUncheckedIndexedAccess
```
```
noPropertyAccessFromIndexSignature
```
```
noImplicitOverride
```
```
noImplicitReturns
```
```
noFallthroughCasesInSwitch
```

json

{
	"extends": "@isentinel/tsconfig/roblox"
}

使用带roblox预设的

@isentinel/tsconfig

。开启严格模式并启用额外检查：

```
exactOptionalPropertyTypes
```
```
noUncheckedIndexedAccess
```
```
noPropertyAccessFromIndexSignature
```
```
noImplicitOverride
```
```
noImplicitReturns
```
```
noFallthroughCasesInSwitch
```

json

{
	"extends": "@isentinel/tsconfig/roblox"
}

Linting

代码检查

Use

@isentinel/eslint-config

. No Prettier - ESLint handles formatting.

// eslint.config.ts
import { isentinel } from "@isentinel/eslint-config";

export default isentinel();

Fix errors with

nr lint --fix

使用

@isentinel/eslint-config

。无需Prettier - ESLint会处理代码格式化。

// eslint.config.ts
import { isentinel } from "@isentinel/eslint-config";

export default isentinel();

使用

nr lint --fix

修复错误。

Error Handling

错误处理

Prefer assertions over silent failing. Fail fast, fail loud.

See error-handling.md for patterns.

优先使用断言而非静默失败。快速失败，明确报错。

查看error-handling.md获取相关模式。

Test-Driven Development

测试驱动开发（TDD）

Red → Green → Refactor:

Write a failing test
Write minimal code to pass
Refactor with test protection

红 → 绿 → 重构：

编写一个失败的测试用例
编写最少代码使测试通过
在测试的保障下重构代码

Simplicity Rules (in order)

简洁性规则（优先级排序）

Passes all tests
Expresses intent clearly
Contains no duplication
Has minimum elements

Three similar lines of code is better than a premature abstraction.

See testing.md for Jest-roblox setup.

通过所有测试
清晰表达代码意图
无代码重复
代码元素最小化

三行相似的代码比过早的抽象更优。

查看testing.md获取Jest-roblox的设置方法。

References

参考文档

Topic	Reference
Tooling details	tooling.md
TypeScript config	typescript.md
Linting rules	linting.md
Testing (TDD)	testing.md
Error handling	error-handling.md

主题	参考文档
工具链详情	tooling.md
TypeScript 配置	typescript.md
代码检查规则	linting.md
测试（TDD）	testing.md
错误处理	error-handling.md