# Local setup

Configure a clone without overwriting an existing project’s identity or credentials.

## Prerequisites [#prerequisites]

Use the repository’s pnpm version (`packageManager` in the root manifest), a supported Node runtime (CI uses Node 24), Git and a local Postgres installation for integration tests.

<Steps>
  <Step title="Install the workspace">```sh pnpm install --frozen-lockfile ```</Step>
  <Step title="Configure the project">
    ```sh pnpm setup pnpm doctor ``` Setup covers identity, environment files and the selected
    database/Cloudflare providers. For an existing clone, preserve its identity and credentials and
    repair only missing configuration.
  </Step>
  <Step title="Apply migrations and start">```sh pnpm db:migrate pnpm dev:web ```</Step>
</Steps>

## Local runtime [#local-runtime]

The web dev server defaults to port 3005 and uses Nitro/Node, not workerd. The production build uses the Cloudflare plugin. A successful dev request alone does not validate Worker compatibility. Use the [built-Worker checks](/docs/development/testing) for changes to server dependencies.

Parallel worktrees need separate ports and isolated databases. Set an explicit dev-server port and stop only processes you started. Do not run migrations against another lane’s database.

## Common setup failures [#common-setup-failures]

Missing credentials belong in the correct [environment file](/docs/development/environments). A database history mismatch needs investigation, not `db:push`. Start with `pnpm doctor` and the existing setup skill before manually rewriting project identifiers.

## Key files [#key-files]

- [`packages/project-setup-cli/src/index.mjs`](https://github.com/CarlosZiegler/template-cloudflare/blob/main/packages/project-setup-cli/src/index.mjs)
- [`.agents/skills/setup-envs/SKILL.md`](https://github.com/CarlosZiegler/template-cloudflare/blob/main/.agents/skills/setup-envs/SKILL.md)
- [`.agents/skills/startup/SKILL.md`](https://github.com/CarlosZiegler/template-cloudflare/blob/main/.agents/skills/startup/SKILL.md)