Skip to content

Latest commit

 

History

History
110 lines (76 loc) · 3.82 KB

nextrules.md

File metadata and controls

110 lines (76 loc) · 3.82 KB

Welcome

YOUR PLATFORM is a platform for TARGET AUDIENCE. Our current goal is to GOAL.

We do not currently leverage a monorepo; this repo is only for app.YOURLINK.com. We do leverage a src/ directory.

We follow standard React/TypeScript naming conventions: camelCase for variables/functions and PascalCase for components/classes.

Branding

Our brand colors are defined in site.ts; never define colors by hand, always pull from here.

Tech Stack

  • Next.js (app, not pages)
  • Tailwind (never write vanilla CSS)
  • Supabase (used for both auth and database)
  • Prisma (ORM)
  • TypeScript (never write vanilla JS, unless absolutely necessary)
  • Zustand (always use a store for state)
  • Posthog
  • Framer Motion (this is used for any and all motion, regardless of its complexity)
  • ShadCN (this is used for any and all UI components, regardless of its complexity)

App Feel

It's critical that our app feel fast. We leverage all of the great out of the box features from Next here, use onMouseDown rather than onClick where it doesn't hinder the user experience, use lots of caching, pre-fetching, states, etc. Additionally, we are very mindful of rerenders, and try to optimize servers & DBs to be as fast as possible. We always show things optimistically when possible.

That said, when we do need to load, there are a few different ways we handle this:

  1. Loading States: used for longer loading between pages/while fetching data on new laod that is hard to avoid. We use the COMPONENT.tsx component to handle this.
  2. Skeletons: used for loading states that are easy to avoid, such as loading a table of data. We use the COMPONENT.tsx component to handle this.
  3. In some cases, it's fine just to show a blank white page for .5 second ~ longer; use critical thinking here.
  4. In cases where we are sending data up to a server, we display this on the actual button, using the correct components.

Database Migration Guidelines

Safe Migration Rules

  1. Never Drop Data

    • ❌ Never drop columns
    • ❌ Never change column types
    • ✅ Add new columns with defaults
    • ✅ Add new tables
    • ✅ Add new relations

  2. Making Breaking Changes

    • Add new nullable columns instead of modifying existing ones
    • Use multiple migrations for complex changes
    • Keep old columns temporarily when changing data structure
    • Add new columns → migrate data → remove old columns (in separate PRs)

Development Workflow

  1. Local Development

    # Create a new migration
npx prisma migrate dev --name descriptive_name

# Test your changes
npm run dev

  2. Before Committing

    • Pre-commit hooks will automatically check for destructive changes
    • Review migration files manually
    • Test migrations against a copy of production data if possible

  3. CI/CD Process

    • Push to main triggers automatic migration deployment
    • CI checks for destructive changes
    • Migrations are applied automatically after validation

Emergency Rollback

If something goes wrong:

  1. Immediate Actions

    # Revert to the last known good migration
npx prisma migrate reset --preview-feature
git checkout [last-known-good-commit]

  2. Data Recovery

    • Recent backups are maintained in Supabase
    • Contact team lead before any emergency rollbacks

Best Practices

  1. Always Add, Never Remove

    • Add new columns instead of modifying existing ones
    • Keep deprecated columns until data migration is complete
    • Use database triggers for automatic data population

  2. Testing

    • Test migrations against a copy of production data
    • Verify both up and down migrations
    • Include migration tests in your PR

  3. Documentation

    • Comment complex migrations
    • Update API documentation when schema changes
    • Document any required application changes