How Feynman Manages Its Installed Packages: A Monorepo Approach

Feynman organizes its codebase as a monorepo using standard npm package management, where the root package.json coordinates core dependencies while nested manifests in /website/ and test fixtures maintain isolated tooling requirements within a shared node_modules directory.

The Feynman project, hosted at advaitpaliwal/feynman, demonstrates how modern TypeScript applications structure complex dependencies across multiple functional domains. Understanding how Feynman manages its installed packages reveals a clean separation between core runtime libraries, frontend documentation tooling, and isolated test environments. This architecture relies on Node.js package management conventions to maintain clear boundaries while enabling efficient dependency sharing.

Monorepo Architecture and Package Organization

Feynman adopts a monorepo structure that distributes functionality across multiple package.json files rather than maintaining a single manifest. This approach allows distinct components to declare precise version requirements while npm's hoisting mechanism consolidates compatible dependencies into a unified node_modules directory.

Root Package Configuration

The central manifest at /package.json defines the core runtime dependencies required by Feynman's main application. According to the advaitpaliwal/feynman source code, this includes the Pi runtime environment, TypeScript compiler infrastructure, and essential utility modules that power the framework's execution logic. Running npm install from the repository root resolves these primary dependencies and establishes the foundation for all sub-packages.

Website and Documentation Dependencies

The documentation interface resides in /website/ with its own dedicated /website/package.json. This manifest isolates frontend-specific tooling such as React, Vite, and styling libraries from the core engine. The separation ensures that build tools and UI frameworks needed for the documentation site do not bloat the main application's runtime footprint.

Test Fixture Isolation

Test environments maintain strict isolation through separate manifests. The OTEL test fixture at /tests/fixtures/pi-otel-0.1.0/package.json and the web-access fixture at /fixtures/pi-web-access-0.28.0/package.json each declare their own dependency sets. This pattern prevents testing utilities from polluting the production dependency tree while allowing fixtures to simulate specific runtime scenarios with precise library versions.

Dependency Resolution and Installation Workflow

When developers execute npm install at the repository root, npm traverses the entire monorepo hierarchy to construct a flattened dependency graph. The package manager analyzes version constraints across the root, website, and fixture manifests, resolving conflicts according to semantic versioning rules. All compatible libraries install into the shared node_modules folder, eliminating duplicate copies and ensuring consistent import resolution across package boundaries.

This unified installation strategy means that adding new packages requires only creating a directory with its own package.json—the next root-level install automatically incorporates those dependencies into the shared tree.

Build Scripts and Automation

Each package.json defines targeted npm scripts that automate compilation, testing, and deployment tasks specific to that component. These scripts execute via npm run <command>, orchestrating the build pipeline without manual configuration.

Root package scripts in /package.json typically include build, test, and prepare. These commands compile TypeScript sources and trigger the comprehensive test suite across all fixtures.

Website scripts in /website/package.json provide dev, build, and preview commands. The dev script launches the Vite development server for local documentation preview, while build generates production-static assets.

Fixture scripts within test directories expose setup and test commands that initialize isolated environments and validate specific integration scenarios.

# Install all dependencies across the monorepo

npm install

# Compile the core Feynman TypeScript sources

npm run build

# Launch the documentation website locally

cd website
npm run dev

# Execute the full test suite including fixtures

npm test

Summary

• Feynman uses a monorepo structure with multiple package.json files to separate concerns between core runtime, website tooling, and test fixtures.
• The root /package.json manages essential dependencies like the Pi runtime and TypeScript, while nested manifests handle specialized requirements.
• All packages share a unified node_modules directory through npm's workspace-style resolution, activated by running npm install at the repository root.
• Environment-specific scripts (build, dev, test) defined in each manifest automate compilation and validation without cross-contaminating dependencies.
• Test fixtures maintain isolated dependency declarations at paths like /tests/fixtures/pi-otel-0.1.0/package.json to ensure clean testing environments.

Frequently Asked Questions

Does Feynman use npm workspaces or pnpm for package management?

Feynman relies on standard npm package management without explicit workspace configuration. While the monorepo structure allows npm to naturally hoist shared dependencies into the root node_modules, individual package files in /website/package.json and fixture directories manage their own specific tooling requirements independently.

How do I add a new dependency to only the Feynman website?

Navigate to the /website/ directory and install the package locally using npm install <package-name>. This updates /website/package.json while keeping the dependency isolated from the core application runtime, ensuring that frontend build tools remain separate from the Pi execution environment.

Why do test fixtures have their own package.json files?

Test fixtures such as /tests/fixtures/pi-otel-0.1.0/ maintain separate manifests to simulate specific runtime scenarios with precise library versions. This isolation prevents testing utilities and fixture-specific dependencies from leaking into the main application's production dependency tree, ensuring accurate integration validation.

Can I run scripts for individual packages without affecting the entire monorepo?

Yes. Use cd to navigate to the specific directory (such as cd website/) and execute npm run <script> from that location. This runs the localized script defined in that folder's package.json without triggering operations across other monorepo components, though shared dependencies remain available through the hoisted node_modules structure.

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