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 1.0.0 release

Version 1.0.0 consolidates the native Zap 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 1.0.0 package is written to dist/zap-language-support-1.0.0.vsix. Install that file with Extensions: Install from VSIX....

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

File icon theme

The extension contributes a file icon theme named Zap File Icons. To show the Zap logo beside .zp files in the Explorer, open the Command Palette and choose Preferences: File Icon Theme, then select Zap File Icons.

VS Code does not allow an extension to silently replace the user's global file icon theme, so this selection is intentionally manual.

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
}

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/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. References, symbol rename, code actions, semantic tokens, and document symbols are not exposed until the native Zap LSP implements the corresponding protocol methods.

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 theme, 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.