|
| 1 | +--- |
| 2 | +description: 'Guidelines for TypeScript Development targeting TypeScript 5.x and ES2022 output' |
| 3 | +applyTo: '**/*.ts' |
| 4 | +--- |
| 5 | + |
| 6 | +# TypeScript Development |
| 7 | + |
| 8 | +> These instructions assume projects are built with TypeScript 5.x (or newer) compiling to an ES2022 JavaScript baseline. Adjust guidance if your runtime requires older language targets or down-level transpilation. |
| 9 | +
|
| 10 | +## Core Intent |
| 11 | + |
| 12 | +- Respect the existing architecture and coding standards. |
| 13 | +- Prefer readable, explicit solutions over clever shortcuts. |
| 14 | +- Extend current abstractions before inventing new ones. |
| 15 | +- Prioritize maintainability and clarity, short methods and classes, clean code. |
| 16 | + |
| 17 | +## General Guardrails |
| 18 | + |
| 19 | +- Target TypeScript 5.x / ES2022 and prefer native features over polyfills. |
| 20 | +- Use pure ES modules; never emit `require`, `module.exports`, or CommonJS helpers. |
| 21 | +- Rely on the project's build, lint, and test scripts unless asked otherwise. |
| 22 | +- Note design trade-offs when intent is not obvious. |
| 23 | + |
| 24 | +## Project Organization |
| 25 | + |
| 26 | +- Follow the repository's folder and responsibility layout for new code. |
| 27 | +- Use kebab-case filenames (e.g., `user-session.ts`, `data-service.ts`) unless told otherwise. |
| 28 | +- Keep tests, types, and helpers near their implementation when it aids discovery. |
| 29 | +- Reuse or extend shared utilities before adding new ones. |
| 30 | + |
| 31 | +## Naming & Style |
| 32 | + |
| 33 | +- Use PascalCase for classes, interfaces, enums, and type aliases; camelCase for everything else. |
| 34 | +- Skip interface prefixes like `I`; rely on descriptive names. |
| 35 | +- Name things for their behavior or domain meaning, not implementation. |
| 36 | + |
| 37 | +## Formatting & Style |
| 38 | + |
| 39 | +- Run the repository's lint/format scripts (e.g., `npm run lint`) before submitting. |
| 40 | +- Match the project's indentation, quote style, and trailing comma rules. |
| 41 | +- Keep functions focused; extract helpers when logic branches grow. |
| 42 | +- Favor immutable data and pure functions when practical. |
| 43 | + |
| 44 | +## Type System Expectations |
| 45 | + |
| 46 | +- Avoid `any` (implicit or explicit); prefer `unknown` plus narrowing. |
| 47 | +- Use discriminated unions for realtime events and state machines. |
| 48 | +- Centralize shared contracts instead of duplicating shapes. |
| 49 | +- Express intent with TypeScript utility types (e.g., `Readonly`, `Partial`, `Record`). |
| 50 | + |
| 51 | +## Async, Events & Error Handling |
| 52 | + |
| 53 | +- Use `async/await`; wrap awaits in try/catch with structured errors. |
| 54 | +- Guard edge cases early to avoid deep nesting. |
| 55 | +- Send errors through the project's logging/telemetry utilities. |
| 56 | +- Surface user-facing errors via the repository's notification pattern. |
| 57 | +- Debounce configuration-driven updates and dispose resources deterministically. |
| 58 | + |
| 59 | +## Architecture & Patterns |
| 60 | + |
| 61 | +- Follow the repository's dependency injection or composition pattern; keep modules single-purpose. |
| 62 | +- Observe existing initialization and disposal sequences when wiring into lifecycles. |
| 63 | +- Keep transport, domain, and presentation layers decoupled with clear interfaces. |
| 64 | +- Supply lifecycle hooks (e.g., `initialize`, `dispose`) and targeted tests when adding services. |
| 65 | + |
| 66 | +## External Integrations |
| 67 | + |
| 68 | +- Instantiate clients outside hot paths and inject them for testability. |
| 69 | +- Never hardcode secrets; load them from secure sources. |
| 70 | +- Apply retries, backoff, and cancellation to network or IO calls. |
| 71 | +- Normalize external responses and map errors to domain shapes. |
| 72 | + |
| 73 | +## Security Practices |
| 74 | + |
| 75 | +- Validate and sanitize external input with schema validators or type guards. |
| 76 | +- Avoid dynamic code execution and untrusted template rendering. |
| 77 | +- Encode untrusted content before rendering HTML; use framework escaping or trusted types. |
| 78 | +- Use parameterized queries or prepared statements to block injection. |
| 79 | +- Keep secrets in secure storage, rotate them regularly, and request least-privilege scopes. |
| 80 | +- Favor immutable flows and defensive copies for sensitive data. |
| 81 | +- Use vetted crypto libraries only. |
| 82 | +- Patch dependencies promptly and monitor advisories. |
| 83 | + |
| 84 | +## Configuration & Secrets |
| 85 | + |
| 86 | +- Reach configuration through shared helpers and validate with schemas or dedicated validators. |
| 87 | +- Handle secrets via the project's secure storage; guard `undefined` and error states. |
| 88 | +- Document new configuration keys and update related tests. |
| 89 | + |
| 90 | +## UI & UX Components |
| 91 | + |
| 92 | +- Sanitize user or external content before rendering. |
| 93 | +- Keep UI layers thin; push heavy logic to services or state managers. |
| 94 | +- Use messaging or events to decouple UI from business logic. |
| 95 | + |
| 96 | +## Testing Expectations |
| 97 | + |
| 98 | +- Add or update unit tests with the project's framework and naming style. |
| 99 | +- Expand integration or end-to-end suites when behavior crosses modules or platform APIs. |
| 100 | +- Run targeted test scripts for quick feedback before submitting. |
| 101 | +- Avoid brittle timing assertions; prefer fake timers or injected clocks. |
| 102 | + |
| 103 | +## Performance & Reliability |
| 104 | + |
| 105 | +- Lazy-load heavy dependencies and dispose them when done. |
| 106 | +- Defer expensive work until users need it. |
| 107 | +- Batch or debounce high-frequency events to reduce thrash. |
| 108 | +- Track resource lifetimes to prevent leaks. |
| 109 | + |
| 110 | +## Documentation & Comments |
| 111 | + |
| 112 | +- Add JSDoc to public APIs; include `@remarks` or `@example` when helpful. |
| 113 | +- Write comments that capture intent, and remove stale notes during refactors. |
| 114 | +- Update architecture or design docs when introducing significant patterns. |
0 commit comments