wesl-plugin wesl.toml schema diverges from wesl-spec (`dependencies` array vs. table) — breaks wgsl-analyzer

[andyinabox]

Hi 👋🏻 -- human being here,

I'm starting to learn WESL/WGSL/WebGPU and running into some tooling issues on my machine. It seems like there's some divergence between the most recent wesl.toml spec and the one used by wesl-js. I'm just learning about this ecosystem so I'm having to use an LLM to troubleshoot, so apologies for the slop. Clanker-generated output below:

---

Problem

wesl-plugin reads wesl.toml with a schema that doesn't match the official wesl-spec/WeslToml.md. Two differences:

• Top-level keys: wesl-plugin reads edition, root, and include at the top level, whereas the spec nests them under a [package] section.
• dependencies: wesl-plugin (0.6.53 through the latest 0.6.75) expects an array of strings — ["random_wgsl"] or ["auto"] — whereas the spec expects a [dependencies] table, e.g. random_wgsl = {}.

Because the formats are incompatible (TOML can't express both an array and a table for the same key, and the section layout differs), a single wesl.toml cannot satisfy both wesl-plugin and wgsl-analyzer:

• Array form → builds with Vite, but wgsl-analyzer (v0.11.318) errors: Project discovery failed: ... invalid type: sequence, expected a map.
• Spec table form → wgsl-analyzer is happy, but vite build fails with [wesl-plugin] ... dep.replaceAll is not a function.

The relevant code (confirmed in 0.6.75):

const depsArray = Array.isArray(dependencies) ? dependencies : [dependencies ?? "auto"];
const sanitizedDeps = autoDeps.map((dep) => dep.replaceAll("/", "_")); // assumes string deps

What I'd like

wesl-plugin to accept the spec-compliant wesl.toml format ([package] section + [dependencies] table), ideally while still accepting the current array form for backwards compatibility, so the same manifest works across the JS tooling and wgsl-analyzer/wesl-rs.

Repro

wesl@0.7.4 + wesl-plugin@0.6.53, Vite 7, with:

edition = "unstable_2025"
include = [ "./shaders/**/*.wesl" ]
root = "./shaders"
dependencies = ["random_wgsl"]

shaders/app.wesl: import random_wgsl::pcg_2u_3f;

Companion issue filed on wgsl-analyzer for the editor-side symptom: wgsl-analyzer/wgsl-analyzer#1211.

[stefnotch]

For the top level keys, we have to update the spec.

For the dependencies, I'll let @mighdoll comment on the wesl-js implementation. In wgsl-analyzer, the current state is that import statements are currently being implemented.
Dependencies will be the next big task, though it will take a bit longer until I get around to those. (Human contributions of any kind are always appreciated!) What is your use case and what would be the minimum that would unblock you?
wgsl-analyzer/wgsl-analyzer#976

[mighdoll]

@andyinabox, thanks for catching this.

For wesl-js, the default ("auto") should work to find library dependencies via package.json automatically. The current spec's form of explicit dependencies is not yet supported. I imagine "auto" should work for most applications. One exception I expect is if you want to write an app that uses dual published npm/cargo libraries and is compiled both with wesl-rs and wesl-js. (wesl-rs probably won't support "auto" for structural reasons with cargo.)

I'll take a look at least offering a clear error message on the wesl-js side in the meantime, and please let me know if auto isn't working for you.

[andyinabox]

@mighdoll @stefnotch thanks for responding! 🙂

To clarify, I am able to get the project to build with wesl-js, but wgsl-analyzer doesn't recognize the configuration as correct so I get constant errors in Zed when I try and run the LSP.

From my perspective the immediate fix has more to do with wgsl-analyzer/wgsl-analyzer#1211 -- if there are two specs in active use it seems like the LSP should recognize both of them. Unfortunately I don't have any rust experience, so I'm not able to lend much help implementing that fix.

I created this issue because I thought the longer-term solution might be to enforce the same wesl.toml standard for wesl-rs and wesl-js.

Is the eventual goal of the project to support the spec from https://github.com/webgpu-tools/wesl-spec/blob/main/WeslToml.md in wesl-js?

[BenjaminBrienen]

There aren't two specs. There is one unstable spec that changed and wesl-js hasn't updated yet.

[mighdoll]

I'll push a fix shortly to wesl-js to drop the legacy format.

[mighdoll]

709827b drops support for the legacy wesl.toml format for dependencies.

The new wesl.toml dependencies format is allowed but ignored for now. Apps that want to dual-build wesl-rs and wesl-js with dual-published wesl libraries can list the same package in wesl.toml, cargo.toml, and package.json.

I think that's probably enough to close this issue (the spec update and wgs-analyzer implementation are separate issues). Keep 'em coming @andyinabox!

[andyinabox]

Oh wow that was fast, thanks!