or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

extension-points.mdindex.mdworkspace-commands.mdworkspace-file-handling.mdworkspace-preferences.mdworkspace-server.mdworkspace-service.md
tile.json

tessl/npm-theia--workspace

Theia workspace extension providing workspace functionality and services for Eclipse Theia IDE framework

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@theia/workspace@1.64.x

To install, run

npx @tessl/cli install tessl/npm-theia--workspace@1.64.0

index.mddocs/

@theia/workspace

The @theia/workspace extension provides comprehensive workspace functionality and services for the Eclipse Theia IDE framework. It enables workspace management, file operations, workspace configuration, and extensibility points for both frontend and backend development environments. The extension supports multi-root workspaces, workspace trust management, and integrates with Theia's dependency injection system.

Package Information

  • Package Name: @theia/workspace
  • Package Type: npm
  • Language: TypeScript
  • Installation: This is a Theia extension - install as part of a Theia application

Core Imports

Common (shared between frontend/backend):

import { 
  WorkspaceServer, 
  WorkspaceFileService, 
  UntitledWorkspaceService,
  workspacePath
} from "@theia/workspace/lib/common";

Browser/Frontend:

import { 
  WorkspaceService, 
  WorkspaceCommands,
  CanonicalUriService,
  WorkspacePreferences,
  WorkspaceTrustService
} from "@theia/workspace/lib/browser";

Node/Backend:

import { 
  DefaultWorkspaceServer,
  WorkspaceCliContribution 
} from "@theia/workspace/lib/node";

Basic Usage

import { injectable, inject } from "@theia/core/shared/inversify";
import { WorkspaceService } from "@theia/workspace/lib/browser";
import { CommandContribution, CommandRegistry } from "@theia/core/lib/common";

@injectable()
export class MyWorkspaceContribution implements CommandContribution {
  
  @inject(WorkspaceService)
  protected readonly workspaceService: WorkspaceService;

  registerCommands(registry: CommandRegistry): void {
    registry.registerCommand({
      id: 'my.workspace.info',
      label: 'Show Workspace Info'
    }, {
      execute: async () => {
        if (this.workspaceService.opened) {
          const roots = await this.workspaceService.roots;
          console.log(`Workspace has ${roots.length} root folders`);
          
          if (this.workspaceService.workspace) {
            console.log(`Workspace file: ${this.workspaceService.workspace.uri}`);
          }
        } else {
          console.log('No workspace opened');
        }
      }
    });
  }
}

Architecture

The @theia/workspace extension is structured around several key architectural components:

  • Common Module: Provides protocol interfaces and shared services that work across frontend and backend
  • Browser Module: Frontend-specific workspace services, UI contributions, and command handlers
  • Node Module: Backend workspace server implementation and CLI integration
  • Dependency Injection: Follows Theia's inversify-based DI pattern for service registration and extension points
  • Event-Driven: Uses event emitters for workspace state changes and lifecycle management
  • Extension Points: Provides interfaces for extending workspace opening, handling, and validation logic

Capabilities

Core Workspace Management

Central workspace service providing workspace lifecycle management, root folder operations, and workspace state tracking.

interface WorkspaceService {
  readonly ready: Promise<void>;
  readonly roots: Promise<FileStat[]>;
  readonly workspace: FileStat | undefined;
  readonly opened: boolean;
  readonly saved: boolean;
  readonly isMultiRootWorkspaceOpened: boolean;
  readonly onWorkspaceChanged: Event<FileStat[]>;
  readonly onWorkspaceLocationChanged: Event<FileStat | undefined>;
  
  tryGetRoots(): FileStat[];
  open(uri: URI, options?: WorkspaceInput): void;
  close(): Promise<void>;
  addRoot(uris: URI[] | URI): Promise<void>;
  removeRoots(uris: URI[]): Promise<void>;
  spliceRoots(start: number, deleteCount?: number, ...rootsToAdd: URI[]): Promise<URI[]>;
  recentWorkspaces(): Promise<string[]>;
  containsSome(paths: string[]): Promise<boolean>;
  save(uri: URI | FileStat): Promise<void>;
  getWorkspaceRootUri(uri?: URI): URI | undefined;
  getWorkspaceRelativePath(uri: URI): Promise<string>;
  areWorkspaceRoots(uris: URI[]): boolean;
}

Workspace Service

Workspace Commands and Operations

Command definitions and handlers for all workspace operations including file management, workspace opening, and folder operations.

namespace WorkspaceCommands {
  const OPEN: Command & { dialogLabel: string };
  const OPEN_FILE: Command & { dialogLabel: string };
  const OPEN_FOLDER: Command & { dialogLabel: string };
  const OPEN_WORKSPACE: Command & { dialogLabel: string };
  const OPEN_RECENT_WORKSPACE: Command;
  const CLOSE: Command;
  const NEW_FILE: Command;
  const NEW_FOLDER: Command;
  const FILE_RENAME: Command;
  const FILE_DELETE: Command;
  const FILE_DUPLICATE: Command;
  const FILE_COMPARE: Command;
  const ADD_FOLDER: Command;
  const REMOVE_FOLDER: Command;
  const SAVE_WORKSPACE_AS: Command;
  const OPEN_WORKSPACE_FILE: Command;
  const COPY_RELATIVE_FILE_PATH: Command;
}

Workspace Commands

Workspace File Handling

Services for managing workspace file formats, validation, and untitled workspace creation.

interface WorkspaceFileService {
  isWorkspaceFile(candidate: FileStat | URI): boolean;
  getWorkspaceFileTypes(): WorkspaceFileType[];
  getWorkspaceFileExtensions(dot?: boolean): string[];
}

interface UntitledWorkspaceService {
  isUntitledWorkspace(candidate?: URI): boolean;
  getUntitledWorkspaceUri(configDirUri: URI, isAcceptable: Function): Promise<URI>;
}

Workspace File Handling

Workspace Server Protocol

Backend server interface for workspace persistence, recent workspace tracking, and workspace validation.

interface WorkspaceServer {
  getMostRecentlyUsedWorkspace(): Promise<string | undefined>;
  setMostRecentlyUsedWorkspace(uri: string): Promise<void>;
  removeRecentWorkspace(uri: string): Promise<void>;
  getRecentWorkspaces(): Promise<string[]>;
}

Workspace Server

Workspace Preferences and Configuration

Preference management and workspace-specific configuration handling.

interface WorkspaceConfiguration {
  'workspace.preserveWindow': boolean;
}

type WorkspacePreferences = PreferenceProxy<WorkspaceConfiguration>;

Workspace Preferences

Canonical URI Service

Service for providing canonical URI transformations between different URI schemes.

interface CanonicalUriProvider extends Disposable {
  provideCanonicalUri(uri: URI, targetScheme: string, token: CancellationToken): Promise<URI | undefined>;
}

interface CanonicalUriService {
  registerCanonicalUriProvider(scheme: string, provider: CanonicalUriProvider): Disposable;
  provideCanonicalUri(uri: URI, targetScheme: string, token?: CancellationToken): Promise<URI | undefined>;
}

Workspace Trust Management

Service for managing workspace trust settings and user consent for workspace operations.

interface WorkspaceTrustService {
  getWorkspaceTrust(): Promise<boolean>;
  resolveWorkspaceTrust(givenTrust?: boolean): Promise<void>;
}

Extension Points and Customization

Interfaces for extending workspace functionality with custom handlers and contributions. See the Types section below for the complete interface definitions.

Extension Points

Types

interface WorkspaceData {
  folders: Array<{ path: string; name?: string }>;
  settings?: { [id: string]: any };
  [key: string]: any;
}

interface WorkspaceInput {
  preserveWindow?: boolean;
}

interface WorkspaceFileType {
  extension: string;
  name: string;
}

enum WorkspaceStates {
  empty = 'empty',
  workspace = 'workspace', 
  folder = 'folder'
}

interface DidCreateNewResourceEvent {
  uri: URI;
  parent: URI;
}

interface WorkspaceOpenHandlerContribution {
  canHandle(uri: URI): MaybePromise<boolean>;
  openWorkspace(uri: URI, options?: WorkspaceInput): MaybePromise<void>;
  getWorkspaceLabel?(uri: URI): MaybePromise<string | undefined>;
}

interface WorkspaceHandlerContribution {
  canHandle(uri: URI): boolean;
  workspaceStillExists(uri: URI): Promise<boolean>;
}

type MaybePromise<T> = T | Promise<T>;