https://github.com/dankeboy36/vscode-arduino-api
Type-only Arduino API contract for Arduino IDE 2.x and BoardLab extensions
https://github.com/dankeboy36/vscode-arduino-api
arduino arduino-ide theia-ide vscode vscode-extension
Last synced: 7 days ago
JSON representation
Type-only Arduino API contract for Arduino IDE 2.x and BoardLab extensions
- Host: GitHub
- URL: https://github.com/dankeboy36/vscode-arduino-api
- Owner: dankeboy36
- License: mit
- Created: 2023-05-14T15:05:37.000Z (about 3 years ago)
- Default Branch: main
- Last Pushed: 2026-02-24T17:04:11.000Z (5 months ago)
- Last Synced: 2026-02-24T20:54:53.151Z (5 months ago)
- Topics: arduino, arduino-ide, theia-ide, vscode, vscode-extension
- Language: TypeScript
- Homepage: https://github.com/dankeboy36/vscode-arduino-api/blob/main/docs/interfaces/ArduinoContext.md
- Size: 515 KB
- Stars: 5
- Watchers: 4
- Forks: 0
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# vscode-arduino-api
[](https://github.com/dankeboy36/vscode-arduino-api/actions/workflows/ci.yml)
This is a types-only npm package providing the ArduinoContext API contract for Arduino IDE 2.x and BoardLab tools. The npm tarball ships no runtime JavaScript; runtime providers are supplied by the host environment.
## What this is
- A compile-time contract for the `ArduinoContext` API.
- The npm package contains no runtime JavaScript.
- The runtime provider is host-specific (IDE2 built-in or BoardLab in VS Code).
The primary, current target is Visual Studio Code with BoardLab as the runtime provider. The IDE2 lane (0.1.x) is legacy and receives compatibility-only updates.
## Runtime providers
- Visual Studio Code: provider is BoardLab (`dankeboy36.boardlab`). Tools should depend on BoardLab for runtime access.
- Arduino IDE 2.x: provider is bundled in the IDE. It does not download this extension from Open VSX or the Visual Studio Code Marketplace.
## Compatibility lanes
- BoardLab lane: `vscode-arduino-api@latest` (0.2.x+) for Visual Studio Code + BoardLab.
- IDE2 lane: `vscode-arduino-api@ide2` (0.1.x) for Arduino IDE 2.x tools ([deprecated API surface](https://github.com/dankeboy36/vscode-arduino-api/blob/0.1.2/src/api.ts)).
## Install types
This package provides only TypeScript types. Install the appropriate version depending on your target environment:
### Visual Studio Code + BoardLab tools
```shell
npm install -D vscode-arduino-api
```
BoardLab provides the runtime API in Visual Studio Code and must be present as an extension dependency.
### Arduino IDE 2.x tools (deprecated API)
```shell
npm install -D vscode-arduino-api@ide2
```
### Additional type dependencies
These peer dependencies are required for type resolution. Install them if they are not already present in your extension development setup:
```shell
npm install -D ardunno-cli boards-list @types/vscode
```
Only one provider is active at a time. Choose the provider that matches your target. If you target IDE2 only, use the IDE2 provider ID and do not include BoardLab.
## Resolve provider at runtime
```ts
import * as vscode from 'vscode'
import type { ArduinoContext } from 'vscode-arduino-api'
// Visual Studio Code + BoardLab target.
const PROVIDERS = ['dankeboy36.boardlab'] as const
// Arduino IDE 2.x target: use this instead of the BoardLab provider.
// const PROVIDERS = ['dankeboy36.vscode-arduino-api'] as const
export function tryGetArduinoContext(): ArduinoContext | undefined {
for (const id of PROVIDERS) {
const ext = vscode.extensions.getExtension(id)
const api = ext?.exports as ArduinoContext | undefined
if (api) return api
}
return undefined
}
```
## Publishing guidance
- Visual Studio Code extension: add `extensionDependencies` on `dankeboy36.boardlab`.
- This repo publishes npm types only; it does not build or publish a VSIX artifact.
## Dist-tags and releases
- IDE2 lane: publish 0.1.x patch releases and apply the `ide2` dist-tag, which always points to the latest 0.1.x version compatible with Arduino IDE 2.x.
- BoardLab lane: `latest` remains 0.2.x+.
```shell
npm dist-tag ls vscode-arduino-api
```
## API reference
See the generated API docs in [`docs/README.md`](./docs/README.md).