app-dev-practices

App Dev Practices

Always Scaffold First

Run fusebase scaffold --template spa --dir apps/<name> before writing any app files. This generates the canonical React + Vite + Tailwind v4 + shadcn/ui project structure. For apps needing a backend, also run fusebase scaffold --template backend --dir apps/<name>. Customize from there — never recreate boilerplate by hand.

Multi-User by Default

Every app is multi-user. Multiple users access the same deployed app simultaneously, each with their own identity (app token). Never design for a single user.

Rules:

• Per-user state (OAuth tokens, preferences, selections) must be stored per-user — use httpOnly cookies (set by the server, scoped to the user's browser) or dashboard rows keyed by user ID

• Shared env vars / Fusebase secrets are global — they are the same for all users. Never use them for per-user credentials or settings

• In-memory backend variables are shared across all requests from all users — never store per-user data in module-level variables

• When integrating third-party APIs with OAuth, each user must go through their own auth flow and get their own tokens

• Stable partition keys only: when storing per-user rows, the partition key must come from a stable identity (userId, orgUserId, email if immutable), not from session/token artifacts.

• Never use token-derived keys (e.g. ft:*, JWT fragments, rotating session IDs) as persistent user_key/partition keys — they change between sessions and split one user's data into multiple buckets.

• Recommended format: normalize once in backend (user:<userId>) and reuse the same key for both read and write paths.

Ask yourself: "If two users open this app at the same time, will they interfere with each other?" If yes, the design is wrong.

Project Structure

Apps are React/Vite apps in apps/:

apps/
  my-app/
    package.json
    vite.config.ts
    src/
      App.tsx
      main.tsx

Use existing apps in apps/ as reference when building new ones.