erode-app/erode / .agents/skills/typescript-dev
typescript-dev
VerifiedTypeScript best practices: strict mode, ESLint rules, file naming, imports, type safety, Zod validation, error handling, and testing with Vitest. Use when writing TypeScript code, reviewing for code quality, fixing lint errors, creating types/interfaces, writing tests, or adding validation.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 5.7 KB |
SKILL.md
View on GitHub---
name: typescript-dev
description: >-
TypeScript best practices: strict mode, ESLint rules, file naming, imports,
type safety, Zod validation, error handling, and testing with Vitest.
Use when writing TypeScript code, reviewing for code quality, fixing lint
errors, creating types/interfaces, writing tests, or adding validation.
---
# TypeScript Development
## Strict Mode Essentials
Both projects use `strict: true` with these additional flags:
- `noUncheckedIndexedAccess` — array/record indexing returns `T | undefined`, must guard before use
- `noUnusedLocals` / `noUnusedParameters` — prefix unused with `_`
- `noImplicitReturns`, `noImplicitOverride`, `noFallthroughCasesInSwitch`, `noPropertyAccessFromIndexSignature` (erode)
```typescript
const items = ['a', 'b', 'c'];
const first = items[0]; // type: string | undefined
// ❌ first.toUpperCase() — might be undefined
// ✅ if (first !== undefined) { first.toUpperCase() }
```
## ESLint Rules
Both projects use `@typescript-eslint/strict-type-checked` + `stylisticTypeChecked`.
- **`eqeqeq`** — always use `===`/`!==` (erode allows `== null` via smart mode; forestry is strict)
- **`max-lines: 500`** (skipBlankLines, skipComments) — split files when approaching the limit
- **`no-unsafe-assignment`**, **`no-unsafe-member-access`** — never bypass with `as` casts
- **`restrict-template-expressions`** — only strings/numbers in template literals (erode allows numbers)
- **`prefer-nullish-coalescing`** — use `??` over `||` for nullable values
- Never suppress with `eslint-disable` — fix the root cause
```typescript
// ❌ Loose equality
if (value == '') { ... }
// ✅ Strict equality
if (value === '') { ... }
// ❌ Logical OR for nullable (falsy '' or 0 are lost)
const name = input || 'default';
// ✅ Nullish coalescing (only null/undefined trigger fallback)
const name = input ?? 'default';
```
## File Naming & Imports
Enforced via `eslint-plugin-check-file`:
- **kebab-case** for all `.ts`/`.tsx` files and `src/` folders
- **`.js` extensions** in all local ESM imports (required by both Node16 and NodeNext resolution)
```typescript
// ❌ Missing extension
import { validate } from './utils/validation';
// ✅ With .js extension
import { validate } from './utils/validation.js';
// ❌ File naming
src / utils / myHelper.ts;
src / UserService / index.ts;
// ✅ File naming
src / utils / my - helper.ts;
src / user - service / index.ts;
```
## Type Safety
- **Constrained types** over raw `string`/`number` — use literal unions, enums, or branded types for domain values with known sets
- **`unknown` over `any`** — then narrow with type guards or `instanceof`
- **`satisfies`** for type-checked object literals that preserve literal types
- **Before creating types:** search existing types, enums, and Zod schemas first — never duplicate
```typescript
// ❌ function setStatus(status: string) — raw string for known values
// ✅ type Status = 'pending' | 'active' | 'archived';
// function setStatus(status: Status)
// ❌ function handle(input: any) { return input.name; }
// ✅ function handle(input: unknown) {
// if (typeof input === 'object' && input !== null && 'name' in input) { ... }
// }
```
## Zod Validation
Schema-first pattern — define Zod schema, derive type with `z.infer<>`:
- `z.coerce` for string-to-number conversion (CLI args, query params)
- Wrap `schema.parse()` in a helper that converts `ZodError` to project error type
- Keep schemas in dedicated files (`src/schemas/` or `src/validation/`), not inline in business logic
```typescript
const ConfigSchema = z.object({
port: z.coerce.number().min(1).max(65535),
debug: z.boolean().default(false),
});
type Config = z.infer<typeof ConfigSchema>;
// Wrap parse in helper that converts ZodError to project error type
function validate<T>(schema: z.ZodType<T>, data: unknown): T {
try {
return schema.parse(data);
} catch (error) {
if (error instanceof z.ZodError) {
throw new AppError(`Validation failed: ${error.issues.map((i) => i.message).join(', ')}`);
}
throw error;
}
}
```
## Error Handling
Base error class with `code` (enum), `message`, and `context` metadata:
- Set `this.name` in constructor and call `Error.captureStackTrace`
- `static fromError(error: unknown)` factory for safely wrapping unknown errors
- Extend for domain-specific error types (config, API, validation)
```typescript
class AppError extends Error {
constructor(
message: string,
public readonly code: ErrorCode,
public readonly context: Record<string, unknown> = {}
) {
super(message);
this.name = 'AppError';
Error.captureStackTrace(this, AppError);
}
static fromError(error: unknown, code = ErrorCode.UNKNOWN): AppError {
if (error instanceof AppError) return error;
if (error instanceof Error)
return new AppError(error.message, code, { originalError: error.name });
return new AppError(String(error), code);
}
}
```
## Testing with Vitest
- Tests colocated near source in `__tests__/` directories
- Behavior-focused tests — test _what_ the code does, not _how_
- Test file naming: `*.test.ts`
- Use `.js` extensions in test imports too
## Avoid
- `any` type — use `unknown` and narrow
- `eslint-disable` comments — fix the root cause
- `as` type assertions to silence errors — use type guards or `satisfies`
- Duplicating existing types — search first
- `==` comparisons — use `===` (`== null` only in smart-mode projects)
- Files over 500 lines — split into focused modules
- Non-kebab-case file/folder names
- Missing `.js` extension in local imports
- Inline Zod schemas in business logic — keep in schema files
- Untyped catch blocks — `error` is `unknown`, narrow before use
- Raw `string`/`number` for domain values with known constrained sets
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the work | Stars: 321k | Updated | Claude CodeCodex | Verified | Install |
| systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixes | Stars: 321k | Updated | Claude CodeCodex | Verified | Install |
| test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation code | Stars: 321k | Updated | Claude CodeCodex | Verified | Install |
| skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy. | Stars: 197k | Updated | Claude CodeCodex | Verified | Install |