vscode-kopytko

A Visual Studio Code extension providing first-class language support for BrightScript (Roku's scripting language) and the Kopytko Framework ecosystem.

Features

• Syntax highlighting and language configuration for .brs files
• IntelliSense completions for 59 ro* components, 76 interfaces, and ~700 methods
• Hover documentation for components, methods, built-in functions, and Kopytko exports
• CreateObject type inference — member completions appear automatically after .
• Diagnostics and go-to-definition for @import annotations
• Kopytko module catalog with package name completions
• Roku device discovery — scans the local network and shows available devices in the Explorer sidebar
• BrightScript debugger — deploy, set breakpoints, inspect variables, step through code on a real Roku device

See docs/features.md for the full feature list.

Testing the extension in VS Code

These steps run the extension in VS Code's Extension Development Host — a separate VS Code window where the extension is live and you can interact with it as a real user would.

Prerequisites

• Node.js 24 or later
• Visual Studio Code

1. Install dependencies and compile

npm install
npm run compile

2. Open the project in VS Code

code .

3. Launch the Extension Development Host

Press F5 (or go to Run → Start Debugging).

VS Code will open a second window titled [Extension Development Host]. The extension is now active in that window.

4. Open or create a BrightScript file

In the Extension Development Host window, open any .brs file or create one:

sub init()
    transfer = CreateObject("roUrlTransfer")
    transfer.
end sub

5. Exercise the features

Reloading after a code change

After editing source files, run npm run compile again, then in the Extension Development Host window press Ctrl+Shift+P and choose Developer: Reload Window (or simply close and re-launch with F5).

For a faster loop, open two terminals and run the watchers in parallel:

npm run watch          # watches extension (client)
npm run watch:server   # watches language server

Changes are picked up automatically; reload the Host window to apply them.

Running the automated test suite

npm test

Runs all unit tests with Mocha. No VS Code instance is needed — tests run in Node.js directly.

npm run test:coverage   # same, with nyc coverage report

Project layout

src/
  extension.ts               Extension entry point
  client/languageClient.ts   LSP client
  server/
    server.ts                Language server entry point
    brightscript/            Component catalog, built-ins, type inference
    kopytko/                 @import resolver, module catalog
    providers/               Completion, hover, diagnostics, definition
test/                        Mocha unit tests (mirrors src/server/)
docs/                        Feature and reference documentation
syntaxes/                    TextMate grammar
snippets/                    VS Code snippets

Roku device discovery

The Roku Devices panel in the Explorer sidebar scans your local network using SSDP and lists all discovered Roku devices with their model, IP, and firmware version.

1. Expand Roku Devices in the Explorer sidebar.
2. Click ↺ in the panel title to scan.
3. Right-click a device → Set as Active Device to make it the default deploy target.

The active device's IP is automatically injected into your launch.json when you start a debug session.

Debugging on a Roku device

Prerequisites

Enable developer mode on the Roku: on the remote press Home × 3, Up, Right, Left, Right, Left, Right. Note the device IP and set a developer password.

launch.json configuration

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "kopytko",
      "request": "launch",
      "name": "Run on Roku",
      "host": "192.168.1.100",
      "password": "rokudev",
      "rootDir": "${workspaceFolder}",
      "env": "dev"
    }
  ]
}

Press F5 to start. The extension will:

1. Build the project using @dazn/kopytko-packager (reads .kopytkorc, runs plugins, generates manifest)
2. Inject stop statements at your breakpoints
3. Deploy to the Roku via kopytko-packager's AppDeployer
4. Connect to the BrightScript Micro Debugger on port 8085

What you can do once paused

See docs/roku-debug.md for full details and architecture notes.

Further reading

• Feature overview
• Roku device management and debugging
• BrightScript component catalog
• Kopytko @import annotations
• Language server architecture

Formatting Settings Reference

The formatter is configured in .vscode/settings.json (workspace) or VS Code's user settings. All settings use the kopytko.format. prefix.

See docs/formatting.md for the complete reference with before/after examples.

Indentation & Whitespace

Compound Keywords

Functions & Subs

Line Length & Wrapping

Arrays & Associative Arrays

Operators & Expressions

Comments

Imports

Blank Lines

Control Flow

BrightScript Patterns

Miscellaneous

Releasing

Both packages are released via GitHub Actions workflows (Actions tab → Run workflow → pick patch/minor/major).

Release kopytko-formatter (npm)

1. Go to Actions → Release kopytko-formatter → Run workflow
2. Select patch, minor, or major
3. The workflow runs tests, bumps the version, updates the changelog, tags kopytko-formatter-v{x.y.z}, publishes to npm (OIDC provenance), and creates a GitHub Release

Release vscode-kopytko (VS Code Marketplace)

1. Go to Actions → Release vscode-kopytko → Run workflow
2. Select patch, minor, or major
3. The workflow compiles, tests, bumps the version, updates the changelog, tags v{x.y.z}, publishes to the Marketplace, and creates a GitHub Release with the .vsix attached

Release order

When the formatter changes affect the extension:

1. Release kopytko-formatter first
2. Update the extension's kopytko-formatter dependency version
3. Release vscode-kopytko

Required secrets

npm uses OIDC provenance — no token needed. See docs/publishing.md for full setup.