What Is the Purpose of the `packages` Directory in makeplane/plane?

The packages directory serves as the modular backbone of Plane's monorepo architecture, housing independently versioned npm packages that encapsulate reusable functionality—from UI utilities and state management to logging and internationalization—shared across the web, admin, and API applications.

The packages directory in the makeplane/plane repository is the cornerstone of the project's monorepo structure. It organizes the codebase into discrete, reusable modules that power the Plane product. This architectural choice enables the team to maintain a clean dependency graph while sharing code efficiently between multiple applications.

Monorepo Architecture and Modular Design

The packages folder implements a modular monorepo pattern that isolates well-defined concerns into separate npm packages. According to the makeplane/plane source code, each package encapsulates a specific domain—such as MobX state management, utility functions, or Tailwind configuration—preventing code duplication and simplifying maintenance.

Shared State Management

The @plane/shared-state package demonstrates this isolation by providing a centralized MobX store used across multiple applications. Located at packages/shared-state/package.json, this package defines its own build scripts and dependencies, including internal references to other workspace packages like @plane/utils.

Utility Libraries

Similarly, @plane/utils contains domain-specific helpers such as orderWorkspacesList, defined in packages/utils/src/workspace.ts. These utilities are consumed by importing directly from the package:

// src/components/SomeComponent.tsx
import { orderWorkspacesList } from "@plane/utils/src/workspace";

const sorted = orderWorkspacesList(workspaces);

Build Configuration and Dependency Management

Independent Build Pipelines

Each package in the packages directory maintains its own build configuration using tsdown, a fast TypeScript compiler. For example, packages/logger/tsdown.config.ts defines the compilation settings for the logging package, enabling selective rebuilding and faster CI/CD cycles.

Workspace Protocol Dependencies

The monorepo leverages pnpm's workspace protocol to manage internal dependencies. Packages reference each other using "workspace:*" in their package.json files, allowing pnpm to resolve them locally without publishing to a registry. In packages/shared-state/package.json, you'll find dependencies like @plane/utils specified using this protocol, creating a clear dependency graph while keeping everything within the repository.

{
  "dependencies": {
    "@plane/utils": "workspace:*"
  }
}

Key Packages and Their Responsibilities

The packages directory contains a diverse ecosystem of modules that form the reusable backbone of Plane:

• @plane/shared-state: MobX-based state management stores shared across React applications
• @plane/logger: Express middleware and logging utilities found in packages/logger/src/middleware.ts
• @plane/editor: Rich-text editor components exported from packages/editor/src/lib.ts
• @plane/i18n: Internationalization provider for React located in packages/i18n/src/provider/index.tsx
• @plane/decorators: API call wrappers and decorators defined in packages/decorators/src/rest.ts
• @plane/constants: Centralized static values for themes and settings

Practical Implementation Examples

Consuming Shared State in React

Components import stores directly from the shared-state package and interact with MobX observables:

import { useEffect } from "react";
import { workspaceStore } from "@plane/shared-state";

export const WorkspaceList = () => {
  useEffect(() => {
    workspaceStore.fetchAll(); // triggers MobX action
  }, []);

  return (
    <ul>
      {workspaceStore.list.map(ws => (
        <li key={ws.id}>{ws.name}</li>
      ))}
    </ul>
  );
};

Adding Logger Middleware

Server-side applications utilize the logger package for request tracking:

import express from "express";
import { loggerMiddleware } from "@plane/logger";

const app = express();
app.use(loggerMiddleware());

app.get("/", (req, res) => res.send("Hello"));

Source: packages/logger/src/middleware.ts

Development and Testing Advantages

Incremental Testing

The modular structure enables targeted test execution. Developers can run tests for specific packages without executing the entire suite, using commands like pnpm turbo run test --filter=@plane/logger. This granularity reduces CI/CD times and provides faster feedback loops.

Consistent Tooling Configuration

All packages inherit common TypeScript, linting, and formatting rules defined in the root pnpm-workspace.yaml. This ensures uniform development standards across the monorepo while allowing packages to extend or override configurations as needed.

Feature Flagging and Scalability

The package-based architecture supports progressive enhancement and A/B testing. Packages like @plane/editor can be lazy-loaded or swapped independently, enabling feature flagging strategies where specific functionality is enabled or disabled without affecting the core application bundle.

Summary

• The packages directory implements a monorepo architecture that organizes Plane's codebase into independently versioned, reusable modules.
• Each package maintains its own build pipeline using tsdown and can be published or consumed via the workspace:* protocol.
• Key packages include @plane/shared-state for MobX stores, @plane/utils for helpers, and @plane/logger for middleware.
• The structure enables incremental testing, consistent tooling across the repository, and supports feature flagging for scalable development.

Frequently Asked Questions

What build tool does the packages directory use in makeplane/plane?

The packages use tsdown, a fast TypeScript compiler, configured via individual tsdown.config.ts files within each package. For example, packages/logger/tsdown.config.ts defines the compilation settings for the logging package, enabling independent builds and faster CI/CD cycles.

How do packages in the makeplane/plane repository reference each other?

Packages reference internal dependencies using pnpm's workspace protocol with the syntax "workspace:*" in their package.json files. This allows pnpm to resolve dependencies locally without publishing to an external registry, as seen in packages/shared-state/package.json where it imports @plane/utils.

Can I run tests for only one specific package in makeplane/plane?

Yes. The monorepo structure supports incremental testing via pnpm filters. You can execute tests for a specific package using commands like pnpm turbo run test --filter=@plane/logger, which runs only the affected test suite rather than the entire repository.

What is the purpose of the @plane/shared-state package?

The @plane/shared-state package provides MobX-based state management stores that are shared across multiple React applications in the Plane ecosystem. Located in packages/shared-state/, it encapsulates reactive state logic and actions, preventing duplication of state management code between the web, admin, and API interfaces.

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