Zap Language Support for VS Code

A VS Code extension for the Zap programming language. It provides .zp language registration, TextMate syntax highlighting, snippets, native Zap LSP integration, diagnostics, formatting, and common Zap CLI workflows.

The extension intentionally does not bundle the Zap compiler or runtime. It uses the zap executable installed on the developer machine.

Features

Snippets

Open a .zp file and type a snippet prefix such as say, let, fn, asyncfn, ifelse, forrange, try, spawn, taskjoin, return, list, map, jsonencode, readfile, httpget, resultif, or main, then press Tab or choose the completion item. Every template uses VS Code tab stops and placeholders so you can move through names, types, expressions, and block bodies quickly. Output snippets use Zap's canonical say statement.

For project-specific templates, copy examples/zap-custom.code-snippets into your project as .vscode/zap.code-snippets. You can then edit the JSON, add a project-specific scope, and create new prefixes without modifying the extension. The template includes API, async worker, test, and logging examples. The built-in catalog also covers return/control-flow statements, typed/default-argument functions, nested functions, collection literals and iteration, JSON, filesystem, environment, HTTP, and Result/Option workflows.

Stable 2.2.9 release

Version 2.2.9 adds Rename Symbol through the native Zap LSP, complete highlighting and fallback completion coverage for all 64 canonical stable stdlib builtins, and general user-defined function-call highlighting. It retains the visible non-destructive Z badge, native LSP integration, canonical say syntax, expanded built-in snippets, project custom snippets, formatting, diagnostics, quick fixes, workspace commands, and restart/recovery support. The extension does not bundle the Zap compiler or runtime; install the matching Zap CLI separately.

Requirements

The extension requires:

1. Visual Studio Code 1.85 or newer.
2. The Zap CLI installed and available as zap on PATH, or an explicit path configured through zap.executable.
3. A Zap project with zap.toml when using workspace-level check, build, or test commands.

A standalone .zp file can still use syntax highlighting and LSP features. Workspace diagnostics that require project metadata are skipped until a zap.toml file is present.

Installation

Install from a VSIX

Download the latest .vsix file from the repository, then open VS Code and run Extensions: Install from VSIX.... After installation, run Developer: Reload Window if the language mode or icon does not appear immediately.

Build and install from source

git clone https://github.com/hidecard/zap-vscode-extension.git
cd zap-vscode-extension
npm ci
npm test
npm run package

The stable 2.2.9 package is written to dist/zap-language-support-2.2.9.vsix. Install that file with Extensions: Install from VSIX....

For development, use Developer: Install Extension from Location... and select the extension directory.

File icon behavior

The extension uses icons/zap-logo.png as its own marketplace and Extensions view icon. It intentionally does not register a global VS Code file icon theme. Instead, it shows a configurable Z badge and tooltip on .zp files through the file decoration API. This keeps the active icon theme unchanged, so icons supplied by other extensions continue to work while Zap files remain visibly identifiable.

The badge is enabled by default and can be disabled with zap.showFileBadge. VS Code file icon themes are global selections rather than additive contributions: selecting a small theme that only defines .zp can make unrelated file icons disappear. If you require a custom image beside .zp, use a complete icon theme that supports the desired associations; the Zap extension itself will not replace that choice.

Zap project setup

Workspace commands expect the workspace root to contain a zap.toml file. A minimal project manifest is:

[package]
name = "hello-zap"
version = "0.1.0"
main = "main.zp"

A matching main.zp file can contain:

let name: text = "Zap"
let port: number = 8080
let enabled: bool = true

say name
say port
say enabled

Zap blocks use indentation:

fn greet(name: text = "World") -> text:
    return "Hello, " + name

if enabled:
    say greet(name)
else:
    say "Disabled"

The Zap language uses .zp source files. Common language constructs include let, typed annotations, fn, if/else, for, while, async/await, spawn, task_join, task_is_ready, say, class, module, import, try/catch, raise, lists, maps, and Result/Option values. See the Zap syntax guide and async LSP guide for the complete language and editor reference.

Commands

The following commands are available from the Command Palette:

The Run command uses the integrated terminal by default. Disable zap.runInTerminal to send command output to the Zap Output channel instead.

Settings

{
  "zap.executable": "zap",
  "zap.enableLsp": true,
  "zap.enableDiagnostics": true,
  "zap.diagnosticDelay": 350,
  "zap.runInTerminal": true,
  "zap.formatOnSave": false,
  "zap.lspRequestTimeout": 10000,
  "zap.showFileBadge": true
}

LSP integration

The extension starts zap lsp as a stdio JSON-RPC server and synchronizes opened, changed, and closed .zp documents. It currently uses the following LSP capabilities:

• initialize and graceful shutdown.
• textDocument/didOpen, didChange, and didClose.
• textDocument/completion.
• textDocument/signatureHelp.
• textDocument/hover.
• textDocument/definition.
• textDocument/rename.
• textDocument/formatting.
• workspace/symbol.
• textDocument/publishDiagnostics.

The extension also provides a manual Zap: Restart Language Server command and request timeouts so a stalled native server does not leave completion or hover requests pending. Rename Symbol is available through the native Zap LSP. References, code actions, semantic tokens, and document symbols are not exposed until the corresponding protocol methods are implemented.

Development and validation

Install dependencies and run the extension checks:

npm ci
npm test
npm run package

The validation script checks the package manifest, icon-safety policy, grammar, snippets, extension JavaScript, and LSP integration. The packaging script uses the official VS Code extension packager and writes a real .vsix package under dist/.

Repository links

• Zap language repository
• Zap VS Code extension repository
• Zap syntax guide
• Zap LSP implementation

License

This extension is distributed under the MIT License. See LICENSE.