Quick framework switch
Prefer another stack? Jump straight there with the icons below.
Setup & Installation
1. Scaffold the workspace
I start by generating a Vite + React + TypeScript workspace so the dev server stays fast while I iterate.
Create the project
2. Wire Tailwind CSS 4 design tokens
Next I install Tailwind CSS 4 with PostCSS/Autoprefixer, then extend the theme with our shared design tokens.
Install Tailwind CSS
tailwind.config.ts
import type { Config } from 'tailwindcss';
import defaultTheme from 'tailwindcss/defaultTheme';
export default {
content: ['./index.html', './src/**/*.{ts,tsx,mdx}'],
theme: {
extend: {
fontFamily: {
sans: ['"InterVariable"', ...defaultTheme.fontFamily.sans],
},
colors: {
brand: {
50: '#fff7f5',
500: '#F53003',
700: '#bb2402',
},
},
},
},
plugins: [],
} satisfies Config;
3. Install UI primitives and data layer
With styling set, I install shadcn/ui components and TanStack Query so the UI and data layer move in sync.
Generate shadcn/ui primitives
Add TanStack Query
src/main.tsx
import React from 'react';
import ReactDOM from 'react-dom/client';
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
import App from './App.tsx';
import './index.css';
const queryClient = new QueryClient();
ReactDOM.createRoot(document.getElementById('root')!).render(
<React.StrictMode>
<QueryClientProvider client={queryClient}>
<App />
</QueryClientProvider>
</React.StrictMode>,
);
4. Enable linting & telemetry
Finally I wire ESLint/Prettier and add Sentry so build quality and runtime visibility are locked in.
Install quality and telemetry tooling
Reference Links
Architecture Patterns
Rendering Model
- • Hybrid SPA: TanStack Router for routing with Suspense boundaries per route.
- • Defer non-critical widgets via dynamic `import()` + React.lazy.
Data Flow
- • GraphQL gateway with generated hooks via GraphQL Codegen.
- • Realtime events bridged by Pusher Channels or AWS AppSync.
LiveOps Hooks
- • Feature flag adapters (LaunchDarkly + custom YAML).
- • In-app announcements delivered via CMS webhooks.
Preferred Libraries
UI & Styling
- • Tailwind CSS with shared tokens synced from Figma.
- • shadcn/ui (Radix primitives) for accessible building blocks.
- • Framer Motion with `tailwind-merge` for clean animation control.
Developer Experience
- • Playwright component and smoke suites backed by Percy snapshots.
- • msw so I can develop offline while keeping the API contract honest.
- • Hygen generators (`npx hygen feature new`) for repeatable feature scaffolding.
Content & Localization
- • Contentlayer whenever MDX needs to stay type-safe.
- • LinguiJS for an ICU-friendly localization workflow.
- • Cloudinary SDK plus vite-imagetools for responsive assets.
State & Data Flow
Patterns
- • I keep `/src/features/<domain>` self-contained with components, hooks, and tests.
- • TanStack Query is the backbone for remote data with devtools on by default.
- • Zustand + immer power lightweight shared UI state such as modals or wizards.
Data Pipeline
- • GraphQL Code Generator or `openapi-typescript` keep API usage fully typed.
- • `ky` combined with `zod` validates every REST response before hitting the UI.
- • Realtime streams from Pusher or Supabase dispatch into Zustand actions.
Authentication & Security
Preferred Providers
- • Auth0 whenever the client needs enterprise SSO.
- • Clerk for rapid onboarding with hosted widgets and MFA.
- • Supabase Auth when prototypes need fast row-level security.
Security Practices
- • TanStack Router `beforeLoad` plus Suspense fallbacks guard protected routes.
- • JWTs stay in HTTP-only cookies with a background refresh worker.
- • Helmet, CSP, and Trusted Types run on the edge layer (Netlify or CloudFront).
Performance & Optimization
Checklist
- • Hold the main bundle under 180kb using `npm run analyze` (with `rollup-plugin-visualizer`).
- • Lazy-load analytics and heatmaps only after user consent during idle time.
- • Virtualize heavy tables and feeds with `@tanstack/react-virtual` or `react-window`.
- • Preload fonts via `@fontsource` or manual `<link rel="preload">` tags to avoid CLS.
Tooling
- • Lighthouse CI gates the GitHub Actions pipeline before merging.
- • Sentry Performance + Replay reveals real-user slowdowns.
- • Calibre synthetic checks alert Slack when performance budgets break.
Deployment & Ops
Strategies
- Preview Branches: Amplify Hosting + GitHub Environments
- Mainline: Blue/green with canary at 10% / 30% / 100%
- Telemetry: Datadog RUM + Sentry releases
Checkpoints
- • Lighthouse CI gating at 90+ for Performance & Accessibility.
- • Synthetic checks in multiple regions for core flows.
- • Automated visual diffs through Percy.
Tooling & Integrations
CLI
- • npm scripts
- • nx (optional monorepo)
Testing
- • Vitest + Testing Library
- • Playwright smoke grid
CMS Integrations
- • Sanity
- • Contentful
- • Strapi