CShare/AGENTS.md

Repository Guidelines

Commands

Run from cshare-app/:

npm run dev       # Vite dev server
npm run build     # Build + precompress (creates .gz/.br)
npm run check     # lint + build (run before committing)
npm run lint      # ESLint

Run from backend/:

npm run dev       # tsx watch src/server.ts
npm test          # tsx --test test/*.test.ts
npm run build     # tsc
npm run check     # test + build (run before committing)

Architecture

Two packages: cshare-app/ (React 19 + Vite 8, JavaScript/JSX, no TypeScript) and backend/ (Express 5 + TypeScript strict mode).

Backend storage: Currently uses local JSON (backend/data/db.json) and disk storage. PostgreSQL/Redis/R2 adapters are planned in CONTINUE.md but not yet implemented.

Frontend routing: React Router v7 with lazy-loaded routes. All routes defined in src/App.jsx.

Styling: Tailwind CSS 4 via @tailwindcss/vite plugin (not PostCSS). Custom design system in src/index.css with CSS variables and component classes (.btn, .card, .input).

Toast system: ToastProvider wraps app in App.jsx. Use useToast() hook → addToast(message, type) where type is 'success' | 'info' | 'error'.

API client: src/lib/api.js contains uploadFile (XHR with progress), listFiles, deleteFile, getDashboardStats, resolveLink, downloadUrl, previewUrl.

Environment

Frontend: Set VITE_API_BASE_URL=http://localhost:4001 only when API runs on different port. Omit in production if using Nginx reverse proxy (frontend calls window.location.origin).

Backend: Requires .env with JWT_ACCESS_SECRET, JWT_REFRESH_SECRET, ADMIN_API_KEY (64+ char random strings). See backend/.env.example.

Build gotcha: dist/ may be owned by root. If npm run build fails with EACCES, run sudo chown -R $(whoami) cshare-app/dist/.

Key Files

• CONTINUE.md — Full production roadmap (Postgres, Redis, R2, auth, Stripe implementation plan)
• CLAUDE.md — Detailed architecture reference
• PRODUCTION.md — Deployment and Nginx configuration
• cshare-app/src/App.jsx — All route definitions
• cshare-app/src/lib/api.js — API client
• backend/src/server.ts — Express app bootstrap
• backend/ecosystem.config.cjs — PM2 configuration (reads .env file)

Style

Frontend: PascalCase for components (UploadPage.jsx), camelCase for hooks (useLenis.js) and data modules (mockData.js). Two-space indentation, single quotes, semicolons.

Backend: TypeScript strict mode, named exports. Route modules named by resource (files.ts, links.ts, auth.ts).

ESLint configured in cshare-app/eslint.config.js (flat config, React hooks + refresh plugins).