VS Code Extension

The optional Hosanna UI extension for VS Code adds editor navigation and AppConfig-aware language features. It does not build or launch applications; use the project-local hst commands for that:

npx hst run web dev emulator
npx hst run roku dev device
npx hst build roku dev device

The extension currently requires VS Code 1.85 or later.

What the extension understands

AppConfig and style paths

By default the extension resolves ./assets/meta/app.config.json from each workspace folder. It follows AppConfig extension files, watches the resolved files, and builds a map of paths such as styles.card.title and translations.en.home.heading.

That map provides:

• completion in JSON, JSONC, TypeScript, and TSX;
• definition navigation from style and translation references;
• hover details and replacement helpers;
• AppConfig property completion;
• JSON document symbols and property-to-property navigation;
• asset-path definition navigation.

Set vsc-hosanna-ui.jsonFilePath when the root config lives elsewhere. Relative paths are resolved from each workspace folder; absolute paths and file:// URLs are also accepted. Changing the setting or any resolved config file reloads the map automatically. Run Process JSON Style Files to force a reload.

TypeScript and generated-source navigation

The extension can:

• navigate between TypeScript and transpiled Roku code by using generated source maps;
• keep selections synchronized while you move between those files;
• reload source maps after a rebuild;
• redirect definitions from *-generated*.ts and generated-*.ts files to their source implementation;
• navigate generated view declarations and symbols back to their real view files.

vsc-hosanna-ui.buildFolder identifies the generated build folder. Its default is src/components; change it if the project's transpiled files live somewhere else.

Authoring helpers

The extension also provides:

• Create Hosanna View from the Explorer context menu or Command Palette;
• Replace strings with keys, using the configured translation location and key format;
• Filter JSON and Go to Symbol in JSON for large config files;
• embedded documentation, release notes, and links to this guide and the API reference.

Commands

Open the Command Palette with Cmd+Shift+P on macOS or Ctrl+Shift+P on Windows and Linux.

Command Palette title	Command ID	Purpose
Navigate to Roku Code	vsc-hosanna-ui.navigateToRokuCode	Open the transpiled location for the current source selection.
Navigate to Source Code	vsc-hosanna-ui.navigateToSourceCode	Return from transpiled Roku code to TypeScript.
Toggle Transpiled Code Sync	vsc-hosanna-ui.toggleTranspiledCodeSync	Enable or disable selection synchronization.
Reload Source Maps	vsc-hosanna-ui.reloadSourceMaps	Re-read source maps after generation or compilation.
Process JSON Style Files	vsc-hosanna-ui.processJsonStyleFiles	Rebuild AppConfig and style maps immediately.
Replace strings with keys	vsc-hosanna-ui.lang-extractor	Move matching text into the configured translation section.
Create Hosanna View	vsc-hosanna-ui.createView	Generate a view in the selected workspace location.
Filter JSON	vsc-hosanna-ui.filterJson	Filter the active JSON or JSONC document.
Go to Symbol in JSON	vsc-hosanna-ui.goToSymbolInJson	Jump to a property in the active JSON document.
Open Hosanna Documentation	vsc-hosanna-ui.openDocumentation	Open the extension's embedded guide.
Show Welcome Screen	vsc-hosanna-ui.showWelcome	Reopen the extension welcome page.
Open Hosanna UI Documentation	vsc-hosanna-ui.openHosannaDocs	Open this documentation site.
Open Hosanna UI API Reference	vsc-hosanna-ui.openHosannaApi	Open the generated API reference.

The published manifest currently declares the whitespace-toggle action under a different command ID from its registered handler. Until that is aligned in the extension, change transpiledCodeNavigator.ignoreWhiteSpaceInSelections directly in VS Code settings.

Settings

Setting	Default	Effect
vsc-hosanna-ui.buildFolder	src/components	Folder containing generated/transpiled files used for navigation.
transpiledCodeNavigator.ignoreWhiteSpaceInSelections	true	Ignore whitespace when matching synchronized selections.
vsc-hosanna-ui.jsonFilePath	./assets/meta/app.config.json	Root AppConfig/style JSON file for each workspace.
vsc-hosanna-ui.propRegex	built-in text-property expression	Selects source properties eligible for language extraction.
vsc-hosanna-ui.jsonSection	translations.en	Destination object for extracted strings.
vsc-hosanna-ui.keyPrefix	this.translate('{{locale.	Text inserted before a generated translation key.
vsc-hosanna-ui.keySuffix	}}')	Text inserted after a generated translation key.
vsc-hosanna-ui.switchToJsonFile	false	Open the translation JSON after extraction.
vsc-hosanna-ui.excludeDiagnosticsGlobs	[]	Files excluded from extension diagnostics.
vsc-hosanna-ui.showWelcomeScreen	true	Show the welcome screen after install or update.

Large-file safeguards are enabled by default:

Setting	Default	Limit
vsc-hosanna-ui.performance.enableLargeFileOptimizations	true	Enables all safeguards below.
vsc-hosanna-ui.performance.maxLinesForCompletions	10000	Stops completion work above this line count.
vsc-hosanna-ui.performance.maxFileSizeForCompletions	10	Stops completion work above this size in MB.
vsc-hosanna-ui.performance.maxSymbolsForDocumentSymbols	10000	Stops emitting JSON symbols above this count.
vsc-hosanna-ui.performance.maxFileSizeForParsing	2	Skips JSON parsing above this size in MB.

A numeric limit of 0 disables that individual limit. Raise limits only when the additional language intelligence is worth the editor cost.

Troubleshooting

• If source navigation opens the wrong generated file, rebuild the target and run Reload Source Maps.
• If style completion is empty, confirm vsc-hosanna-ui.jsonFilePath is correct for that workspace and run Process JSON Style Files.
• If a large JSON file has no symbols or completion, inspect the performance limits before assuming the config is invalid.
• In a multi-root workspace, configure the JSON path and generated folder at the appropriate workspace-folder scope.