apps/vscode/DOCS.md
The tldraw VS Code extension brings the full power of tldraw's infinite canvas directly into your code editor. You can create, view, and edit .tldr files seamlessly within VS Code, making it perfect for sketching ideas, creating diagrams, wireframes, and visual documentation alongside your code.
This extension provides a native editing experience that's fully compatible with tldraw.com, so you can start a drawing in VS Code and continue it in the browser, or vice versa.
Install the extension directly from the VS Code marketplace:
Alternatively, you can install from a .vsix file by running:
code --install-extension tldraw-vscode.vsix
Here's how to get started with your first tldraw file:
# Create a new .tldr file
touch my-diagram.tldr
# Open it in VS Code - the tldraw editor will launch automatically
code my-diagram.tldr
You'll immediately have access to the full tldraw toolset: drawing, shapes, text, arrows, and more.
The extension provides comprehensive support for tldraw files:
Supported File Types
.tldr files - Native tldraw format.tldr.json files - JSON representation of tldraw documentsFile Operations
Cmd/Ctrl+Shift+P → "tldraw: New Project").tldr files with automatic editor activationYou have access to tldraw's complete toolset within VS Code:
Core Drawing Tools
Shape Creation
Advanced Features
The extension integrates seamlessly with VS Code's interface:
Custom Editor Provider
.tldr filesKeyboard Shortcuts
Cmd/Ctrl + - Zoom inCmd/Ctrl - - Zoom outCmd/Ctrl 0 - Reset zoom to fit contentCmd/Ctrl D - Toggle dark modeCommand Palette Integration
.tldr fileYou can create new tldraw files in several ways:
Via Command Palette
# Open Command Palette
Cmd/Ctrl + Shift + P
# Type and select
tldraw: New Project
This creates a new untitled .tldr file and opens it in the tldraw editor.
Via File Explorer
# Create an empty .tldr file
touch project-wireframes.tldr
# VS Code will automatically open it with the tldraw editor
Programmatically
You can also create .tldr files through VS Code's file system APIs if you're building extensions or automation.
The extension handles file persistence automatically:
Auto-Save Behavior
File Format
Your .tldr files work seamlessly across platforms:
Browser Integration
Sharing and Collaboration
.tldr files like any other project assetThe extension consists of two main components working together:
Extension Process (apps/vscode/extension/)
Webview Editor (apps/vscode/editor/)
The extension uses a robust RPC (Remote Procedure Call) system for communication:
Bidirectional Messaging
// Extension to webview
webview.postMessage({
type: 'openFile',
data: { content: fileContent },
})
// Webview to extension
message.addEventListener('message', (event) => {
if (event.data.type === 'fileChanged') {
// Save changes to disk
saveFile(event.data.content)
}
})
File Change Synchronization
For extension developers, the build system supports hot reload:
Development Setup
# Start extension development with hot reload
cd apps/vscode
yarn dev
# This starts both extension and editor in watch mode
# Extension reloads automatically when files change
Development Workflow
The extension can handle external content intelligently:
Link Unfurling
Asset Management
The extension is optimized for performance in VS Code:
Memory Management
File Loading
.tldr filesZoom and Pan Performance
The extension works well with VS Code's ecosystem:
Multi-Root Workspaces
Split Editors
.tldr files in split panesExtension Compatibility
File Won't Open
.tldr or .tldr.json extensionPerformance Issues
.tldr files to free memorySync Issues with tldraw.com
To build the extension locally:
Prerequisites
Build Process
# Install dependencies
cd apps/vscode
yarn install
# Build extension and editor
yarn build
# Package for distribution
yarn package
This creates a .vsix file that can be installed locally or distributed.
Development Testing
# Start development environment
yarn dev
# This opens VS Code Extension Development Host
# Test your changes in the new VS Code window
The extension supports multiple distribution channels:
VS Code Marketplace
Manual Installation
# Install from local .vsix file
code --install-extension tldraw-vscode-*.vsix
# Or drag the .vsix file into VS Code Extensions view
GitHub Releases
.vsix downloads from repository releasesThe extension supports customization through VS Code settings:
Available Settings
Settings Access
{
"tldraw.theme": "auto",
"tldraw.autoSave": true,
"tldraw.gridSize": 20
}
Access these through VS Code's Settings UI or directly in settings.json.
This extension follows VS Code's development best practices:
The extension provides a professional-grade drawing experience that integrates seamlessly with your development workflow, making visual thinking and documentation a natural part of your coding process.