How Maka Is Structured as an npm Workspaces Monorepo: Complete Architecture Guide

Maka uses npm workspaces to manage core libraries, storage layers, UI components, runtime, CLI, desktop app, and documentation as independent yet interconnected packages within a single repository.

Apache Maka is organized as a npm workspaces monorepo that enables independent building, testing, and publishing of eleven distinct packages while maintaining unified dependency management. This architecture keeps related code colocated for easier coordination but treats each component as a separate logical unit with its own package.json, build pipeline, and export contracts.

Workspace Declaration in Root package.json

The monorepo structure is defined in the root package.json, which declares "private": true to prevent accidental publication of the entire repository as a single package. The workspaces array enumerates every package location, establishing the workspace boundaries for npm's dependency resolution and script orchestration.

{
  "private": true,
  "workspaces": [
    "packages/core",
    "packages/storage",
    "packages/mcp",
    "packages/runtime",
    "packages/runtime-host",
    "packages/eval",
    "packages/computer-use",
    "packages/cli",
    "packages/ui",
    "apps/desktop",
    "website"
  ]
}

Source: [package.json](https://github.com/apache/maka/blob/main/package.json)

This configuration instructs npm to treat each directory as a separate package while hoisting shared dependencies to the root node_modules folder. The "private": true setting ensures that only individual workspaces explicitly marked for public release can be published to the npm registry, protecting the monorepo from being distributed as a single artifact.

Monorepo Package Architecture

The Maka npm workspaces monorepo contains eleven distinct workspaces organized by functional domain. Each workspace maintains its own dependencies, build scripts, and public API surface through the exports field in its local package.json.

Workspace	Path	Purpose	Key Exports
@maka/core	packages/core	Pure TypeScript types and logic utilities	./runtime-event, ./session, ./tool-result-preview
@maka/storage	packages/storage	Persistent storage abstractions	./session-store, ./artifact-stores, ./runtime-event-persistence
@maka/mcp	packages/mcp	Multi-Channel Provider integration layer	Defined in package exports
@maka/runtime	packages/runtime	Runtime engine for agents and tasks	./runtime-boundary, ./runtime-policy, ./agent-graph-*
@maka/runtime-host	packages/runtime-host	OS process host for runtime isolation	OS-specific launchers for Windows, macOS, Linux
@maka/eval	packages/eval	LLM skill evaluation harness	Defined in package exports
@maka/computer-use	packages/computer-use	Host computer control APIs	Mouse, keyboard, clipboard abstractions
@maka/cli	packages/cli	Command-line interface	cli/dev-cli.js and sub-commands
@maka/ui	packages/ui	React component library	./icons, ./assistant-stream, ./composer-attachments
@maka/desktop	apps/desktop	Electron-based desktop client	Bundles UI and runtime
website	website	Documentation and blog site	Vite/React static site

Sources: Individual package definitions in [packages/core/package.json](https://github.com/apache/maka/blob/main/packages/core/package.json), [packages/ui/package.json](https://github.com/apache/maka/blob/main/packages/ui/package.json), and [apps/desktop/package.json](https://github.com/apache/maka/blob/main/apps/desktop/package.json).

The separation between packages/ (reusable libraries) and apps/ (consuming applications) clarifies dependency direction. The website workspace exists at the root level alongside apps/, indicating it serves a distinct documentation and marketing function rather than being a runtime dependency of the core system.

Cross-Workspace Build Orchestration

The root package.json provides high-level scripts that leverage npm's workspace filtering capabilities. Commands use the npm --workspace <name> prefix to target specific packages while respecting inter-workspace dependencies.

{
  "scripts": {
    "dev": "npm --workspace @maka/desktop run dev:hmr --",
    "build": "npm --workspace @maka/core run build && npm --workspace @maka/ui run build",
    "test": "npm run build:test && node scripts/run-workspace-tests-parallel.mjs --concurrency=3"
  }
}

Source: [package.json](https://github.com/apache/maka/blob/main/package.json)

Practical usage examples demonstrate how to execute commands within specific workspaces:

# Build only the core library

npm --workspace @maka/core run build

# Run the desktop app in hot-module-replacement mode

npm --workspace @maka/desktop run dev:hmr

# Execute unit tests for the UI package specifically

npm --workspace @maka/ui run test:dist

When building @maka/ui, npm automatically builds @maka/core first because the UI package declares the core package as a dependency. This implicit dependency resolution ensures that downstream packages always consume the current version of upstream code without manual ordering scripts.

Shared TypeScript Configuration

All TypeScript packages extend a central tsconfig.base.json located at the repository root. This file defines compiler options, path aliases, and module resolution strategies that remain consistent across the npm workspaces monorepo, preventing configuration drift between packages.

{
  "extends": "./tsconfig.base.json",
  "include": ["src"],
  "exclude": ["node_modules", "dist"]
}

Source: [tsconfig.base.json](https://github.com/apache/maka/blob/main/tsconfig.base.json) at repository root.

The scripts/ directory at the root contains shared utilities such as clean-paths.mjs for removing dist folders and sync-model-metadata.mjs for maintaining consistent metadata across packages. These scripts are invoked from individual workspace package.json files, centralizing repetitive build logic while allowing each workspace to customize its execution context.

Dependency Management Strategy

Internal dependencies within the Maka monorepo use a synchronized version scheme (0.1.0) across all private workspaces. This convention simplifies internal linking while maintaining the flexibility to publish individual packages independently when they mature for public release.

npm workspaces automatically hoist shared dependencies—such as react, typescript, and electron—to the root node_modules folder. This deduplication reduces disk usage and installation time while allowing each workspace to declare its own dependency requirements in its local package.json. When a workspace depends on another local workspace (e.g., @maka/desktop depending on @maka/ui), npm creates a symbolic link in the consumer's node_modules folder pointing to the source workspace, enabling real-time code changes to propagate without reinstallation.

Summary

• The root package.json defines eleven workspaces across packages/, apps/, and website/ directories with "private": true to control publication scope.
• Each workspace maintains independent build scripts and export contracts while sharing a central TypeScript configuration via tsconfig.base.json.
• The npm --workspace <name> CLI pattern enables targeted builds and tests with automatic dependency ordering.
• Shared dependencies are hoisted to the root node_modules to reduce duplication, while inter-workspace dependencies use symbolic links for development.
• All internal packages currently use version 0.1.0, supporting future independent public releases while maintaining internal consistency.

Frequently Asked Questions

How do I build a single package in the Maka monorepo?

Use the npm --workspace flag followed by the package name and build script. For example, run npm --workspace @maka/core run build to compile only the core library. npm will automatically build any workspace dependencies (such as @maka/core when building @maka/ui) before executing the requested script.

Why does Maka use npm workspaces instead of pnpm or Yarn?

The Maka project leverages npm workspaces as the standard package manager included with Node.js, reducing external tooling dependencies for Apache Software Foundation contributors. The built-in workspace functionality satisfies the project's requirements for dependency hoisting, cross-package scripting, and symbolic linking without requiring additional package manager installations.

How are inter-workspace dependencies handled?

When one workspace depends on another (declared in its local package.json), npm creates a symbolic link from the consumer's node_modules folder to the source workspace directory. For instance, @maka/ui automatically receives updates from @maka/core through this linking mechanism, and the root-level build scripts ensure upstream packages compile before downstream consumers during orchestrated builds.

Can I publish individual packages from the Maka monorepo?

Yes. Although the root package.json declares "private": true to prevent accidental monorepo-wide publication, individual workspaces can be published independently by adjusting their package.json settings and running npm publish from within the specific workspace directory. The current version strategy uses 0.1.0 uniformly across private packages, allowing maintainers to bump versions selectively when specific packages mature for public release.

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