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

> Discover how Maka uses npm workspaces to structure its monorepo, managing core libraries, UI components, runtime, and more within a single repository for efficient development.

- Repository: [The Apache Software Foundation/maka](https://github.com/apache/maka)
- Tags: architecture
- Published: 2026-09-12

---

**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`](https://github.com/apache/maka/blob/main/package.json), build pipeline, and export contracts.

## Workspace Declaration in Root package.json

The monorepo structure is defined in the root [`package.json`](https://github.com/apache/maka/blob/main/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.

```json
{
  "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)](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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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)](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)](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)](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`](https://github.com/apache/maka/blob/main/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.

```json
{
  "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)](https://github.com/apache/maka/blob/main/package.json)

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

```bash

# 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`](https://github.com/apache/maka/blob/main/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.

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

```

*Source:* [[`tsconfig.base.json`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/package.json) declares `"private": true` to prevent accidental monorepo-wide publication, individual workspaces can be published independently by adjusting their [`package.json`](https://github.com/apache/maka/blob/main/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.