|
| 1 | +--- |
| 2 | +description: OpenAPI Qraft project conventions - architecture, TypeScript, and testing standards |
| 3 | +alwaysApply: true |
| 4 | +--- |
| 5 | + |
| 6 | +# OpenAPI Qraft Project Conventions |
| 7 | + |
| 8 | +## Project Overview |
| 9 | + |
| 10 | +OpenAPI Qraft is a monorepo that generates type-safe TanStack Query React hooks from OpenAPI documents. |
| 11 | + |
| 12 | +### Key Packages |
| 13 | + |
| 14 | +- `@openapi-qraft/cli` - CLI tool for code generation |
| 15 | +- `@openapi-qraft/react` - Runtime library with Proxy-based API client |
| 16 | +- `@openapi-qraft/plugin` - Core plugin infrastructure and OpenAPI processing |
| 17 | +- `@openapi-qraft/tanstack-query-react-plugin` - Service generator plugin |
| 18 | +- `@openapi-qraft/openapi-typescript-plugin` - TypeScript types generator |
| 19 | +- `@openapi-qraft/tanstack-query-react-types` - Shared type definitions |
| 20 | + |
| 21 | +## Architecture |
| 22 | + |
| 23 | +- **Monorepo**: Yarn 4 workspaces + Turbo for builds |
| 24 | +- **Module System**: ESM (`"type": "module"` in package.json) |
| 25 | +- **Bundling**: Rollup with SWC for runtime packages |
| 26 | +- **Internal Dependencies**: Use `workspace:*` for inter-package dependencies |
| 27 | + |
| 28 | +## TypeScript Conventions |
| 29 | + |
| 30 | +- **Strict Mode**: All packages use strict TypeScript |
| 31 | +- **Node Imports**: Use `node:` prefix for built-in modules (e.g., `import { sep } from 'node:path'`) |
| 32 | +- **Local Imports**: Use `.js` extension for local imports (e.g., `import { foo } from './foo.js'`) |
| 33 | +- **Import Order**: Managed by Prettier plugin - do not manually reorder |
| 34 | +- **React Imports**: Do NOT import default React (use named imports like `{ useState }`) |
| 35 | + |
| 36 | +## Testing |
| 37 | + |
| 38 | +- **Framework**: Vitest |
| 39 | +- **Test Location**: Either `*.test.ts` next to source or in `tests/` folder |
| 40 | +- **HTTP Mocking**: MSW (Mock Service Worker) for React client tests |
| 41 | +- **Test Naming**: Use English for test names and descriptions |
| 42 | + |
| 43 | +## Code Style |
| 44 | + |
| 45 | +- **Formatter**: Prettier with single quotes and ES5 trailing commas |
| 46 | +- **Comments**: Do not add comments unless explicitly requested |
| 47 | +- **Language**: English for all code, tests, and commit messages |
| 48 | + |
| 49 | +## Commands |
| 50 | + |
| 51 | +```bash |
| 52 | +yarn build # Build all packages |
| 53 | +yarn test # Run tests |
| 54 | +yarn lint # Run linting |
| 55 | +yarn typecheck # Type checking |
| 56 | +yarn dev # Development mode |
| 57 | +``` |
0 commit comments