Building a VS Code Extension: Running Python in the Browser with Webview and Pyodide#

VS Code Extension Architecture#

VS Code extensions operate in an “extension host” process, which is a Node.js environment separate from the main VS Code UI process.

• Extensions are defined by a package.json manifest file specifying activation events (when the extension loads) and contributions (commands, menus, views).
• The core logic resides in a main file (often extension.ts or extension.js), which is loaded when an activation event occurs.
• Extensions interact with VS Code and the workspace via the vscode API.
• Commands are a primary way users trigger extension functionality.

Webviews in VS Code#

Webviews provide a mechanism for extensions to create custom views or editors using standard web technologies.

• They display arbitrary HTML content within a panel in the VS Code window.
• Each Webview runs in an isolated context, similar to an <iframe> or a separate browser tab, with restricted access to the user’s machine for security.
• Communication between the extension host (Node.js) and the Webview (JavaScript in the browser) is facilitated exclusively through message passing using the postMessage API. Data sent must be serializable JSON.
• Local resources (like CSS, JavaScript, images) needed by the Webview must be exposed by the extension using special URIs obtained via webview.asWebviewUri.

Pyodide#

Pyodide brings the Python interpreter to the browser environment.

• It compiles the CPython interpreter and standard library to WebAssembly.
• It allows running Python code directly within a web page’s JavaScript environment.
• Pyodide provides seamless interoperability between Python and JavaScript, allowing Python to access the DOM and JavaScript objects, and vice-versa.
• It supports loading many pure-Python packages from PyPI, and some packages with C extensions that have been compiled to WebAssembly.

The Interaction Model#

The combined approach involves these steps:

1. An activation event triggers the extension.
2. A user action (e.g., executing a command) prompts the extension to create a new Webview panel.
3. The extension sets the HTML content for the Webview. This HTML file typically loads necessary CSS and JavaScript resources.
4. The Webview’s JavaScript loads the Pyodide environment (fetching the WebAssembly files and Python standard library).
5. Once Pyodide is ready, the Webview is capable of executing Python code.
6. The extension host can send Python code (as a string) to the Webview via postMessage.
7. The Webview’s JavaScript receives the message, passes the Python code string to the Pyodide interpreter (pyodide.runPythonAsync).
8. Pyodide executes the code. Output (like print statements) and results are captured by the Webview’s JavaScript.
9. The Webview’s JavaScript sends the execution results and any errors back to the extension host via postMessage.
10. The extension host receives the result message and can update the VS Code UI, display output in an output channel, or perform other actions.

This message-passing architecture ensures security and separation of concerns between the trusted extension host environment and the less-trusted Webview browser environment.

Prerequisites#

• Node.js and npm installed.
• VS Code installed.
• Yeoman and the VS Code Extension Generator installed globally:

  1
  npm install -g yo generator-code
  

Project Setup#

1. Run the VS Code Extension Generator:

   1
   yo code
   

2. Select “New Extension (TypeScript)”.
3. Follow the prompts: Enter extension name (e.g., pyodide-webview-demo), identifier, description, author, and select whether to initialize a Git repository.
4. Open the generated project in VS Code (code pyodide-webview-demo).

The core files generated include package.json (extension manifest), src/extension.ts (main extension code), and tsconfig.json (TypeScript configuration).

Creating the Webview Files#

Create a directory (e.g., media) in the project root to hold the Webview’s static files. Inside media, create three files: index.html, script.js, and style.css.

• media/index.html: The structure of the Webview’s page. This will include placeholders for loading scripts and styles that the extension will replace with correct webviewUris.

  1
  <!DOCTYPE html>
  2
  <html lang="en">
  3
  <head>
  4
      <meta charset="UTF-8">
  5
      <meta name="viewport" content="width=device-width, initial-scale=1.0">
  6
      <title>Pyodide Console</title>
  7
      <link rel="stylesheet" href="%styleUri%">
  8
  </head>
  9
  <body>
  10
      <h1>Pyodide Web Console</h1>
  11
      <textarea id="python-code" rows="10" cols="80">print("Hello from Pyodide!")</textarea>
  12
      <button id="run-button">Run Python</button>
  13
      <pre id="output"></pre>
  14
  
  15
      <script src="https://cdn.jsdelivr.net/pyodide/v0.25.0/full/pyodide.js"></script>
  16
      <script src="%scriptUri%"></script>
  17
  </body>
  18
  </html>
  

  • %styleUri% and %scriptUri% are placeholders.
  • The Pyodide script is loaded directly from a CDN.

• media/style.css: Basic styling for the Webview content.

  1
  body {
  2
      font-family: sans-serif;
  3
      padding: 20px;
  4
  }
  5
  #output {
  6
      background-color: #f0f0f0;
  7
      padding: 10px;
  8
      white-space: pre-wrap;
  9
      word-wrap: break-word;
  10
      max-height: 300px;
  11
      overflow-y: auto;
  12
  }
  

• media/script.js: The JavaScript code that runs inside the Webview. This handles loading Pyodide, receiving messages from the extension, sending messages back, and interacting with the HTML elements.

  1
  const vscode = acquireVsCodeApi();
  2
  
  3
  let pyodide;
  4
  
  5
  async function loadPyodideAndRun() {
  6
      console.log("Loading Pyodide...");
  7
      try {
  8
          pyodide = await loadPyodide({
  9
              indexURL: "https://cdn.jsdelivr.net/pyodide/v0.25.0/full/"
  10
          });
  11
          console.log("Pyodide loaded.");
  12
          appendToOutput("Pyodide ready.\n");
  13
      } catch (err) {
  14
          appendToOutput(`Error loading Pyodide: ${err}\n`, true);
  15
          console.error("Error loading Pyodide:", err);
  16
      }
  17
  }
  18
  
  19
  async function runPythonCode(code) {
  20
      if (!pyodide) {
  21
          appendToOutput("Pyodide is not loaded yet.\n", true);
  22
          return;
  23
      }
  24
      appendToOutput(`>>> ${code}\n`);
  25
      try {
  26
          // Redirect stdout/stderr to capture print output
  27
          await pyodide.runPythonAsync(`
  28
              import sys
  29
              import io
  30
              sys.stdout = io.StringIO()
  31
              sys.stderr = io.StringIO()
  32
          `);
  33
          await pyodide.runPythonAsync(code);
  34
          const stdout = pyodide.globals.get("sys").stdout.getvalue();
  35
          const stderr = pyodide.globals.get("sys").stderr.getvalue();
  36
          appendToOutput(stdout);
  37
          if (stderr) {
  38
               appendToOutput(stderr, true);
  39
          }
  40
          // Send result back to extension (optional for simple console)
  41
          // vscode.postMessage({ type: 'pythonResult', result: stdout + stderr });
  42
      } catch (err) {
  43
          appendToOutput(`Error: ${err}\n`, true);
  44
          // Send error back to extension
  45
          // vscode.postMessage({ type: 'pythonError', error: err.toString() });
  46
          console.error("Error running Python:", err);
  47
      } finally {
  48
           // Reset stdout/stderr
  49
           await pyodide.runPythonAsync(`
  50
               sys.stdout = sys.__stdout__
  51
               sys.stderr = sys.__stderr__
  52
           `);
  53
      }
  54
  }
  55
  
  56
  function appendToOutput(text, isError = false) {
  57
      const outputDiv = document.getElementById('output');
  58
      const span = document.createElement('span');
  59
      span.style.color = isError ? 'red' : 'black';
  60
      span.textContent = text;
  61
      outputDiv.appendChild(span);
  62
      outputDiv.scrollTop = outputDiv.scrollHeight; // Auto-scroll
  63
  }
  64
  
  65
  // Handle messages from the extension host
  66
  window.addEventListener('message', async event => {
  67
      const message = event.data; // The JSON data sent from the extension
  68
      switch (message.type) {
  69
          case 'runCode':
  70
              runPythonCode(message.code);
  71
              break;
  72
          // Add other message types as needed
  73
      }
  74
  });
  75
  
  76
  // Handle button click to run code from the textarea
  77
  document.getElementById('run-button').addEventListener('click', () => {
  78
      const code = document.getElementById('python-code').value;
  79
      runPythonCode(code);
  80
  });
  81
  
  82
  // Initial load
  83
  loadPyodideAndRun();
  

  • acquireVsCodeApi() is a global function available in Webviews to get the messaging API.
  • pyodide.runPythonAsync is used for executing Python code, important for async operations like loading packages.
  • sys.stdout and sys.stderr are redirected within Pyodide to capture printed output and errors.

Implementing Extension Logic (src/extension.ts)#

Modify src/extension.ts to register a command that creates and manages the Webview panel.

1. Import the vscode module.
2. Register a command in the activate function.
3. Inside the command handler:
   • Create a new vscode.WebviewPanel.
   • Set its html property by calling a function that loads index.html and replaces the placeholder URIs.
   • Handle messages received from the Webview using panel.webview.onDidReceiveMessage.
   • Optionally handle panel disposal using panel.onDidDispose.

1
import * as vscode from 'vscode';
2
import * as path from 'path';
3
import * as fs from 'fs';
4

5
export function activate(context: vscode.ExtensionContext) {
6

7
  console.log('Congratulations, extension "pyodide-webview-demo" is now active!');
8

9
  let disposable = vscode.commands.registerCommand('pyodide-webview-demo.startConsole', () => {
10
    // Create and show a new webview panel
11
    const panel = vscode.window.createWebviewPanel(
12
      'pyodideConsole', // Identifies the type of the webview. Used internally
13
      'Pyodide Web Console', // Title of the panel displayed to the user
14
      vscode.ViewColumn.One, // Editor column to show the new panel in.
15
      {
16
        // Enable javascript in the webview
17
        enableScripts: true,
18
        // Restrict the webview to only loading content from our extension's `media` directory.
19
        localResourceRoots: [vscode.Uri.file(path.join(context.extensionPath, 'media'))]
20
      }
21
    );
22

23
        // Get the path to the media directory
24
        const mediaPath = path.join(context.extensionPath, 'media');
25

26
        // Get URIs for the webview
27
        const scriptUri = panel.webview.asWebviewUri(vscode.Uri.file(path.join(mediaPath, 'script.js')));
28
        const styleUri = panel.webview.asWebviewUri(vscode.Uri.file(path.join(mediaPath, 'style.css')));
29

30
        // Load the HTML content
31
        let htmlContent = fs.readFileSync(path.join(mediaPath, 'index.html'), 'utf8');
32

33
        // Replace placeholders with actual URIs
34
        htmlContent = htmlContent.replace('%scriptUri%', scriptUri.toString());
35
        htmlContent = htmlContent.replace('%styleUri%', styleUri.toString());
36

37
    // Set the HTML content
38
    panel.webview.html = htmlContent;
39

40
    // Handle messages from the webview
41
    panel.webview.onDidReceiveMessage(
42
      message => {
43
        switch (message.type) {
44
          case 'pythonResult':
45
            // Handle results received from the webview's python execution
46
            console.log('Python Result:', message.result);
47
            // Example: Display in an output channel
48
                        // const outputChannel = vscode.window.createOutputChannel('Pyodide Output');
49
                        // outputChannel.appendLine('Result: ' + message.result);
50
                        // outputChannel.show();
51
            return;
52
                    case 'pythonError':
53
                        // Handle errors
54
                        console.error('Python Error:', message.error);
55
                        // Example: Display error in an output channel
56
                        // const outputChannel = vscode.window.createOutputChannel('Pyodide Output');
57
                        // outputChannel.appendLine('Error: ' + message.error);
58
                        // outputChannel.show();
59
                        return;
60
        }
61
      },
62
      undefined,
63
      context.subscriptions
64
    );
65

66
        // Example: Send a message to the webview after it's created (optional)
67
        // setTimeout(() => {
68
        //     panel.webview.postMessage({ type: 'runCode', code: 'print("Message from extension!")' });
69
        // }, 2000);
70
  });
71

72
  context.subscriptions.push(disposable);
73
}
74

75
// This method is called when your extension is deactivated
76
export function deactivate() {}

• vscode.window.createWebviewPanel creates the panel.
• enableScripts: true is necessary for the JavaScript (script.js) to run within the Webview.
• localResourceRoots is crucial for security, specifying which local directories the Webview is allowed to load resources from (like media).
• panel.webview.asWebviewUri converts a local file path into a special URI (vscode-resource://... or similar) that the Webview can safely load.
• panel.webview.onDidReceiveMessage sets up the handler for incoming messages from the Webview.

Testing the Extension#

1. Press F5 in VS Code. This compiles the TypeScript extension and opens a new Extension Development Host window.
2. In the Extension Development Host window, open the command palette (Ctrl+Shift+P or Cmd+Shift+P).
3. Search for and run the command registered by the extension (e.g., “Pyodide Webview Demo: Start Console”).
4. A new panel should open containing the HTML content. Once Pyodide loads (check the browser’s developer console for “Pyodide ready.”), you can type Python code in the text area and click “Run Python”.
5. Output should appear in the <pre id="output"> block within the Webview.