Scaffold App

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)

``tsx import { HeroUIProvider } from '@heroui/react' // wrap: ``

• Use HeroUI Button instead of plain `` 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 ` 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.

1. If app type is Dashboard, apply the LAYOUT_STYLE choice:

• If LAYOUT_STYLE = sidebar:
• Use AppShell with `` 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 `` 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

1. 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: admin@example.com / 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

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Global-Software-Consulting
• Source: Global-Software-Consulting/project-scaffolding-skills
• License: MIT

Install and usage instructions live in the source repository linked above.