What Is `pnpm dev` in Paperclip? A Deep Dive Into the Local Development Runtime

pnpm dev is the single command that launches Paperclip's complete local development environment, starting both the API server and React UI while handling database setup, file watching, auto-restart, and migration management automatically.

In the paperclipai/paperclip repository, this command serves as the central entry point for developers building on or extending the platform. Rather than manually orchestrating multiple services, developers rely on pnpm dev to mirror production behavior—including service registration, health checks, and schema migrations—while maintaining a fast feedback loop through hot reloading.

What pnpm dev Actually Starts

When you run pnpm dev from the repository root, the orchestration logic in scripts/dev-runner.ts initializes several interconnected systems.

API Server and React UI on a Unified Port

The command binds both backend and frontend to http://localhost:3100 by default, as documented in docs/start/quickstart.md. This unified port eliminates cross-origin complications during local development and ensures the control plane behaves as it would in production.

Embedded PostgreSQL with Zero Configuration

If DATABASE_URL is unset, the dev runner automatically provisions an embedded PostgreSQL instance. This removes external database dependencies for new contributors and guarantees version compatibility with Paperclip's schema expectations.

File Watching and Auto-Restart Across the Monorepo

The runner monitors backend code, database migrations, UI components, and configuration files. As implemented in scripts/dev-runner.ts#L5045-L5069, it triggers safe restarts when changes are detected—preserving in-memory state where possible while ensuring code changes take effect immediately.

Migration Handling and Schema Synchronization

Before the server accepts traffic, pnpm dev evaluates pending schema migrations. The logic in scripts/dev-runner.ts#L4250-L4265 either prompts for confirmation or auto-applies migrations based on safety heuristics. This keeps the development database synchronized with server/src/db/migrations without requiring manual prisma migrate invocations.

Plugin SDK Regeneration

On every restart, the dev runner rebuilds the plugin SDK as shown in scripts/dev-runner.ts#L4778-L4892. This ensures locally developed plugins compiled from packages/plugin-sdk are instantly available to running workspaces, eliminating the need for separate build watches.

Service Registration and Local Discovery

The dev runtime registers itself with Paperclip's local service supervisor, implemented in server/src/services/local-service-supervisor.ts. This registration—detailed in scripts/dev-runner.ts#L1895-L1901 and scripts/dev-runner.ts#L3320-L3329—exposes:

• URL: The bound address for API/UI access
• PID: Process identifier for lifecycle management
• Health status: Current operational state

Other Paperclip components, such as workspace runtime controls in the UI, query this registry to discover and interact with the active dev environment.

Network Binding Modes for Multi-Machine Testing

The dev runner supports configurable exposure beyond localhost. As defined in scripts/dev-runner.ts#L58-L70 and utilized in server/src/routes/access.ts#L1629-L1632:

Flag	Purpose
--bind lan	Exposes the dev server to your local network for device testing
--bind tailnet	Publishes via Tailscale for secure remote collaboration

These modes enable testing from mobile devices, browser stacks, or colleague machines without deployment pipelines.

Common pnpm dev Commands and Variants

# Standard development mode with full watch and auto-restart

pnpm dev

# Single execution without file watching (CI scripts, debugging)

pnpm dev:once

# Expose to local network for cross-device testing

pnpm dev --bind lan

# Frontend-only mode when API runs separately

pnpm dev:ui

# Terminate running dev runtime and clean registry

pnpm dev:stop

These variants are defined in the root package.json script definitions and delegate to scripts/dev-runner.ts with appropriate CLI flags.

Key Implementation Files

File	Responsibility
package.json	Entry point definitions for dev, dev:once, dev:watch, dev:ui, dev:stop
scripts/dev-runner.ts	Core orchestration: environment setup, SDK build, file watching, migration handling, service registration, network binding
docs/start/quickstart.md	User-facing documentation confirming unified port 3100 and embedded database behavior
server/src/services/local-service-supervisor.ts	Persistent registry for dev runtime discovery
server/src/routes/access.ts	Validation for --bind network modes
ui/src/pages/ProjectWorkspaceDetail.tsx	UI reference reinforcing pnpm dev as the expected startup command

Summary

• pnpm dev is the canonical command for Paperclip local development, unifying API, UI, and database in one terminal.
• It auto-manages PostgreSQL, watches and restarts on code changes, and handles migrations before server startup.
• The plugin SDK rebuilds automatically on every restart, keeping local plugin development friction-free.
• Service registration enables other Paperclip components to discover and control the dev runtime.
• Network binding flags (--bind lan, --bind tailnet) support realistic multi-device testing scenarios.

Frequently Asked Questions

What port does pnpm dev use by default?

Paperclip's dev server binds to port 3100 for both API and UI traffic. This is hardcoded as the default in scripts/dev-runner.ts and documented in docs/start/quickstart.md. You can override this via PORT environment variable if needed.

Does pnpm dev require a separate PostgreSQL installation?

No. When DATABASE_URL is unset, the dev runner automatically provisions an embedded PostgreSQL instance. This self-contained approach matches the zero-configuration philosophy described in the quickstart documentation.

How does pnpm dev differ from pnpm dev:once?

pnpm dev enables persistent file watching and auto-restart behavior ideal for active development. pnpm dev:once executes a single server run without watchers—useful for CI pipelines, migration scripts, or debugging startup sequences without filesystem monitoring overhead.

Can I run just the UI frontend with pnpm dev?

Yes. The pnpm dev:ui variant starts only the React development server, assuming you have the API running separately. This split mode is documented in the root package.json scripts and referenced in ui/src/pages/ProjectWorkspaceDetail.tsx for workspace control scenarios.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}