0
# Theia Filesystem Extension
1

2
The @theia/filesystem extension is a comprehensive file system integration package for the Eclipse Theia IDE framework. It provides complete filesystem functionality including file operations, tree widgets, dialogs, file watching, and cross-platform compatibility for browser, desktop, and Node.js environments.
3

4
## Package Information
5

6
- **Package Name**: @theia/filesystem
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @theia/filesystem`
10
- **Version**: 1.64.1
11

12
## Core Imports
13

14
The package provides different entry points for different environments:
15

16
```typescript
17
// Core filesystem types and interfaces
18
import { 
19
  FileStat, FileSystemProvider, FileChangeType, FileType, FileOperation,
20
  FileChange, FileChangesEvent, WatchOptions, FileWriteOptions,
21
  FileDeleteOptions, FileOpenOptions
22
} from "@theia/filesystem/lib/common";
23

24
// File service and high-level operations
25
import { FileService, FileContent, FileStreamContent } from "@theia/filesystem/lib/browser";
26

27
// File tree components
28
import { FileTreeWidget, FileTreeModel, FileStatNode } from "@theia/filesystem/lib/browser";
29

30
// File dialog system
31
import { FileDialogService, OpenFileDialogProps, SaveFileDialogProps } from "@theia/filesystem/lib/browser";
32

33
// File resource management
34
import { FileResource, FileResourceResolver } from "@theia/filesystem/lib/browser";
35

36
// Upload and download services
37
import { FileUploadService, FileDownloadService } from "@theia/filesystem/lib/browser";
38
```
39

40
For Theia extension usage:
41

42
```typescript
43
// In your Theia extension module
44
import { bindFileSystemPreferences } from "@theia/filesystem/lib/browser";
45
import { FileSystemFrontendModule } from "@theia/filesystem/lib/browser";
46

47
// For node/backend modules
48
import { FileSystemBackendModule } from "@theia/filesystem/lib/node";
49
```
50

51
## Basic Usage
52

53
```typescript
54
import { FileService } from "@theia/filesystem/lib/browser";
55
import { FileTreeWidget } from "@theia/filesystem/lib/browser";
56
import { FileDialogService } from "@theia/filesystem/lib/browser";
57
import { URI } from "@theia/core/lib/common/uri";
58

59
// Reading a file with encoding handling
60
const fileService = container.get(FileService);
61
const fileContent = await fileService.readFile(URI.parse('file:///path/to/file.txt'));
62
console.log(fileContent.value.toString());
63

64
// Reading text content with automatic encoding detection
65
const textContent = await fileService.readTextContent(URI.parse('file:///path/to/file.txt'));
66
console.log(textContent.content);
67

68
// File tree widget with location service
69
const fileTree = container.get(FileTreeWidget);
70
fileTree.model.location = URI.parse('file:///workspace');
71

72
// File dialog with options
73
const dialogService = container.get(FileDialogService);
74
const uri = await dialogService.showOpenDialog({
75
  title: 'Select File',
76
  canSelectFiles: true,
77
  canSelectFolders: false,
78
  canSelectMany: false,
79
  filters: { 'Text files': ['txt', 'md'] }
80
});
81

82
// File upload service
83
const uploadService = container.get(FileUploadService);
84
await uploadService.upload(URI.parse('file:///upload-target'), files);
85
```
86

87
## Architecture
88

89
The @theia/filesystem extension is structured around several key components:
90

91
- **Common Layer**: Shared interfaces, types, and utilities for filesystem operations
92
- **Browser Layer**: Frontend UI components, services, and widgets for file management
93
- **Node Layer**: Backend file system providers and services for disk access
94
- **Integration Layer**: Theia extension modules providing dependency injection bindings
95
- **Multi-Environment**: Separate implementations for browser-only, electron, and hybrid deployments
96

97
## Capabilities
98

99
### Core Filesystem Operations
100

101
Fundamental file system operations including reading, writing, watching, and metadata access with full streaming support and encoding detection.
102

103
```typescript { .api }
104
interface FileSystemProvider {
105
  readonly capabilities: FileSystemProviderCapabilities;
106
  readonly onDidChangeCapabilities: Event<void>;
107
  readonly onDidChangeFile: Event<readonly FileChange[]>;
108
  readonly onFileWatchError: Event<void>;
109
  
110
  watch(resource: URI, opts: WatchOptions): Disposable;
111
  stat(resource: URI): Promise<Stat>;
112
  mkdir(resource: URI): Promise<void>;
113
  readdir(resource: URI): Promise<[string, FileType][]>;
114
  delete(resource: URI, opts: FileDeleteOptions): Promise<void>;
115
  rename(from: URI, to: URI, opts: FileOverwriteOptions): Promise<void>;
116
  copy?(from: URI, to: URI, opts: FileOverwriteOptions): Promise<void>;
117
  readFile?(resource: URI): Promise<Uint8Array>;
118
  writeFile?(resource: URI, content: Uint8Array, opts: FileWriteOptions): Promise<void>;
119
}
120

121
interface FileStat extends BaseStat {
122
  readonly isFile: boolean;
123
  readonly isDirectory: boolean;
124
  readonly isSymbolicLink: boolean;
125
  readonly isReadonly: boolean;
126
  children?: FileStat[];
127
}
128

129
interface BaseStat {
130
  resource: URI;
131
  name: string;
132
  size?: number;
133
  mtime?: number;
134
  ctime?: number;
135
  etag?: string;
136
}
137
```
138

139
[Core Filesystem Operations](./filesystem-core.md)
140

141
### File Tree Widget System
142

143
Interactive file tree widget with lazy loading, drag-and-drop, context menus, and full integration with Theia's tree framework.
144

145
```typescript { .api }
146
interface FileTree extends Tree {
147
  resolveChildren(parent: CompositeTreeNode): Promise<TreeNode[]>;
148
}
149

150
interface FileTreeModel extends TreeModel, LocationService {
151
  location: URI | undefined;
152
  selectedFileStatNodes: Readonly<FileStatNode>[];
153
  getNodesByUri(uri: URI): IterableIterator<TreeNode>;
154
}
155
```
156

157
[File Tree Widget](./file-tree.md)
158

159
### File Dialog System
160

161
Configurable file and folder selection dialogs with filtering, navigation controls, and support for both native and web-based implementations.
162

163
```typescript { .api }
164
interface FileDialogService {
165
  showOpenDialog(props: OpenFileDialogProps, folder?: FileStat): Promise<URI | undefined>;
166
  showSaveDialog(props: SaveFileDialogProps, folder?: FileStat): Promise<URI | undefined>;
167
}
168

169
interface OpenFileDialogProps extends FileDialogProps {
170
  canSelectFiles?: boolean;
171
  canSelectFolders?: boolean;
172
  canSelectMany?: boolean;
173
}
174
```
175

176
[File Dialog System](./file-dialog.md)
177

178
### File Resource Management
179

180
Resource abstraction for files with content management, encoding detection, version control, and integration with Theia's resource framework.
181

182
```typescript { .api }
183
interface FileResource extends Resource {
184
  readonly uri: URI;
185
  readonly version: FileResourceVersion | undefined;
186
  readonly encoding: string | undefined;
187
  readonly readOnly: boolean | MarkdownString;
188
  
189
  readContents(options?: { encoding?: string }): Promise<string>;
190
  readStream(options?: { encoding?: string }): Promise<ReadableStream<string>>;
191
  guessEncoding(): Promise<string>;
192
}
193
```
194

195
[File Resource Management](./file-resource.md)
196

197
### File Service Integration
198

199
Unified file service providing high-level file operations, encoding handling, streaming I/O, and event coordination across multiple file system providers.
200

201
```typescript { .api }
202
interface FileService {
203
  readonly providers: Map<string, FileSystemProvider>;
204
  
205
  readFile(resource: URI, options?: ReadEncodingOptions): Promise<FileContent>;
206
  readFileStream(resource: URI, options?: ReadEncodingOptions): Promise<FileStreamContent>;
207
  writeFile(resource: URI, content: string | Uint8Array, options?: WriteFileOptions): Promise<FileStat>;
208
  
209
  onDidFilesChange: Event<FileChangesEvent>;
210
  onDidRunFileOperation: Event<FileOperationEvent>;
211
}
212
```
213

214
[File Service Integration](./file-service.md)
215

216
### Filesystem Preferences
217

218
User preference management for file operations, encoding, watching, exclusions, and behavior customization.
219

220
```typescript { .api }
221
interface FileSystemConfiguration {
222
  'files.watcherExclude': { [globPattern: string]: boolean };
223
  'files.exclude': { [key: string]: boolean };
224
  'files.enableTrash': boolean;
225
  'files.associations': { [filepattern: string]: string };
226
  'files.encoding': string;
227
  'files.autoGuessEncoding': boolean;
228
  'files.maxFileSizeMB': number;
229
}
230
```
231

232
[Filesystem Preferences](./filesystem-preferences.md)
233

234
## Core Types
235

236
```typescript { .api }
237
enum FileType {
238
  Unknown = 0,
239
  File = 1,
240
  Directory = 2,
241
  SymbolicLink = 64
242
}
243

244
enum FileChangeType {
245
  UPDATED = 0,
246
  ADDED = 1,
247
  DELETED = 2
248
}
249

250
enum FileOperation {
251
  CREATE,
252
  DELETE,
253
  MOVE,
254
  COPY
255
}
256

257
enum FileOperationResult {
258
  FILE_IS_DIRECTORY,
259
  FILE_NOT_FOUND,
260
  FILE_NOT_DIRECTORY,
261
  FILE_PERMISSION_DENIED,
262
  FILE_MOVE_CONFLICT,
263
  FILE_EXISTS,
264
  FILE_INVALID_PATH,
265
  FILE_TOO_LARGE,
266
  FILE_EXCEEDS_MEMORY_LIMIT,
267
  FILE_OTHER_ERROR
268
}
269

270
enum FileSystemProviderCapabilities {
271
  FileReadWrite = 2,
272
  FileOpenReadWriteClose = 4,
273
  FileReadStream = 16,
274
  FileFolderCopy = 8,
275
  PathCaseSensitive = 1024,
276
  Readonly = 2048,
277
  Trash = 4096
278
}
279

280
interface FileStatNode extends TreeNode {
281
  readonly fileStat: FileStat;
282
}
283

284
interface FileChangesEvent {
285
  readonly changes: readonly FileChange[];
286
  contains(resource: URI, type?: FileChangeType): boolean;
287
  affects(resource: URI, type?: FileChangeType): boolean;
288
  getAdded(): FileChange[];
289
  getUpdated(): FileChange[];
290
  getDeleted(): FileChange[];
291
}
292

293
interface FileChange {
294
  readonly type: FileChangeType;
295
  readonly resource: URI;
296
}
297

298
interface FileOperationEvent {
299
  readonly operation: FileOperation;
300
  readonly target: URI;
301
  readonly source?: URI;
302
}
303

304
interface FileContent {
305
  readonly resource: URI;
306
  readonly value: BinaryBuffer;
307
  readonly etag?: string;
308
  readonly mtime?: number;
309
  readonly ctime?: number;
310
  readonly name: string;
311
  readonly size?: number;
312
}
313

314
interface FileStreamContent {
315
  readonly resource: URI;
316
  readonly value: ReadableStreamEvents<BinaryBuffer>;
317
  readonly etag?: string;
318
  readonly mtime?: number;
319
  readonly ctime?: number;
320
  readonly name: string;
321
  readonly size?: number;
322
}
323
```