MCP HubMCP Hub
← Back to Skills

scaffold-nextjs-app

pjt222
Updated 2 days ago
4 views
17
2
17
View on GitHub
Metareactapidesign

About

This skill scaffolds a new Next.js application with App Router and TypeScript, establishing the project structure, routing, and configuration. It's for developers starting a web project needing a React-based, full-stack foundation with server-side rendering. Use it to quickly generate a production-ready TypeScript web application from scratch.

Quick Install

Claude Code

Recommended
Primary
npx skills add pjt222/agent-almanac -a claude-code
Plugin CommandAlternative
/plugin add https://github.com/pjt222/agent-almanac
Git CloneAlternative
git clone https://github.com/pjt222/agent-almanac.git ~/.claude/skills/scaffold-nextjs-app

Copy and paste this command in Claude Code to install this skill

Documentation

Scaffold Next.js App

Make new Next.js app with App Router, TypeScript, prod-ready defaults.

When Use

  • Start new web app project
  • Make React frontend with server-side rendering
  • Build full-stack app with API routes
  • Set up TypeScript web project

Inputs

  • Required: App name
  • Required: Package manager (npm, yarn, pnpm)
  • Optional: Tailwind CSS (default: yes)
  • Optional: ESLint (default: yes)
  • Optional: src/ dir structure (default: yes)

Steps

Step 1: Create Project

npx create-next-app@latest my-app \
  --typescript \
  --tailwind \
  --eslint \
  --app \
  --src-dir \
  --import-alias "@/*"

Answer prompts or use flags to set all options non-interactive.

Got: Project dir made with all deps installed.

If fail: Check Node.js version (node --version, must be >= 18.17). Ensure npx available. Command hangs on prompts? Add --use-npm (or --use-pnpm/--use-yarn) to skip package manager prompt.

Step 2: Verify Project Structure

my-app/
├── src/
│   ├── app/
│   │   ├── layout.tsx        # Root layout
│   │   ├── page.tsx          # Home page
│   │   ├── globals.css       # Global styles
│   │   └── favicon.ico
│   └── lib/                  # Shared utilities (create manually)
├── public/                   # Static assets
├── next.config.ts            # Next.js configuration
├── tailwind.config.ts        # Tailwind configuration
├── tsconfig.json             # TypeScript configuration
├── package.json
└── .eslintrc.json

Got: All listed dirs and files present.

If fail: src/ dir missing? --src-dir flag not passed. Re-run create-next-app with flag, or move files manually into src/app/.

Step 3: Configure Next.js

Edit next.config.ts for project needs.

import type { NextConfig } from "next";

const nextConfig: NextConfig = {
  // Enable React strict mode
  reactStrictMode: true,

  // Image optimization domains
  images: {
    remotePatterns: [
      {
        protocol: "https",
        hostname: "example.com",
      },
    ],
  },
};

export default nextConfig;

Got: next.config.ts saved without TypeScript errors.

If fail: File uses .js not .ts? Rename. Ensure NextConfig type imported from "next".

Step 4: Set Up Directory Conventions

Make common dirs.

mkdir -p src/app/api
mkdir -p src/components
mkdir -p src/lib
mkdir -p src/types

Got: All four dirs made under src/.

If fail: src/ does not exist? Make it first or adjust paths to match (non-src layout uses app/ at root).

Step 5: Create Base Layout

Edit src/app/layout.tsx.

import type { Metadata } from "next";
import { Inter } from "next/font/google";
import "./globals.css";

const inter = Inter({ subsets: ["latin"] });

export const metadata: Metadata = {
  title: "My Application",
  description: "Application description",
};

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en">
      <body className={inter.className}>{children}</body>
    </html>
  );
}

Got: Layout renders with Inter font, wraps all pages.

If fail: Font fails to load? Check network. Replace Inter with system font fallback as temp workaround.

Step 6: Add Example API Route

Make src/app/api/health/route.ts.

import { NextResponse } from "next/server";

export async function GET() {
  return NextResponse.json({ status: "ok", timestamp: new Date().toISOString() });
}

Got: File made at src/app/api/health/route.ts.

If fail: Ensure api/health/ dir exists. File must export named HTTP method handlers (GET, POST, etc.), not default export.

Step 7: Run Dev Server

cd my-app
npm run dev

Got: App running at http://localhost:3000.

If fail: Check Node.js version (>= 18.17). Run npm install if deps missing.

Checks

  • npm run dev starts without errors
  • Home page loads at localhost:3000
  • TypeScript compiles
  • Tailwind CSS classes applied
  • API route responds at /api/health
  • ESLint runs without errors (npm run lint)

Pitfalls

  • Node.js version: Next.js needs Node.js >= 18.17. Check with node --version.
  • Port conflicts: Default port 3000 may be used. Use npm run dev -- -p 3001.
  • Import alias confusion: @/* maps to src/*. Do not confuse with node_modules imports.
  • Pages vs App Router: Ensure App Router (src/app/) not Pages (src/pages/).

See Also

  • setup-tailwind-typescript - detailed Tailwind + TypeScript config
  • deploy-to-vercel - deploy scaffolded app
  • configure-git-repository - version control setup

GitHub Repository

pjt222/agent-almanac
Path: i18n/caveman/skills/scaffold-nextjs-app
0
agentsagentskillsai-assisted-developmentclaude-codeskillsteams

Related Skills

content-collections

Meta

This skill provides a production-tested setup for Content Collections, a TypeScript-first tool that transforms Markdown/MDX files into type-safe data collections with Zod validation. Use it when building blogs, documentation sites, or content-heavy Vite + React applications to ensure type safety and automatic content validation. It covers everything from Vite plugin configuration and MDX compilation to deployment optimization and schema validation.

View skill

polymarket

Meta

This skill enables developers to build applications with the Polymarket prediction markets platform, including API integration for trading and market data. It also provides real-time data streaming via WebSocket to monitor live trades and market activity. Use it for implementing trading strategies or creating tools that process live market updates.

View skill

creating-opencode-plugins

Meta

This skill helps developers create OpenCode plugins that hook into 25+ event types like commands, files, and LSP operations. It provides the plugin structure, event API specifications, and implementation patterns for JavaScript/TypeScript modules. Use it when you need to intercept, monitor, or extend the OpenCode AI assistant's lifecycle with custom event-driven logic.

View skill

sglang

Meta

SGLang is a high-performance LLM serving framework that specializes in fast, structured generation for JSON, regex, and agentic workflows using its RadixAttention prefix caching. It delivers significantly faster inference, especially for tasks with repeated prefixes, making it ideal for complex, structured outputs and multi-turn conversations. Choose SGLang over alternatives like vLLM when you need constrained decoding or are building applications with extensive prefix sharing.

View skill