Codewalkers/.planning/phases/16-frontend-scaffold/16-01-PLAN.md

phase, plan, type, wave, depends_on, files_modified, autonomous

phase	plan	type	wave	depends_on	files_modified	autonomous
16-frontend-scaffold	01	execute	1		packages/web/package.json packages/web/vite.config.ts packages/web/tsconfig.json packages/web/tsconfig.app.json packages/web/index.html packages/web/src/main.tsx packages/web/src/App.tsx packages/web/src/index.css packages/web/postcss.config.js packages/web/components.json packages/web/tailwind.config.ts packages/web/src/lib/utils.ts package.json tsconfig.json	true

Create the Vite + React project with Tailwind CSS and shadcn/ui component library.

Purpose: Establish the frontend build toolchain and component foundation for all subsequent UI work. This is the bare-bones project that compiles and serves an empty page with styling ready. Output: A working packages/web/ directory with Vite dev server, Tailwind CSS, and shadcn/ui configured.

<execution_context> @/.claude/get-shit-done/workflows/execute-plan.md @/.claude/get-shit-done/templates/summary.md </execution_context>

@.planning/PROJECT.md @.planning/ROADMAP.md @.planning/STATE.md

Existing project structure - this is currently a single package

@package.json @tsconfig.json

Task 1: Create Vite + React + TypeScript project packages/web/package.json, packages/web/vite.config.ts, packages/web/tsconfig.json, packages/web/tsconfig.app.json, packages/web/index.html, packages/web/src/main.tsx, packages/web/src/App.tsx, packages/web/src/index.css, package.json, tsconfig.json 1. Create `packages/web/` directory. 2. Initialize a new Vite project with React + TypeScript template files manually (do NOT use `npm create vite` interactively): - `packages/web/package.json` with name `@codewalk-district/web`, type `module`, scripts: `dev`, `build`, `preview`, `lint`. Dependencies: `react`, `react-dom`. Dev dependencies: `@types/react`, `@types/react-dom`, `@vitejs/plugin-react`, `typescript`, `vite`. - `packages/web/vite.config.ts` with react plugin. Set server proxy: `/trpc` → `http://127.0.0.1:3847/trpc` to avoid CORS issues during development. - `packages/web/tsconfig.json` extending `tsconfig.app.json` with references. - `packages/web/tsconfig.app.json` targeting ES2020, module ESNext, moduleResolution bundler, strict mode, jsx react-jsx, include `src`. - `packages/web/index.html` standard Vite entry pointing to `/src/main.tsx`. - `packages/web/src/main.tsx` rendering `` into `#root`. - `packages/web/src/App.tsx` minimal component returning `

Codewalkers

`.

3. Update root package.json:

   • Add "workspaces": ["packages/*"] for npm workspaces.
   • Add script "dev:web": "npm run dev --workspace=packages/web".
   • Keep all existing scripts and dependencies unchanged.

4. Run npm install from root to link workspaces.

Do NOT modify any existing source files in src/. Only touch root package.json and tsconfig.json for workspace config. cd packages/web && npx vite build succeeds without errors. npm run dev:web starts dev server (verify it starts, then kill). Vite dev server starts and builds. Root workspace config links packages/web.

Task 2: Configure Tailwind CSS and shadcn/ui packages/web/tailwind.config.ts, packages/web/postcss.config.js, packages/web/src/index.css, packages/web/components.json, packages/web/src/lib/utils.ts, packages/web/package.json 1. Install Tailwind CSS v3 in packages/web: - Dev dependencies: `tailwindcss`, `postcss`, `autoprefixer`, `@tailwindcss/typography` - `postcss.config.js` with tailwindcss and autoprefixer plugins. - `tailwind.config.ts` with content paths pointing to `./src/**/*.{ts,tsx}`, extend theme as needed.

2. Update packages/web/src/index.css with Tailwind directives:

   @tailwind base;
   @tailwind components;
   @tailwind utilities;
   

   Plus CSS custom properties for shadcn theming (the standard shadcn/ui CSS variables for colors, radius, etc.).

3. Install shadcn/ui dependencies:

   • Dependencies: class-variance-authority, clsx, tailwind-merge, lucide-react
   • Dev dependency: tailwindcss-animate
   • Add tailwindcss-animate plugin to tailwind.config.ts

4. Create packages/web/components.json (shadcn/ui config):

   {
     "$schema": "https://ui.shadcn.com/schema.json",
     "style": "default",
     "rsc": false,
     "tsx": true,
     "tailwind": {
       "config": "tailwind.config.ts",
       "css": "src/index.css",
       "baseColor": "neutral",
       "cssVariables": true
     },
     "aliases": {
       "components": "@/components",
       "utils": "@/lib/utils"
     }
   }
   

5. Create packages/web/src/lib/utils.ts:

   import { type ClassValue, clsx } from "clsx"
   import { twMerge } from "tailwind-merge"
   
   export function cn(...inputs: ClassValue[]) {
     return twMerge(clsx(inputs))
   }
   

6. Configure path aliases in vite.config.ts and tsconfig.app.json:

   • @/ → ./src/ (standard shadcn convention)
   • Install @types/node as dev dependency for path resolution in vite config.

7. Update packages/web/src/App.tsx to use a Tailwind class (e.g., <div className="text-2xl font-bold p-8">Codewalkers</div>) to verify Tailwind works.

8. Run npm install from root after adding dependencies. npx vite build in packages/web succeeds. The built output includes Tailwind styles (check dist/assets/*.css contains Tailwind resets). Tailwind CSS compiles. shadcn/ui configured with components.json and utils.ts. Path alias @/ resolves.

Before declaring plan complete: - [ ] `cd packages/web && npx vite build` succeeds - [ ] Root `npm install` completes without errors - [ ] `npm run dev:web` starts Vite dev server - [ ] Tailwind classes render in built output - [ ] `@/` path alias resolves in imports

<success_criteria>

• Vite + React + TypeScript project builds in packages/web/
• Tailwind CSS configured and compiling
• shadcn/ui components.json and utils ready
• Root npm workspaces configured
• Dev server starts with proxy to backend </success_criteria>

After completion, create `.planning/phases/16-frontend-scaffold/16-01-SUMMARY.md`