### Example Configuration
Source: https://github.com/microsoft/vscode-livepreview/blob/main/_autodocs/configuration.md
An example of how to configure Live Preview settings in a JSON file.
```json
{
"livePreview.portNumber": 3000,
"livePreview.hostIP": "127.0.0.1",
"livePreview.serverRoot": "",
"livePreview.defaultPreviewPath": "index.html",
"livePreview.autoRefreshPreview": "On All Changes in Editor",
"livePreview.openPreviewTarget": "Embedded Preview",
"livePreview.previewDebounceDelay": 50,
"livePreview.serverKeepAliveAfterEmbeddedPreviewClose": 3,
"livePreview.showServerStatusNotifications": false,
"livePreview.notifyOnOpenLooseFile": true,
"livePreview.debugOnExternalPreview": false,
"livePreview.customExternalBrowser": "Default",
"livePreview.tasks.runTaskWithExternalPreview": false,
"livePreview.useIntegratedBrowser": true,
"livePreview.httpHeaders": {
"Accept-Ranges": "bytes"
}
}
```
--------------------------------
### ServerGrouping openServer example
Source: https://github.com/microsoft/vscode-livepreview/blob/main/_autodocs/api-reference/server.md
Example of how to use the openServer method.
```typescript
if (!serverGrouping.isRunning) {
await serverGrouping.openServer();
}
```
--------------------------------
### Example Live Preview Task
Source: https://github.com/microsoft/vscode-livepreview/blob/main/_autodocs/configuration.md
An example of a tasks.json configuration to run the Live Preview server.
```json
{
"version": "2.0.0",
"tasks": [
{
"label": "Run Live Preview Server",
"type": "Live Preview",
"workspacePath": "${workspaceFolder}"
}
]
}
```
--------------------------------
### Install dependencies
Source: https://github.com/microsoft/vscode-livepreview/wiki/How-To-Contribute
Install necessary dependencies using npm after cloning the repository.
```bash
cd vscode-livepreview
npm install
```
--------------------------------
### livePreview.httpHeaders Common Examples
Source: https://github.com/microsoft/vscode-livepreview/blob/main/_autodocs/configuration.md
Common examples of custom HTTP headers for the preview server.
```json
{
"livePreview.httpHeaders": {
"Accept-Ranges": "bytes",
"Access-Control-Allow-Origin": "*",
"X-Custom-Header": "value",
"Cache-Control": "no-cache"
}
}
```
--------------------------------
### ServerGrouping showPreviewInExternalBrowser example
Source: https://github.com/microsoft/vscode-livepreview/blob/main/_autodocs/api-reference/server.md
Example of how to use the showPreviewInExternalBrowser method.
```typescript
await serverGrouping.showPreviewInExternalBrowser(true, fileUri);
```
--------------------------------
### serverStarted Example
Source: https://github.com/microsoft/vscode-livepreview/blob/main/_autodocs/api-reference/task-management.md
Example of notifying the task terminal that the server has started.
```typescript
provider.serverStarted(
vscode.Uri.parse('http://localhost:3000'),
ServerStartedStatus.JUST_STARTED,
workspaceFolder
);
```
--------------------------------
### ServerGrouping dispose example
Source: https://github.com/microsoft/vscode-livepreview/blob/main/_autodocs/api-reference/server.md
Example of how to use the dispose method.
```typescript
serverGrouping.dispose();
```
--------------------------------
### ServerGrouping refresh example
Source: https://github.com/microsoft/vscode-livepreview/blob/main/_autodocs/api-reference/server.md
Example of how to use the refresh method.
```typescript
serverGrouping.refresh();
```
--------------------------------
### livePreview.httpHeaders Security Headers Example
Source: https://github.com/microsoft/vscode-livepreview/blob/main/_autodocs/configuration.md
Example of security-related HTTP headers for the preview server.
```json
{
"livePreview.httpHeaders": {
"X-Content-Type-Options": "nosniff",
"X-Frame-Options": "DENY",
"X-XSS-Protection": "1; mode=block"
}
}
```
--------------------------------
### ServerGrouping createOrShowEmbeddedPreview example
Source: https://github.com/microsoft/vscode-livepreview/blob/main/_autodocs/api-reference/server.md
Example of how to use the createOrShowEmbeddedPreview method.
```typescript
await serverGrouping.createOrShowEmbeddedPreview(undefined, fileUri);
```
--------------------------------
### Extension Command: livePreview.start
Source: https://github.com/microsoft/vscode-livepreview/blob/main/_autodocs/DOCUMENTATION_SUMMARY.txt
Start server with default settings.
```plaintext
livePreview.start
Start server with default settings
```
--------------------------------
### openPreview Method Example
Source: https://github.com/microsoft/vscode-livepreview/blob/main/_autodocs/api-reference/manager.md
Example of how to use the openPreview method to open a preview at the default location.
```typescript
await manager.openPreview();
```
--------------------------------
### PreviewManager launchFileInEmbeddedPreview() Example
Source: https://github.com/microsoft/vscode-livepreview/blob/main/_autodocs/api-reference/preview.md
Example of launching a file in the embedded preview.
```typescript
await previewManager.launchFileInEmbeddedPreview(undefined, connection, fileUri);
```
--------------------------------
### connected() Example
Source: https://github.com/microsoft/vscode-livepreview/blob/main/_autodocs/api-reference/connection.md
Example of awaiting the connected() method.
```typescript
await connection.connected();
```
--------------------------------
### Basic Setup Configuration
Source: https://github.com/microsoft/vscode-livepreview/blob/main/_autodocs/configuration.md
Basic configuration for Live Preview, setting the port number and default preview path.
```json
{
"livePreview.portNumber": 3000,
"livePreview.defaultPreviewPath": "index.html"
}
```
--------------------------------
### BrowserPreview reveal() Example
Source: https://github.com/microsoft/vscode-livepreview/blob/main/_autodocs/api-reference/preview.md
Example of revealing the browser preview.
```typescript
await browserPreview.reveal(vscode.ViewColumn.Beside, '/index.html', connection);
```
--------------------------------
### livePreview.showServerStatusNotifications Configuration
Source: https://github.com/microsoft/vscode-livepreview/blob/main/_autodocs/configuration.md
Example of enabling notifications for server status.
```json
{
"livePreview.showServerStatusNotifications": true
}
```
--------------------------------
### Executing the 'livePreview.start' command
Source: https://github.com/microsoft/vscode-livepreview/blob/main/_autodocs/api-reference/extension-activation.md
Example of how to programmatically execute the 'livePreview.start' command.
```typescript
await vscode.commands.executeCommand('livePreview.start');
```
--------------------------------
### Example: Opening Previews
Source: https://github.com/microsoft/vscode-livepreview/blob/main/_autodocs/DOCUMENTATION_SUMMARY.txt
Illustrates how to open previews in embedded or external browsers.
```markdown
CODE EXAMPLES PROVIDED:
- Opening previews in embedded/external browsers
- Running server tasks
- Configuration updates
- Command invocation
- Path manipulation
- Server lifecycle management
```
--------------------------------
### Executing 'livePreview.start.preview.atFile' with options
Source: https://github.com/microsoft/vscode-livepreview/blob/main/_autodocs/api-reference/extension-activation.md
Example of executing the command with additional options.
```typescript
await vscode.commands.executeCommand(
'livePreview.start.preview.atFile',
fileUri,
{ workspace: workspaceFolder }
);
```
--------------------------------
### injectScript Example
Source: https://github.com/microsoft/vscode-livepreview/blob/main/_autodocs/api-reference/endpoints-and-content.md
Example demonstrating the usage of the injectScript method.
```typescript
const injected = htmlInjector.injectScript(
'Content',
'/index.html'
);
// Returns: 'Content'
```
--------------------------------
### Context Variable Usage
Source: https://github.com/microsoft/vscode-livepreview/blob/main/_autodocs/configuration.md
Example of using the 'LivePreviewServerOn' context variable in keybindings.
```json
{
"command": "livePreview.end",
"when": "LivePreviewServerOn"
}
```
--------------------------------
### extRunTask Example
Source: https://github.com/microsoft/vscode-livepreview/blob/main/_autodocs/api-reference/task-management.md
Example of manually running a server task from the extension.
```typescript
await provider.extRunTask(workspaceFolder);
```
--------------------------------
### constructLocalUri() Example
Source: https://github.com/microsoft/vscode-livepreview/blob/main/_autodocs/api-reference/connection.md
Example of constructing a local URI.
```typescript
const uri = connection.constructLocalUri(3000, '/index.html');
// Returns: http://127.0.0.1:3000/index.html
```
--------------------------------
### forceCloseServers Method Example
Source: https://github.com/microsoft/vscode-livepreview/blob/main/_autodocs/api-reference/manager.md
Example of how to use forceCloseServers to close all running servers, with user interaction if multiple servers exist.
```typescript
await manager.forceCloseServers();
```
--------------------------------
### ServerGrouping openServer method
Source: https://github.com/microsoft/vscode-livepreview/blob/main/_autodocs/api-reference/server.md
Starts HTTP and WebSocket servers.
```typescript
public async openServer(): Promise
```
--------------------------------
### package.json Contributions
Source: https://github.com/microsoft/vscode-livepreview/blob/main/_autodocs/api-reference/extension-activation.md
Example of `package.json` contributions for the Live Preview extension, including activation events and main entry point.
```json
{
"activationEvents": [
"onWebviewPanel:browserPreview",
"onTaskType:Live Preview"
],
"main": "./out/extension.js",
"contributes": {
"commands": [...],
"menus": {...},
"configuration": {...},
"taskDefinitions": [...]
}
}
```
--------------------------------
### Executing 'livePreview.start.preview.atFile' from a file context menu
Source: https://github.com/microsoft/vscode-livepreview/blob/main/_autodocs/api-reference/extension-activation.md
Example of executing the command from a file context menu.
```typescript
await vscode.commands.executeCommand(
'livePreview.start.preview.atFile',
fileUri
);
```
--------------------------------
### HttpServer.start Method
Source: https://github.com/microsoft/vscode-livepreview/blob/main/_autodocs/api-reference/server.md
Starts the HTTP server, automatically finding an available port if the initial one is busy.
```typescript
public start(port: number): Promise
```
```typescript
await httpServer.start(3000);
// Server will auto-increment port if 3000 is busy
```
--------------------------------
### openPreviewAtFileUri Method Example
Source: https://github.com/microsoft/vscode-livepreview/blob/main/_autodocs/api-reference/manager.md
Example of how to use openPreviewAtFileUri to open a preview at a specific file URI with options.
```typescript
const fileUri = vscode.Uri.file('/path/to/index.html');
await manager.openPreviewAtFileUri(fileUri, { workspace: workspaceFolder });
```
--------------------------------
### WSServer.start Method
Source: https://github.com/microsoft/vscode-livepreview/blob/main/_autodocs/api-reference/server.md
Starts the WebSocket server on a specified port, attempting subsequent ports if the initial one is occupied.
```typescript
public start(wsPort: number): Promise
```
```typescript
await wsServer.start(3001);
```
--------------------------------
### Console Logs
Source: https://github.com/microsoft/vscode-livepreview/blob/main/test-workspace/page0.html
Example of console log messages.
```javascript
console.info("hello world!");
console.info("a log!");
```
--------------------------------
### livePreview.notifyOnOpenLooseFile Configuration
Source: https://github.com/microsoft/vscode-livepreview/blob/main/_autodocs/configuration.md
Example of disabling warnings for opening previews of loose files.
```json
{
"livePreview.notifyOnOpenLooseFile": false
}
```
--------------------------------
### BrowserPreview close() Example
Source: https://github.com/microsoft/vscode-livepreview/blob/main/_autodocs/api-reference/preview.md
Example of how to close the browser preview.
```typescript
browserPreview.close();
```
--------------------------------
### openPreviewAtFileString Method Example
Source: https://github.com/microsoft/vscode-livepreview/blob/main/_autodocs/api-reference/manager.md
Example of how to use openPreviewAtFileString to open a preview using a file path string.
```typescript
await manager.openPreviewAtFileString('index.html', 'internalPreview');
```
--------------------------------
### closeAllServers Method Example
Source: https://github.com/microsoft/vscode-livepreview/blob/main/_autodocs/api-reference/manager.md
Example of how to use closeAllServers to immediately close all running servers without user interaction.
```typescript
manager.closeAllServers();
```
--------------------------------
### ILaunchInfo Interface
Source: https://github.com/microsoft/vscode-livepreview/blob/main/_autodocs/types.md
Information needed to launch a preview after the server starts.
```typescript
interface ILaunchInfo {
external: boolean;
uri?: vscode.Uri;
debug: boolean;
panel?: vscode.WebviewPanel;
connection: Connection;
}
```
--------------------------------
### Windows Path Endpoint Example
Source: https://github.com/microsoft/vscode-livepreview/blob/main/_autodocs/api-reference/endpoints-and-content.md
Example of an endpoint for a file path on Windows.
```text
File: C:\Users\John\file.html
Endpoint: /endpoint_C:\Users\John\file.html
```
--------------------------------
### sendServerInfoToTerminal Example
Source: https://github.com/microsoft/vscode-livepreview/blob/main/_autodocs/api-reference/task-management.md
Example of sending server information to the terminal.
```typescript
provider.sendServerInfoToTerminal({
method: 'GET',
url: '/index.html',
status: 200
}, workspaceFolder);
```
--------------------------------
### runTaskForFile Method Example
Source: https://github.com/microsoft/vscode-livepreview/blob/main/_autodocs/api-reference/manager.md
Example of how to use runTaskForFile to run a server logging task for a file's workspace.
```typescript
await manager.runTaskForFile();
```
--------------------------------
### Regular File Endpoint Example
Source: https://github.com/microsoft/vscode-livepreview/blob/main/_autodocs/api-reference/endpoints-and-content.md
Example of an endpoint for a regular file that exists on disk.
```text
File: /home/user/projects/loose-file.html
Endpoint: /endpoint_/home/user/projects/loose-file.html
```
--------------------------------
### Executing 'livePreview.start.preview.atFileString' command
Source: https://github.com/microsoft/vscode-livepreview/blob/main/_autodocs/api-reference/extension-activation.md
Example of executing the internal command with a file path string.
```typescript
await vscode.commands.executeCommand(
'livePreview.start.preview.atFileString',
'index.html'
);
```
--------------------------------
### isTaskRunning Example
Source: https://github.com/microsoft/vscode-livepreview/blob/main/_autodocs/api-reference/task-management.md
Example of how to check if a server task is running for a specific workspace.
```typescript
if (provider.isTaskRunning(workspaceFolder)) {
console.log('Server task is running');
}
```
--------------------------------
### Unsaved File Endpoint Example
Source: https://github.com/microsoft/vscode-livepreview/blob/main/_autodocs/api-reference/endpoints-and-content.md
Example of an endpoint for an unsaved file.
```text
File: /tmp/untitled.html (unsaved)
Endpoint: /endpoint_unsaved/untitled.html
```
--------------------------------
### Windows UNC Path Endpoint Example
Source: https://github.com/microsoft/vscode-livepreview/blob/main/_autodocs/api-reference/endpoints-and-content.md
Example of an endpoint for a Windows UNC path.
```text
File: \\server\share\file.html
Endpoint: /endpoint_unc/server/share/file.html
Decoded: //server/share/file.html
```
--------------------------------
### serverStop Example
Source: https://github.com/microsoft/vscode-livepreview/blob/main/_autodocs/api-reference/task-management.md
Examples of notifying the task terminal about server stop status.
```typescript
provider.serverStop(true, workspaceFolder); // Server stopped now
provider.serverStop(false, workspaceFolder); // Server will stop soon
```
--------------------------------
### tasks.json Configuration
Source: https://github.com/microsoft/vscode-livepreview/blob/main/_autodocs/api-reference/task-management.md
Example configuration for a Live Preview task in tasks.json.
```json
{
"version": "2.0.0",
"tasks": [
{
"label": "Run Live Preview Server",
"type": "Live Preview",
"workspacePath": "${workspaceFolder}",
"problemMatcher": []
}
]
}
```
--------------------------------
### livePreview.tasks.runTaskWithExternalPreview Configuration
Source: https://github.com/microsoft/vscode-livepreview/blob/main/_autodocs/configuration.md
Example of automatically closing the server when the external preview is closed.
```json
{
"livePreview.tasks.runTaskWithExternalPreview": true
}
```
--------------------------------
### livePreview.serverKeepAliveAfterEmbeddedPreviewClose Configuration
Source: https://github.com/microsoft/vscode-livepreview/blob/main/_autodocs/configuration.md
Example of configuring the server keep-alive duration after closing an embedded preview.
```json
{
"livePreview.serverKeepAliveAfterEmbeddedPreviewClose": 5
}
```
--------------------------------
### livePreview.previewDebounceDelay Configuration
Source: https://github.com/microsoft/vscode-livepreview/blob/main/_autodocs/configuration.md
Example of setting the debounce delay for preview refreshes.
```json
{
"livePreview.previewDebounceDelay": 100
}
```
--------------------------------
### livePreview.useIntegratedBrowser Configuration
Source: https://github.com/microsoft/vscode-livepreview/blob/main/_autodocs/configuration.md
Example of disabling the use of VS Code's integrated browser.
```json
{
"livePreview.useIntegratedBrowser": false
}
```
--------------------------------
### PathBeginsWith Example
Source: https://github.com/microsoft/vscode-livepreview/blob/main/_autodocs/api-reference/utilities.md
Checks if `file1` is a child of `file2` (file1 starts with file2 as a parent).
```typescript
const isChild = PathUtil.PathBeginsWith('C:\\path\\subdir\\file', 'C:\\path');
// Returns: true
```
--------------------------------
### GetFileName Example
Source: https://github.com/microsoft/vscode-livepreview/blob/main/_autodocs/api-reference/utilities.md
Gets the filename from a path. Optionally returns empty string if the path is a directory.
```typescript
const name = await PathUtil.GetFileName('c:/a/file/path.txt');
// Returns: 'path.txt'
```
--------------------------------
### ServerStartedStatus Enum
Source: https://github.com/microsoft/vscode-livepreview/blob/main/_autodocs/types.md
Enumeration of reasons why a server started.
```typescript
enum ServerStartedStatus {
JUST_STARTED = 0,
STARTED_BY_EMBEDDED_PREV = 1
}
```
--------------------------------
### getPathRelativeToWorkspace Example
Source: https://github.com/microsoft/vscode-livepreview/blob/main/_autodocs/api-reference/utilities.md
Gets the file path relative to its workspace root. Returns undefined if the file is not in a workspace.
```typescript
const relative = await PathUtil.getPathRelativeToWorkspace(fileUri);
// Returns: '/subdir/file.html' (relative to workspace root)
```
--------------------------------
### GetParentDir Example
Source: https://github.com/microsoft/vscode-livepreview/blob/main/_autodocs/api-reference/utilities.md
Gets the parent directory of a file path. If the path is already a directory, returns the path itself.
```typescript
const parent = await PathUtil.GetParentDir('c:/a/file/path.txt');
// Returns: 'c:/a/file/'
```
--------------------------------
### ServerTaskTerminal.serverStarted Method
Source: https://github.com/microsoft/vscode-livepreview/blob/main/_autodocs/api-reference/task-management.md
Method to display server start messages.
```typescript
public serverStarted(externalUri: vscode.Uri, status: ServerStartedStatus): void
```
--------------------------------
### ConvertToPosixPath Example
Source: https://github.com/microsoft/vscode-livepreview/blob/main/_autodocs/api-reference/utilities.md
Converts a path to use POSIX delimiters (`/`) regardless of platform.
```typescript
const posix = PathUtil.ConvertToPosixPath('C:\\path\\to\\file.txt');
// Returns: 'C:/path/to/file.txt'
```
--------------------------------
### serverStarted Method
Source: https://github.com/microsoft/vscode-livepreview/blob/main/_autodocs/api-reference/task-management.md
Notifies the task terminal that the server has started.
```typescript
public serverStarted(
externalUri: vscode.Uri,
status: ServerStartedStatus,
workspace: vscode.WorkspaceFolder | undefined
): void
```
--------------------------------
### resolveExternalWSUri() Example
Source: https://github.com/microsoft/vscode-livepreview/blob/main/_autodocs/api-reference/connection.md
Example of resolving an external WebSocket URI.
```typescript
const wsUri = await connection.resolveExternalWSUri(3001, '/ws');
// Returns: ws://localhost:3001/ws (or mapped address)
```
--------------------------------
### resolveExternalHTTPUri() Example
Source: https://github.com/microsoft/vscode-livepreview/blob/main/_autodocs/api-reference/connection.md
Example of resolving an external HTTP URI.
```typescript
const externalUri = await connection.resolveExternalHTTPUri(3000);
// Returns: http://localhost:3000 (or mapped address for remote/codespace)
```
--------------------------------
### Running Tasks Programmatically
Source: https://github.com/microsoft/vscode-livepreview/blob/main/_autodocs/api-reference/task-management.md
Example of how to run a Live Preview task programmatically using VS Code API.
```typescript
// From extension code
import * as vscode from 'vscode';
// Run the server task
const tasks = await vscode.tasks.fetchTasks({
type: 'Live Preview'
});
if (tasks.length > 0) {
vscode.tasks.executeTask(tasks[0]);
}
```
--------------------------------
### PathEquals Example
Source: https://github.com/microsoft/vscode-livepreview/blob/main/_autodocs/api-reference/utilities.md
Checks if two paths are equal, normalizing path delimiters for platform differences.
```typescript
const equal = PathUtil.PathEquals('C:\\path\\file', 'C:\\path\\file');
// Returns: true (platform-agnostic)
```
--------------------------------
### HttpServer Constructor
Source: https://github.com/microsoft/vscode-livepreview/blob/main/_autodocs/api-reference/server.md
Initializes the HttpServer with necessary dependencies.
```typescript
constructor(
extensionUri: vscode.Uri,
reporter: TelemetryReporter,
endpointManager: EndpointManager,
connection: Connection
)
```
--------------------------------
### changePrefixesForAbsPathDecode Example (Windows UNC Path)
Source: https://github.com/microsoft/vscode-livepreview/blob/main/_autodocs/api-reference/endpoints-and-content.md
Performs prefix transformations for decoding Windows UNC paths.
```typescript
// Windows UNC path
endpointManager.changePrefixesForAbsPathDecode('/unc/server/share/file.txt');
// Returns: '//server/share/file.txt'
```
--------------------------------
### changePrefixesForAbsPathDecode Example (Regular Absolute Path)
Source: https://github.com/microsoft/vscode-livepreview/blob/main/_autodocs/api-reference/endpoints-and-content.md
Performs prefix transformations for decoding absolute file paths.
```typescript
// Regular absolute path
endpointManager.changePrefixesForAbsPathDecode('/C:\Windows\file.txt');
// Returns: 'C:\Windows\file.txt'
```
--------------------------------
### Large Project with Server Root Configuration
Source: https://github.com/microsoft/vscode-livepreview/blob/main/_autodocs/configuration.md
Configuration for large projects, specifying a server root, default preview path, debounce delay, and auto-refresh behavior.
```json
{
"livePreview.serverRoot": "dist",
"livePreview.defaultPreviewPath": "index.html",
"livePreview.previewDebounceDelay": 200,
"livePreview.autoRefreshPreview": "On Changes to Saved Files"
}
```
--------------------------------
### Run Server Logging Task
Source: https://github.com/microsoft/vscode-livepreview/blob/main/_autodocs/api-reference/extension-activation.md
Starts a persistent server task with HTTP request logging. This command registers a VS Code command to run a task for a given file, enabling server logging.
```typescript
vscode.commands.registerCommand(
`${SETTINGS_SECTION_ID}.runServerLoggingTask`,
async (file?: vscode.Uri) => {
await serverPreview.runTaskForFile(file);
}
)
```
--------------------------------
### WSServer Constructor
Source: https://github.com/microsoft/vscode-livepreview/blob/main/_autodocs/api-reference/server.md
Initializes the WSServer with telemetry, endpoint management, and connection details.
```typescript
constructor(
reporter: TelemetryReporter,
endpointManager: EndpointManager,
connection: Connection
)
```
--------------------------------
### Production-Ready Server Configuration
Source: https://github.com/microsoft/vscode-livepreview/blob/main/_autodocs/configuration.md
Configuration for a production-ready server, including host IP, custom HTTP headers, and server status notifications.
```json
{
"livePreview.hostIP": "0.0.0.0",
"livePreview.httpHeaders": {
"X-Content-Type-Options": "nosniff",
"X-Frame-Options": "SAMEORIGIN",
"Cache-Control": "public, max-age=3600"
},
"livePreview.showServerStatusNotifications": true
}
```
--------------------------------
### Registering the 'livePreview.start' command
Source: https://github.com/microsoft/vscode-livepreview/blob/main/_autodocs/api-reference/extension-activation.md
Registers the command to open a preview using default or configured settings.
```typescript
vscode.commands.registerCommand(`${SETTINGS_SECTION_ID}.start`, async () => {
serverPreview.openPreview();
})
```
--------------------------------
### Format sources
Source: https://github.com/microsoft/vscode-livepreview/wiki/How-To-Contribute
Command to format the project sources using npm.
```bash
npm run format
```
--------------------------------
### HTTP Request Logging Example
Source: https://github.com/microsoft/vscode-livepreview/blob/main/_autodocs/api-reference/task-management.md
Example format of HTTP request logs displayed in the server task terminal.
```text
GET /index.html - 200 [2.5ms]
GET /styles/main.css - 200 [1.2ms]
GET /js/app.js - 200 [1.5ms]
GET /images/logo.png - 404 [0.8ms]
```
--------------------------------
### Extension Command: livePreview.start.internalPreview.atFile
Source: https://github.com/microsoft/vscode-livepreview/blob/main/_autodocs/DOCUMENTATION_SUMMARY.txt
Show embedded preview.
```plaintext
livePreview.start.internalPreview.atFile
Show embedded preview
```
--------------------------------
### Extension Command: livePreview.start.preview.atFile
Source: https://github.com/microsoft/vscode-livepreview/blob/main/_autodocs/DOCUMENTATION_SUMMARY.txt
Open or show preview at specific file.
```plaintext
livePreview.start.preview.atFile
Open or show preview at specific file
```
--------------------------------
### Extension Command: livePreview.start.preview.atFileString
Source: https://github.com/microsoft/vscode-livepreview/blob/main/_autodocs/DOCUMENTATION_SUMMARY.txt
Open preview at file path string (internal).
```plaintext
livePreview.start.preview.atFileString
Open preview at file path string (internal)
```
--------------------------------
### livePreview.openPreviewTarget Configuration
Source: https://github.com/microsoft/vscode-livepreview/blob/main/_autodocs/configuration.md
Configuration for the default location where previews should open.
```json
{
"livePreview.openPreviewTarget": "Embedded Preview"
}
```
--------------------------------
### Get All Connections
Source: https://github.com/microsoft/vscode-livepreview/blob/main/_autodocs/api-reference/connection.md
Retrieves an array of all currently active connections.
```typescript
public get connections(): Connection[]
```
```typescript
const allConnections = connectionManager.connections;
allConnections.forEach(conn => console.log(conn.httpPort));
```
--------------------------------
### Extension Command: livePreview.start.externalPreview.atFile
Source: https://github.com/microsoft/vscode-livepreview/blob/main/_autodocs/DOCUMENTATION_SUMMARY.txt
Show external browser preview.
```plaintext
livePreview.start.externalPreview.atFile
Show external browser preview
```
--------------------------------
### GetWorkspaceFromURI
Source: https://github.com/microsoft/vscode-livepreview/blob/main/_autodocs/api-reference/utilities.md
Gets the workspace folder that contains the given file URI.
```typescript
public static async GetWorkspaceFromURI(file: vscode.Uri): Promise
```
--------------------------------
### Extension Command: livePreview.start.externalDebugPreview.atFile
Source: https://github.com/microsoft/vscode-livepreview/blob/main/_autodocs/DOCUMENTATION_SUMMARY.txt
Show external debug preview.
```plaintext
livePreview.start.externalDebugPreview.atFile
Show external debug preview
```
--------------------------------
### External Browser with Debugging Configuration
Source: https://github.com/microsoft/vscode-livepreview/blob/main/_autodocs/configuration.md
Configuration to open the preview in an external browser with debugging enabled.
```json
{
"livePreview.openPreviewTarget": "External Browser",
"livePreview.debugOnExternalPreview": true,
"livePreview.customExternalBrowser": "Chrome"
}
```
--------------------------------
### UnescapePathParts Example
Source: https://github.com/microsoft/vscode-livepreview/blob/main/_autodocs/api-reference/utilities.md
Reverses URI encoding applied by `EscapePathParts` while preserving `/` delimiters.
```typescript
const unescaped = PathUtil.UnescapePathParts('path/to/my%20file.html');
// Returns: 'path/to/my file.html'
```
--------------------------------
### Registering the 'livePreview.start.preview.atFile' command
Source: https://github.com/microsoft/vscode-livepreview/blob/main/_autodocs/api-reference/extension-activation.md
Registers the command to open or show a preview at a specific file.
```typescript
vscode.commands.registerCommand(
`${SETTINGS_SECTION_ID}.start.preview.atFile`,
async (file?: vscode.Uri, options?: IOpenFileOptions) => {
await serverPreview.openPreviewAtFileUri(file, options);
}
)
```
--------------------------------
### GetExternalPreviewType
Source: https://github.com/microsoft/vscode-livepreview/blob/main/_autodocs/api-reference/utilities.md
Gets the external preview type, accounting for debug mode setting.
```typescript
public static GetExternalPreviewType(): string
```
--------------------------------
### livePreview.hostIP Configuration
Source: https://github.com/microsoft/vscode-livepreview/blob/main/_autodocs/configuration.md
Configuration for the IP address to bind the server to.
```json
{
"livePreview.hostIP": "127.0.0.1"
}
```
--------------------------------
### GetWorkspaceFromAbsolutePath
Source: https://github.com/microsoft/vscode-livepreview/blob/main/_autodocs/api-reference/utilities.md
Gets the workspace folder that contains the given absolute file path.
```typescript
public static async GetWorkspaceFromAbsolutePath(
file: string | undefined
): Promise
```
--------------------------------
### Extension Command: livePreview.start.debugPreview.atFile
Source: https://github.com/microsoft/vscode-livepreview/blob/main/_autodocs/DOCUMENTATION_SUMMARY.txt
Show debug preview (external).
```plaintext
livePreview.start.debugPreview.atFile
Show debug preview (external)
```
--------------------------------
### Configuration Setting: livePreview.serverRoot
Source: https://github.com/microsoft/vscode-livepreview/blob/main/_autodocs/DOCUMENTATION_SUMMARY.txt
Web root relative to workspace. Default: "".
```plaintext
livePreview.serverRoot (default: "")
Web root relative to workspace
```
--------------------------------
### GetWorkspaceFromRelativePath
Source: https://github.com/microsoft/vscode-livepreview/blob/main/_autodocs/api-reference/utilities.md
Gets the workspace folder that contains the given relative file path.
```typescript
public static async GetWorkspaceFromRelativePath(
file: string,
ignoreFileRoot?: boolean
): Promise
```
--------------------------------
### Registering the 'livePreview.start.preview.atFileString' command
Source: https://github.com/microsoft/vscode-livepreview/blob/main/_autodocs/api-reference/extension-activation.md
Registers the command to open a preview at a file path specified as a string, used internally.
```typescript
vscode.commands.registerCommand(
`${SETTINGS_SECTION_ID}.start.preview.atFileString`,
async (filePath?: string) => {
filePath = filePath ?? '/';
await serverPreview.openPreviewAtFileString(filePath);
}
)
```
--------------------------------
### encodeLooseFileEndpoint Example
Source: https://github.com/microsoft/vscode-livepreview/blob/main/_autodocs/api-reference/endpoints-and-content.md
Encodes an absolute file path into a URL endpoint.
```typescript
const endpoint = await endpointManager.encodeLooseFileEndpoint('/home/user/Documents/index.html');
// Returns: '/endpoint_/home/user/Documents/index.html'
```
--------------------------------
### onPanelTitleChange Event
Source: https://github.com/microsoft/vscode-livepreview/blob/main/_autodocs/api-reference/preview.md
An event that fires when the panel title should be updated, for example, when navigating to a different page.
```typescript
public readonly onPanelTitleChange: vscode.Event
```
--------------------------------
### Live Preview Task Definition
Source: https://github.com/microsoft/vscode-livepreview/blob/main/_autodocs/configuration.md
Defines the 'Live Preview' task type for running a persistent server.
```json
{
"type": "Live Preview",
"label": "Run Server",
"properties": {
"workspacePath": {
"type": "string",
"description": "Workspace path to serve"
}
}
}
```
--------------------------------
### decodeLooseFileEndpoint Example
Source: https://github.com/microsoft/vscode-livepreview/blob/main/_autodocs/api-reference/endpoints-and-content.md
Decodes a URL endpoint back to an absolute file path.
```typescript
const filePath = await endpointManager.decodeLooseFileEndpoint('/endpoint_/home/user/Documents/index.html');
// Returns: '/home/user/Documents/index.html' (if valid and exists)
```
--------------------------------
### Development with Live Reload Configuration
Source: https://github.com/microsoft/vscode-livepreview/blob/main/_autodocs/configuration.md
Configuration for development environments, enabling live reload on all editor changes and setting debounce delay.
```json
{
"livePreview.autoRefreshPreview": "On All Changes in Editor",
"livePreview.openPreviewTarget": "Embedded Preview",
"livePreview.previewDebounceDelay": 50
}
```
--------------------------------
### Clone the Live Preview repository
Source: https://github.com/microsoft/vscode-livepreview/wiki/How-To-Contribute
Steps to fork and clone the Live Preview repository locally.
```git
git clone https://github.com/<<>>/vscode-livepreview.git
```
--------------------------------
### EscapePathParts Example
Source: https://github.com/microsoft/vscode-livepreview/blob/main/_autodocs/api-reference/utilities.md
Escapes a path for use in URLs while preserving the `/` delimiter. Applies URI encoding to each path segment.
```typescript
const escaped = PathUtil.EscapePathParts('path/to/my file.html');
// Returns: 'path/to/my%20file.html'
```
--------------------------------
### Extension Command: livePreview.runServerLoggingTask
Source: https://github.com/microsoft/vscode-livepreview/blob/main/_autodocs/DOCUMENTATION_SUMMARY.txt
Run server logging task.
```plaintext
livePreview.runServerLoggingTask
Run server logging task
```
--------------------------------
### livePreview.defaultPreviewPath Configuration
Source: https://github.com/microsoft/vscode-livepreview/blob/main/_autodocs/configuration.md
Configuration for the default file to preview when opening a preview without a specific file.
```json
{
"livePreview.defaultPreviewPath": "index.html"
}
```
--------------------------------
### ILivePreviewConfigItem Interface
Source: https://github.com/microsoft/vscode-livepreview/blob/main/_autodocs/types.md
Type-safe representation of all Live Preview configuration settings.
```typescript
interface ILivePreviewConfigItem {
portNumber: number;
showServerStatusNotifications: boolean;
autoRefreshPreview: AutoRefreshPreview;
openPreviewTarget: OpenPreviewTarget;
serverKeepAliveAfterEmbeddedPreviewClose: number;
notifyOnOpenLooseFile: boolean;
runTaskWithExternalPreview: boolean;
defaultPreviewPath: string;
debugOnExternalPreview: boolean;
hostIP: string;
customExternalBrowser: CustomExternalBrowser;
serverRoot: string;
previewDebounceDelay: number;
httpHeaders: any;
useIntegratedBrowser: boolean;
}
```
--------------------------------
### Registering the 'livePreview.start.internalPreview.atFile' command
Source: https://github.com/microsoft/vscode-livepreview/blob/main/_autodocs/api-reference/extension-activation.md
Registers the command to open a preview in the embedded preview panel.
```typescript
vscode.commands.registerCommand(
`${SETTINGS_SECTION_ID}.start.internalPreview.atFile`,
async (file?: vscode.Uri, options?: IOpenFileOptions) => {
reporter.sendTelemetryEvent('preview', {
type: 'internal',
location: 'atFile',
});
await serverPreview.openPreviewAtFileUri(file, options, PreviewType.internalPreview);
}
)
```
--------------------------------
### livePreview.debugOnExternalPreview Configuration
Source: https://github.com/microsoft/vscode-livepreview/blob/main/_autodocs/configuration.md
Configuration to enable JavaScript debugging support for external browser previews.
```json
{
"livePreview.debugOnExternalPreview": true
}
```
--------------------------------
### IExternalPreviewArgs Interface
Source: https://github.com/microsoft/vscode-livepreview/blob/main/_autodocs/types.md
Arguments for launching an external browser preview.
```typescript
interface IExternalPreviewArgs {
uri?: vscode.Uri;
debug: boolean;
connection: Connection;
}
```
--------------------------------
### IOpenFileOptions Interface
Source: https://github.com/microsoft/vscode-livepreview/blob/main/_autodocs/api-reference/manager.md
Options passed when opening a preview at a file location.
```typescript
interface IOpenFileOptions {
workspace?: vscode.WorkspaceFolder;
port?: number;
manager?: ServerGrouping;
}
```
--------------------------------
### Extension Command: livePreview.end
Source: https://github.com/microsoft/vscode-livepreview/blob/main/_autodocs/DOCUMENTATION_SUMMARY.txt
Stop all servers.
```plaintext
livePreview.end
Stop all servers
```
--------------------------------
### livePreview.serverRoot Configuration
Source: https://github.com/microsoft/vscode-livepreview/blob/main/_autodocs/configuration.md
Configuration for the root directory of your web server, relative to the workspace.
```json
{
"livePreview.serverRoot": "public"
}
```
--------------------------------
### connected() Method
Source: https://github.com/microsoft/vscode-livepreview/blob/main/_autodocs/api-reference/connection.md
Called by the server to inform the Connection that servers have successfully started. Resolves external URIs and fires the onConnected event.
```typescript
public async connected(): Promise
```
--------------------------------
### IEmbeddedPreviewArgs Interface
Source: https://github.com/microsoft/vscode-livepreview/blob/main/_autodocs/types.md
Arguments for launching an embedded preview.
```typescript
interface IEmbeddedPreviewArgs {
uri?: vscode.Uri;
panel: vscode.WebviewPanel | undefined;
connection: Connection;
}
```
--------------------------------
### Telemetry event for extension startup
Source: https://github.com/microsoft/vscode-livepreview/blob/main/_autodocs/api-reference/extension-activation.md
Sends a telemetry event to track extension startup with workspace count.
```typescript
reporter.sendTelemetryEvent(
'extension.startUp',
{},
{ numWorkspaceFolders: vscode.workspace.workspaceFolders?.length ?? 0 }
);
```
--------------------------------
### GetPreviewType
Source: https://github.com/microsoft/vscode-livepreview/blob/main/_autodocs/api-reference/utilities.md
Gets the current preview type setting. Returns 'internalPreview' for embedded preview, or the external preview type if external browser is configured.
```typescript
public static GetPreviewType(): string
```
```typescript
const type = SettingUtil.GetPreviewType();
// Returns: 'internalPreview' or 'externalPreview' or 'externalDebugPreview'
```
--------------------------------
### GetValidServerRootForWorkspace
Source: https://github.com/microsoft/vscode-livepreview/blob/main/_autodocs/api-reference/utilities.md
Gets the valid server root prefix for a workspace from settings. Returns empty string if the configured root is invalid or doesn't exist.
```typescript
public static async GetValidServerRootForWorkspace(
workspace: vscode.WorkspaceFolder
): Promise
```
--------------------------------
### Architecture Overview
Source: https://github.com/microsoft/vscode-livepreview/blob/main/_autodocs/README.md
The extension follows a layered architecture.
```text
┌─────────────────────────────────────────┐
│ VS Code Extension API │
│ (Commands, Webview, Configuration) │
└────────────┬────────────────────────────┘
│
┌────────────▼────────────────────────────┐
│ Extension Entry Point │
│ (extension.ts - activate/deactivate) │
└────────────┬────────────────────────────┘
│
┌────────────▼────────────────────────────┐
│ Manager (Singleton) │
│ - Orchestrates all components │
│ - Manages server lifecycle │
│ - Routes preview requests │
└────────────┬────────────────────────────┘
│
┌───────┴───────────────────────┬──────────────┬───────────────────┐
│ │ │ │
┌────▼──────────────┐ ┌─────────────▼──┐ ┌──────▼────────┐ ┌───────▼─────────┐
│ ConnectionManager │ │ PreviewManager │ │ ServerGrouping│ │ ServerTaskProvider
│ - Manages ports │ │ - Embedded UI │ │ - HTTP server │ │ - Task logging
│ - Tracks hosts │ │ - External URLs │ │ - WS server │ │ - Terminal display
└───────────────────┘ └─────────────────┘ └───────────────┘ └───────────────────┘
```
--------------------------------
### Configuration Setting: livePreview.defaultPreviewPath
Source: https://github.com/microsoft/vscode-livepreview/blob/main/_autodocs/DOCUMENTATION_SUMMARY.txt
Default file to preview. Default: "".
```plaintext
livePreview.defaultPreviewPath (default: "")
Default file to preview
```
--------------------------------
### ServerGrouping createOrShowEmbeddedPreview method
Source: https://github.com/microsoft/vscode-livepreview/blob/main/_autodocs/api-reference/server.md
Creates or shows an embedded preview panel.
```typescript
public async createOrShowEmbeddedPreview(
panel?: vscode.WebviewPanel,
file?: vscode.Uri,
relative?: boolean
): Promise
```
--------------------------------
### IServerQuickPickItem Interface
Source: https://github.com/microsoft/vscode-livepreview/blob/main/_autodocs/types.md
Quick pick item shown when closing multiple servers.
```typescript
interface IServerQuickPickItem extends vscode.QuickPickItem {
accept(): void;
}
```
--------------------------------
### Set Default Preview File
Source: https://github.com/microsoft/vscode-livepreview/blob/main/_autodocs/api-reference/extension-activation.md
Sets the default file to open when starting a preview without specifying a file. This command registers a VS Code command to update the default preview file setting, either globally or per workspace folder.
```typescript
vscode.commands.registerCommand(
`${SETTINGS_SECTION_ID}.setDefaultOpenFile`,
async (file: vscode.Uri) => {
const workspace = vscode.workspace.getWorkspaceFolder(file);
if (!workspace) {
await SettingUtil.UpdateSettings(
Settings.defaultPreviewPath,
PathUtil.ConvertToPosixPath(file.fsPath),
vscode.ConfigurationTarget.Global
);
return;
}
const relativeFileStr = file.fsPath.substring(workspace.uri.fsPath.length);
await SettingUtil.UpdateSettings(
Settings.defaultPreviewPath,
PathUtil.ConvertToPosixPath(relativeFileStr),
vscode.ConfigurationTarget.WorkspaceFolder,
file
);
}
)
```
--------------------------------
### goToFile Method
Source: https://github.com/microsoft/vscode-livepreview/blob/main/_autodocs/api-reference/preview.md
Navigates the preview to a specific file path. Can force navigation even if the same file is already displayed.
```typescript
public async goToFile(
file: string,
force?: boolean,
connection?: Connection
): Promise
```
```typescript
await webviewComm.goToFile('/index.html');
```
--------------------------------
### goBack Method
Source: https://github.com/microsoft/vscode-livepreview/blob/main/_autodocs/api-reference/preview.md
Goes back one page in history if available.
```typescript
public goBack(): string | undefined
```
--------------------------------
### ServerGrouping showPreviewInExternalBrowser method
Source: https://github.com/microsoft/vscode-livepreview/blob/main/_autodocs/api-reference/server.md
Opens the preview in an external browser.
```typescript
public async showPreviewInExternalBrowser(debug?: boolean, file?: vscode.Uri): Promise
```
--------------------------------
### goForward Method
Source: https://github.com/microsoft/vscode-livepreview/blob/main/_autodocs/api-reference/preview.md
Goes forward one page in history if available.
```typescript
public goForward(): string | undefined
```
--------------------------------
### Configuration Setting: livePreview.showServerStatusNotifications
Source: https://github.com/microsoft/vscode-livepreview/blob/main/_autodocs/DOCUMENTATION_SUMMARY.txt
Show server status notifications. Default: false.
```plaintext
livePreview.showServerStatusNotifications (default: false)
Show server status notifications
```
--------------------------------
### onShouldLaunchExternalPreview Event
Source: https://github.com/microsoft/vscode-livepreview/blob/main/_autodocs/api-reference/server.md
Fires when a preview should be opened in an external browser.
```typescript
public readonly onShouldLaunchExternalPreview: vscode.Event
```
--------------------------------
### onShouldLaunchEmbeddedPreview Event
Source: https://github.com/microsoft/vscode-livepreview/blob/main/_autodocs/api-reference/server.md
Fires when a preview should be opened in the embedded preview panel.
```typescript
public readonly onShouldLaunchEmbeddedPreview: vscode.Event
```
--------------------------------
### Extension Command: livePreview.setDefaultOpenFile
Source: https://github.com/microsoft/vscode-livepreview/blob/main/_autodocs/DOCUMENTATION_SUMMARY.txt
Set default preview file.
```plaintext
livePreview.setDefaultOpenFile
Set default preview file
```
--------------------------------
### Configuration Setting: livePreview.hostIP
Source: https://github.com/microsoft/vscode-livepreview/blob/main/_autodocs/DOCUMENTATION_SUMMARY.txt
Bind address (IPv4). Default: 127.0.0.1.
```plaintext
livePreview.hostIP (default: 127.0.0.1)
Bind address (IPv4)
```
--------------------------------
### livePreview.autoRefreshPreview Configuration
Source: https://github.com/microsoft/vscode-livepreview/blob/main/_autodocs/configuration.md
Configuration to control when the preview automatically refreshes.
```json
{
"livePreview.autoRefreshPreview": "On All Changes in Editor"
}
```
--------------------------------
### Configuration Setting: livePreview.notifyOnOpenLooseFile
Source: https://github.com/microsoft/vscode-livepreview/blob/main/_autodocs/DOCUMENTATION_SUMMARY.txt
Warn on loose file preview. Default: true.
```plaintext
livePreview.notifyOnOpenLooseFile (default: true)
Warn on loose file preview
```
--------------------------------
### Connection Constructor
Source: https://github.com/microsoft/vscode-livepreview/blob/main/_autodocs/api-reference/connection.md
Initializes a new Connection instance with workspace, root prefix, ports, and host information.
```typescript
constructor(
workspace: vscode.WorkspaceFolder | undefined,
rootPrefix: string,
httpPort: number,
wsPort: number,
host: string
)
```
--------------------------------
### livePreview.portNumber Configuration
Source: https://github.com/microsoft/vscode-livepreview/blob/main/_autodocs/configuration.md
Configuration for the port number on which to run the server.
```json
{
"livePreview.portNumber": 3000
}
```