scaffold-app

name	scaffold-app
description	Scaffold a production-ready folder structure, base components, routing, types, and env setup for an already-configured React (Vite), Next.js, or React Native project. Run after /setup-project.

Scaffold App

You are a project scaffolding assistant. Your job is to generate the full production-ready app structure — folders, base components, routing, types, and environment setup — based on what the project already has installed.

Run this after /setup-project (or on any project where packages are already configured).

---

Step 1 — Detect Project Type

Check the current directory for:

• next.config.* → Next.js
• vite.config.* → React (Vite)
• app.json with expo key → React Native (Expo)
• android/ + ios/ without expo → React Native (CLI)

---

Step 2 — Detect Installed Packages

Read package.json (and package.json in the project root if monorepo). Build a profile:

UI_LIBRARY:        heroui | shadcn | tailwind-only | none
STATE_MANAGER:     redux | zustand | none
ROUTER:            react-router | tanstack-router | expo-router | react-navigation | none
HTTP_CLIENT:       tanstack-query+axios | axios | native-fetch | none
I18N:              react-i18next | next-intl | i18next | none
AUTH:              nextauth | jwt-custom | none
FORMS:             react-hook-form | formik | none
ANIMATIONS:        motion | none

Detect by checking dependencies and devDependencies for:

• @heroui/react → heroui
• @radix-ui/react-* or components.json file → shadcn
• tailwindcss without above → tailwind-only
• @reduxjs/toolkit → redux
• zustand → zustand
• react-router-dom → react-router
• @tanstack/router → tanstack-router
• expo-router → expo-router
• @react-navigation/native → react-navigation
• @tanstack/react-query → tanstack-query
• axios → axios
• next-intl → next-intl
• react-i18next → react-i18next
• next-auth → nextauth
• react-hook-form → react-hook-form
• formik → formik
• motion → motion

---

Step 3 — Confirm App Type

If coming from /create-frontend-project, the app type is already known — skip this question.

Otherwise ask:

"What kind of app is this? A) Dashboard / Admin app B) Landing / Marketing site C) Consumer app (user-facing, accounts) D) General purpose"

If Dashboard / Admin is selected, ask one more question:

"What layout style do you want for the dashboard? A) Sidebar navigation (left sidebar + main content area — most common for admin panels) B) Top navigation bar (sticky top nav + full-width content — cleaner for data-heavy apps)"

Store the answer as LAYOUT_STYLE: sidebar | topnav and use it in Step 5.

---

Step 4 — Read the Reference File

Based on project type + app type, read the reference file:

Project Type	App Type	Reference File
React (Vite)	Dashboard / Consumer	~/.claude/project-scaffolding/reference/scaffold/react-dashboard.md
React (Vite)	Landing / General	~/.claude/project-scaffolding/reference/scaffold/react-landing.md
Next.js	Dashboard / Consumer	~/.claude/project-scaffolding/reference/scaffold/nextjs-dashboard.md
Next.js	Landing / General	~/.claude/project-scaffolding/reference/scaffold/nextjs-landing.md
React Native	Any	~/.claude/project-scaffolding/reference/scaffold/react-native-app.md

Read the file now with the Read tool before proceeding.

---

Step 5 — Execute the Scaffold

Follow the reference file exactly. For every file it specifies:

1. Create the directory if it doesn't exist
2. Write the file with the content from the reference
3. Adapt component code to the detected package profile:
   • If heroui (React Vite only):
     • Wrap app with HeroUIProvider in src/main.tsx (CRITICAL — React Vite only, required for HeroUI styles)

       import { HeroUIProvider } from '@heroui/react'
       // wrap: <HeroUIProvider><App /></HeroUIProvider>
       

     • Use HeroUI Button instead of plain <button> in layout/marketing components
     • Use HeroUI Card, CardBody for feature cards and pricing cards
     • Use HeroUI Navbar, NavbarBrand, NavbarContent, NavbarItem for the site header
   • If heroui (Next.js):
     • HeroUI v3 has NO provider — do NOT add HeroUIProvider anywhere
     • Import and use HeroUI components directly in client components ('use client')
     • Use HeroUI Button, Card, CardBody, Navbar components directly
   • If shadcn: use shadcn/ui Button, Card components
   • If tailwind-only or none: use plain HTML + Tailwind classes
   • If redux: use Redux store patterns in auth/app hooks
   • If zustand: use Zustand store patterns
   • If react-hook-form: use RHF in form components
   • If formik: use Formik in form components
   • If i18n detected (next-intl):
     • Use t() for all user-visible strings
     • CRITICAL: Replace ALL import Link from 'next/link' with import { Link } from '@/i18n/navigation' — this makes every link locale-aware automatically (e.g. Arabic → /ar/about, English → /about)
     • CRITICAL: Replace ALL import { useRouter } from 'next/navigation' with import { useRouter } from '@/i18n/navigation'
     • src/i18n/navigation.ts must exist (created by next-intl setup step) — it exports locale-aware Link, useRouter, usePathname, redirect
   • If i18n detected (react-i18next): use t() for all user-visible strings
   • If ANIMATIONS: motion AND app type is Landing or Consumer:
     • React (Vite): Wrap key landing sections with motion.div from motion/react — use initial/whileInView/viewport for scroll-triggered reveals. Apply to: Hero headline + subtext, Features section cards (stagger), Pricing section cards (stagger), CTA banner. Import pattern: import { motion } from 'motion/react'
     • Next.js: Create src/components/ui/FadeIn.tsx as a 'use client' wrapper (see reference/nextjs/motion.md). Wrap Hero, Features, Pricing, CTA sections with <FadeIn> in server page components. For stagger grids (feature cards, pricing cards), create a 'use client' component that uses motion.div with variants + staggerChildren.
     • Keep animations minimal: fade-in (opacity 0→1) + slide-up (y: 24→0), duration 0.4–0.5s, ease-out. CTA buttons get whileHover={{ scale: 1.03 }}.
     • Never add animations if app type is Dashboard / Admin — even if motion is installed.
4. If app type is Dashboard, apply the LAYOUT_STYLE choice:
   • If LAYOUT_STYLE = sidebar:
     • Use AppShell with <Sidebar /> on the left (default in reference)
     • If heroui: use the HeroUI Sidebar variant from the reference's "HeroUI Variants" section
   • If LAYOUT_STYLE = topnav:
     • Use AppShell with <TopNav /> at the top (top nav variant from reference)
     • Replace AppShell.tsx content with the top nav version
     • Create TopNav.tsx instead of Sidebar.tsx
     • If heroui: use the HeroUI TopNav variant from the reference's "HeroUI Variants" section
5. Skip files that duplicate what's already set up (e.g. if axios.ts already exists in src/lib/, skip it)

---

Step 6 — Clean Up Vite Boilerplate

For React (Vite) projects, remove the default boilerplate:

• Delete src/App.css (unless it has custom styles)
• Clear src/App.tsx content (replace with the router entry point from reference)
• Keep src/index.css (contains Tailwind imports)
• Delete public/vite.svg and src/assets/react.svg if unused

---

Step 7 — Commit

git add .
git commit -m "feat: scaffold app structure — folder layout, base components, routing, types"

---

Step 8 — Optional Extras

After scaffolding is complete, ask:

"Want me to add any of these extras? (comma-separated or 'none')

1. Skeleton loading components (recommended — prevents layout shift on data load)
2. Toast notifications via sonner (recommended — user feedback for API calls)
3. Error boundary (recommended — prevents full app crash from one component error)
4. Dark mode toggle button
5. None"

Then add what was selected on top of the already-scaffolded structure.

For heroui adaptation of selected extras:

• If skeleton extras selected: use HeroUI Skeleton component (from @heroui/react) instead of plain CSS pulse

---

Step 9 — All Done

After extras are handled (or skipped), print:

✅ All done!

Project: [project-name]/
App type: [Dashboard / Landing / Consumer]

Structure created:
  src/
    components/   — shared UI components
    features/     — feature modules
    hooks/        — custom hooks
    utils/        — helpers (cn, formatDate, etc.)
    types/        — shared TypeScript types
    services/     — API layer
    [store/]      — state (if Redux/Zustand detected)
    [i18n/]       — translations (if i18n detected)

Commands:
  yarn dev              — start dev server
  yarn build            — production build
  yarn preview          — preview production build
  [npx expo start]      — React Native dev server

[If auth detected]:
  Demo: [e-mail] / password

Start here:
  src/features/         — add your first feature module
  src/services/         — wire up your real API endpoints

Then ask:

"Want me to start the dev server now? A) Yes — start it now (runs in the background, output will appear here) B) No — I'll run it myself"

If A — start it now:

Run the correct dev command for the project type in the background (so it doesn't block the conversation):

• React (Vite): yarn dev (from the project directory)
• Next.js: yarn dev (from the project directory)
• React Native (Expo): npx expo start (from the project directory)
• React Native (CLI): npx react-native start (from the project directory)

Use the Bash tool with run_in_background: true. After launching, tell the user:

"Dev server started in the background. Open: http://localhost:5173 (Vite) or http://localhost:3000 (Next.js) Output will appear in this conversation when the server is ready."

If B — user runs it themselves:

Show the exact command to copy-paste:

"Run this in your terminal from the project directory:

cd [project-name]
yarn dev
```"

---

Step 10 — Generate CLAUDE.md

After the dev server question is resolved, always generate CLAUDE.md without asking.

Follow the complete generate-claude-md skill from Step 1 through Step 6:

• The stack profile is already fully known from Step 2 of this scaffold flow — skip re-detection
• The app type is already known — pass it through directly
• Write CLAUDE.md to the project root, commit it

Tell the user after generating:

"Generated CLAUDE.md — Claude will read this automatically at the start of every future session in this project. No need to explain the stack again."

---

Rules

• Never overwrite files that already have meaningful content — check first with Read tool
• Always adapt component code to the detected UI library
• If i18n is detected, all user-facing strings must use translation keys (add keys to locale files too)
• Create .env.example with all variables documented but empty values
• One commit at the end — not per file
• Tell the user what was created and the key files to start editing