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

> Discover the purpose of @plane/shared-state, a MobX library centralizing reactive stores for consistent, type-safe frontend state management in Plane.

- Repository: [Plane/plane](https://github.com/makeplane/plane)
- Tags: deep-dive
- Published: 2026-08-22

---

**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`](https://github.com/makeplane/plane/blob/main/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`](https://github.com/makeplane/plane/blob/main/workspace.store.ts))

The workspace store, defined in [`packages/shared-state/src/store/workspace.store.ts`](https://github.com/makeplane/plane/blob/main/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.

```typescript
// 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`](https://github.com/makeplane/plane/blob/main/user.store.ts))

Located at [`packages/shared-state/src/store/user.store.ts`](https://github.com/makeplane/plane/blob/main/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.

```typescript
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.

```typescript
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`](https://github.com/makeplane/plane/blob/main/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`](https://github.com/makeplane/plane/blob/main/packages/shared-state/src/index.ts) aggregates all public exports, ensuring consumers can import everything from the package root:

```typescript
// 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`](https://github.com/makeplane/plane/blob/main/workspace.store.ts) and [`user.store.ts`](https://github.com/makeplane/plane/blob/main/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`](https://github.com/makeplane/plane/blob/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`](https://github.com/makeplane/plane/blob/main/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.