@mstfucrr/create-next-template

A CLI tool for scaffolding customizable Next.js (App Router) projects on up-to-date versions — TypeScript, Turbopack, and Tailwind CSS v4 out of the box, with optional Axios, Zod, React Hook Form, Shadcn UI, TanStack Query, and a proxy.ts-based authorization starter.

Table of Contents

• Requirements
• Installation
• Usage
• Features
• Development
• License

Requirements

• Node.js >=20.9.0
• pnpm (must be installed globally)

Installation

You can use this template in two ways:

Option 1: Using npx (Recommended)

npx @mstfucrr/create-next-template

Option 2: Global Installation

npm install -g @mstfucrr/create-next-template
create-my-next-template

Usage

1. Run the template using either method above.

2. The CLI will guide you through the following options:

   • Project name
   • Next.js version (defaults to latest)
   • React Compiler (enabled by default, opt-out)
   • Additional features:
     • Axios for HTTP requests
     • Zod for schema validation
     • React Hook Form for form handling (+ @hookform/resolvers when combined with Zod)
     • Shadcn UI for components
     • TanStack Query (React Query) — automatically wraps src/app/layout.tsx with a QueryClientProvider (see below)
     • A minimal, working proxy.ts-based authorization template (Next.js 16's replacement for middleware.ts)
     • PostHog product analytics
     • Husky + lint-staged for a pre-commit lint/format hook
     • Playwright for end-to-end testing

3. The tool will automatically:

   • Set up a Next.js (App Router) project with TypeScript, using Turbopack and Tailwind CSS v4 by default
   • Add ESLint (flat config)
   • Set up Prettier + prettier-plugin-tailwindcss
   • Create a recommended folder structure, including (public)/(private) route groups under src/app and an error.tsx/global-error.tsx error boundary
   • Add .vscode/settings.json (format-on-save) and .vscode/extensions.json (recommended extensions)
   • Add a shared src/hooks/useDebounce.ts hook
   • Add a .nvmrc pinned to Node 24
   • Generate example service (src/services/example.service.ts) and module (src/modules/example/) files so you can see how the two are meant to be structured (see Features below) — safe to delete once you don't need them
   • Install selected dependencies
   • Work around pnpm 11's strictDepBuilds default so native build scripts (e.g. sharp, @tailwindcss/oxide) install correctly

4. Once the installation is complete, navigate to your project:

cd your-project-name
pnpm dev

Note: Right after scaffolding, your editor may show Cannot find name 'LayoutProps' (or PageProps) in layout.tsx/page.tsx. These are Next.js's typed-routes ambient types, generated into .next/types/ only after next dev or next build has run at least once — not an issue with the generated code. Run pnpm dev once, then restart your editor's TypeScript server (in VS Code: Cmd/Ctrl+Shift+P → "TypeScript: Restart TS Server") if the error persists.

Features

• ⚡ Next.js (App Router) with Turbopack and Tailwind CSS v4 out of the box
• 📝 TypeScript support
• 🎯 ESLint flat config (via eslint-config-next)
• 💅 Prettier + Tailwind class sorting, pre-configured for Tailwind v4
• 📦 PNPM package manager
• 🏗️ Recommended project structure, including src/app/(public)/layout.tsx and src/app/(private)/layout.tsx route groups (the existing home page is moved into (public)), an error.tsx/global-error.tsx error boundary, and a shared src/hooks/useDebounce.ts hook
• 🔢 .nvmrc pinned to Node 24, generated in every project
• 🧩 Example service & module scaffolding, generated in every project to illustrate the intended structure:
  • src/services/example.service.ts — a generic, shared service (fetches example users via Axios or fetch, depending on your Axios choice)
  • src/modules/example/ — a self-contained feature module with its own types/, services/, components/, an index.tsx entry component, and (only if TanStack Query is selected) a hooks/useExampleQuery.ts built on useQuery
  • Both are safe to delete once you've built your own services/modules
• 🔧 Optional integrations:
  • Axios
  • Zod
  • React Hook Form (with @hookform/resolvers when paired with Zod)
  • Shadcn UI
  • TanStack Query, with a generated src/components/providers/query-provider.tsx (Client Component) that automatically wraps layout.tsx — if the generated layout.tsx doesn't match the expected pattern, the provider file is still created and you wrap {children} with <QueryProvider> yourself.
  • proxy.ts-based authorization starter (App Router src/proxy.ts)
  • React Compiler
  • PostHog: a src/components/providers/posthog-provider.tsx (Client Component) that wraps layout.tsx's {children} automatically — this wrap works even if another provider (e.g. TanStack Query's) is already wrapping {children}. Also generates a committable .env.example (with a .gitignore exception, since the project's default .env* rule would otherwise hide it) — copy it to .env.local and fill in NEXT_PUBLIC_POSTHOG_KEY to start tracking.
  • Husky + lint-staged: a .husky/pre-commit hook that runs lint-staged (ESLint --fix + Prettier --write on staged files). Only wires up core.hooksPath if the generated project has its own .git directory.
  • Playwright: playwright.config.ts + an example e2e/home.spec.ts, with test:e2e/test:e2e:ui scripts. Browsers aren't downloaded automatically — run pnpm exec playwright install once inside the generated project.

Development

Want to contribute to the CLI itself (not the projects it generates)? See CONTRIBUTING.md for local setup, testing, and lint/format instructions. Notable changes are tracked in CHANGELOG.md.

npm install
npm test        # Vitest unit tests
npm run lint    # ESLint
npm run format  # Prettier

License

MIT © Mustafa Uçar