What Is the @plane/shared-state Package? Purpose and Implementation in Plane

The @plane/shared-state package is an internal MobX-based state management library that centralizes shared reactive stores—such as workspace, user, and filter states—across all Plane frontend applications, ensuring a single source of truth with type-safe consistency.

The @plane/shared-state package eliminates state duplication in the makeplane/plane monorepo by providing a dedicated layer for observable data that must persist across application boundaries. Located at packages/shared-state/, this library exports ready-to-use MobX stores and filtering utilities that both the main web app and administrative interfaces consume, reducing bundle size while maintaining synchronized UI state.

Architecture and Core Purpose

The primary purpose of @plane/shared-state is to decouple reactive state logic from presentation components and house it in a reusable, compiled package. By consolidating MobX stores in one location, Plane achieves three critical objectives:

• Single Source of Truth – Changes to the active workspace, authenticated user, or active filter set in packages/shared-state/src/store/ instantly propagate to every subscribing component across the frontend.
• Type Safety – All stores integrate with @plane/types definitions, ensuring that TypeScript validations remain consistent whether the consumer is the web app or the admin dashboard.
• Build Optimization – The package compiles via tsdown (as configured in packages/shared-state/package.json), producing a shared bundle that prevents duplicate state logic from inflating individual application chunks.

Core Store Implementations

Workspace Store (workspace.store.ts)

The workspace store, defined in packages/shared-state/src/store/workspace.store.ts, manages the currently selected project and workspace metadata. It exposes observable properties that UI components can track for real-time updates to the active context.

// packages/shared-state/src/store/workspace.store.ts
import { workspaceStore } from "@plane/shared-state";

// Accessing the current workspace observable
const currentWorkspace = workspaceStore.useWorkspace();

User Store (user.store.ts)

Located at packages/shared-state/src/store/user.store.ts, this store maintains authenticated user information, preferences, and session state. It ensures that user-specific data remains synchronized across route changes and application mounts without redundant API calls.

Filter Management Stores

Work-Item Filter Store

The packages/shared-state/src/store/work-item-filters/ directory contains the WorkItemFilterStore class, which encapsulates complex querying logic for issue lists. This store handles state for status, priority, and assignee filters, exposing methods like setFilter() to mutate query parameters reactively.

import { WorkItemFilterStore } from "@plane/shared-state";

const filterStore = new WorkItemFilterStore();

filterStore.setFilter({
  key: "status",
  value: "completed",
});

Rich Filter Helpers

For advanced querying scenarios, packages/shared-state/src/store/rich-filters/ provides constructors for building structured filter objects. These stores support nested logical operators and field-specific conditions that go beyond simple key-value pairs.

Utility Functions and Helpers

Beyond stores, the package exports pure functions from packages/shared-state/src/utils/ for constructing filter objects without class instantiation. The getRichFilter helper, located in the utils directory, generates typed filter configurations compatible with Plane's backend query syntax.

import { getRichFilter } from "@plane/shared-state/utils/rich-filter.helper";

const richFilter = getRichFilter({
  field: "priority",
  operator: "eq",
  value: "high",
});

Package Configuration and Dependencies

The packages/shared-state/package.json declares the package's runtime dependencies, including MobX for reactivity, lodash-es for utility operations, and Zod for runtime schema validation. The build entry point at packages/shared-state/src/index.ts aggregates all public exports, ensuring consumers can import everything from the package root:

// packages/shared-state/src/index.ts
export * from "./store/workspace.store";
export * from "./store/user.store";
export * from "./store/work-item-filters";
export * from "./store/rich-filters";
export * from "./utils";

Summary

• Centralized MobX State – @plane/shared-state houses all observable stores that must persist across Plane's frontend applications, preventing state drift between the web app and admin panels.
• Typed Store Architecture – Files like workspace.store.ts and user.store.ts provide fully-typed reactive data sources that integrate with @plane/types definitions.
• Advanced Filter Management – The package exports both WorkItemFilterStore for stateful filtering and getRichFilter utilities for constructing complex queries.
• Optimized Build Output – Compiled via tsdown and consumed through the main src/index.ts barrel file, the library minimizes bundle duplication while maximizing code reuse.

Frequently Asked Questions

How does @plane/shared-state differ from React Context?

React Context provides prop-drilling avoidance through a component tree, but @plane/shared-state implements MobX observables that exist outside the React lifecycle. According to the Plane source code, this allows non-React utilities and external scripts to read and mutate workspace state without mounting components, while Context requires a provider hierarchy.

Can I use @plane/shared-state outside the Plane monorepo?

No. The package is an internal library scoped to the makeplane/plane repository. It depends on specific @plane/types definitions and internal API contracts that are not published to public registries as standalone packages.

What build tool compiles the shared-state package?

The package uses tsdown (configured in packages/shared-state/package.json) to compile TypeScript into optimized JavaScript bundles. This tool generates the distribution files that consuming applications import when they reference @plane/shared-state.

Where are the filter utility functions located?

Filter helpers reside in packages/shared-state/src/utils/, while their corresponding stateful stores live in packages/shared-state/src/store/work-item-filters/ and packages/shared-state/src/store/rich-filters/. The getRichFilter function specifically imports from the utils path for lightweight, stateless filter construction.

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