nextjs-sandbox-starter

name: nextjs-sandbox-starter description: Create, install, run, and troubleshoot a Next.js project for non-technical users in Codex environments. Use when a user asks to start a new Next.js app, install Next.js/React prerequisites, run an existing Next.js app, fix common setup/runtime issues, or wants full hands-off setup on macOS, Windows, or Linux.

Next.js Sandbox Starter

Execute end-to-end setup with minimal user effort. Prefer doing the work instead of giving long instructions.

Operating Mode

• Assume the user is non-technical unless they explicitly say otherwise.
• Pick safe defaults and proceed without back-and-forth.
• Explain outcomes in plain language.
• Always report the final app URL and exact project path.

Default Choices

Use these defaults unless the user asks differently:

• Package manager: npm
• Language: JavaScript
• Router: App Router
• Styling: no Tailwind
• Project name: hello-world (or user-provided name)
• Project location: current workspace unless user provides a path

Workflow Selection

Route the request to one workflow:

1. Create new app when user says install/start/new Next project.
2. Run existing app when project exists and user wants it launched.
3. Troubleshoot when install/build/run fails.

For troubleshooting details, load references/troubleshooting.md.

Workflow 1: Create New App

1. Inspect destination path and avoid overwriting existing project files.
2. Check toolchain:

• node -v
• npm -v

3. If Node is missing, install Node LTS by OS:

• macOS: brew install node
• Windows (PowerShell): winget install OpenJS.NodeJS.LTS
• Linux (Debian/Ubuntu): sudo apt-get update && sudo apt-get install -y nodejs npm

4. Scaffold app:

• npx create-next-app@latest <project-name> --js --app --eslint --no-tailwind --use-npm --yes

5. Verify build:

• cd <project-name> && npm run build

6. Start dev server:

• npm run dev

7. If port 3000 is busy, accept fallback port and report it.
8. Return:

• absolute project path
• active local URL
• one command to run later (npm run dev)

Workflow 2: Run Existing App

1. Confirm app folder contains package.json and Next files.
2. Install dependencies if needed:

• npm install

3. Start:

• npm run dev

4. Report the running URL and note port fallback if any.

Workflow 3: Troubleshoot

When a step fails, apply quick fixes in this order:

1. Sandbox/network restrictions
2. Missing Node or outdated Node
3. Package install issues
4. Build errors from remote font fetching
5. Port conflicts
6. Permissions/path issues

Use concrete fixes from references/troubleshooting.md.

Codex Sandbox Rules

• If install/fetch fails with network errors (for example ENOTFOUND, registry unreachable, remote fonts fetch failed), rerun the needed command with escalation/approval flow and continue automatically after approval.
• Do not stop after first failure; retry with the least risky correction.
• Avoid destructive commands unless user asked.

Non-Technical Response Contract

At completion, always provide:

1. What was done (1-3 bullets)
2. Project path (absolute)
3. URL to open
4. Single command for future startup

Keep wording simple and avoid jargon.