Yisroel Baum
a225433cec
Document Attainly-specific TDD, worktree, Laravel, database, and future Vue conventions adapted from the youngstartup workflow.
90 lines
3.7 KiB
Markdown
90 lines
3.7 KiB
Markdown
# Frontend context
|
|
|
|
Read `ai/shared.md` first. This file covers frontend-specific rules.
|
|
|
|
## Current state
|
|
|
|
The Vue frontend has not been scaffolded yet. The backend has Inertia Laravel
|
|
installed and an Inertia route, but there is no `package.json`, Vue source
|
|
tree, Vite configuration, or frontend test setup.
|
|
|
|
- Do not create the frontend unless the user explicitly asks.
|
|
- Do not invent a frontend directory, package manager, dependency version, or
|
|
command before the scaffold establishes it.
|
|
- When the frontend is created, update this file with its actual paths,
|
|
package versions, scripts, and testing tools.
|
|
|
|
## Vue conventions
|
|
|
|
Apply these rules once a Vue 3 frontend exists:
|
|
|
|
- Use the Composition API and `<script setup lang="ts">`.
|
|
- Use PascalCase component filenames.
|
|
- Keep page, component, composable, and store responsibilities distinct.
|
|
- Prefer small components with explicit props and emitted events.
|
|
- Keep component styles scoped unless the scaffold establishes a deliberate
|
|
global styling system.
|
|
- Follow the routing and page conventions established by the chosen Inertia
|
|
or Vue Router scaffold. Do not mix the two approaches without an explicit
|
|
architectural reason.
|
|
- Inspect similar files before introducing a new component, composable, store,
|
|
or data-access pattern.
|
|
|
|
## TypeScript
|
|
|
|
- Enable and preserve strict mode.
|
|
- Do not use `any`. Model unknown external values as `unknown` and narrow or
|
|
validate them.
|
|
- Derive types from runtime schemas when a schema library is adopted. Do not
|
|
maintain a hand-written type that can drift from its validation schema.
|
|
- Validate payloads at trust boundaries, especially backend responses and
|
|
user-submitted forms.
|
|
- Keep request and response types close to the API or store boundary that owns
|
|
them.
|
|
- Add a path alias only when it is configured consistently in Vite,
|
|
TypeScript, tests, and Cypress.
|
|
|
|
## State and API access
|
|
|
|
- Use the state-management approach chosen by the scaffold consistently.
|
|
- Keep server data fetching and transformation at an API/store boundary, not
|
|
scattered through presentation components.
|
|
- Represent loading, empty, success, validation-error, and unexpected-error
|
|
states explicitly.
|
|
- Do not cast unchecked JSON directly to an application interface.
|
|
- Keep read and write payload types separate when their shapes differ.
|
|
|
|
## Testing
|
|
|
|
Use layered tests once the frontend test setup exists:
|
|
|
|
- Unit tests cover pure transformations, composables, store logic, computed
|
|
values, and formatting.
|
|
- Component tests cover rendering, events, form behavior, and conditional UI.
|
|
- Cypress tests cover routing, multi-page flows, and request wiring.
|
|
- Prefer the cheapest layer that proves the behavior.
|
|
- Import test functions explicitly rather than relying on globals unless the
|
|
scaffold deliberately configures globals.
|
|
- Build test data with small typed builders instead of repeated bare object
|
|
literals.
|
|
|
|
## Frontend/backend test boundary
|
|
|
|
- Mock backend requests in frontend tests.
|
|
- A frontend test should verify how the UI consumes a response and which
|
|
request it sends, not retest Laravel's business rules.
|
|
- Test backend persistence, validation, authentication, and mail behavior in
|
|
PHPUnit.
|
|
- Keep mocked response bodies typed against the frontend's exported API or
|
|
store types.
|
|
- When runtime schemas exist, parse mock-builder output through the same
|
|
schema so drift fails at the test boundary.
|
|
|
|
## Before completing frontend work
|
|
|
|
- Run the formatter, linter, type checker, unit tests, and Cypress scripts
|
|
defined by the frontend's `package.json`.
|
|
- Do not substitute a hand-picked subset for the repository's eventual full
|
|
frontend gate.
|
|
- If the frontend cannot run because the scaffold or a required service is
|
|
absent, report the precise environmental or baseline failure.
|