Building for Production

The web-archive project is a pnpm monorepo structured into three main packages: server, web, and plugin. The production build process compiles these packages into two primary distributable artifacts: a Cloudflare service (combining the server and web client) and a browser extension (with variants for Chrome and Firefox).

The build system leverages Vite for all packages, with specialized configurations for each target environment. The root package.json orchestrates the entire process through a set of high-level npm scripts.

Build Orchestration

The primary build commands are defined in the root package.json file. These scripts utilize pnpm --filter to target specific workspaces within the monorepo.

Sources: package.json:24-27

Build Scripts

High-Level Build Flow

The following diagram illustrates the main build commands and the packages they trigger.

Service Build (build:service)

The build:service command is responsible for creating the deployable Cloudflare service. It sequentially builds the @web-archive/server and @web-archive/web packages.

"build:service": "pnpm --filter=server build && pnpm --filter=web build && node scripts/build_clear.mjs"

Sources: package.json:25

The process ensures that the web client's static assets are built first and placed into the server's output directory, creating a self-contained service ready for deployment to Cloudflare Pages.

Service Build Flow

This diagram shows how the server and web packages are built and their outputs are combined.

Server Package (@web-archive/server)

The server is a Hono application designed to run on Cloudflare Workers.

• Configuration: packages/server/vite.config.ts
• Entry Point: src/server.ts
• Output Directory: ../../dist/service/src
• Key Plugin: @hono/vite-cloudflare-pages is used to compile the Hono application into a Cloudflare Pages function.
• Static Assets: The viteStaticCopy plugin copies necessary deployment files:
  • wrangler.raw.toml is copied and renamed to wrangler.toml.
  • SQL migration files from src/sql/migrations are copied to the output.

Sources: packages/server/vite.config.ts:19-39, packages/server/package.json:4

Web Client Package (@web-archive/web)

The web client is a React single-page application.

• Configuration: packages/web/vite.config.ts
• Entry Point: src/index.tsx
• Output Directory: ../../dist/service/src/static
• Integration: The web client is built directly into the static subdirectory of the server's output. This allows the Hono server to serve the React application's static files.
• Optimization: The build uses Rollup's manualChunks option to split vendor libraries (react, radix-ui, recharts) into separate chunks for better caching and initial load times.

Sources: packages/web/vite.config.ts:18-29, packages/web/package.json:3

Plugin Build (build:plugin & build:plugin-firefox)

The browser extension is built using a separate production configuration that handles multiple entry points and targets different browser platforms.

Sources: packages/plugin/package.json:11-12

Plugin Build Configuration

• Configuration: packages/plugin/vite.production.config.ts
• Build Logic: A command-line flag, --firefox, determines the build target.
  • const isFirefox = process.argv.includes('--firefox')
• Output Directory:
  • Chrome: ../../dist/extension
  • Firefox: ../../dist/extension-firefox
• Manifest Handling: The viteStaticCopy plugin selects the correct manifest file based on the isFirefox flag.
  • Chrome: manifest.json
  • Firefox: manifest.firefox.json
• Entry Points: The plugin has multiple entry points for its different components:
  • popup/index.html
  • background/background.ts
  • contentScripts/content.ts
  • contentScripts/main.ts
• Output Structure: The Rollup output configuration organizes the built files into logical subdirectories (popup/, background/, contentScripts/) within the final extension package.

Sources: packages/plugin/vite.production.config.ts:7-39

Plugin Build Flow

This diagram shows the conditional logic for building the browser extension for different platforms.

Summary

The production build process for web-archive is a well-defined, script-driven system that handles the complexities of a monorepo targeting multiple platforms. It uses Vite's flexible configuration to produce two distinct artifacts: a unified Cloudflare service and a multi-platform browser extension. The build:service script cleverly integrates the web client's static assets into the server's deployable package, while the build:plugin script uses conditional logic to generate tailored extension packages for both Chrome and Firefox from a single codebase.