0
# @theia/workspace
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: @theia/workspace
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: This is a Theia extension - install as part of a Theia application
10

11
## Core Imports
12

13
**Common (shared between frontend/backend):**
14

15
```typescript
16
import { 
17
  WorkspaceServer, 
18
  WorkspaceFileService, 
19
  UntitledWorkspaceService,
20
  workspacePath
21
} from "@theia/workspace/lib/common";
22
```
23

24
**Browser/Frontend:**
25

26
```typescript
27
import { 
28
  WorkspaceService, 
29
  WorkspaceCommands,
30
  CanonicalUriService,
31
  WorkspacePreferences,
32
  WorkspaceTrustService
33
} from "@theia/workspace/lib/browser";
34
```
35

36
**Node/Backend:**
37

38
```typescript
39
import { 
40
  DefaultWorkspaceServer,
41
  WorkspaceCliContribution 
42
} from "@theia/workspace/lib/node";
43
```
44

45
## Basic Usage
46

47
```typescript
48
import { injectable, inject } from "@theia/core/shared/inversify";
49
import { WorkspaceService } from "@theia/workspace/lib/browser";
50
import { CommandContribution, CommandRegistry } from "@theia/core/lib/common";
51

52
@injectable()
53
export class MyWorkspaceContribution implements CommandContribution {
54
  
55
  @inject(WorkspaceService)
56
  protected readonly workspaceService: WorkspaceService;
57

58
  registerCommands(registry: CommandRegistry): void {
59
    registry.registerCommand({
60
      id: 'my.workspace.info',
61
      label: 'Show Workspace Info'
62
    }, {
63
      execute: async () => {
64
        if (this.workspaceService.opened) {
65
          const roots = await this.workspaceService.roots;
66
          console.log(`Workspace has ${roots.length} root folders`);
67
          
68
          if (this.workspaceService.workspace) {
69
            console.log(`Workspace file: ${this.workspaceService.workspace.uri}`);
70
          }
71
        } else {
72
          console.log('No workspace opened');
73
        }
74
      }
75
    });
76
  }
77
}
78
```
79

80
## Architecture
81

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

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

91
## Capabilities
92

93
### Core Workspace Management
94

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

97
```typescript { .api }
98
interface WorkspaceService {
99
  readonly ready: Promise<void>;
100
  readonly roots: Promise<FileStat[]>;
101
  readonly workspace: FileStat | undefined;
102
  readonly opened: boolean;
103
  readonly saved: boolean;
104
  readonly isMultiRootWorkspaceOpened: boolean;
105
  readonly onWorkspaceChanged: Event<FileStat[]>;
106
  readonly onWorkspaceLocationChanged: Event<FileStat | undefined>;
107
  
108
  tryGetRoots(): FileStat[];
109
  open(uri: URI, options?: WorkspaceInput): void;
110
  close(): Promise<void>;
111
  addRoot(uris: URI[] | URI): Promise<void>;
112
  removeRoots(uris: URI[]): Promise<void>;
113
  spliceRoots(start: number, deleteCount?: number, ...rootsToAdd: URI[]): Promise<URI[]>;
114
  recentWorkspaces(): Promise<string[]>;
115
  containsSome(paths: string[]): Promise<boolean>;
116
  save(uri: URI | FileStat): Promise<void>;
117
  getWorkspaceRootUri(uri?: URI): URI | undefined;
118
  getWorkspaceRelativePath(uri: URI): Promise<string>;
119
  areWorkspaceRoots(uris: URI[]): boolean;
120
}
121
```
122

123
[Workspace Service](./workspace-service.md)
124

125
### Workspace Commands and Operations
126

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

129
```typescript { .api }
130
namespace WorkspaceCommands {
131
  const OPEN: Command & { dialogLabel: string };
132
  const OPEN_FILE: Command & { dialogLabel: string };
133
  const OPEN_FOLDER: Command & { dialogLabel: string };
134
  const OPEN_WORKSPACE: Command & { dialogLabel: string };
135
  const OPEN_RECENT_WORKSPACE: Command;
136
  const CLOSE: Command;
137
  const NEW_FILE: Command;
138
  const NEW_FOLDER: Command;
139
  const FILE_RENAME: Command;
140
  const FILE_DELETE: Command;
141
  const FILE_DUPLICATE: Command;
142
  const FILE_COMPARE: Command;
143
  const ADD_FOLDER: Command;
144
  const REMOVE_FOLDER: Command;
145
  const SAVE_WORKSPACE_AS: Command;
146
  const OPEN_WORKSPACE_FILE: Command;
147
  const COPY_RELATIVE_FILE_PATH: Command;
148
}
149
```
150

151
[Workspace Commands](./workspace-commands.md)
152

153
### Workspace File Handling
154

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

157
```typescript { .api }
158
interface WorkspaceFileService {
159
  isWorkspaceFile(candidate: FileStat | URI): boolean;
160
  getWorkspaceFileTypes(): WorkspaceFileType[];
161
  getWorkspaceFileExtensions(dot?: boolean): string[];
162
}
163

164
interface UntitledWorkspaceService {
165
  isUntitledWorkspace(candidate?: URI): boolean;
166
  getUntitledWorkspaceUri(configDirUri: URI, isAcceptable: Function): Promise<URI>;
167
}
168
```
169

170
[Workspace File Handling](./workspace-file-handling.md)
171

172
### Workspace Server Protocol
173

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

176
```typescript { .api }
177
interface WorkspaceServer {
178
  getMostRecentlyUsedWorkspace(): Promise<string | undefined>;
179
  setMostRecentlyUsedWorkspace(uri: string): Promise<void>;
180
  removeRecentWorkspace(uri: string): Promise<void>;
181
  getRecentWorkspaces(): Promise<string[]>;
182
}
183
```
184

185
[Workspace Server](./workspace-server.md)
186

187
### Workspace Preferences and Configuration
188

189
Preference management and workspace-specific configuration handling.
190

191
```typescript { .api }
192
interface WorkspaceConfiguration {
193
  'workspace.preserveWindow': boolean;
194
}
195

196
type WorkspacePreferences = PreferenceProxy<WorkspaceConfiguration>;
197
```
198

199
[Workspace Preferences](./workspace-preferences.md)
200

201
### Canonical URI Service
202

203
Service for providing canonical URI transformations between different URI schemes.
204

205
```typescript { .api }
206
interface CanonicalUriProvider extends Disposable {
207
  provideCanonicalUri(uri: URI, targetScheme: string, token: CancellationToken): Promise<URI | undefined>;
208
}
209

210
interface CanonicalUriService {
211
  registerCanonicalUriProvider(scheme: string, provider: CanonicalUriProvider): Disposable;
212
  provideCanonicalUri(uri: URI, targetScheme: string, token?: CancellationToken): Promise<URI | undefined>;
213
}
214
```
215

216
### Workspace Trust Management
217

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

220
```typescript { .api }
221
interface WorkspaceTrustService {
222
  getWorkspaceTrust(): Promise<boolean>;
223
  resolveWorkspaceTrust(givenTrust?: boolean): Promise<void>;
224
}
225
```
226

227
### Extension Points and Customization
228

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

231
[Extension Points](./extension-points.md)
232

233
## Types
234

235
```typescript { .api }
236
interface WorkspaceData {
237
  folders: Array<{ path: string; name?: string }>;
238
  settings?: { [id: string]: any };
239
  [key: string]: any;
240
}
241

242
interface WorkspaceInput {
243
  preserveWindow?: boolean;
244
}
245

246
interface WorkspaceFileType {
247
  extension: string;
248
  name: string;
249
}
250

251
enum WorkspaceStates {
252
  empty = 'empty',
253
  workspace = 'workspace', 
254
  folder = 'folder'
255
}
256

257
interface DidCreateNewResourceEvent {
258
  uri: URI;
259
  parent: URI;
260
}
261

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

268
interface WorkspaceHandlerContribution {
269
  canHandle(uri: URI): boolean;
270
  workspaceStillExists(uri: URI): Promise<boolean>;
271
}
272

273
type MaybePromise<T> = T | Promise<T>;
274
```