---
name: nextjs-project-manual-scaffold
description: "Scaffold a Next.js + TypeScript + Tailwind project manually when create-next-app fails (old macOS, missing build tools, broken npm). Creates all config files and directory structure by hand."
---

# Next.js Project Manual Scaffold

## When to use

Use this skill when you need to create a Next.js project but standard tooling fails:
- `create-next-app` fails due to old Node.js version (e.g., Node 16 on macOS High Sierra 10.13)
- `npm install` is broken (wrong `require()` path in npm/npx binaries)
- Xcode Command Line Tools / git are missing
- Running on macOS 10.13 (High Sierra) where Node.js is capped at v16

## Checklist before starting

- [ ] `node --version` — must be ≥ 16 (older may work but packages have engine requirements)
- [ ] `npm --version` — test first; if broken, fix (see below)
- [ ] Target Node.js version for your packages (Next.js 14+ needs Node 18+)

## Step 1: Fix broken npm (if needed)

On High Sierra, the npm binary often has a wrong `require()` path:

```
/Users/valen/.local/node/bin/npm:
  require('../lib/cli.js')          # WRONG — resolves to /Users/valen/.local/lib/cli.js
```

Fix: make the path point to npm's actual location inside `node_modules`:

```
require('../lib/node_modules/npm/lib/cli.js')   # RIGHT
```

Apply the fix:
```bash
sed -i '' 's|require('\''../lib/cli.js'\'')|require('\''../lib/node_modules/npm/lib/cli.js'\'')|' $(which npm)
sed -i '' 's|require('\''./npm-cli.js'\'')|require('\''../lib/node_modules/npm/bin/npm-cli.js'\'')|' $(which npx)
sed -i '' 's|require('\''../lib/utils/config/index.js'\'')|require('\''../lib/node_modules/npm/lib/utils/config/index.js'\'')|' $(which npx)
```

Verify: `npm --version` should return a version, not crash.

## Step 2: Directory structure

Create the project folder and core directories manually:

```bash
mkdir -p ~/Desktop/myproject
mkdir -p src/app
mkdir -p src/app/api
mkdir -p src/components/ui
mkdir -p src/components/layout
mkdir -p src/lib
mkdir -p src/types
mkdir -p public/images
```

## Step 3: package.json (core dependencies)

Write `package.json` with pinned versions compatible with Node 16 (if on Node 16):

```json
{
  "name": "myproject",
  "version": "0.1.0",
  "private": true,
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start"
  },
  "dependencies": {
    "next": "^14.2.0",
    "react": "^18.2.0",
    "react-dom": "^18.2.0",
    "clsx": "^2.1.0",
    "tailwind-merge": "^2.2.0",
    "lucide-react": "^0.350.0"
  },
  "devDependencies": {
    "typescript": "^5.3.0",
    "@types/node": "^20.11.0",
    "@types/react": "^18.2.0",
    "@types/react-dom": "^18.2.0",
    "autoprefixer": "^10.4.0",
    "postcss": "^8.4.0",
    "tailwindcss": "^3.4.0",
    "eslint": "^8.56.0",
    "eslint-config-next": "^14.2.0"
  }
}
```

For Node 18+ you can use later versions — the structure is the same.

## Step 4: Config files (write manually)

### tsconfig.json
```json
{
  "compilerOptions": {
    "lib": ["dom", "dom.iterable", "esnext"],
    "allowJs": true,
    "skipLibCheck": true,
    "strict": true,
    "noEmit": true,
    "esModuleInterop": true,
    "module": "esnext",
    "moduleResolution": "bundler",
    "resolveJsonModule": true,
    "isolatedModules": true,
    "jsx": "preserve",
    "incremental": true,
    "plugins": [{ "name": "next" }],
    "paths": { "@/*": ["./src/*"] },
    "baseUrl": "."
  },
  "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx", ".next/types/**/*.ts"],
  "exclude": ["node_modules"]
}
```

### next.config.ts
```typescript
import type { NextConfig } from "next";
const nextConfig: NextConfig = {
  images: { remotePatterns: [{ protocol: "https", hostname: "**" }] },
};
export default nextConfig;
```

### tailwind.config.ts
Standard Tailwind CSS config with `content` paths pointing to `./src/`.
Use the `nautica_platform_plan.md` file on desktop as a reference for a production-grade Tailwind config with brand colors, animations, and CSS variable definitions.

### postcss.config.js
```js
module.exports = { plugins: { tailwindcss: {}, autoprefixer: {} } };
```

### globals.css
CSS variables for `:root` (light mode) and `.dark` (dark mode) with:
- `--background`, `--foreground`, `--primary`, `--secondary`, `--muted`, `--accent`, `--border`, `--ring`
- `@tailwind base/components/utilities` directives
- Custom component classes (`.card-hover`, `.glass`, `.gradient-text`, `.hero-gradient`)
- Custom scrollbar styles

### .env.local.example
```env
# App
NEXT_PUBLIC_APP_URL=http://localhost:3000
# Add service-specific keys below
```

## Step 5: Core files to write

### src/app/layout.tsx
Root layout with:
- HTML language attribute
- Font loading (Inter from next/font/google)
- `<Header />` and `<Footer />` component wrappers
- Metadata export (title, description, openGraph)

### src/app/page.tsx
Main page with hero section, AI input, results section.

### src/lib/utils.ts
Utility function `cn()` for merging Tailwind classes (clsx + tailwind-merge):
```typescript
import { clsx, type ClassValue } from "clsx";
import { twMerge } from "tailwind-merge";
export function cn(...inputs: ClassValue[]) {
  return twMerge(clsx(inputs));
}
```

### src/types/index.ts
TypeScript interfaces for your data model — the Nautica types file (on desktop) is a good reference for a real-world schema.

### Components
Write manual versions of:
- `Header.tsx` — fixed top nav with glass effect, mobile hamburger menu
- `Footer.tsx` — multi-column footer with link groups
- UI components with Tailwind classes

## Step 6: .gitignore
```
node_modules
.next
.env*.local
.DS_Store
*.tsbuildinfo
next-env.d.ts
```

## Step 7: Install dependencies

```bash
cd ~/Desktop/myproject
npm install
```

Note: On macOS High Sierra with Node 16, `npm install` will show `EBADENGINE` warnings but will still install. The project will work on a proper dev machine. Push to GitHub, clone on a modern machine, run `npm install && npm run dev`.

## Step 8: Verify project runs

```bash
npm run build  # or npm run dev
```

If build succeeds, the project is properly scaffolded.

## Pitfalls

1. **npm binary broken on High Sierra**: The `require('../lib/cli.js')` path in `/bin/npm` resolves to the wrong location. Patch it to `../lib/node_modules/npm/lib/cli.js`.

2. **Node 18+ binary doesn't work on High Sierra (10.13)**: Binaries are built for macOS 10.15+. You cannot just download a newer Node. Use nvm or stay with Node 16.

3. **nvm installs require Xcode CLT**: If `xcode-select -p` fails, nvm can't compile from source. Pre-built binaries from nodejs.org won't work either (wrong macOS version).

4. **create-next-app requires Node 18.17+**: On Node 16, use manual scaffold (this skill).

5. **Supabase and modern packages need Node 18+**: Omit `@supabase/supabase-js` from package.json on Node 16, or use an older version (`^2.0.0` with specific pinning).

6. **Some Tailwind v3.4+ plugins require Node 18**: Pin to `tailwindcss@3.3.0` if on Node 16 and encountering issues.

## Verification

```bash
ls -la
# Should see: package.json, tsconfig.json, next.config.ts, tailwind.config.ts, postcss.config.js, .gitignore, src/

cd src && find . -name "*.tsx" -o -name "*.ts" | sort
# Should see: layout.tsx, page.tsx, types/index.ts, lib/utils.ts, components/...

npm run build
# Should complete without errors
```
