Development Workflow

Relevant source files

Purpose and Scope

This document describes the development workflow for Prompt Optimizer, including environment setup, build processes, development commands, and testing procedures. It focuses on the practical aspects of working with the monorepo structure and building the various platform targets.

For information about the overall project structure and package organization, see Project Structure and Packages. For deployment procedures, see Deployment and Operations.

Prerequisites and Environment Setup

Required Tools

Tool	Version Requirement	Purpose
Node.js	`^18.0.0 \|\| ^20.0.0 \|\| ^22.0.0`	Runtime environment
pnpm	`10.6.1`	Package manager (enforced)
TypeScript	`^5.8.2`	Type checking and compilation

The project enforces pnpm as the package manager through the packageManager field and engine constraints that reject npm and yarn with Chinese error messages.

Sources: package.json5-10

Initial Setup

The pnpm install command triggers workspace dependency resolution across all packages defined in pnpm-workspace.yaml.

Sources: package.json34

Monorepo Package Dependency Graph

The project uses pnpm workspaces to manage a monorepo with six packages. Build order matters due to inter-package dependencies.

Dependency Chain:

core has no dependencies on other workspace packages
ui depends on core (workspace:*)
web and extension depend on ui (workspace:*)
desktop copies the built web package
mcp-server depends on core but builds independently

Sources: package.json12-19 packages/core/package.json2 packages/ui/package.json2-32 packages/desktop/package.json24

Build Commands

Root-Level Build Scripts

Command	Description	Script Chain
`pnpm run build`	Full production build	`build:core` → `build:ui` → `build:parallel`
`pnpm run build:core`	Build core package only	`pnpm -F @prompt-optimizer/core build`
`pnpm run build:ui`	Build UI package only	`pnpm -F @prompt-optimizer/ui build`
`pnpm run build:parallel`	Build web and extension in parallel	Uses `npm-run-all --parallel`
`pnpm run build:web`	Build web application	`pnpm -F @prompt-optimizer/web build`
`pnpm run build:ext`	Build browser extension	`pnpm -F @prompt-optimizer/extension build`
`pnpm run build:desktop`	Full desktop build	`build:core` → `build:ui` → `build:web` → `build:desktop-only`
`pnpm run mcp:build`	Build MCP server	`pnpm --filter @prompt-optimizer/mcp-server build`

The desktop build has a special process that copies web artifacts:

Sources: package.json12-42 packages/desktop/package.json11-12

Development Commands

Development Server Workflows

The project provides multiple development workflows optimized for different scenarios:

Command	Use Case	Parallel Processes
`pnpm run dev`	Web application development	UI watch mode + Web dev server
`pnpm run dev:fresh`	Clean start web development	Runs `clean` → `pnpm-install` → `dev`
`pnpm run dev:ext`	Extension development	Single process: extension dev mode
`pnpm run dev:desktop`	Electron app development	Web dev server + Electron dev mode
`pnpm run dev:desktop:fresh`	Clean start desktop development	Runs `clean` → `pnpm-install` → `dev:desktop`
`pnpm run mcp:dev`	MCP server development	Single process: MCP server in dev mode

Concurrent Development Processes

The development commands use concurrently with the -k flag (kill all on first exit) and custom prefixes:

Web Development:

Desktop Development:

The UI package builds in watch mode, detecting changes and rebuilding automatically. The web/desktop packages run Vite dev servers with hot module replacement (HMR).

Sources: package.json20-26 packages/ui/package.json24

Package-Specific Build Configuration

Core Package Build (tsup)

The core package uses tsup for fast TypeScript bundling:

Export Configuration:

This dual-format output enables compatibility with both ESM and CommonJS consumers.

Sources: packages/core/package.json9-18

UI Package Build (Vite Library Mode)

The UI package builds Vue components and exports them as a library:

Export Configuration:

The CSS export allows consuming applications to import styles separately.

Sources: packages/ui/package.json6-25

Desktop Package Build Process

The desktop package has a unique two-stage build:

Key Points:

The web application is built with --base=./ for relative path resolution
A Node.js inline script copies packages/web/dist/ to packages/desktop/web-dist/
electron-builder packages the Electron main/preload scripts with the copied web files
Multi-platform artifacts are generated based on the build.win, build.mac, build.linux configuration

Sources: packages/desktop/package.json11-89

Testing Strategy

Test Framework Configuration

Test Commands

Command	Scope	Description
`pnpm test`	All packages	Runs `pnpm -r test --run --passWithNoTests`
`pnpm test:e2e`	Root	Executes Playwright E2E tests
`pnpm test:e2e:ui`	Root	Opens Playwright UI mode
`pnpm test:e2e:debug`	Root	Runs Playwright in debug mode
`pnpm --filter @prompt-optimizer/core test`	Core package	Runs vitest in core package
`pnpm --filter @prompt-optimizer/core test:watch`	Core package	Runs vitest in watch mode
`pnpm --filter @prompt-optimizer/core test:unit`	Core package	Runs only unit tests
`pnpm --filter @prompt-optimizer/core test:integration`	Core package	Runs only integration tests

The -r flag in the root test command runs tests recursively across all workspace packages that have a test script defined.

Sources: package.json27-30 packages/core/package.json19-23

Test Organization in Core Package

The core package separates unit and integration tests:

packages/core/tests/ ├── unit/ # Fast, isolated tests └── integration/ # Tests requiring external services

This separation allows running fast unit tests during development and slower integration tests in CI.

Sources: packages/core/package.json22-23

Cleaning and Maintenance

Clean Commands

Command	Target	Description
`pnpm run clean`	All	Runs `clean:dist` and `clean:vite`
`pnpm run clean:dist`	Build outputs	Removes `dist/` from all packages and `web-dist/` from desktop
`pnpm run clean:vite`	Vite cache	Removes `.vite/` cache directories from all packages

Cleaned Directories:

packages/core/dist
packages/ui/dist
packages/web/dist
packages/extension/dist
packages/desktop/dist
packages/desktop/web-dist
packages/*/node_modules/.vite

The clean:dist command uses rimraf for cross-platform directory removal.

Sources: package.json31-33

Version Management

Version Synchronization

The project uses a custom version synchronization script to keep all package versions aligned:

Version Workflow:

The version script in package.json has a hook that automatically runs version:sync and stages changes:

Sources: package.json35-39

Common Development Workflows

Starting Fresh Development

Working on Core Services

Testing a Specific Package

Building for Production

Extension Development

Sources: package.json20-26 packages/extension/public/manifest.json1-34

Linting and Code Quality

Linting Commands

The linting configuration uses:

eslint with TypeScript support (@typescript-eslint/parser, @typescript-eslint/eslint-plugin)
Vue plugin (eslint-plugin-vue)
Custom .eslintrc.json configuration in the UI package

Sources: package.json44-45 packages/ui/package.json28-50

Package Manager Enforcement

The project strictly enforces pnpm through multiple mechanisms:

Engine Constraints

Package Manager Field

This field enables Corepack (Node.js 16.9+) to automatically use the correct pnpm version.

PNPM-Specific Configuration

The onlyBuiltDependencies optimization prevents unnecessary native module rebuilds for packages other than Electron.

Sources: package.json5-95