PWA Agent Guide

Overview

Progressive Web App for The Blue Alliance, a data archive site for the FIRST Robotics Competition, built with TanStack Start / Router, TypeScript, and Tailwind CSS.

Tech Stack

Framework: TanStack Start / Router
Styling: Tailwind CSS v4, Shadcn UI, Radix UI
API: Auto-generated OpenAPI clients in
```
app/api/tba/{read,mobile}/
```
Data Fetching: TanStack Query
Type Safety: TypeScript with strict mode

Project Structure

app/
  ├── routes/           # File-based routing
  ├── components/
  │   ├── ui/          # Shadcn/Radix components
  │   └── tba/         # TBA-specific components
  ├── lib/             # Utilities and helpers
  └── api/             # Generated API clients
tests/                 # Playwright E2E tests

Key Conventions

Tests must accompany every change - no code changes without corresponding tests
Use functional components with TypeScript interfaces (not types)
Mobile-first responsive design with Tailwind
```
~/
```
alias resolves to
```
app/
```
directory
NEVER modify autogenerated code - regenerate via
```
./generate-api.sh
```
Components use declarative JSX with minimal curly braces

Linting & Formatting

ESLint

No relative imports - use
```
~/
```
alias instead of
```
../
```
TypeScript strict mode - no non-null assertions, proper error handling
React Hooks - proper hooks usage and dependencies
Accessibility - JSX a11y standards
Console statements are warnings only
Autogenerated code in
```
app/api/tba/
```
is ignored by linter

Prettier

Auto-sorts imports - external → icons → local, with separations
Tailwind class sorting - via prettier-plugin-tailwindcss
Style: single quotes, semicolons, trailing commas
Formats Tailwind in
```
clsx()
```
,
```
cn()
```
,
```
cva()
```
functions

Vite

Icons: Use
```
~icons/{collection}/{name}
```
- search at icon-sets.iconify.design
Env vars: Required:
```
VITE_TBA_API_READ_KEY
```
(copy
```
default.env
```
to
```
.env
```
)

Adding Environment Variables

Add example to
```
default.env
```
Add type to
```
app/vite-env.d.ts
```
Add validator to
```
vite.config.ts
```
Reference with
```
import.meta.env.VITE_MY_VAR
```

Dependencies

Node.js: Version pinned to
```
22.14.0
```
(see
```
package.json
```
engines field)
npm packages: Always pin to specific versions (e.g.,
```
"react": "19.2.0"
```
, not
```
"^19.2.0"
```
)

Testing

Playwright tests in
```
./tests/
```
Test names with
```
mobile
```
run on mobile viewports
Run with
```
npx playwright test
```
or
```
--ui
```
for interactive mode

Running

npm run dev          # Development server
npm run typecheck    # Type checking
npm run lint         # Lint code
npx playwright test  # E2E tests

Project Structure

app/
  ├── routes/           # File-based routing
  ├── components/
  │   ├── ui/          # Shadcn/Radix components
  │   └── tba/         # TBA-specific components
  ├── lib/             # Utilities and helpers
  └── api/             # Generated API clients
tests/                 # Playwright E2E tests

Key Conventions

Tests must accompany every change - no code changes without corresponding tests

Use functional components with TypeScript interfaces (not types)

Mobile-first responsive design with Tailwind

~/

alias resolves to

app/

PWA Agent Guide

PWA Agent Guide

Overview

Tech Stack

Project Structure

Key Conventions

Linting & Formatting

ESLint

Prettier

Vite

Adding Environment Variables

Dependencies

Testing

Running

Related Skills

Markdown Converter

Nano Banana Pro

1password

PWA Agent Guide

Overview

Tech Stack

Project Structure

Key Conventions

Linting & Formatting

ESLint

Prettier

Vite

Adding Environment Variables

Dependencies

Testing

Running