Skills › Compound Engineering › ce-polish › dev-server-next.md

dev-server-next.md

61 lines · skills/ce-polish/references/dev-server-next.md at 3449230

Open on GitHub

1# Next.js dev-server recipe (auto-detect fallback)

3Loaded when `detect-project-type.sh` returns `next` and the startup tuple still lacks a command.

Next.js dev-server recipe (auto-detect fallback)

Loaded when detect-project-type.sh returns next and the startup tuple still lacks a command.

Raw lines 1 to 4

5## Signature

7- `next.config.js`, `next.config.mjs`, `next.config.ts`, or `next.config.cjs` exists

8- `package.json` contains a `next` dependency

Signature

next.config.js, next.config.mjs, next.config.ts, or next.config.cjs exists
package.json contains a next dependency

Raw lines 5 to 9

10## Start command

12Standard:

14```bash

15npm run dev

16```

18Also valid (read `package.json` scripts to confirm which the project uses):

20```bash

21pnpm dev

22yarn dev

23bun run dev

24```

26Prefer the package manager indicated by the lockfile:

27- `pnpm-lock.yaml` -> `pnpm dev`

28- `yarn.lock` -> `yarn dev`

29- `bun.lock` / `bun.lockb` -> `bun run dev`

30- `package-lock.json` or none -> `npm run dev`

Start command

Standard:

npm run dev

Also valid (read package.json scripts to confirm which the project uses):

pnpm dev
yarn dev
bun run dev

Prefer the package manager indicated by the lockfile:

pnpm-lock.yaml -> pnpm dev
yarn.lock -> yarn dev
bun.lock / bun.lockb -> bun run dev
package-lock.json or none -> npm run dev

Raw lines 10 to 31

32## Port

34Default: `3000`. Next.js respects `-p <port>` / `--port <port>` and the `PORT` env var. Overrides follow the cascade in `references/dev-server-detection.md`.

Port

Default: 3000. Next.js respects -p <port> / --port <port> and the PORT env var. Overrides follow the cascade in references/dev-server-detection.md.

Raw lines 32 to 35

36## Turbopack

38Next.js 14+ supports `--turbo` (and 15+ makes it default). If the `dev` script in `package.json` includes `--turbo`, preserve it. Turbopack changes reload behavior but not port or URL conventions.

Turbopack

Next.js 14+ supports --turbo (and 15+ makes it default). If the dev script in package.json includes --turbo, preserve it. Turbopack changes reload behavior but not port or URL conventions.

Raw lines 36 to 39

40## Stub generation

42```json

43{

44 "version": "0.2.0",

45 "configurations": [

46 {

47 "name": "Next dev",

48 "runtimeExecutable": "npm",

49 "runtimeArgs": ["run", "dev"],

50 "port": 3000

51 }

52 ]

53}

54```

56Substitute the resolved package manager (`npm` / `pnpm` / `yarn` / `bun`) and port.

Stub generation

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Next dev",
      "runtimeExecutable": "npm",
      "runtimeArgs": ["run", "dev"],
      "port": 3000
    }
  ]
}

Substitute the resolved package manager (npm / pnpm / yarn / bun) and port.

Raw lines 40 to 57

58## Common gotchas

60- **Monorepo roots:** in a pnpm/Turborepo monorepo, `npm run dev` at the root typically fans out to multiple packages. Users should set `cwd` in `.claude/launch.json` to the specific Next app (`cwd: "apps/web"`).

61- **Env loading:** `.env.local` is loaded automatically by Next; polish does not need to export it.

Common gotchas

Monorepo roots: in a pnpm/Turborepo monorepo, npm run dev at the root typically fans out to multiple packages. Users should set cwd in .claude/launch.json to the specific Next app (cwd: "apps/web").
Env loading: .env.local is loaded automatically by Next; polish does not need to export it.

Raw lines 58 to 61