BMAD-METHOD/BETA-V3/docs/technical-preferences-sample-2.md

My Frontend Tech Preferences (Next.js & React)

Just some notes for myself and the AI on how I like to build my Next.js apps. Trying to keep things consistent.

Overall Project Structure

• /app directory for routing (Next.js App Router):
  • Really like this new router. Makes sense to group UI and logic by route.
  • layout.tsx and page.tsx as the main files for each route.
  • Loading UI: loading.tsx is pretty cool.
  • Error UI: error.tsx for catching errors.
• /components directory (root level):
  • For all shared/reusable React components.
  • Sub-folders per component: e.g., /components/Button/Button.tsx, /components/Button/Button.stories.tsx, /components/Button/Button.test.tsx.
  • I like to keep stories and unit tests with the component.
• /lib directory (root level):
  • Helper functions, utilities, constants, type definitions that are not components.
  • e.g., lib/utils.ts, lib/hooks.ts, lib/types.ts
• /styles directory (root level):
  • Global styles in globals.css.
  • Maybe Tailwind CSS config here if I use it (tailwind.config.js).
• /public directory: For static assets, as usual.
• /store or /contexts directory (root level):
  • For state management. If using Zustand, maybe /store/userStore.ts. If React Context, /contexts/ThemeContext.tsx.

React & Next.js Conventions

• TypeScript Everywhere:
  • Definitely. Helps catch a lot of bugs.
  • Use interface for public API type definitions (props), type for internal/utility types.
• Functional Components with Hooks:
  • Standard practice.
• Server Components vs. Client Components (Next.js App Router):
  • Try to use Server Components by default as much as possible for performance.
  • "use client"; only when necessary (event handlers, state, browser-only APIs).
• Routing:
  • Next.js App Router.
  • Dynamic routes with [] and [... ] folders.
• API Routes:
  • In the /app/api/... folders.
  • Good for small backend-for-frontend tasks.
• State Management:
  • Zustand: My go-to for most global state. Simple, less boilerplate than Redux.
  • React Context: For simpler, localized state sharing (like theme, user auth status if not too complex).
  • Avoid Prop Drilling: Use Zustand or Context if props go more than 2-3 levels deep without being used.
• Component Design:
  • Small, focused components.
  • Props should be clear. Destructure props.
  • Use React.FC<Props> for component typings.
  • Fragments (<>...</>) when no extra DOM node is needed.
• Styling:
  • Tailwind CSS: Strongly preferred. Makes styling fast and keeps HTML cleaner than tons of CSS Modules files.
  • CSS Modules as a fallback or for very specific component-level styles if Tailwind isn't a good fit for some reason.
• Environment Variables:
  • NEXT_PUBLIC_ prefix for client-side accessible env vars.
  • Standard .env.local for local development.

Testing

• E2E Testing Tool: Playwright
  • Love Playwright. It's fast and has great features (auto-waits, good selectors).
  • Tests in an /e2e folder at the root.
  • Page Object Model (POM) pattern is good for maintainable E2E tests.
    • e.g., e2e/pages/loginPage.ts, e2e/tests/auth.spec.ts
• Unit Testing: Jest & React Testing Library
  • Standard for React components.
  • Focus on testing component behavior from a user's perspective, not implementation details.
  • Mock API calls using jest.mock.
• Integration Testing:
  • Could be a mix of Jest/RTL for testing how multiple components work together, or focused Playwright tests for small user flows.

Other Preferred Libraries/Tools

• Linting/Formatting:
  • ESLint with standard configs (e.g., eslint-config-next).
  • Prettier for code formatting.
  • Run on pre-commit hook (Husky + lint-staged).
• Data Fetching:
  • Next.js built-in fetch (extended for server components, automatic caching).
  • SWR or React Query if client-side data fetching gets complex (caching, revalidation, etc.), but try to use Server Components for data fetching first.
• Forms:
  • React Hook Form: Good for handling forms with validation.
  • Schema validation with Zod.
• Storybook:
  • Yes, for component development and UI documentation.
  • Keep stories next to components.

Things I'm still learning/exploring:

• Advanced Next.js features (Route Handlers, Server Actions in more depth).
• More sophisticated testing strategies for server components.
• Performance optimization beyond the basics.