Workspace API

The Workspace API provides methods to interact with the current workspace, manage files and folders, and handle workspace-level operations.

Overview

The Workspace API allows you to:

• Access and modify workspace files
• Monitor file system changes
• Manage workspace settings
• Handle multiple workspace folders
• Execute workspace-wide operations

Basic Usage

Getting Workspace Information

import { TraeAPI } from '@trae/api';

// Get workspace folders
const workspaceFolders = TraeAPI.workspace.workspaceFolders;
if (workspaceFolders) {
  console.log('Workspace folders:', workspaceFolders.map(f => f.uri.fsPath));
}

// Get workspace name
const workspaceName = TraeAPI.workspace.name;
console.log('Workspace name:', workspaceName);

File Operations

// Read file content
const fileUri = TraeAPI.Uri.file('/path/to/file.txt');
const content = await TraeAPI.workspace.fs.readFile(fileUri);
const text = Buffer.from(content).toString('utf8');

// Write file content
const newContent = Buffer.from('Hello, World!', 'utf8');
await TraeAPI.workspace.fs.writeFile(fileUri, newContent);

// Check if file exists
const exists = await TraeAPI.workspace.fs.stat(fileUri)
  .then(() => true)
  .catch(() => false);

Workspace Events

// Listen to file changes
TraeAPI.workspace.onDidChangeTextDocument((event) => {
  console.log('Document changed:', event.document.fileName);
  console.log('Changes:', event.contentChanges);
});

// Listen to file creation/deletion
TraeAPI.workspace.onDidCreateFiles((event) => {
  console.log('Files created:', event.files.map(f => f.fsPath));
});

TraeAPI.workspace.onDidDeleteFiles((event) => {
  console.log('Files deleted:', event.files.map(f => f.fsPath));
});

API Reference

Properties

workspaceFolders

Returns an array of workspace folders.

readonly workspaceFolders: readonly WorkspaceFolder[] | undefined;

name

The name of the workspace.

readonly name: string | undefined;

Methods

openTextDocument()

Opens a text document.

openTextDocument(uri: Uri): Thenable<TextDocument>;
openTextDocument(fileName: string): Thenable<TextDocument>;

saveAll()

Saves all dirty files.

saveAll(includeUntitled?: boolean): Thenable<boolean>;

findFiles()

Finds files in the workspace.

findFiles(
  include: GlobPattern,
  exclude?: GlobPattern,
  maxResults?: number
): Thenable<Uri[]>;

File System API

fs.readFile()

Reads the entire contents of a file.

readFile(uri: Uri): Thenable<Uint8Array>;

fs.writeFile()

Writes data to a file.

writeFile(uri: Uri, content: Uint8Array): Thenable<void>;

fs.createDirectory()

Creates a new directory.

createDirectory(uri: Uri): Thenable<void>;

Examples

Project File Scanner

async function scanProjectFiles() {
  const files = await TraeAPI.workspace.findFiles('**/*.{js,ts,jsx,tsx}');
  
  for (const file of files) {
    const document = await TraeAPI.workspace.openTextDocument(file);
    console.log(`File: ${file.fsPath}, Lines: ${document.lineCount}`);
  }
}

Workspace Configuration

// Get workspace configuration
const config = TraeAPI.workspace.getConfiguration('myExtension');
const setting = config.get<string>('mySetting', 'defaultValue');

// Update configuration
await config.update('mySetting', 'newValue', TraeAPI.ConfigurationTarget.Workspace);

File Watcher

const watcher = TraeAPI.workspace.createFileSystemWatcher('**/*.json');

watcher.onDidCreate((uri) => {
  console.log('JSON file created:', uri.fsPath);
});

watcher.onDidChange((uri) => {
  console.log('JSON file changed:', uri.fsPath);
});

watcher.onDidDelete((uri) => {
  console.log('JSON file deleted:', uri.fsPath);
});

Best Practices

1. Always check for workspace existence before performing operations
2. Use proper error handling for file system operations
3. Dispose of watchers when no longer needed
4. Use relative paths when possible for portability
5. Respect user settings and workspace configuration

Related APIs

• Editor API - For working with text editors
• Commands API - For executing workspace commands
• Settings API - For managing workspace settings