Skip to main content

​
Overview

The vscode.workspace namespace provides functions to work with the workspace, including accessing files and folders, managing configuration, and listening to file system events.

​
Workspace Folders

​
workspaceFolders

All workspace folders opened in the editor. 
const workspaceFolders: readonly WorkspaceFolder[] | undefined
Example: 
import * as vscode from 'vscode';

const folders = vscode.workspace.workspaceFolders;
if (folders) {
  folders.forEach(folder => {
    console.log(`Folder: ${folder.name} at ${folder.uri.fsPath}`);
  });
}

​
getWorkspaceFolder

Get the workspace folder for a given URI. 
function getWorkspaceFolder(uri: Uri): WorkspaceFolder | undefined
Example: 
const document = vscode.window.activeTextEditor?.document;
if (document) {
  const folder = vscode.workspace.getWorkspaceFolder(document.uri);
  console.log(`Document is in folder: ${folder?.name}`);
}

​
Configuration

​
getConfiguration

Get workspace or section configuration. 
function getConfiguration(
  section?: string,
  scope?: ConfigurationScope
): WorkspaceConfiguration
Example: 
// Get all configuration
const config = vscode.workspace.getConfiguration();

// Get section configuration
const editorConfig = vscode.workspace.getConfiguration('editor');
const fontSize = editorConfig.get<number>('fontSize');

// Update configuration
await editorConfig.update('fontSize', 14, vscode.ConfigurationTarget.Global);
Configuration can be scoped to Global, Workspace, or WorkspaceFolder level.

​
onDidChangeConfiguration

Event fired when configuration changes. 
const onDidChangeConfiguration: Event<ConfigurationChangeEvent>
Example: 
vscode.workspace.onDidChangeConfiguration(event => {
  if (event.affectsConfiguration('myExtension.setting')) {
    // Reload settings
    const newValue = vscode.workspace
      .getConfiguration('myExtension')
      .get('setting');
  }
});

​
File Operations

​
openTextDocument

Open a text document. 
function openTextDocument(uri: Uri): Thenable<TextDocument>
function openTextDocument(fileName: string): Thenable<TextDocument>
Example: 
// Open by URI
const uri = vscode.Uri.file('/path/to/file.txt');
const doc = await vscode.workspace.openTextDocument(uri);

// Show in editor
await vscode.window.showTextDocument(doc);

// Create untitled document
const untitled = await vscode.workspace.openTextDocument({
  content: 'Hello World',
  language: 'plaintext'
});

​
findFiles

Find files across all workspace folders. 
function findFiles(
  include: GlobPattern,
  exclude?: GlobPattern,
  maxResults?: number,
  token?: CancellationToken
): Thenable<Uri[]>
Example: 
// Find all TypeScript files
const tsFiles = await vscode.workspace.findFiles('**/*.ts');

// Find with exclusions
const files = await vscode.workspace.findFiles(
  '**/*.js',
  '**/node_modules/**',
  1000
);

console.log(`Found ${files.length} files`);

​
fs

File system provider for reading and writing files. 
const fs: FileSystem
Example: 
const uri = vscode.Uri.file('/path/to/file.txt');

// Read file
const content = await vscode.workspace.fs.readFile(uri);
const text = new TextDecoder().decode(content);

// Write file
const data = new TextEncoder().encode('Hello World');
await vscode.workspace.fs.writeFile(uri, data);

// Create directory
await vscode.workspace.fs.createDirectory(vscode.Uri.file('/path/to/dir'));

// Delete file
await vscode.workspace.fs.delete(uri);

​
File System Events

​
onDidCreateFiles

Fires when files are created. 
const onDidCreateFiles: Event<FileCreateEvent>

​
onDidDeleteFiles

Fires when files are deleted. 
const onDidDeleteFiles: Event<FileDeleteEvent>

​
onDidRenameFiles

Fires when files are renamed. 
const onDidRenameFiles: Event<FileRenameEvent>
Example: 
vscode.workspace.onDidCreateFiles(event => {
  event.files.forEach(uri => {
    console.log(`File created: ${uri.fsPath}`);
  });
});

​
Text Document Events

​
onDidOpenTextDocument

Fires when a text document is opened. 
const onDidOpenTextDocument: Event<TextDocument>

​
onDidCloseTextDocument

Fires when a text document is closed. 
const onDidCloseTextDocument: Event<TextDocument>

​
onDidChangeTextDocument

Fires when a text document changes. 
const onDidChangeTextDocument: Event<TextDocumentChangeEvent>
Example: 
vscode.workspace.onDidChangeTextDocument(event => {
  const document = event.document;
  const changes = event.contentChanges;
  
  console.log(`Document ${document.fileName} changed`);
  console.log(`Number of changes: ${changes.length}`);
});

​
onDidSaveTextDocument

Fires when a text document is saved. 
const onDidSaveTextDocument: Event<TextDocument>

​
Text Editors

​
textDocuments

All text documents currently known to the system. 
const textDocuments: readonly TextDocument[]
Example: 
const allDocs = vscode.workspace.textDocuments;
const unsaved = allDocs.filter(doc => doc.isDirty);
console.log(`${unsaved.length} unsaved documents`);

​
Edit Operations

​
applyEdit

Apply a workspace edit. 
function applyEdit(edit: WorkspaceEdit): Thenable<boolean>
Example: 
const edit = new vscode.WorkspaceEdit();

// Edit a document
const uri = vscode.Uri.file('/path/to/file.ts');
edit.insert(uri, new vscode.Position(0, 0), '// Header comment\n');

// Create a file
const newFile = vscode.Uri.file('/path/to/new.ts');
edit.createFile(newFile);

// Apply all edits
const success = await vscode.workspace.applyEdit(edit);

​
Best Practices

Check Workspace Folders

Always verify workspaceFolders exists before accessing it

Use Glob Patterns

Use appropriate glob patterns when searching files to avoid performance issues

Configuration Changes

Listen to configuration changes and update your extension behavior accordingly

Batch Edits

Use WorkspaceEdit for multiple file changes to enable undo/redo

Build docs developers (and LLMs) love

Get started for freeTalk to us