Skip to main content

​
Activation Events

Activation events define when your extension should be loaded and activated. VS Code follows a lazy loading model where extensions are only activated when specific conditions are met, ensuring optimal performance.

​
Overview

Activation events are declared in your extension’s package.json file under the activationEvents field. When VS Code detects that one of these events has occurred, it loads and calls your extension’s activate() function. 
{
  "activationEvents": [
    "onLanguage:javascript",
    "onCommand:myExtension.sayHello"
  ]
}

​
Core Activation Events

​
onLanguage

Activates when a file of a specific language is opened. 
{
  "activationEvents": [
    "onLanguage:javascript",
    "onLanguage:typescript",
    "onLanguage:python"
  ]
}

{
  "activationEvents": [
    "onLanguage:javascript",
    "onLanguage:javascriptreact",
    "onLanguage:typescript",
    "onLanguage:typescriptreact",
    "onLanguage:jsx-tags",
    "onLanguage:jsonc"
  ]
}
The TypeScript language features extension activates for JavaScript, TypeScript, JSX, and JSON with Comments files.
Language IDs are case-sensitive and must match the language identifiers defined in VS Code or other extensions.

​
onCommand

Activates when a specific command is invoked via the Command Palette, keybinding, or programmatically. 
{
  "activationEvents": [
    "onCommand:myExtension.sayHello",
    "onCommand:myExtension.openSettings"
  ],
  "contributes": {
    "commands": [
      {
        "command": "myExtension.sayHello",
        "title": "Say Hello"
      }
    ]
  }
}
Commands referenced in activationEvents must be declared in the contributes.commands section or registered programmatically in your activate() function.
{
  "activationEvents": [
    "onCommand:typescript.tsserverRequest",
    "onCommand:_typescript.configurePlugin",
    "onCommand:_typescript.learnMoreAboutRefactorings",
    "onCommand:typescript.fileReferences"
  ]
}

​
onFileSystem

Activates when a file or folder from a specific scheme is accessed. 
{
  "activationEvents": [
    "onFileSystem:ssh",
    "onFileSystem:ftp"
  ]
}

{
  "activationEvents": [
    "onFileSystem:git",
    "onFileSystem:git-show"
  ]
}
The Git extension activates when accessing files through the git or git-show file system schemes, allowing it to provide virtual file content for git operations.

​
onView

Activates when a specific view is expanded in the VS Code UI. 
{
  "activationEvents": [
    "onView:myExtension.explorerView"
  ],
  "contributes": {
    "views": {
      "explorer": [
        {
          "id": "myExtension.explorerView",
          "name": "My Custom View"
        }
      ]
    }
  }
}

​
onTaskType

Activates when tasks of a specific type are about to run. 
{
  "activationEvents": [
    "onTaskType:npm",
    "onTaskType:gulp"
  ]
}

{
  "activationEvents": [
    "onTaskType:typescript"
  ]
}
Activates when TypeScript build or watch tasks are executed.

​
onDebug

Activates when a debug session is about to start. 
{
  "activationEvents": [
    "onDebug"
  ]
}
For specific debug types: 
{
  "activationEvents": [
    "onDebugResolve:node",
    "onDebugInitialConfigurations"
  ]
}

​
onEditSession

Activates when an edit session for a specific scheme is loaded. 
{
  "activationEvents": [
    "onEditSession:file"
  ]
}

{
  "activationEvents": [
    "onEditSession:file"
  ]
}

​
onWalkthrough

Activates when a walkthrough is opened. 
{
  "activationEvents": [
    "onWalkthrough:myExtension.gettingStarted"
  ]
}

{
  "activationEvents": [
    "onWalkthrough:nodejsWelcome"
  ]
}

​
onUri

Activates when a URI with your extension’s scheme is opened. 
{
  "activationEvents": [
    "onUri"
  ]
}

​
onWebviewPanel

Activates when a webview of a specific type needs to be restored. 
{
  "activationEvents": [
    "onWebviewPanel:myExtension.preview"
  ]
}

​
onCustomEditor

Activates when a custom editor for a specific view type is opened. 
{
  "activationEvents": [
    "onCustomEditor:myExtension.imageEditor"
  ]
}

​
onAuthenticationRequest

Activates when authentication for a specific provider is requested. 
{
  "activationEvents": [
    "onAuthenticationRequest:github"
  ]
}

​
onRenderer

Activates when a notebook renderer is needed. 
{
  "activationEvents": [
    "onRenderer:myExtension.markdownRenderer"
  ]
}

​
onStartupFinished

Activates after VS Code has fully started, but before the user interacts with the editor. 
{
  "activationEvents": [
    "onStartupFinished"
  ]
}
This is better than using * as it doesn’t slow down VS Code startup. Use this when you need to activate early but don’t need to be available immediately.

​
* (Star - Activate on Startup)

Activates immediately when VS Code starts. 
{
  "activationEvents": [
    "*"
  ]
}
Avoid using * as it impacts VS Code startup performance. Only use this if absolutely necessary. Consider onStartupFinished instead.
{
  "activationEvents": [
    "*",
    "onEditSession:file",
    "onFileSystem:git",
    "onFileSystem:git-show"
  ]
}
The Git extension uses * because git repository detection needs to happen immediately on startup.

​
Best Practices

Activation Strategy

  1. Be specific: Use precise activation events rather than broad ones
  2. Combine events: Use multiple specific events rather than one general event
  3. Avoid *: Use onStartupFinished if you need early activation
  4. Test activation: Verify your extension only activates when needed

​
Good Example

{
  "activationEvents": [
    "onLanguage:markdown",
    "onCommand:markdown.showPreview"
  ]
}

​
Poor Example

{
  "activationEvents": [
    "*"
  ]
}

​
Debugging Activation

You can check when your extension activates by adding logging to your activate() function: 
export function activate(context: vscode.ExtensionContext) {
  console.log('Extension "my-extension" is now active!');
  
  // Your extension code
}
Use the Developer: Show Running Extensions command to see which extensions are activated and their activation times.

​
Multiple Activation Events

Extensions typically need multiple activation events. Your extension will activate when any of the listed events occur: 
{
  "activationEvents": [
    "onLanguage:typescript",
    "onLanguage:javascript",
    "onCommand:myExtension.refactor",
    "onTaskType:typescript"
  ]
}
This extension activates when:
  • A TypeScript file is opened OR
  • A JavaScript file is opened OR
  • The refactor command is invoked OR
  • A TypeScript task runs

​
Migration from workspaceContains

The workspaceContains activation event has been deprecated. Use onStartupFinished combined with workspace file detection in your activate() function instead.

​
Old Pattern (Deprecated)

{
  "activationEvents": [
    "workspaceContains:**/package.json"
  ]
}

​
New Pattern

{
  "activationEvents": [
    "onStartupFinished"
  ]
}

import * as vscode from 'vscode';

export async function activate(context: vscode.ExtensionContext) {
  const files = await vscode.workspace.findFiles('**/package.json');
  if (files.length > 0) {
    // Initialize your extension
  }
}

Build docs developers (and LLMs) love

Get started for freeTalk to us