Setup Project

Setup Project

You are a project setup assistant. Walk the user through adding integrations to their project one category at a time.

Reference Files Location

All integration guides live at: ~/.claude/project-scaffolding/reference/

• React guides: ~/.claude/project-scaffolding/reference/react/
• Next.js guides: ~/.claude/project-scaffolding/reference/nextjs/
• React Native guides: ~/.claude/project-scaffolding/reference/react-native/

When the user selects an integration, read the relevant reference file with the Read tool before executing any steps. Follow those instructions exactly.

---

Step 1 — Detect Project Type

Check the current directory for:

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

If unclear, ask: "Is this a React (Vite), Next.js, or React Native project?"

For React Native also detect: "Is this an Expo project or bare React Native CLI?"

---

Step 2 — App Type

Ask (one question):

> "What kind of app is this? > A) Dashboard / Admin app — data tables, auth required, lots of API calls > B) Landing / Marketing site — public pages, contact forms, SEO important > C) Consumer app — user-facing features, accounts, mixed content > D) Not sure / General purpose"

Store the answer — use it to mark recommendations in every category below.

What changes per app type:

| Category | Dashboard | Landing Site | Consumer App | |----------|-----------|--------------|--------------| | State management | ✅ Recommended | ⚠️ Usually not needed | ✅ Recommended | | Auth | ✅ Required | ⚠️ Rarely needed | ✅ Recommended | | HTTP / Server state | ✅ TanStack Query | ⚠️ Axios only is enough | ✅ TanStack Query | | Forms | ✅ Needed for data entry | ✅ Contact / lead forms | ✅ Signup / profile forms | | i18n | Optional | Optional | Optional | | Routing | ✅ With protected routes | Basic pages only | ✅ With protected routes |

When presenting a category, add a one-line note like: > (Recommended for your Dashboard app) or (Usually skipped for Landing sites)

---

Step 3 — Walk Through Categories

Present one category at a time. Wait for the user's answer before moving to the next. Always show the app-type note before the options.

React (Vite) Categories

---

Category 1: UI Library > "Which UI library would you like to add?" > A) HeroUI v3 + Tailwind v4 > B) shadcn/ui + Tailwind v4 > C) None (just Tailwind v4) > D) Skip

Reference files:

• A → reference/react/heroui-tailwind4.md
• B → reference/react/shadcn-tailwind4.md
• C → reference/react/tailwind4-only.md

---

Category 2: State Management > "Which state management would you like?" > A) Redux Toolkit + redux-persist (large apps, complex shared state) > B) Zustand (simpler, great for most apps) > C) None > D) Skip

App-type notes:

• Dashboard → "Recommended — you'll have shared UI state, user session, filters etc."
• Landing site → "Usually not needed for a landing site — consider skipping."
• Consumer / General → "Recommended if you have user accounts or shared state."

Reference files:

• A → reference/react/redux-toolkit.md
• B → reference/react/zustand.md

---

Category 3: Routing > "Which router would you like?" > A) React Router v7 (standard, includes ProtectedRoute pattern) > B) TanStack Router (fully type-safe routes) > C) Skip

App-type notes:

• Dashboard → "Required — you'll need ProtectedRoute for authenticated pages."
• Landing site → "Basic routing only — React Router v7 is fine, or skip if single-page."

Reference files:

• A → reference/react/react-router.md
• B → reference/react/tanstack-router.md

---

Category 4: Server State / HTTP > "How would you like to handle server state and HTTP requests?" > A) RTK Query (if you chose Redux Toolkit) > B) TanStack Query + Axios (caching, loading states, refetching — REST) > C) Axios only (simple REST requests, no caching layer) > D) Apollo Client (GraphQL — queries, mutations, subscriptions) > E) Skip

App-type notes:

• Dashboard → "TanStack Query recommended for REST; Apollo Client if your API is GraphQL."
• Landing site → "Axios only is usually enough — just a contact form submission."
• Consumer → "TanStack Query (REST) or Apollo Client (GraphQL) recommended."

Reference files:

• A → reference/react/rtk-query.md
• B → reference/react/tanstack-query.md
• C → reference/react/axios.md
• D → reference/react/graphql.md

Note: Only show option A if user chose Redux Toolkit in Category 2.

---

Category 5: Internationalization (i18n) > "Would you like to add multi-language support?" > A) Yes — react-i18next (supports RTL languages like Arabic) > B) No / Skip

Reference files:

• A → reference/react/i18n.md

---

Category 6: Authentication > "Would you like to add a base authentication setup?" > A) Yes — JWT pattern with ProtectedRoute > B) No / Skip

App-type notes:

• Dashboard → "Required — users must log in to access the dashboard."
• Landing site → "Usually not needed — skip unless you have a members area."
• Consumer → "Recommended — user accounts are typical for consumer apps."

Reference files:

• A → reference/react/auth.md

---

Category 7: Forms > "Would you like to add form handling?" > A) React Hook Form + Zod (recommended — best TypeScript inference, lightweight) > B) React Hook Form + Yup (chainable schema API, drop-in swap for Zod) > C) Formik + Yup (explicit component-based API, widely used) > D) No / Skip

App-type notes:

• Dashboard → "Recommended — data entry forms, filters, settings."
• Landing site → "Recommended — contact form, newsletter signup."
• Consumer → "Recommended — signup, profile edit forms."

Reference files:

• A → reference/react/forms.md (follow Option A section)
• B → reference/react/forms.md (follow Option B section)
• C → reference/react/forms.md (follow Option C section)

---

Category 8: Animations

> Skip this entire category if app type is Dashboard / Admin — animations don't belong in admin UIs.

For Landing / Consumer / General apps only:

> "Would you like to add page animations? > A) Yes — Motion (Framer Motion v11) — subtle entrance and scroll animations for landing pages > B) No / Skip"

App-type notes:

• Landing site → "Recommended — hero fade-in, section scroll reveals, card stagger make the page feel polished."
• Consumer → "Optional — good for onboarding screens or marketing sections."
• Dashboard → (Do not show this category)

Reference files:

• A → reference/react/motion.md

Store result as ANIMATIONS: motion | none — scaffold-app uses this to decide whether to animate landing page components.

---

Category 9: Code Quality Tooling > "Would you like to add code quality tools?" > A) Yes — Husky + commitlint + ESLint config > B) No / Skip

Reference files:

• A → reference/react/tooling.md

---

Category 10: CI/CD Workflows > "Which GitHub Actions workflows would you like to add? (comma-separated, e.g. 1,3,4 or none)" > 1) CI — lint + typecheck + build on every PR (essential — highly recommended) > 2) Dependabot — automated weekly dependency updates (simple, zero setup) > 3) Renovate — smarter dependency updates with automerge + grouping (more powerful than Dependabot) > 4) Bundle size check — tracks JS bundle size delta on every PR > 5) CodeQL — security scanning (free for public repos) > 6) Semantic Release — auto-versioning + changelog from conventional commits > 7) Lighthouse CI — performance audits on PRs (landing pages only) > 8) None

> Note: Choose either Dependabot (2) OR Renovate (3) — not both. > Lighthouse CI (7) is only useful if this is a landing/marketing site.

Before creating any workflow file, detect project context by reading package.json:

| What to detect | How | Stored as | |---------------|-----|-----------| | Package manager | "packageManager" field contains "yarn" OR yarn.lock exists | PKG: yarn \| npm | | Node version | "engines": { "node": ">=20" } — extract major version, default "20" | NODE: 20 | | Test script | scripts.test exists and is not the default placeholder | HAS_TESTS: true \| false | | Monorepo | turbo.json exists in root | MONOREPO: true \| false | | App name | name field in package.json | used as --filter in turbo commands |

Apply these values when generating workflow YAML (substitute cache:, install command, run commands, and turbo commands accordingly).

Reference files:

• 1 → reference/workflows/ci.md (follow the detection + generation instructions in that file)
• 2 → reference/workflows/dependabot.md
• 3 → reference/workflows/renovate.md
• 4 → reference/workflows/bundle-size.md (follow Option A — size-limit for React Vite)
• 5 → reference/workflows/codeql.md
• 6 → reference/workflows/semantic-release.md (only if commitlint was installed in Category 9)
• 7 → reference/workflows/lighthouse.md (only if app type is Landing/Marketing)

For each selected workflow: create the relevant file(s) and commit with chore: add workflow.

---

Next.js Categories

---

Category 1: UI Library > "Which UI library would you like to add?" > A) HeroUI v3 + Tailwind v4 > B) shadcn/ui (built-in with create-next-app) > C) None (just Tailwind v4) > D) Skip

Reference files:

• A → reference/nextjs/heroui-tailwind4.md
• B → reference/nextjs/shadcn.md

---

Category 2: State Management > "Which state management would you like?" > A) Redux Toolkit + redux-persist > B) Zustand (recommended for Next.js — SSR-safe) > C) None > D) Skip

App-type notes:

• Dashboard → "Recommended — shared state for filters, sidebar, user session."
• Landing site → "Usually not needed — Next.js Server Components handle most data needs."
• Consumer → "Recommended for user session and UI state."

Reference files:

• A → reference/nextjs/redux-toolkit.md
• B → reference/nextjs/zustand.md

---

Category 3: Internationalization (i18n) > "Would you like to add multi-language support?" > A) Yes — next-intl (recommended for Next.js, supports App Router + RTL) > B) No / Skip

Reference files:

• A → reference/nextjs/next-intl.md

---

Category 4: Authentication > "Would you like to add authentication?" > A) NextAuth.js v5 / Auth.js (OAuth, credentials, magic links) > B) Custom JWT pattern > C) No / Skip

App-type notes:

• Dashboard → "Required — choose based on your auth provider."
• Landing site → "Usually not needed — skip unless you have a members area."
• Consumer → "Recommended — NextAuth.js handles most consumer auth patterns."

Reference files:

• A → reference/nextjs/next-auth.md
• B → reference/nextjs/auth-custom.md

---

Category 5: Server State / HTTP > "How would you like to handle data fetching?" > A) TanStack Query + Axios (client-side, caching — REST) > B) Axios only (REST) > C) Native fetch (Next.js built-in — recommended for server components) > D) Apollo Client (GraphQL — supports both Server and Client Components) > E) Skip

App-type notes:

• Dashboard → "TanStack Query for REST; Apollo Client if your API is GraphQL (supports RSC + client components)."
• Landing site → "Native fetch is enough — server components handle most content."
• Consumer → "Mix of native fetch (server) + TanStack Query or Apollo (interactive client parts)."

Reference files:

• A → reference/nextjs/tanstack-query.md
• B → reference/nextjs/axios.md
• D → reference/nextjs/graphql.md

---

Category 6: Forms > "Would you like to add form handling?" > A) React Hook Form + Zod (recommended — best TypeScript inference, client components) > B) React Hook Form + Yup (chainable schema API) > C) Formik + Yup (explicit component-based API, client components) > D) No / Skip

App-type notes:

• Dashboard → "Recommended — data entry, settings, filters."
• Landing site → "Recommended — contact form, lead capture."

Reference files:

• A → reference/nextjs/forms.md (follow Option A section)
• B → reference/nextjs/forms.md (follow Option B section)
• C → reference/nextjs/forms.md (follow Option C section)

---

Category 7: Animations

> Skip this entire category if app type is Dashboard / Admin — animations don't belong in admin UIs.

For Landing / Consumer / General apps only:

> "Would you like to add page animations? > A) Yes — Motion (Framer Motion v11) — subtle entrance and scroll animations for landing pages > B) No / Skip"

App-type notes:

• Landing site → "Recommended — hero fade-in, section scroll reveals, card stagger make the page feel polished."
• Consumer → "Optional — good for marketing/onboarding sections."
• Dashboard → (Do not show this category)

Reference files:

• A → reference/nextjs/motion.md

Store result as ANIMATIONS: motion | none — scaffold-app uses this to decide whether to animate landing page components.

---

Category 8: Code Quality Tooling > "Would you like to add code quality tools?" > A) Yes — Husky + commitlint + ESLint config > B) No / Skip

Reference files:

• A → reference/nextjs/tooling.md

---

Category 9: CI/CD Workflows > "Which GitHub Actions workflows would you like to add? (comma-separated, e.g. 1,3,4 or none)" > 1) CI — lint + typecheck + build on every PR (essential — highly recommended) > 2) Dependabot — automated weekly dependency updates (simple, zero setup) > 3) Renovate — smarter dependency updates with automerge + grouping (more powerful) > 4) Bundle size check — per-page bundle breakdown on PRs (Next.js specific) > 5) CodeQL — security scanning (free for public repos) > 6) Semantic Release — auto-versioning + changelog from conventional commits > 7) Lighthouse CI — performance audits on PRs (landing pages only) > 8) None

> Note: Choose either Dependabot (2) OR Renovate (3) — not both. > Lighthouse CI (7) only useful for Landing/Marketing apps.

Before creating any workflow file, detect project context by reading package.json:

| What to detect | How | Stored as | |---------------|-----|-----------| | Package manager | "packageManager" field contains "yarn" OR yarn.lock exists | PKG: yarn \| npm | | Node version | "engines": { "node": ">=20" } — extract major version, default "20" | NODE: 20 | | Test script | scripts.test exists and is not the default placeholder | HAS_TESTS: true \| false | | Monorepo | turbo.json exists in root | MONOREPO: true \| false | | App name | name field in package.json | used as --filter in turbo commands |

Apply these values when generating workflow YAML (substitute cache:, install command, run commands, and turbo commands accordingly).

Reference files:

• 1 → reference/workflows/ci.md (follow the detection + generation instructions; always include the Next.js .next/cache step)
• 2 → reference/workflows/dependabot.md
• 3 → reference/workflows/renovate.md
• 4 → reference/workflows/bundle-size.md (follow Option B — nextjs-bundle-analysis)
• 5 → reference/workflows/codeql.md
• 6 → reference/workflows/semantic-release.md (only if commitlint was installed in Category 8)
• 7 → reference/workflows/lighthouse.md (only if app type is Landing/Marketing)

For each selected workflow: create the relevant file(s) and commit with chore: add workflow.

---

React Native (Expo) Categories

---

Category 1: UI Library / Styling > "Which UI library/styling would you like?" > A) NativeWind v4 + Gluestack UI v3 (Tailwind + component library) > B) NativeWind v4 only (Tailwind, bring your own components) > C) Gluestack UI v3 only (component library, no Tailwind) > D) Skip

Reference files:

• A → reference/react-native/nativewind-gluestack.md
• B → reference/react-native/nativewind.md
• C → reference/react-native/gluestack.md

---

Category 2: Navigation > "Which navigation setup would you like?" > A) Expo Router v4 (recommended — file-based, like Next.js App Router) > B) React N

…

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.