Zig ⚡️ Nova

Write, build, test and debug Zig projects natively in Nova

I built this extension to bring functional Zig support to Nova, including debugging, to aid my Zig learning process. As the project is currently in an experimental stage, it may be subject to breaking changes; however, I wanted to develop in the open and share my progress. Please reach out to bugs@dcz.at with any ideas or issues you encounter.

Features

Code Editing

• Syntax highlighting for .zig and .zon files
• Code folding
• Code structure headers
• Path bar
• Symbols
• Type and function separators
• Completions ¹
• Hovers ¹
• Signature help ¹
• Issues and Warnings as you type ¹
• Compiler Issues and Warnings displayed inline upon compilation ²

Building & Testing

• Auto-discovery of build steps via zig build --list-steps ²
• Run current Zig file without build.zig or configuration ²
• Task templates for advanced configuration:
• Build arguments
• Custom -D flags and values
• Run arguments
• Cross-compile field (-Dtarget=)
• Drop-down for -Doptimize=
• Test summary options

Debugging

• Debug with the Zig Debug task template via LLDB ³
• Breakpoints
• Execution control ³
• Variable inspection ³
• Performance information ³
• Manual lldb commands ³

1: ZLS required
2: Zig required
3: Xcode Command line tools required

The extension automatically resolves zig, zls, and lldb-dap via PATH or xcrun. You can override these via global Extension Settings or Workspace Settings (for project-specific Zig versions).

Security & Trust

Auto-discovery of build steps invokes zig build --list-steps in the workspace root. That command executes the workspace’s build.zig. This is the same trust grant as typing zig build in a terminal: only enable auto-discovery in Zig workspaces you trust.

Auto-discovery is disabled by default if you install the extension for the first time. Although you can enable it globally in the extension settings, consider using a per-workspace setting.

Known Issues

• The Current Zig file and auto-discovered Zig steps cannot open Output / Report automatically due to a restriction in Nova’s API.
• The Zig Debug task pipes the program’s stdout / stderr through Nova’s debug console, which does not accept keyboard input. For programs that read stdin (TUIs, REPLs, prompts), run lldb yourself in a terminal of your choice and load the binary with (lldb) file /path/to/binary.

Please report issues to bugs@dcz.at.

Troubleshooting

ZLS isn’t working

• Confirm ZLS is enabled in the workspace or extension config
• Check if the workspace config overrides the extension config
• Confirm ZLS is installed
• Configure the path to ZLS manually
• Confirm ZLS and Zig are version-compatible
• Open .nova/Configuration.json and ensure that no lines start with zls like zls.zig_exe_path. Delete them if present
• Check the extension console for errors

Debugging isn’t working

• Ensure that the Xcode Command line tools are installed
• Configure the path to lldb-dap manually
• Run xcrun --find lldb-dap and check if it can be found
• Run which lldb-dap and check if it can be found

Build on Save (ZLS) isn’t working

• Make sure it is enabled in the workspace or extension config
• Check if the workspace config overrides the extension config
• Ensure build.zig contains the check step

License

This software is a personal project and is not endorsed by or affiliated with the Zig Software Foundation.

This software is licensed under the BSD 2-Clause “Simplified” License. Read the full license text here.

The Zig logo is the original work of the Zig Software Foundation. The Zig logo, as well as the icon assets derived from it, remain licensed under CC BY-SA 4.0.

This software contains a pre-compiled tree-sitter grammar for Zig. The source code is taken from github.com/tree-sitter-grammars/tree-sitter-zig and is distributed under the MIT License. A copy of the license is packaged alongside the binary.

0.2.5 – 2026-05-17

• Removed the Console setting (Internal Console / External Terminal) from the Zig Build and Zig Debug task templates. The External Terminal path was unreliable and a hacky workaround.
• The foreign zls.* key check no longer rewrites .nova/Configuration.json. The dialog now offers to open the file so you can delete the keys yourself. This allows the extension to drop the read-write permission down to read-only.
• Auto-discovery of build steps is now turned off globally by default as described in the new Security & Trust section of the readme.

0.2.4 – 2026-05-15

• New Build Root workspace setting under Project Settings → Zig → Tasks for projects where the build.zig file is in a subdirectory. If you leave this setting empty, the behavior remains unchanged.
• ZLS now shuts down cleanly when disabled or when the extension is restarted.
• Step discovery logs its result (found steps or failure reason) in the Extension Console.
• Executable paths that are configured but not executable now produce a clear warning instead of silently failing.
• Scans the workspace configuration for zls.* keys interfering with ZLS and offers to remove them. These keys can break ZLS because Nova forwards them always, no matter how to configure the language server.
• Lots of smaller bug fixes.
• Logging is a lot clearer now and the information logged is more useful. The logs are separated by topic (e.g. ZLS, debug, tasks), and show only info needed to understand what the extension does.
• Internal: Large extension code has been split into multiple smaller files, each containing a certain topic only.
• Internal: The whole code has been refactored to be simpler and shorter and therefore more stable.

0.2.3 – 2026-05-12

• Zig is now an optional dependency and no longer required to edit zig and zon files and configure tasks. However, it is still required for building or running tasks. The warning that the Zig executable was not found now only appears when it is actually needed.

0.2.2 – 2026-05-12

• In case zig build --list-steps fails, the extension gives up trying after a while, avoiding an infinite loop.
• Improved documentation.

0.2.1 — 2026-05-11

• Compiler errors and warnings now clear properly before each build instead of accumulating across runs.
• Fixed -D user options not being passed to zig build when set via the task configuration.
• Issue matcher split into separate patterns for errors, warnings, and notes to show the correct severity.

0.2.0 — 2026-05-10

• Zig Package is now Zig Build. The macOS Terminal variant is gone – use the new Console setting instead.
• New specialized Zig Test and Zig Watch templates.
• Every template now has fields for optimization mode, cross-compilation target, and custom -D flags.
• Build steps from build.zig show up automatically as individual tasks and refresh when you save the file.
• Zig Debug can guess the compiled program path from build.zig.zon.
• Run Step for tasks now defaults to empty, which runs zig build without specifying a step, so that Zig has to resolve the default step.
• Task settings (step discovery, current file task visibility) apply immediately without restarting Nova.
• Clean won’t touch paths outside the workspace and runs zig build uninstall first when the project has it.
• Localizations updated.

0.1.8 — 2026-05-07

• New setting to log lldb-dap traffic to a file — useful when the debug adapter misbehaves.
• ZLS errors now show up properly in the extension console if logging is enabled.
• German localization and third-party notices improved.

0.1.7 — 2026-05-07

Initial release. Syntax highlighting, ZLS, task templates, and LLDB debugging.

BSD 2-Clause

Copyright 2026 David Czihak

Redistribution and use in source and binary forms, with or without modification,
are permitted provided that the following conditions are met:

1. Redistributions of source code must retain the above copyright notice,
   this list of conditions and the following disclaimer.

2. Redistributions in binary form must reproduce the above copyright notice,
   this list of conditions and the following disclaimer in the documentation
   and / or other materials provided with the distribution.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS “AS IS” AND
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR
ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.