Local Development
Connected projects expose two targets for running them on your machine: serve and dev. The difference is one of scope — how much of your application runs locally versus pointing at deployed AWS infrastructure.
Consider a workspace with the following connections: a website that calls a tRPC api, and also calls an agent which in turn calls an mcp server.
The serve target runs only the targeted project locally. Every other project it connects to is expected to be deployed, and is reached at its real AWS URL.
pnpm nx serve websiteyarn nx serve websitenpx nx serve websitebunx nx serve websiteBecause the targeted project talks to deployed resources, it needs to know where they are. For a website this is provided by its runtime-config.json (see Local Runtime Config), which you load from a deployed application. For server-side projects (APIs and agents) that read Runtime Configuration, set the RUNTIME_CONFIG_APP_ID environment variable to point at your deployed AppConfig application.
Use serve when you want to iterate on a single project against the “real”, deployed versions of everything it depends on.
The dev target runs the targeted project and every project connected to it transitively, all on your machine. The connection generator wires this up automatically — running dev on the website also starts local servers for the api, the agent, and the mcp server it reaches through the agent.
pnpm nx dev websiteyarn nx dev websitenpx nx dev websitebunx nx dev websiteWhen run this way, the website’s runtime-config.json is automatically overridden (via Vite’s MODE, set to local-dev) so that it points at your locally running servers instead of deployed URLs.
Every project runs locally, so there are no deployed dependencies.
Use dev when you are working across several connected projects at once and want to iterate quickly without deploying your infrastructure.
Projects with multiple components
Section titled “Projects with multiple components”Some project types can hold multiple components in a single project (for example a TypeScript or Python project containing several agents and MCP servers). For these:
- The project-level
devtarget starts all of the project’s components together. Each component is added todevas it is generated:
pnpm nx dev my-projectyarn nx dev my-projectnpx nx dev my-projectbunx nx dev my-project- Each component also exposes a
<component-name>-devtarget, so you can run a single component on its own:
pnpm nx my-component-dev my-projectyarn nx my-component-dev my-projectnpx nx my-component-dev my-projectbunx nx my-component-dev my-projectFor more detail on each project type’s local development server, see the relevant guide — for example the React Website guide.