---
title: Native
description: Compile WGSL modules into a native shader library and generated integration for application-owned Metal code.
---

# Native



Use vgpu's WGSL module system with native GPU code. A build step resolves imports, validates the
selected programs, compiles a shader library, and generates the host-language integration. Your
application keeps control of the platform GPU API.

> Beta: Native tooling is available through the optional `@vgpu/native` companion. The direct Metal guides
> identify the generated APIs exercised by native tests. Those tests do not establish a complete
> release support matrix. Pin matching exact RC versions of `vgpu` and `@vgpu/native`.

## Compile once, use native code

For macOS, the build produces a self-contained Swift package containing generated Swift and a
compiled Metal library. Node.js, Tint, WGSL, and generated Metal source stay on the build machine;
the application does not run a JavaScript renderer or translate WGSL at launch.

The generated types load selected functions on your Metal device and provide the supported
packing and binding helpers. They do not create a device, command queue, pipeline, frame loop,
or view. You can use several programs with different resources and native render state.

## Keep Metal in control

| vgpu provides                                          | The application provides                                        |
| ------------------------------------------------------ | --------------------------------------------------------------- |
| WGSL import resolution and selected-program validation | Shader selection and application logic                          |
| A compiled library and typed function loading          | Metal devices, pipelines, and render state                      |
| Supported uniform packers and checked buffer bindings  | Buffer and texture allocation, data updates, and lifetimes      |
| Binding metadata and prepared internal bytes           | Command encoding, synchronization, submission, and presentation |

This boundary does not require a Swift equivalent of every TypeScript vgpu primitive. Use ordinary
Metal commands before, between, and after generated shader work. Native composition remains
available without going through another renderer abstraction.

One configuration packages all of its selected shader programs together. Use separate configurations
when shader payloads must be distributed independently; choosing fewer Swift symbols does not remove
functions from an already compiled library.

## Start with macOS

Read [macOS](/docs/native/macos) for the current workflow, then
[Render WGSL with Metal](/docs/native/macos/metal/rendering) for a complete draw.

Continue with [uniform packing](/docs/native/macos/metal/uniforms),
[buffer bindings](/docs/native/macos/metal/bindings), or
[compute dispatch](/docs/native/macos/metal/compute/dispatch). Each guide states its supported profile.

macOS and Metal are the initial target. Windows and Vulkan are future work, not available backends.


---

For a semantic overview of all documentation, see [/sitemap.md](/sitemap.md)

For an index of all available documentation, see [/llms.txt](/llms.txt)

For agent-facing discovery, including API and MCP surfaces, see [/agents.md](/agents.md)