wcz-layout
Version:
123 lines (108 loc) • 7.08 kB
Markdown
---
name: general
description: "Use ALWAYS, before any other skill here, for every code change in this project. Defines the approved stack (TanStack, Vite+, MUI), TypeScript and naming conventions, date formatting, light/dark theming, testing and the validation command, and the src/ and tests/ folder layout that decides where each new file goes."
metadata:
type: convention
library: wcz-layout
---
> This is the default skill. Reference it in combination with more specific skills (e.g., `forms`, `table`, `dialogs`, etc.) for targeted tasks. For the full catalogue of every `wcz-layout` import subpath and what it exports, read [references/exports.md](references/exports.md).
## Preferred Technology Stack
Favor the established platform before introducing custom code or a new dependency:
- **TanStack ecosystem:** Reach for the TanStack library that owns the problem instead of hand-rolling it — Start for the full-stack app and server functions, Router for routing and route-level data loading, DB for client-side collections and live queries, AI for LLM-backed chat and streaming, Form for form state and validation, Hotkeys for keyboard shortcuts, Virtual for long lists and grids, Pacer for debouncing, throttling, rate limiting and queueing.
- **Vite+:** Use Vite+ for the development server, formatting, linting and testing.
- **Material UI:** Use Material UI for interface components and icons. When an advanced capability is needed, consider MUI X Charts for data visualization, Tree View for hierarchical data, Scheduler for calendars and timelines, and Chat for AI-powered conversations.
When the requirement is not covered above, look for an existing library before writing any logic. Prefer a well-maintained, widely adopted, typed library over custom implementations, even for seemingly simple functionality where a library can reduce edge cases and bugs. If a suitable library exists, install it and use it. Only implement the functionality yourself when it takes a few lines or no suitable library exists.
## Coding Conventions
- Write strict ES2023 TypeScript. Preserve local inference, type public boundaries and never use explicit `any`.
- Stick to double quotes, semicolons, and the `~/` alias for `src/` imports.
- Avoid `useMemo` / `useCallback`; the React Compiler handles memoization.
- Keep code self-documenting; only add comments to clarify non-obvious intent.
- Run the narrow relevant test, then `vp check --fix`. It formats, lints and type-checks.
## User Interface
- Translate every user-facing string via `useTranslation` (or `t` outside components).
- Format all client-side dates with `"L LT"` or `"L"`.
- Build skeletons for loading states.
- When building UI, always design for both light and dark mode; this app uses `colorSchemeSelector: "data-mui-color-scheme"`, so prefer `theme.applyStyles("dark", ...)` for mode-specific styling.
- Always design for desktop and mobile, using responsive layouts and breakpoints to keep the UI usable on any screen.
## Testing
- Tests run on `vp test` (bundled in vite-plus).
## File Organization
Use this ownership model for new application code. Keep feature-specific code close to its route; promote it to a root directory only when it is shared across multiple features. One database table = one file per layer: every `<table>` slot below is the same singular camelCase table name, never grouped with its parent or child tables.
```txt
src/ # client-first architecture
├── components/ # shared components across multiple routes
├── db/ # TanStack DB
│ ├── collections/ # collection descriptors
│ │ └── <table>.ts
│ ├── queries/ # live query option objects
│ │ └── <table>.ts
│ └── persistence.ts # browser SQLite persistence
├── env.ts # clientEnv + serverEnv via createEnv
├── hooks/ # shared hooks across multiple routes
│ └── useTheme.ts # MUI theme + color schemes
├── lib/ # isomorphic/shared logic usable by client and server
│ ├── auth/
│ │ ├── permissions.ts # as const satisfies Permissions
│ │ └── scopes.ts # as const satisfies Scopes
│ ├── locales/
│ │ ├── cs.json
│ │ └── en.json
│ └── schemas/ # shared Zod schemas
│ └── <table>.ts
├── router.tsx # QueryClient, DbClient, router options
├── routes/ # TanStack Router file-based routing
│ ├── __root.tsx
│ ├── index.tsx
│ ├── login.tsx # required by requireAuth
│ ├── auth/ # OAuth handlers
│ │ ├── login.ts
│ │ ├── callback.ts
│ │ └── logout.ts
│ ├── api/ # REST API routes (only when a public API is required)
│ │ └── features/
│ │ ├── index.ts
│ │ └── $id.ts
│ └── features/ # feature folder with multiple routes (kebab-case, plural)
│ ├── -components/ # route-specific components
│ ├── -hooks/ # route-specific hooks
│ ├── index.tsx
│ ├── create.tsx
│ ├── $id.tsx
│ └── edit.$id.tsx
├── server/ # server-only code, never imported from a component
│ ├── actions/
│ │ └── <table>.ts
│ ├── db/
│ │ ├── migrations/
│ │ ├── schemas/ # Drizzle schemas
│ │ │ ├── <table>.ts
│ │ │ └── relations.ts
│ │ └── index.ts # pool, search_path, auto-migrate
│ └── middleware/
│ └── databaseMiddleware.ts # app-local, not a library export
├── start.ts # request middleware, incl. CSRF
├── types/
│ ├── i18next.d.ts # types t() against en.json
│ └── wcz-layout.d.ts # declares virtual:wcz-layout
tests/
├── unit/
│ ├── lib/
│ │ └── schemas/
│ │ └── <table>.test.ts
│ ├── hooks/
│ │ └── useX.test.ts
│ └── routes/
│ └── features/
│ └── -components/
│ └── XCard.test.tsx
├── integration/
│ ├── server/
│ │ └── actions/
│ │ └── <table>.test.ts
│ └── db/
│ └── collections/
│ └── <table>.test.ts
└── e2e/
└── features/
└── create.spec.ts
```