chainsafe-typescript-architect
Architectural guidance for designing TypeScript projects at ChainSafe (Lodestar, web3.js 4.x, ssz, bls, filsnap, other TS projects). Use this skill whenever the user is starting a new TypeScript project, designing a TS package, structuring a Yarn 3 monorepo workspace, picking ESM vs CJS, deciding on type strictness baseline, designing public APIs with branded types, choosing testing frameworks, or writing an ADR for TS work. EVEN IF the user does not explicitly say "architecture" — triggers on "design a TS package", "new TS project", "Lodestar architecture", "monorepo setup", "Yarn workspaces", "ESM or CJS", "branded types", "public API design", "ADR for TypeScript", "tsconfig strict baseline", "type-level tests". Defers to .invariants for invariants themselves. Do NOT use for line-level TS coding (use chainsafe-typescript-developer) or TS PR review (use chainsafe-typescript-reviewer).
소스 정보
- 저장소
- ChainSafe/engineering-handbook
- 최근 소스 활동
- 2026년 7월 20일 11:44
- 감지된 SKILL.md 언어
- 영어
- 스타
- 7
- 포크
- 1
설치 방법
기본적으로 소스를 먼저 확인하는 Prompt가 선택됩니다. 직접 명령으로 전환하거나 로컬 사본을 다운로드할 수도 있습니다.
소스 파일 검토
설치 여부를 결정하기 전에 SKILL.md와 SkillsMP에 표시된 보조 파일을 읽어 보세요.
SKILL.md 표시 중
SKILL.md
소스 지침 · 읽기 전용 미리보기- name
- chainsafe-typescript-architect
- description
- Architectural guidance for designing TypeScript projects at ChainSafe (Lodestar, web3.js 4.x, ssz, bls, filsnap, other TS projects). Use this skill whenever the user is starting a new TypeScript project, designing a TS package, structuring a Yarn 3 monorepo workspace, picking ESM vs CJS, deciding on type strictness baseline, designing public APIs with branded types, choosing testing frameworks, or writing an ADR for TS work. EVEN IF the user does not explicitly say "architecture" — triggers on "design a TS package", "new TS project", "Lodestar architecture", "monorepo setup", "Yarn workspaces", "ESM or CJS", "branded types", "public API design", "ADR for TypeScript", "tsconfig strict baseline", "type-level tests". Defers to .invariants for invariants themselves. Do NOT use for line-level TS coding (use chainsafe-typescript-developer) or TS PR review (use chainsafe-typescript-reviewer).
- metadata
- {"type":"role-workflow","language":"typescript","role":"architect","source":"languages/typescript/architect.md","authored-via":"anthropic-skills:skill-creator (2026-05-27)"}
# TypeScript Architect
Use this when designing TypeScript systems at ChainSafe — Lodestar-shaped work or any TS package/library/app. Full reference: [`languages/typescript/architect.md`](../../languages/typescript/architect.md).
## Key TypeScript-specific decisions
### Project layout
- **Monorepo:** Yarn 3 workspaces. (`lerna` is deprecated at ChainSafe.)
- **Root `package.json`** with `"packageManager": "yarn@3.x"` and `"workspaces": ["packages/*"]`.
- Each package: own `package.json`, `src/`, `test/`, `tsconfig.json`.
- Shared dev tooling (ESLint, Prettier, base tsconfig) at root; extended per-package.
- TypeScript build via `tsc -b` (composite projects) or bundler.
### Type strictness baseline
- **`"strict": true`** — non-negotiable floor.
- **`"noUncheckedIndexedAccess": true`** — array indexing returns `T | undefined`.
- **`"exactOptionalPropertyTypes": true`** when the project can take it.
- **`"isolatedModules": true`** for bundler compatibility.
### Module system
- **ESM by default** for new projects. `"type": "module"` in `package.json`, `.js` extensions in import paths.
- **CJS only** where downstream consumers require it.
- **Dual-publish** (`main` + `module` + `exports`) for libraries needing both.
### Branded types
```ts
type UserId = string & { readonly __brand: "UserId" };
type OrderId = string & { readonly __brand: "OrderId" };
```
Domain identifiers must not be interchangeable. Branded types enforce at the type level with zero runtime cost.
### Error model
- Throw `Error` subclasses (not plain `Error`) so callers can `instanceof` discriminate.
- `Result<T, E>` types for libraries where error-as-value semantics fit; throw for binary entrypoints.
- `AggregateError` for `Promise.allSettled` multi-error cases.
- Never throw strings or non-`Error` objects.
### Async
- `async`/`await` over raw promises for readability.
- `Promise.all` for parallel independent work.
- `Promise.allSettled` when partial failure is acceptable.
- No floating promises. ESLint's `no-floating-promises` catches.
- `AbortSignal` for cancellation propagation.
### Public API
- Type-level tests (`tsd`, `expect-type`) for libraries publishing types.
- Re-exports through a single `index.ts` per package.
- `@internal` JSDoc tag for tooling-exported items not in public API.
## ADR template for TypeScript work
- Public surface — what's exported. Type-level tests covering it.
- Async commitments — where cancellation propagates; where parallelism is exploited.
- Error contract — thrown types vs returned types.
- Build target — Node version, browser support, ESM/CJS, bundler.
- Invariants impacted — deep links into `.invariants`.
## Anti-patterns at design time
- `any` in committed code.
- `as` type assertions without runtime checks.
- Unbounded `Promise.all` over a large input calling a rate-limited API.
- Default exports.
- `enum` when a const object + `as const` produces better types.
- `tsc --noEmit` not in CI.
## Related
- Full reference: [`languages/typescript/architect.md`](../../languages/typescript/architect.md)
- Sister roles: `chainsafe-typescript-developer`, `chainsafe-typescript-reviewer`
- Framework: [`invariants/invariants-framework.md`](../../invariants/invariants-framework.md)
- Workflow: `chainsafe-research-plan-implement`
GitHub에서 보기