Overview

Relevant source files

• CONTRIBUTING.md
• README-en.md
• README.md
• packages/language-plugin/CHANGELOG.md
• packages/language-plugin/package.json
• packages/language-server/CHANGELOG.md
• packages/language-server/package.json
• packages/language-server/src/classes/config-manager.ts
• packages/language-service/CHANGELOG.md
• packages/language-service/package.json
• packages/shared/CHANGELOG.md
• packages/shared/package.json
• packages/typescript-plugin/CHANGELOG.md
• packages/typescript-plugin/package.json
• packages/vscode/CHANGELOG.md
• packages/vscode/README.md
• packages/vscode/package.json
• packages/vscode/schemas/app.schema.json
• packages/vscode/src/generated/meta.ts
• packages/vscode/src/sdk/sdk-analyzer-exception.ts
• packages/vscode/src/tasks/hvigor-assemble-hap.ts

This repository provides comprehensive language tooling for ArkTS (Ark TypeScript) development in Visual Studio Code and compatible editors. It consists of a VS Code extension (vscode-naily-ets) and a complete language server infrastructure built on the Volar framework, enabling intelligent code editing, navigation, diagnostics, and project management for OpenHarmony and HarmonyOS applications.

For information about specific subsystems:

• Extension features and commands: see VS Code Extension
• Language intelligence implementation: see Language Server System
• Language feature details: see Language Features
• SDK installation and management: see SDK Management

Sources: README.md1-195 packages/vscode/package.json1-537

---

What is ArkTS?

ArkTS is the primary programming language for OpenHarmony and HarmonyOS application development. It extends TypeScript with declarative UI syntax, custom annotations, and platform-specific APIs. ArkTS files use the .ets extension and combine standard TypeScript with UI component declarations using decorators like @Component, @State, and @Prop.

This repository provides the tooling infrastructure necessary to develop ArkTS applications outside of DevEco Studio, making VS Code a viable alternative development environment.

Sources: packages/vscode/package.json344-359 README.md22-41

---

Repository Structure

The repository is organized as a pnpm workspace monorepo containing eight published packages and supporting infrastructure:

Package	Purpose	Published To
vscode-naily-ets	VS Code extension providing UI, commands, and integration	VS Code Marketplace, Open VSX
@arkts/language-server	LSP server implementation with Volar integration	npm
@arkts/language-service	Core language features (completion, diagnostics, etc.)	npm
@arkts/language-plugin	Volar language plugin for virtual code generation	npm
@arkts/typescript-plugin	TypeScript server plugin for VS Code's built-in TS service	npm (private)
@arkts/shared	Common utilities and types	npm
@arkts/types	Type definitions for OpenHarmony configuration files	npm
@arkts/vfs	Virtual file system implementation	npm

Additionally, the repository includes:

• @arkts/project-detector: Native module (17 platform variants) for analyzing Hvigor projects and resources
• @ohos-rs/oxk: Rust-based code formatter (15 platform variants)
• ohos-typescript: Customized TypeScript compiler for ArkTS

Sources: packages/vscode/package.json1-14 packages/language-server/package.json1-77 packages/language-service/package.json1-81 packages/language-plugin/package.json1-57 packages/typescript-plugin/package.json1-66 packages/shared/package.json1-66 CONTRIBUTING.md1-78

---

System Architecture

Component Architecture Diagram

Architecture Overview

The system is organized into five cooperating layers:

1. Extension Layer (packages/vscode): Entry point at packages/vscode/src/client.ts provides ArkTSExtension class managing:

   • SdkAnalyzer: Validates SDK paths and generates configuration
   • Command handlers: Implements ets.restartServer, ets.installSDK, etc.
   • ResourceExplorer: TreeView UI for browsing project resources
   • HdcManager: Webview panel for device management
   • Task providers: HvigorAssembleHapTaskProvider, HdcInstallHapTaskProvider, HdcRunAbilityTaskProvider

2. Language Server Protocol Layer: Dual communication paths:

   • LSP Mode: LanguageClient communicates with standalone Node.js process running bin/ets-language-server.js
   • TS Plugin Mode: ets-typescript-plugin loaded by VS Code's built-in tsserver process

3. Language Service Layer (packages/language-service): Core feature implementations:

   • Resource namespace: ResourceProvider, ResourceResolver for $r() references
   • Feature providers: CompletionProvider, DiagnosticProvider, DefinitionProvider, HoverProvider, DocumentLinkProvider
   • LanguageServerConfigManager: Generates TypeScript compiler options from SDK configuration

4. Language Plugin Layer (packages/language-plugin): Volar integration:

   • ETSLanguagePlugin: Implements Volar's createLanguage() interface
   • ETSVirtualCode: Maps .ets source files to virtual TypeScript with source mappings
   • Macro transformers: $$thisFixerPlugin transforms ArkTS-specific constructs using ts-macro

5. External Dependencies: Platform-specific and SDK resources:

   • ohos-typescript: Fork of TypeScript compiler supporting ScriptKind.ETS
   • @ohos-rs/oxk: Rust-based formatter with 15 platform-specific binaries
   • @arkts/project-detector: Rust module with 17 platform-specific binaries for project analysis
   • OpenHarmony SDK: Provides ets/component, ets/build-tools/ets-loader/tsconfig.json, and sysResource.js

Sources: packages/vscode/package.json36-502 packages/language-server/package.json1-77 packages/language-service/package.json1-81 packages/language-plugin/package.json1-57 packages/vscode/src/tasks/hvigor-assemble-hap.ts1-79 packages/vscode/src/sdk/sdk-analyzer-exception.ts1-36 packages/language-server/src/classes/config-manager.ts1-278

---

Technology Stack

Core Frameworks

Volar Framework: The language server is built on @volar/language-core and @volar/language-server, which provide:

• Virtual code generation for mapping ArkTS to TypeScript
• Language service plugin architecture
• Multi-language support (TypeScript, CSS, HTML via embedded services)

Language Server Protocol (LSP): Communication between VS Code and the language server follows the LSP specification, enabling language features like:

• textDocument/completion
• textDocument/definition
• textDocument/diagnostic
• textDocument/hover
• textDocument/formatting

Sources: packages/language-server/package.json64-75

Key Dependencies

• ohos-typescript: Customized TypeScript compiler supporting ArkTS syntax extensions (decorators, declarative UI)
• @arkts/project-detector: Native Rust module providing fast project analysis for Hvigor projects, resources, and modules (supports 17 platforms: darwin-arm64/x64, linux-arm64/x64/musl, windows-x64, etc.)
• @ohos-rs/oxk: Rust-based code formatter built on oxc for ArkTS formatting (supports 15 platforms)
• ts-macro: Enables compile-time macro transformations for handling ArkTS-specific constructs like $this and @interface

Sources: packages/language-service/package.json63-76 packages/language-server/package.json57-76 README.md36-40

---

Feature Categories

The extension provides comprehensive language support across multiple feature domains:

Language Intelligence

• Code Completion: Context-aware suggestions for ArkTS syntax, UI components, and APIs
• Diagnostics: Error and warning detection including ArkTS Linter integration (versions 1.0, 1.1)
• Navigation: Go to definition, find references, document symbols
• Hover Information: Type information and documentation on hover
• Code Formatting: Powered by @ohos-rs/oxk formatter

Resource Management

• $r() Function Support: Intelligent completion and navigation for resource references ($r('app.string.hello'))
• Resource Explorer: Tree view showing application resources organized by type and qualifier
• Resource Validation: Diagnostics for invalid or missing resource references
• Resource Types: Support for string, color, media, float, integer, boolean, intarray, strarray, plural, pattern resources

SDK Management

• Automatic Detection: SDK version detection from build-profile.json5 and local.properties
• SDK Installation: Download and install OpenHarmony SDK versions with ets.installSDK command
• SDK Path Configuration: Three-tier priority system (local.properties → workspace config → global config)
• HMS SDK Support: Optional HMS SDK integration for HarmonyOS development

Project Support

• Configuration Validation: JSON schemas for module.json5, build-profile.json5, oh-package.json5, app.json5, and other configuration files
• Multi-Module Projects: Support for complex project structures with multiple modules
• Hvigor Integration: Build system integration for assembling HAP packages
• HDC Integration: Device connector for deploying and running applications

Development Tools

• Task Definitions: hvigor-assemble-hap, hdc-install-hap, hdc-run-ability task types
• Debugging: ArkTS debugger configuration with sourcemap support
• Icon Theme: Built-in file icon theme supporting ArkTS file types

Sources: packages/vscode/package.json50-519 README.md24-41

---

Dual-Mode Operation

The system provides language intelligence through two complementary modes:

Mode 1: Language Server (Primary)

The primary mode uses a dedicated language server process:

• Activation: Extension activates on workspace containing .ets files, build-profile.json5, or oh-package.json5
• Communication: LSP protocol via LanguageClient from vscode-languageclient
• Process: Separate Node.js process running @arkts/language-server
• Features: Full language intelligence including resource management, custom diagnostics, and formatting

Mode 2: TypeScript Plugin (Fallback)

A complementary mode integrates with VS Code's built-in TypeScript service:

• Registration: typescriptServerPlugins contribution point in package.json registers ets-typescript-plugin
• Loading: VS Code's TypeScript extension loads the plugin into its tsserver process
• Purpose: Provides basic TypeScript features when language server is not running
• Shared Core: Both modes use the same @arkts/language-plugin for virtual code generation

This dual-mode architecture ensures language features remain available even if the language server fails to start, and allows the extension to work with VS Code's existing TypeScript infrastructure.

Sources: packages/vscode/package.json45-49 packages/vscode/package.json497-502 packages/typescript-plugin/package.json1-66

---

Entry Points and Key Classes

Entry Points and Key Code Entities

Extension Entry Point

File: packages/vscode/src/client.ts
Main Class: ArkTSExtension

Activation events trigger extension loading:

The ArkTSExtension class manages:

• Command registration: Maps command IDs to handlers
  • ets.restartServer → Restarts language server process
  • ets.installSDK → Opens SDK installation UI
  • ets.createProject → Opens project creation wizard
  • ets.resourceExplorer.refresh → Refreshes resource tree view
• Language client: Creates LanguageClient instance connecting to language server
• TypeScript plugin: Registers via typescriptServerPlugins contribution point
• UI components: Instantiates ResourceExplorer (tree view), HdcManager (webview panel)
• Task providers: Registers HvigorAssembleHapTaskProvider, HdcInstallHapTaskProvider, HdcRunAbilityTaskProvider

Sources: packages/vscode/package.json45-49 packages/vscode/src/generated/meta.ts15-69

Language Server Entry Point

Package: @arkts/language-server
Binary: bin/ets-language-server.js
Export: Main module at packages/language-server/src/index.ts

Server initialization flow:

1. createConnection() - Establishes LSP connection (stdio/IPC/socket)
2. createLanguageServer() - Creates Volar language server with:
   • Language plugins: ETSLanguagePlugin instance
   • Service plugins: TypeScript, CSS, HTML, Emmet services
   • Configuration: LanguageServerConfigManager for SDK paths
3. Connection listening: connection.listen() starts message processing

Key configuration class: LanguageServerConfigManager

• Methods: setSdkPath(), getTsConfig(), getSysResource(), getEtsLoaderConfigCompilerOptions()
• Generates TypeScript CompilerOptions from SDK configuration
• Loads sysResource.js from SDK using createRequire()

Sources: packages/language-server/package.json39-41 packages/language-server/src/classes/config-manager.ts10-277

Core Service Classes

Resource Namespace (@arkts/language-service/src/resource/)

Key classes:

• ResourceProvider: Main service providing LSP features for $r() references

  • Methods: provideCompletionItems(), provideDefinition(), provideDiagnostics(), provideHover(), provideDocumentLinks()
  • Uses: @arkts/project-detector for resource indexing
  • Supports: App resources ($r('app.string.hello')) and system resources ($r('sys.color.bg'))

• ResourceResolver: Parses and resolves resource references

  • Method: resolveResourceReference() - Parses $r() call expressions
  • Method: getResourceLocation() - Maps references to file locations
  • Returns: { uri: URI, range: Range, value: any } for resolved resources

ETSLanguagePlugin (@arkts/language-plugin/src/index.ts)

Implements Volar's LanguagePlugin interface:

• createVirtualCode(fileId, languageId, snapshot): Creates ETSVirtualCode instance
  • Generates virtual TypeScript from .ets source
  • Applies macro transformations via $$thisFixerPlugin
  • Creates source mappings for error reporting
• typescript.resolveLanguageServiceHost(host): Configures TS host
  • Adds SDK declaration paths to host.getScriptFileNames()
  • Configures module resolution with CompilerOptions

ETSVirtualCode (@arkts/language-plugin/src/virtual-code.ts)

Represents virtual TypeScript generated from .ets:

• Property: mappings: CodeMapping[] - Source position mappings
• Method: update(snapshot) - Regenerates virtual code when source changes
• Method: getContent() - Returns virtual TypeScript string
• Macro application: Uses ts-macro to transform $this to this, handle @interface annotations

Sources: packages/language-service/package.json24-77 packages/language-plugin/package.json24-56

---

Configuration System

The extension exposes configuration through VS Code settings API:

Configuration Key	Type	Purpose	Default
ets.sdkPath	string	OpenHarmony SDK path (triggers server restart)	""
ets.baseSdkPath	string	Base directory for multiple SDK versions	"${os.homedir}/OpenHarmony"
ets.hmsPath	string	HMS SDK path (independent of OHOS SDK)	""
ets.lspDebugMode	boolean	Enable debug logging in language server	false
ets.ignoreWorkspaceLocalPropertiesFile	boolean	Skip reading local.properties for SDK path	false
ets.linterVersion	"1.0" | "1.1" | "off"	ArkTS linter version	"1.1"
ets.resourceReferenceDiagnostic	"error" | "warning" | "none"	Severity for unresolved $r()	"error"
ets.localImagePath	string?	Emulator image storage location	Platform-specific
ets.imageConfigPath	string?	DevEco Studio config path	Platform-specific
ets.deployedEmulatorPath	string?	Deployed emulator instances	Platform-specific
ets.emulatorLogPath	string?	Emulator log files location	Platform-specific

Configuration Usage in Code:

Generated type-safe configuration access via packages/vscode/src/generated/meta.ts87-270:

Configuration Flow:

1. Extension reads config: vscode.workspace.getConfiguration('ets').get('sdkPath')
2. Config change triggers onDidChangeConfiguration event
3. For ets.sdkPath, extension calls client.restart() to reload language server
4. Language server receives config via InitializeParams in LSP protocol
5. LanguageServerConfigManager applies config to TypeScript compiler options

SDK Path Resolution Priority:

1. local.properties (project root, ignored if ets.ignoreWorkspaceLocalPropertiesFile = true)
2. Workspace-level ets.sdkPath setting
3. User-level (global) ets.sdkPath setting

Sources: packages/vscode/package.json421-496 packages/vscode/src/generated/meta.ts87-270 packages/language-server/src/classes/config-manager.ts61-80

---

Package Dependencies Graph

The dependency graph shows:

• Extension Layer: vscode-naily-ets depends on language server, TypeScript plugin, and native tools
• Language Server: Orchestrates language service and plugin
• Language Service: Core implementation using shared utilities, types, and external tools
• Language Plugin: Provides Volar integration and virtual code generation
• Shared Layer: Common utilities used across all packages
• Native Modules: @arkts/project-detector and @ohos-rs/oxk are pre-built binaries
• Compiler: ohos-typescript is the foundation for all language processing

Sources: packages/language-server/package.json57-76 packages/language-service/package.json63-77 packages/typescript-plugin/package.json53-65 packages/vscode/package.json530-535

---

Build and Distribution

The repository uses a sophisticated build pipeline:

Build Tools

• tsdown: Compiles TypeScript packages with ESM/CJS dual output
• pnpm workspaces: Manages monorepo with workspace protocol dependencies
• changesets: Handles versioning and publishing workflow

Platform Support

The extension supports 10 platform variants:

• darwin-arm64, darwin-x64
• linux-arm64, linux-x64, linux-x64-musl
• win32-x64, win32-arm64
• alpine-arm64, alpine-x64
• web (browser-based VS Code)

Native modules (@arkts/project-detector, @ohos-rs/oxk) are bundled for each platform with pre-built binaries.

Publishing Targets

• VS Code Marketplace: Primary distribution channel
• Open VSX: Alternative distribution for open-source editors
• npm: Individual packages published to @arkts scope

Sources: packages/vscode/package.json521-528 CONTRIBUTING.md55-78

---

Development Setup

For information about setting up a development environment, building the project, and contributing code, see Contributing.

Sources: CONTRIBUTING.md1-78