scaffold-nextjs-app

pjt222

Updated 2 days ago

8 views

Metareactapi

About

This skill scaffolds a new Next.js application using the App Router and TypeScript with modern, production-ready defaults. It sets up the project structure, routing, and initial configuration for full-stack or frontend web apps. Use it to quickly bootstrap projects requiring server-side rendering or API routes.

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

Create a new Next.js application with App Router, TypeScript, and production-ready defaults.

When to Use

Starting a new web application
React frontend with server-side rendering
Full-stack application with API routes
TypeScript web project

Inputs

Required: Application name
Required: Package manager preference (npm, yarn, pnpm)
Optional: Include Tailwind CSS (default: yes)
Optional: Include ESLint (default: yes)
Optional: src/ directory structure (default: yes)

Procedure

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-interactively.

Got: Project directory created with all dependencies installed.

If fail: Check Node.js version (node --version, must be >= 18.17). Ensure npx is available. If the command hangs on prompts, add --use-npm (or --use-pnpm/--use-yarn) to skip the 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 directories and files present.

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

Step 3: Configure Next.js

Edit next.config.ts:

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: If file uses .js instead of .ts, rename it. Ensure NextConfig type is imported from "next".

Step 4: Set Up Directory Conventions

Create common directories:

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

Got: All four directories created under src/.

If fail: If src/ does not exist, create it first or adjust paths to match the project structure (non-src layout uses app/ at the 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 the Inter font and wraps all pages.

If fail: If font fails to load, check network access. Replace Inter with a system font fallback as a temporary workaround.

Step 6: Add Example API Route

Create 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 created at src/app/api/health/route.ts.

If fail: Ensure the api/health/ directory exists. The file must export named HTTP method handlers (GET, POST, etc.), not a default export.

Step 7: Run Development Server

cd my-app
npm run dev

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

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

Validation

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

Pitfalls

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

Related Skills

setup-tailwind-typescript - detailed Tailwind and TypeScript configuration
deploy-to-vercel - deploy the scaffolded app
configure-git-repository - version control setup

GitHub Repository

pjt222/agent-almanac

Path: i18n/caveman-lite/skills/scaffold-nextjs-app

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