or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

file-dialog.mdfile-resource.mdfile-service.mdfile-tree.mdfilesystem-core.mdfilesystem-preferences.mdindex.md
tile.json

tessl/npm-theia--filesystem

Theia filesystem extension providing comprehensive file operations, tree widgets, dialogs, and file system integration for IDE environments.

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

To install, run

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

index.mddocs/

Theia Filesystem Extension

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.

Package Information

  • Package Name: @theia/filesystem
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install @theia/filesystem
  • Version: 1.64.1

Core Imports

The package provides different entry points for different environments:

// Core filesystem types and interfaces
import { 
  FileStat, FileSystemProvider, FileChangeType, FileType, FileOperation,
  FileChange, FileChangesEvent, WatchOptions, FileWriteOptions,
  FileDeleteOptions, FileOpenOptions
} from "@theia/filesystem/lib/common";

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

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

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

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

// Upload and download services
import { FileUploadService, FileDownloadService } from "@theia/filesystem/lib/browser";

For Theia extension usage:

// In your Theia extension module
import { bindFileSystemPreferences } from "@theia/filesystem/lib/browser";
import { FileSystemFrontendModule } from "@theia/filesystem/lib/browser";

// For node/backend modules
import { FileSystemBackendModule } from "@theia/filesystem/lib/node";

Basic Usage

import { FileService } from "@theia/filesystem/lib/browser";
import { FileTreeWidget } from "@theia/filesystem/lib/browser";
import { FileDialogService } from "@theia/filesystem/lib/browser";
import { URI } from "@theia/core/lib/common/uri";

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

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

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

// File dialog with options
const dialogService = container.get(FileDialogService);
const uri = await dialogService.showOpenDialog({
  title: 'Select File',
  canSelectFiles: true,
  canSelectFolders: false,
  canSelectMany: false,
  filters: { 'Text files': ['txt', 'md'] }
});

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

Architecture

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

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

Capabilities

Core Filesystem Operations

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

interface FileSystemProvider {
  readonly capabilities: FileSystemProviderCapabilities;
  readonly onDidChangeCapabilities: Event<void>;
  readonly onDidChangeFile: Event<readonly FileChange[]>;
  readonly onFileWatchError: Event<void>;
  
  watch(resource: URI, opts: WatchOptions): Disposable;
  stat(resource: URI): Promise<Stat>;
  mkdir(resource: URI): Promise<void>;
  readdir(resource: URI): Promise<[string, FileType][]>;
  delete(resource: URI, opts: FileDeleteOptions): Promise<void>;
  rename(from: URI, to: URI, opts: FileOverwriteOptions): Promise<void>;
  copy?(from: URI, to: URI, opts: FileOverwriteOptions): Promise<void>;
  readFile?(resource: URI): Promise<Uint8Array>;
  writeFile?(resource: URI, content: Uint8Array, opts: FileWriteOptions): Promise<void>;
}

interface FileStat extends BaseStat {
  readonly isFile: boolean;
  readonly isDirectory: boolean;
  readonly isSymbolicLink: boolean;
  readonly isReadonly: boolean;
  children?: FileStat[];
}

interface BaseStat {
  resource: URI;
  name: string;
  size?: number;
  mtime?: number;
  ctime?: number;
  etag?: string;
}

Core Filesystem Operations

File Tree Widget System

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

interface FileTree extends Tree {
  resolveChildren(parent: CompositeTreeNode): Promise<TreeNode[]>;
}

interface FileTreeModel extends TreeModel, LocationService {
  location: URI | undefined;
  selectedFileStatNodes: Readonly<FileStatNode>[];
  getNodesByUri(uri: URI): IterableIterator<TreeNode>;
}

File Tree Widget

File Dialog System

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

interface FileDialogService {
  showOpenDialog(props: OpenFileDialogProps, folder?: FileStat): Promise<URI | undefined>;
  showSaveDialog(props: SaveFileDialogProps, folder?: FileStat): Promise<URI | undefined>;
}

interface OpenFileDialogProps extends FileDialogProps {
  canSelectFiles?: boolean;
  canSelectFolders?: boolean;
  canSelectMany?: boolean;
}

File Dialog System

File Resource Management

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

interface FileResource extends Resource {
  readonly uri: URI;
  readonly version: FileResourceVersion | undefined;
  readonly encoding: string | undefined;
  readonly readOnly: boolean | MarkdownString;
  
  readContents(options?: { encoding?: string }): Promise<string>;
  readStream(options?: { encoding?: string }): Promise<ReadableStream<string>>;
  guessEncoding(): Promise<string>;
}

File Resource Management

File Service Integration

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

interface FileService {
  readonly providers: Map<string, FileSystemProvider>;
  
  readFile(resource: URI, options?: ReadEncodingOptions): Promise<FileContent>;
  readFileStream(resource: URI, options?: ReadEncodingOptions): Promise<FileStreamContent>;
  writeFile(resource: URI, content: string | Uint8Array, options?: WriteFileOptions): Promise<FileStat>;
  
  onDidFilesChange: Event<FileChangesEvent>;
  onDidRunFileOperation: Event<FileOperationEvent>;
}

File Service Integration

Filesystem Preferences

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

interface FileSystemConfiguration {
  'files.watcherExclude': { [globPattern: string]: boolean };
  'files.exclude': { [key: string]: boolean };
  'files.enableTrash': boolean;
  'files.associations': { [filepattern: string]: string };
  'files.encoding': string;
  'files.autoGuessEncoding': boolean;
  'files.maxFileSizeMB': number;
}

Filesystem Preferences

Core Types

enum FileType {
  Unknown = 0,
  File = 1,
  Directory = 2,
  SymbolicLink = 64
}

enum FileChangeType {
  UPDATED = 0,
  ADDED = 1,
  DELETED = 2
}

enum FileOperation {
  CREATE,
  DELETE,
  MOVE,
  COPY
}

enum FileOperationResult {
  FILE_IS_DIRECTORY,
  FILE_NOT_FOUND,
  FILE_NOT_DIRECTORY,
  FILE_PERMISSION_DENIED,
  FILE_MOVE_CONFLICT,
  FILE_EXISTS,
  FILE_INVALID_PATH,
  FILE_TOO_LARGE,
  FILE_EXCEEDS_MEMORY_LIMIT,
  FILE_OTHER_ERROR
}

enum FileSystemProviderCapabilities {
  FileReadWrite = 2,
  FileOpenReadWriteClose = 4,
  FileReadStream = 16,
  FileFolderCopy = 8,
  PathCaseSensitive = 1024,
  Readonly = 2048,
  Trash = 4096
}

interface FileStatNode extends TreeNode {
  readonly fileStat: FileStat;
}

interface FileChangesEvent {
  readonly changes: readonly FileChange[];
  contains(resource: URI, type?: FileChangeType): boolean;
  affects(resource: URI, type?: FileChangeType): boolean;
  getAdded(): FileChange[];
  getUpdated(): FileChange[];
  getDeleted(): FileChange[];
}

interface FileChange {
  readonly type: FileChangeType;
  readonly resource: URI;
}

interface FileOperationEvent {
  readonly operation: FileOperation;
  readonly target: URI;
  readonly source?: URI;
}

interface FileContent {
  readonly resource: URI;
  readonly value: BinaryBuffer;
  readonly etag?: string;
  readonly mtime?: number;
  readonly ctime?: number;
  readonly name: string;
  readonly size?: number;
}

interface FileStreamContent {
  readonly resource: URI;
  readonly value: ReadableStreamEvents<BinaryBuffer>;
  readonly etag?: string;
  readonly mtime?: number;
  readonly ctime?: number;
  readonly name: string;
  readonly size?: number;
}