@posit-dev/positron

TypeScript definitions and runtime utilities for the Positron API. This package is for extensions that want to utilize the Positron API to add custom functionality for Positron.

The package acquires the API at runtime. Outside Positron, this call returns undefined. As a result, an extension built on this package does not fail to activate in VS Code. It only loses the Positron-specific features.

Installation

npm install --save-dev @posit-dev/positron

Usage

Basic Usage

The tryAcquirePositronApi function is the main entry point for the Positron API. It returns the Positron API object if it is available (aka code is running in Positron), or undefined if it is not. This function is safe to call in both Positron and VS Code.

import { tryAcquirePositronApi } from '@posit-dev/positron';
import * as vscode from 'vscode';

export function activate(context: vscode.ExtensionContext) {
  const positronApi = tryAcquirePositronApi();

  if (positronApi) {
    // Running in Positron - enhanced features available
    vscode.window.showInformationMessage('Enhanced by Positron!');
    positronApi.runtime.executeCode('python', 'print("Hello Positron!")', true);
  } else {
    // Running in VS Code - standard functionality only
    vscode.window.showInformationMessage('Running in VS Code mode');
  }
}

Advanced Usage

Global acquirePositronApi Function

When running in Positron, a global acquirePositronApi function is injected that you can call directly. This package provides TypeScript definitions for this function. Important: This function is undefined when running in VS Code.

// The global function is typed as optional - always check before calling
if (typeof acquirePositronApi !== 'undefined') {
  const positronApi = acquirePositronApi();
  if (positronApi) {
    // Use the API directly
    positronApi.runtime.executeCode('python', 'print("Direct access!")', true);
  }
}

// Alternative using optional chaining
const positronApi = globalThis.acquirePositronApi?.();
if (positronApi) {
  // Safe to use here
}

Recommendation: For most use cases, prefer tryAcquirePositronApi() which handles the detection logic for you and provides cleaner code.

Runtime Detection

import { tryAcquirePositronApi, inPositron } from '@posit-dev/positron';

function executeInPositron(code: string) {
  const api = tryAcquirePositronApi();
  if (api) {
    return api.runtime.executeCode('python', code, false);
  }
  throw new Error('Positron not available');
}

// Clean conditional logic with inPositron()
if (inPositron()) {
  // Positron-specific code
  const api = acquirePositronApi!(); // Safe to assert since inPositron() is true
  api.runtime.executeCode('python', 'print("Hello!")', true);
}

Cross-Platform URL Preview

import { previewUrl } from '@posit-dev/positron';

// Works in both Positron and VS Code
async function showLocalServer() {
  // In Positron: Opens in preview pane
  // In VS Code: Opens in external browser
  await previewUrl('http://localhost:3000');
}

Type-only Imports

import type {
  LanguageRuntimeMetadata,
  RuntimeState,
  LanguageRuntimeSession
} from '@posit-dev/positron';

function processRuntime(runtime: LanguageRuntimeMetadata) {
  // Use types for development, tryAcquirePositronApi() for runtime access
}

Feature Flagging

There are many ways you could "feature flag" Positron-specific functionality. Here is one example:

import { tryAcquirePositronApi, previewUrl } from '@posit-dev/positron';

export class MyExtension {
  private positronApi = tryAcquirePositronApi();

  async doFoo() {
    if (this.positronApi) {
      ... // Positron-specific functionality
    } else {
      ... // VS Code-only functionality
    }
  }
}

API Coverage

This package includes TypeScript definitions for:

Core APIs

• Runtime Management: LanguageRuntimeManager, LanguageRuntimeSession
• Language Runtime Messages: All message types and interfaces
• Runtime States: State enums and metadata interfaces
• Client Management: Runtime client types and handlers

UI APIs

• Window Extensions: Preview panels, output channels, modal dialogs
• Language Features: Statement range providers, help topic providers
• Console Integration: Console API for language-specific interactions

Specialized APIs

• Connections: Database connection driver interfaces
• Environment: Environment variable management
• AI Features: Language model and chat agent interfaces
• Plotting: Plot rendering settings and formats

Stability

This package is pre-1.0. Different parts have different levels of stability. The table below shows what to expect from each part:

Surface	Stability	What to expect
0.2.7	2026.08.1+
tryAcquirePositronApi(), inPositron(), previewUrl(), PositronApi	Stable	These signatures do not change unless there is a major version increase. You can depend on them.
All other Positron API namespaces (runtime, window, languages, …)	Tracks Positron releases	These match the Positron API version listed in the Version Compatibility table. Individual APIs can change between Positron releases. Check that table before you upgrade.
ai namespace	Unstable	Upstream marks this as experimental. It can change or be removed in any release. It depends on VS Code proposed APIs. The build process replaces these with any (#4). As a result, provider-facing signatures are not fully type-checked. If you use this namespace, pin an exact package version.

Version Compatibility

This table shows which version of Positron each package version was built against. The package may still be compatible with earlier Positron versions unless breaking changes are noted.

@posit-dev/positron	Positron Version	VS Code API	Notes
0.2.7	2026.08.1+
0.2.6	2026.08.0+
0.2.5	2026.06.1+
0.2.4	2026.05.0+	1.74.0+	Strips proposed VS Code API references; fixes #4
0.2.3	2026.04.0+
0.2.2	null+
0.2.1	null+
0.2.0	2026.01.0+	1.74.0+

Legend:

• @posit-dev/positron: The package version
• Positron Version: The version of Positron this package was built against
• VS Code API: Minimum VS Code API version required
• Notes: Any breaking changes or compatibility notes

Development

This package is automatically generated from the Positron source code. The types are extracted and processed to be standalone, with all internal dependencies inlined.

Building from Source

# Clone the Positron repository
git clone https://github.com/posit-dev/positron.git
cd positron/positron-api-pkg

# Build the package
npm run build

This will run a single build script that:

1. Gathers types - Copy .d.ts files from main Positron source
2. Compiles TypeScript - Transform source to JavaScript and declarations
3. Copies ambient declarations - Include module declarations in distribution
4. Adds reference directives - Link declarations for proper module resolution

Development Workflow

From the package directory:

# Clean all generated files
npm run clean

# Run complete build process (all steps above)
npm run build

Testing

This package includes a comprehensive test suite built with Vitest that ensures both runtime behavior and TypeScript type definitions work correctly.

Running Tests

# Run all tests
npm test

# Run tests with coverage report
npm run test:coverage

# Run tests in watch mode (for development)
npm run build && npx vitest

Test Structure

The test suite includes:

• Unit Tests (tests/unit/) - Test runtime functions with mocked environments

  • runtime.test.ts - Tests for inPositron() and tryAcquirePositronApi()
  • preview.test.ts - Tests for previewUrl() in both Positron and VS Code environments
  • exports.test.ts - Verifies all expected exports are available

• Type Tests (tests/types/) - Verify TypeScript definitions compile correctly

  • ambient-modules.test.ts - Tests for 'positron' and 'ui-comm' ambient modules
  • exports.test.ts - Tests for exported types and type signatures

Testing Strategy

The tests mock both Positron and VS Code environments to ensure the package works correctly in both contexts:

// Example: Testing in Positron environment
const mockApi = mockPositronEnvironment();
const result = tryAcquirePositronApi();
expect(result).toBe(mockApi);

// Example: Testing in VS Code environment
mockVscodeEnvironment();
const result = tryAcquirePositronApi();
expect(result).toBeUndefined();

The package achieves high test coverage (>95%) for all runtime code, ensuring reliability across different environments.

From Positron Repository Root

# Build the package from the main repo
npm run build-js-sdk

Examples

Working with Language Runtimes

import { tryAcquirePositronApi } from '@posit-dev/positron';
import type { RuntimeCodeExecutionMode } from '@posit-dev/positron';

// Execute code in a runtime (Positron only)
const positronApi = tryAcquirePositronApi();
if (positronApi) {
  await positronApi.runtime.executeCode(
    'python',
    'print("Hello from Positron!")',
    true, // focus console
    false, // require complete code
    RuntimeCodeExecutionMode.Interactive
  );

  // Get active sessions
  const sessions = await positronApi.runtime.getActiveSessions();
  for (const session of sessions) {
    console.log(`Session: ${session.runtimeMetadata.runtimeName}`);
  }
}

Creating Preview Panels

import { tryAcquirePositronApi } from '@posit-dev/positron';
import * as vscode from 'vscode';

// Create a preview panel for web content (Positron only)
const positronApi = tryAcquirePositronApi();
if (positronApi) {
  const panel = positronApi.window.createPreviewPanel(
    'myExtension.preview',
    'My Preview',
    true, // preserve focus
    {
      enableScripts: true,
      localResourceRoots: [vscode.Uri.file('/path/to/resources')]
    }
  );

  panel.webview.html = '<html><body><h1>Hello Positron!</h1></body></html>';
}

Contributing

This package is maintained as part of the Positron project. Please report issues and contribute improvements through the main Positron repository.

License

Licensed under the Elastic License 2.0.