What Is the @plane/services Package Used For? A Complete Guide to Plane’s API Client SDK

The @plane/services package is a typed client-side SDK that provides service classes for interacting with the Plane back-end REST API, centralizing HTTP logic through a base APIService class and exporting domain-specific services for workspaces, users, and authentication.

The @plane/services package serves as the official JavaScript/TypeScript client SDK for the makeplane/plane project management platform. Located within the monorepo's packages/services directory, this package abstracts all low-level HTTP communication into type-safe service classes. Front-end applications use it to consume REST endpoints without manually handling Axios configurations, request URLs, or repetitive error-checking logic.

Core Architecture of the @plane/services Package

The package implements a layered architecture where a centralized base class handles HTTP transport, while specialized subclasses manage domain-specific business logic. This pattern ensures consistent error handling and request formatting across the entire Plane web application.

The APIService Base Class

Located in src/api.service.ts, the APIService class centralizes Axios configuration and injects the base URL from API_BASE_URL (imported from @plane/constants). It exposes protected helper methods—get(), post(), patch(), and delete()—that standardize error handling and request logic. All domain services extend this class, inheriting the same HTTP client instance and interceptors.

Domain-Specific Service Classes

Each functional area of the Plane API has a dedicated service class extending APIService. These include WorkspaceService, UserService, AuthService, and additional services for projects, issues, and file uploads. Every service implements high-level CRUD methods—list(), retrieve(), create(), update(), and destroy()—that correspond to REST endpoints. These methods return typed promises defined in @plane/types, ensuring compile-time safety for API responses.

Key Service Classes and Their Responsibilities

The package organizes functionality into discrete modules, with each major domain represented by its own service file.

WorkspaceService

The WorkspaceService class, defined in src/workspace/workspace.service.ts, manages workspace-related operations. It provides methods for listing user workspaces, retrieving specific workspace details, and validating workspace identifiers through the slugCheck() method.

UserService

Found in src/user/user.service.ts, the UserService handles user profile retrieval and updates. It exposes methods like updateProfile() to modify user attributes while maintaining type safety through interfaces defined in the @plane/types package.

AuthService

The AuthService class in src/auth/auth.service.ts manages authentication flows including signIn(), signOut(), and token refresh operations. This service provides a secure, typed interface for session management and credential handling.

How to Use @plane/services in Your Application

The package exposes a clean, promise-based API that integrates directly with React components, hooks, or any client-side JavaScript code.

Listing All Workspaces

Import WorkspaceService to fetch workspaces for the current authenticated user:

import { WorkspaceService } from "@plane/services";

const workspaceService = new WorkspaceService();
workspaceService
  .list()
  .then((workspaces) => {
    // workspaces is typed as IWorkspace[]
    console.log("User workspaces:", workspaces);
  })
  .catch((err) => {
    console.error("Failed to fetch workspaces:", err);
  });

Updating User Profiles

Use UserService to modify profile information with full TypeScript support:

import { UserService } from "@plane/services";

const userService = new UserService();

async function updateProfile(name: string) {
  try {
    const updated = await userService.updateProfile({ first_name: name });
    console.log("Profile updated:", updated);
  } catch (e) {
    console.error("Profile update error:", e);
  }
}

Validating Workspace Slugs

Check workspace identifier availability before creation:

import { WorkspaceService } from "@plane/services";

const wsService = new WorkspaceService();

wsService
  .slugCheck("my‑team")
  .then((result) => console.log("Slug available:", result))
  .catch((e) => console.error("Slug check failed:", e));

Handling Authentication

Implement login flows using the AuthService class:

import { AuthService } from "@plane/services";

const auth = new AuthService();

auth
  .signIn({ email: "john@example.com", password: "secret" })
  .then(() => console.log("Signed in!"))
  .catch((err) => console.error("Login error:", err));

Package Structure and Export Strategy

The @plane/services package uses src/index.ts as a central export hub, re-exporting every domain service so consumers can import directly from the package name without navigating internal folder structures. The package.json defines the module boundaries and lists dependencies including axios for HTTP transport and file-type for file handling capabilities.

This single-entry-point design means developers can access any service using concise import statements like import { WorkspaceService, UserService } from "@plane/services", while the internal implementation details remain encapsulated and free to evolve.

Summary

• @plane/services acts as the typed client-side SDK for the Plane REST API, bridging the front-end applications with the back-end server.
• The APIService base class in src/api.service.ts centralizes Axios configuration, request methods, and error handling for all derived services.
• Domain services like WorkspaceService, UserService, and AuthService provide high-level CRUD methods that return typed promises from @plane/types.
• The src/index.ts export hub enables clean imports from @plane/services, abstracting the internal file structure and simplifying maintenance.

Frequently Asked Questions

What is the @plane/services package used for?

The @plane/services package provides a type-safe client SDK that Plane's front-end applications use to communicate with the back-end REST API. It wraps low-level HTTP calls in service classes, allowing developers to interact with workspaces, users, and authentication endpoints using typed JavaScript/TypeScript methods rather than raw fetch requests.

How does the APIService class handle HTTP configuration?

The APIService class, defined in src/api.service.ts, serves as the foundation for all domain services. It configures the Axios instance with the base URL from API_BASE_URL, sets up request interceptors, and exposes protected methods (get, post, patch, delete) that standardize error handling and request formatting across the entire package.

What types of operations do the domain services support?

Each domain service supports standard CRUD operations through methods like list(), retrieve(), create(), update(), and destroy(). Additionally, services expose domain-specific methods such as WorkspaceService.slugCheck() for validation or AuthService.signIn() for authentication flows, all returning typed promises defined in the @plane/types package.

How do I import services from the @plane/services package?

You can import any service directly from the package root due to the centralized export pattern in src/index.ts. For example, use import { WorkspaceService, UserService } from "@plane/services" to access the classes without specifying individual file paths, keeping import statements concise and resilient to internal refactoring.

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