This document describes the pnpm workspace structure of the prompt-optimizer repository, detailing all packages, their dependencies, and the build orchestration system. The monorepo contains three core packages that provide shared functionality and three application packages that target different deployment platforms.
For information about how these packages are adapted for different runtime environments, see Multi-Platform Architecture. For details on deployment configurations, see Deployment and Configuration.
The repository is structured as a pnpm monorepo with six distinct packages organized under the packages/ directory. The workspace uses pnpm 10.6.1 with strict package manager enforcement.
Repository Root Structure
Sources: package.json1-107 pnpm-lock.yaml1-22
The @prompt-optimizer/core package contains all business logic for AI model interactions, data management, and prompt optimization. It has no dependencies on UI code and can run in both browser and Node.js environments.
Package Configuration:
| Property | Value |
|---|---|
| Package Name | @prompt-optimizer/core |
| Location | packages/core/ |
| Build Output | dist/index.js (ESM), dist/index.cjs (CJS) |
| Build Tool | tsup |
| Key Dependencies | openai, @google/genai, @anthropic-ai/sdk, dexie, mustache |
Key Responsibilities:
ITextProviderAdapter, TextAdapterRegistry)ModelManager, TextModelConfig)PromptService)TemplateManager)HistoryManager, PromptRecordChain)IStorageProvider, FileStorageProvider)VariableManager)Build Configuration:
The package uses tsup to generate both CommonJS and ESM outputs with TypeScript declarations:
Sources: packages/core/package.json1-46 packages/core/src/services/model/defaults.ts1-119
The @prompt-optimizer/ui package provides reusable Vue.js components and composables that form the shared UI library. It depends on @prompt-optimizer/core and is consumed by all three application packages.
Package Configuration:
| Property | Value |
|---|---|
| Package Name | @prompt-optimizer/ui |
| Location | packages/ui/ |
| Build Output | dist/index.js (ESM), dist/index.cjs (CJS), dist/style.css |
| Build Tool | Vite (library mode) |
| Key Dependencies | @prompt-optimizer/core (workspace), vue, naive-ui, pinia, vue-router, codemirror |
Key Exports:
The package exports Vue components, Pinia stores, composables, and styles:
Style Distribution:
The package includes a CSS bundle at dist/style.css that must be imported by consuming applications.
Sources: packages/ui/package.json1-68 pnpm-lock.yaml305-401
The @prompt-optimizer/mcp-server package implements the Model Context Protocol server, enabling integration with Claude Desktop and other MCP-compatible applications. It depends only on @prompt-optimizer/core and operates independently of the UI layer.
Package Configuration:
| Property | Value |
|---|---|
| Package Name | @prompt-optimizer/mcp-server |
| Location | packages/mcp-server/ |
| Build Output | dist/index.js (ESM), dist/start.cjs (CJS) |
| Binary | prompt-optimizer-mcp |
| Build Tool | tsup |
| Key Dependencies | @prompt-optimizer/core (workspace), @modelcontextprotocol/sdk, express |
Exposed Tools:
The MCP server exposes three tools via the Model Context Protocol:
optimize-user-prompt: Optimizes user-facing promptsoptimize-system-prompt: Optimizes system-level promptsiterate-prompt: Performs targeted iteration on existing promptsModel Configuration Reuse:
The MCP server leverages the core package's defaultModels configuration and ModelManager:
Sources: packages/mcp-server/package.json1-53 packages/mcp-server/src/config/models.ts1-69 docs/user/mcp-server.md1-238
The web application package builds a Single Page Application (SPA) using Vite. It consumes @prompt-optimizer/ui and deploys to Vercel, Docker, or static hosting.
Package Configuration:
| Property | Value |
|---|---|
| Package Name | @prompt-optimizer/web |
| Location | packages/web/ |
| Build Output | dist/ (static files) |
| Build Tool | Vite |
| Key Dependencies | @prompt-optimizer/ui (workspace), vue |
Deployment Targets:
Sources: packages/web/package.json1-36 vercel.json1-33
The browser extension package builds a Chrome Manifest V3 extension that runs in the browser's extension environment.
Package Configuration:
| Property | Value |
|---|---|
| Package Name | @prompt-optimizer/extension |
| Location | packages/extension/ |
| Build Output | dist/ (extension files) |
| Build Tool | Vite |
| Manifest | public/manifest.json |
| Key Dependencies | @prompt-optimizer/ui (workspace), vue |
Extension Configuration:
The extension uses Manifest V3 with a service worker background script:
Sources: packages/extension/package.json1-37 packages/extension/public/manifest.json1-34
The desktop application package uses Electron to provide a native cross-platform application for Windows, macOS, and Linux. It bundles the web application and runs core services in the main process.
Package Configuration:
| Property | Value |
|---|---|
| Package Name | @prompt-optimizer/desktop |
| Location | packages/desktop/ |
| Main Entry | main.js (Electron main process) |
| Preload Script | preload.js (IPC bridge) |
| Build Tool | electron-builder |
| Key Dependencies | @prompt-optimizer/core (workspace), electron, electron-updater |
Build Process:
The desktop build involves multiple steps:
ELECTRON_BUILD=true flagpackages/desktop/web-dist/Output Artifacts:
| Platform | Installer | Portable |
|---|---|---|
| Windows | .exe (NSIS) | .zip |
| macOS | .dmg | .zip (x64, arm64) |
| Linux | .AppImage | .zip |
Sources: packages/desktop/package.json1-99
The following diagram illustrates the dependency relationships between packages, showing how workspace links (workspace:*) connect them:
Package Dependency Graph
Workspace Reference Resolution:
In pnpm-lock.yaml, workspace dependencies are resolved using link: protocol:
Sources: pnpm-lock.yaml10-456 packages/ui/package.json33-49 packages/desktop/package.json24-31
The root package.json defines orchestrated build commands that handle the dependency order and enable parallel builds where possible.
Build Command Structure
Root Build Scripts:
| Script | Command | Purpose |
|---|---|---|
build | npm-run-all build:core build:ui build:parallel | Full monorepo build |
build:core | pnpm -F @prompt-optimizer/core build | Build core package |
build:ui | pnpm -F @prompt-optimizer/ui build | Build UI package |
build:parallel | npm-run-all --parallel build:web build:ext | Parallel app builds |
build:web | pnpm -F @prompt-optimizer/web build | Build web app |
build:ext | pnpm -F @prompt-optimizer/extension build | Build extension |
build:desktop | npm-run-all build:core build:ui build:web build:desktop-only | Build desktop app |
Desktop Special Case:
The desktop build requires the web distribution as input, so it runs a sequential build:
Sources: package.json11-26
Development Commands:
| Script | Command | Purpose |
|---|---|---|
dev | npm-run-all clean:dist build:core build:ui dev:parallel | Start web dev server |
dev:parallel | concurrently -k -p "[{name}]" -n "UI,WEB" "pnpm -F @prompt-optimizer/ui build --watch" "pnpm -F @prompt-optimizer/web dev" | Parallel watch mode |
dev:ext | pnpm -F @prompt-optimizer/extension dev | Extension dev server |
dev:desktop | npm-run-all clean:dist build:core build:ui dev:desktop:parallel | Desktop dev mode |
dev:fresh | npm-run-all kill:dev clean pnpm-install dev | Clean restart |
Workspace Filtering:
The -F flag (filter) targets specific packages:
Sources: package.json20-26 package.json41-43
pnpm Workspace Configuration:
The workspace is defined in package.json with pnpm-specific settings:
Workspace Root Dependencies:
The root package declares shared dependencies that are hoisted to the workspace root:
vue, @vue/reactivity, @vue/runtime-core, @vueuse/core@intlify/unplugin-vue-i18n, typescript, electron@playwright/test, vitestconcurrently, npm-run-all, rimrafDependency Hoisting Strategy:
pnpm uses a content-addressable store with symbolic links, preventing phantom dependencies while allowing efficient disk usage. Each package's node_modules/.pnpm contains its flattened dependency tree.
Sources: package.json5-10 package.json61-106 pnpm-lock.yaml1-9
Testing Commands:
| Script | Command | Purpose |
|---|---|---|
test | npm-run-all -s test:unit test:e2e:smart | Run all tests sequentially |
test:unit | pnpm -r test --run --passWithNoTests | Unit tests across all packages |
test:e2e | playwright test | End-to-end tests |
test:e2e:record | cross-env E2E_VCR_MODE=record playwright test | Record E2E fixtures |
test:e2e:replay | cross-env E2E_VCR_MODE=replay playwright test | Replay E2E from fixtures |
test:gate | npm-run-all -s test:gate:core test:gate:ui | CI gate tests |
Test Distribution:
packages/core/tests/: Core business logic tests (Vitest)packages/ui/tests/: UI component tests (Vitest + Vue Test Utils)packages/web/tests/: Web app integration teststests/e2e/: End-to-end tests (Playwright)Sources: package.json27-40 packages/core/tests/unit/model/defaults.test.ts1-41
The monorepo uses a consistent environment variable naming pattern for configuration:
LLM API Keys:
VITE_OPENAI_API_KEYVITE_GEMINI_API_KEYVITE_ANTHROPIC_API_KEYVITE_DEEPSEEK_API_KEYVITE_SILICONFLOW_API_KEYVITE_ZHIPU_API_KEYVITE_CUSTOM_API_KEY, VITE_CUSTOM_API_BASE_URL, VITE_CUSTOM_API_MODELMulti-Custom Models:
VITE_CUSTOM_API_KEY_<suffix>VITE_CUSTOM_API_BASE_URL_<suffix>VITE_CUSTOM_API_MODEL_<suffix>MCP Server Specific:
MCP_DEFAULT_MODEL_PROVIDERMCP_HTTP_PORTMCP_LOG_LEVELAccess Control (Docker):
ACCESS_USERNAMEACCESS_PASSWORDThe VITE_ prefix ensures these variables are exposed to browser builds, while MCP variables are server-only.
Sources: env.local.example1-147 packages/core/src/services/model/defaults.ts10-21
All packages use version synchronization to ensure consistent releases:
When the root version changes, sync-versions.js updates all package versions to match, ensuring consistency across deployments.
Sources: package.json45-49
Refresh this wiki