---
alwaysApply: true
---
{
"name": "General Node.js/TypeScript Guidelines",
"description": "General coding standards and best practices for Node.js and TypeScript projects.",
"patterns": [
"/*.ts",
"/.tsx",
"**/.js",
"package.json",
"tsconfig.json",
"README.md"
],
"priority": "medium",
"alwaysActive": true,
"instructions": [
"This project is a modern Node.js application built with TypeScript and ES modules. Follow the guidelines below so Cursor (and future contributors) can reliably work in this repository.",
"",
"## Language, Tooling, and Project Layout",
"- Prefer TypeScript with `\"module\": \"ESNext\"` and `strict` compiler options. Only fall back to JavaScript for generated code or when a dependency forces it.",
"- Keep source under `src/`, emit build output to `dist/`, and never check compiled artifacts into git unless explicitly required.",
"- Use `pnpm` or `npm` with lockfiles committed. Add scripts for `build`, `dev`, `lint`, `test`, and `start` so automation can run common tasks consistently.",
"- Configure ESLint + Prettier (or biome) with sensible defaults (imports ordering, no-unused-vars, etc.) and ensure they run in CI.",
"- Keep secrets, tokens, and machine-specific config in `.env` files that are excluded via `.gitignore`. Provide `.env.example` with documented variables.",
"",
"## Dependency Management",
"- Avoid `any`. When interacting with third-party libraries, create lightweight type definitions or wrappers.",
"- Prefer small, focused modules over monolithic files. Group related utilities under directories (e.g., `lib/`, `services/`, `routes/`).",
"- Add runtime guards or zod/valibot schemas when consuming untyped JSON (APIs, env vars). Fail fast with descriptive errors when configuration is invalid.",
"- Keep dependencies minimal; question every addition. Use `devDependencies` for build/test tooling.",
"",
"## Application Design & Observability",
"- Centralize configuration (env var parsing, defaults) in a dedicated module and validate on startup.",
"- Add structured logging (debug/info/warn/error) with log level controlled by env (`LOG_LEVEL`). Do not log secrets. Prefer libraries like `pino` or `winston`, or a tiny custom logger.",
"- Instrument critical operations (HTTP calls, database queries, background jobs) with timings and context IDs so issues are diagnosable.",
"- Write idempotent logic where possible; external calls should handle retries and timeouts.",
"- Enforce graceful shutdown: listen for `SIGINT`/`SIGTERM`, close servers, flush logs, and exit with appropriate codes.",
"",
"## Testing & Quality",
"- Require unit tests for core logic (parsers, providers, services) and follow TDD whenever practical: write/adjust tests before implementing or fixing behavior.",
"- Add integration tests for critical flows (API endpoints, persistence) using mocks or local containers as needed. Document how to run them.",
"- Keep CI fast: run lint, type-check, unit tests, and (optionally) integration tests. Block merges on failures and target ≥80% statement coverage for touched modules.",
"- When fixing a bug, add a regression test.",
"",
"## Documentation & Developer Experience",
"- Maintain `README.md` with quickstart, scripts, env variable descriptions, and deployment instructions.",
"- Include architecture notes or ADRs for non-trivial decisions (e.g., queue selection, caching strategy).",
"- Provide onboarding scripts (`npm run setup`, seeding scripts) when additional steps are needed beyond install/build.",
"- Document any required external services (databases, queues, APIs) and how to run them locally (Docker Compose, mocks, etc.).",
"- After each implementation phase, review and update README, IMPLEMENTATION_PLAN, and other docs to reflect the current state (new tools, commands, env vars, testing requirements). Open a tracking issue if a doc change is deferred.",
"",
"## Security & Compliance",
"- Never store secrets in repo history. Use env vars or secret managers.",
"- Keep dependencies patched; run `npm audit` or similar regularly and document your policy for handling high/critical findings.",
"- Validate and sanitize all external input (HTTP requests, CLI args). Prefer centralized validation middleware.",
"- Follow the principle of least privilege when configuring API keys, database users, or cloud roles.",
"",
"## Collaboration",
"- Keep commits focused; describe both the \"what\" and \"why\". Avoid mixing refactors with feature work unless necessary.",
"- When creating new modules or services, add minimal inline comments for complex logic and ensure public APIs are documented via JSDoc/TSDoc.",
"- Prefer feature flags or configuration toggles for risky changes so they can be rolled out safely.",
"- Ensure automated formatting/linting hooks (e.g., via Husky) do not introduce friction; provide `npm run lint -- --fix` instructions in the README.",
"",
"Following these rules keeps the project easy to reason about, secure, and pleasant to contribute to for both humans and AI collaborators."
]
}
