Installation

Vela’s host adapter resolves typescript from your install and calls into its API. TypeScript 7 moved enough of that API to break the call. A plain typescript install today gets 7.x and a build that dies on the first file:

src/client/Panel.tsx:1:1 - error TS89000: [@vela-rbxts/rbxtsc-host] compiler-invocation-failed: Cannot read properties of undefined (reading 'Latest')

5.9.3 is what the repo pins and tests against, and 6.x also builds. No package declares a peerDependency, so your package manager will not warn you, and the error names neither TypeScript nor a version.

The rest of what Vela is developed against: Node 24 in CI, roblox-ts ^3.0.0, @rbxts/compiler-types ^3.0.0-types.0, @rbxts/types ^1.0.935, @rbxts/react ^17.3.7-ts.1, and @rbxts/services ^1.6.0.

An element Vela could not settle at compile time imports a runtime host: @rbxts/vela-runtime for React, @rbxts/vela-runtime-vide for Vide. Both ship as dependencies of vela-rbxts, and each declares its UI library as an optional peer. The host you do not emit for is one inert ModuleScript.

@rbxts/services matters beyond your own imports. The host reads { UserInputService, Workspace } from it for viewport, input mode and rem, so it must resolve in the built place. @rbxts/react-roblox mounts a React tree, and Vide mounts itself.

vela-rbxts/transformer is a separate export from the package root: the root gives you defineConfig and types, the subpath is the callable roblox-ts consumes.

The plugin entry object is also where transformer options go: file filters, a diagnostic code base, a project root. All are covered in the configuration reference.

The mirror is a build output: an edit inside .vela/src survives until the next run touches that file, with no warning when it disappears. Your editor and tsc --noEmit point at the generated tree too, but the language server still reads your real sources.

Vela walks up from each source file’s directory looking for vela.config.ts or vela.config.json, the .ts form winning when both exist. There are no .js, .mjs or .cjs variants and no package.json key.

Keep it at the project root, outside rootDir — Vela loads it with Node, so it is build tooling rather than game code. Dropped into src/, roblox-ts sweeps it up and fails the build:

src/vela.config.ts:1:30 - error TS roblox-ts: You cannot use modules directly under node_modules.

1 import { defineConfig } from "vela-rbxts";
                               ~~~~~~~~~~~~

Note that this is the opposite of the .d.ts file below, which must live inside rootDir.

One wrinkle at the root: a roblox-ts tsconfig.json includes only src, so typed ESLint reports vela.config.ts as outside the project. Widening include hands the file back to roblox-ts — use an ESLint override for that path, or the JSON form.

The extension watches vela.config.{ts,json}, evaluates every match and pushes the result over the wire — the server never reads the file itself. The .ts form goes through your project’s typescript, so the pin at the top of this page decides whether your editor resolves custom theme keys too.

The server speaks LSP over stdio and has no VS Code dependency. Add it to the project:

pnpm add -D @vela-rbxts/lsp

npm install -D @vela-rbxts/lsp

yarn add -D @vela-rbxts/lsp

bun add -d @vela-rbxts/lsp

Then point your client’s server command at it:

npx --package @vela-rbxts/lsp vela-rbxts-lsp

--package is not optional. The binary is named vela-rbxts-lsp, but the package owning it is @vela-rbxts/lsp. vela-rbxts-lsp alone is the VS Code extension id, published as a VSIX. The platform binary arrives as an optional dependency picked by os/cpu. Linux arm64 musl and Windows on ARM have no prebuilt binary on either channel and need a source build.

Nothing hands the server your config here. Passing the resolved theme is the client’s job, through initializationOptions. Skip it and the server falls back to the default theme, so every custom key reports unknown-theme-key against classes that build perfectly well.

Editor setup has the payload shape, the method that updates it after startup, and the full list of what the server does and does not implement.

Most of what Vela produces is a Roblox property or a helper instance emitted as a JSX child. The rest is an import of @rbxts/vela-runtime, one ModuleScript the whole place shares.

It resolves because roblox-ts only resolves a package whose scope directory is one of the project’s typeRoots. node_modules/@rbxts is the one every roblox-ts project lists and every Rojo template maps to ReplicatedStorage, the same route @rbxts/react takes. This is what the nodeLinker note is about: the directory has to be real for either tool to walk into it.

className is also a type error in your editor. The ambient declaration is not loading. Check that the .d.ts file exists inside src and is not named src/vela-rbxts.d.ts.

className type-checks fine. On track A, either the transformer is not running, or your roblox-ts does not expose context.addDiagnostic and is discarding every Vela warning. For the first, check that the plugins entry spells the /transformer subpath and the file ends in .tsx. The second makes broken classes look clean forever. On track B, check you ran vela build and that its header names the directory you expected.

Check the emitted file: out/ on track A, .vela/src on track B. p-4 should have become a <uipadding> child, and the className attribute should be gone. If the attribute survived, the element was skipped.

The padding values read as __VelaRem.scale(new UDim(0, 16), 0) rather than a bare new UDim(0, 16), and the file grows an import of @rbxts/vela-runtime. That is rem: 16 is the value at the base viewport, and the scaler follows the real one.