Velareference

Configuration

How vela.config.ts is found and loaded, the complete theme schema, the built-in defaults, and the tsconfig plugin options.

Vela reads one optional config file. It sets the theme, whether preflight resets Roblox’s default styling, and which UI framework to emit for. Everything else, such as which files to compile and where output goes, comes from tsconfig.json.

Discovery

Vela looks for vela.config.ts or vela.config.json. No other names work: no .js, .mjs, .cjs, .mts, or package.json key. If a directory has both, the .ts file wins.

Vela walks up from each source file and uses the first config it finds, or defaultConfig if there is none. A config in a subdirectory overrides the root one for the files below it. That is usually a mistake.

A vela.css is found by its own upward walk and applied on top of whichever config was found.

The JSON form takes the same shape as defineConfig’s argument. Add $schema for editor validation. Vela strips it before parsing.

vela.config.json
{
"$schema": "./node_modules/vela-rbxts/schema.json",
"theme": {
"extend": {
"colors": { "brand": { "500": "Color3.fromRGB(99, 102, 241)" } }
}
}
}

Each config is loaded once per build and re-read when it changes. A config that throws is reported once, and your next edit clears it.

How the TypeScript form is loaded

Vela runs the file itself instead of passing it to roblox-ts. That has three effects:

  • The file is not type-checked. A type error passes silently.
  • Imports resolve relative to the config file, not through tsconfig.json paths.
  • The default export must be a resolved config or a defineConfig input. Anything else throws, naming the key that failed.

Every import from vela-rbxts is stripped, and defineConfig and defaultConfig are injected in its place. Those two are the only vela-rbxts exports a config can use. The file runs as real code, so keep it cheap.

vela.config.ts
import { defineConfig } from "vela-rbxts";
export default defineConfig({
theme: {
extend: {
colors: {
brand: {
500: "Color3.fromRGB(99, 102, 241)",
700: "Color3.fromRGB(67, 56, 202)",
},
},
},
},
});

vela.css

Write tokens, utility classes and attribute variants as CSS in a vela.css file. Put it beside the config file, or use it with no config file at all:

vela.css
@import "./tokens.css";
@theme {
--color-brand-500: #3b82f6;
--color-ink: rgb(17 17 17);
--spacing-gutter: 20px;
--radius-card: 12px;
--radius-pill: 50%;
--breakpoint-tv: 1920px;
--font-display: rbxasset://fonts/families/Gotham.json;
}
@custom-variant selected (Selected = true);
.btn { @apply bg-brand-500 rounded-card px-4; }
.panel { BackgroundTransparency: 0.5; ZIndex: 2; }

You write values in CSS units. Vela converts them into theme expressions:

WrittenBecomes
--color-brand-500: #3b82f6colors.brand.500 = Color3.fromRGB(59, 130, 246)
--color-ink: rgb(17 17 17)colors.ink = Color3.fromRGB(17, 17, 17)
--spacing-gutter: 20pxspacing.gutter = new UDim(0, 20)
--radius-pill: 50%radius.pill = new UDim(0.5, 0)
--breakpoint-tv: 1920pxscreens.tv = 1920
--font-display: rbxasset://…fontFamily.display, as written

Every token goes under theme.extend, so a stylesheet never replaces a scale. The other rules map onto plugin features:

  • .name { @apply … } registers a class-list utility, like addUtilities.
  • .name { Property: value; } registers a property map. Values are roblox-ts expressions.
  • @custom-variant selected (Selected = true); registers an attribute variant, like addVariant.
  • @import "./tokens.css"; pulls in a sibling stylesheet as a preset. The importing file wins on conflicts.

When a project has both files, the stylesheet wins: a token defined in both takes the CSS value. The compiler and the editor treat a CSS class the same as a plugin class.

Roblox has no cascade, selectors or inheritance, so neither does vela.css. Any diagnostic fails the config:

".card > .title" is not a supported selector. Vela has no cascade, so a rule names one class, as ".btn".
".btn:hover" is not a supported selector. Vela has no cascade, so a rule names one class, as ".btn".
"@media" is not supported. Vela CSS understands "@theme", "@custom-variant", "@import".
"display" is a CSS property, and vela styles Roblox instances. Use a layout utility such as `flex`.
"hotpink" is not a color. Write a hex literal, "rgb(r g b)", or a Color3 expression.
The rem scale is not a token; set `theme.rem` in `vela.config.ts`.

Use hover: on the class instead of :hover, and theme.screens instead of @media. Set theme.rem in the config file.

Schema

The config has five optional keys: preflight, theme, plugins, framework and presets. Tailwind options such as content, darkMode, prefix, important, corePlugins, safelist and variants do not exist and are ignored.

PropTypeDescription
presetsreadonly (TailwindConfigInput | TailwindConfig)[]Shareable configs applied before this one, in array order. This config always wins. See Presets below.
framework"react" | "vide"The UI library to emit for. Default react. Left unset, it is inferred from tsconfig.json.
preflightbooleanDefault true. Resets Roblox's default background and border on every supported element with a className. Set false to only add what your classes name.
theme.colorsRecord<string, string | Partial<Record<Shade | "DEFAULT", string>>>Replaces the whole color registry. A value is a roblox-ts expression string, or a map from shade (50…950, plus an optional DEFAULT) to one.
theme.radiusRecord<string, string>Replaces the whole radius scale. Each value is a roblox-ts expression producing a UDim.
theme.spacingRecord<string, string>Replaces the whole spacing scale. Each value is a roblox-ts expression producing a UDim.
theme.fontFamilyRecord<string, string>Replaces the whole font family scale. Each value is a rbxasset:// font JSON or an uploaded rbxassetid://. The keys are what font-{family} looks up.
theme.screensRecord<string, number>Replaces the breakpoint scale, in pixels of viewport width. Defaults: sm 640, md 768, lg 1024, xl 1280, 2xl 1536. Each key gives a min-width prefix and its max- complement.
theme.rem{ base?: number; min?: number; max?: number; baseResolution?: { x: number; y: number }; pinnedUnder?: string[] }How one rem resolves against the viewport. Defaults: base 16, min 8, max 64, baseResolution 1920×1020, pinnedUnder ["surfacegui", "billboardgui"]. Merges field by field, except pinnedUnder, which replaces.
pluginsVelaPlugin[] | { utilities, motion }Register your own utility classes and variants, or replace the motion driver. In vela.config.json, write the resolved object form.
theme.extend.colorsRecord<string, string | Partial<Record<Shade | "DEFAULT", string>>>Merges over the default colors, per family and, when both sides are palettes, per shade. Set DEFAULT on a family so a bare bg-brand resolves.
theme.extend.radiusRecord<string, string>Merges over the default radius scale by key.
theme.extend.spacingRecord<string, string>Merges over the default spacing scale by key.
theme.extend.fontFamilyRecord<string, string>Merges over the default font family scale by key.
theme.extend.screensRecord<string, number>Merges over the default breakpoints by key, so a new name joins sm…2xl.
theme.extend.rem{ base?: number; min?: number; max?: number; baseResolution?: { x: number; y: number } }Same as theme.rem. Both merge field by field.

Valid shades are 50 through 950, plus DEFAULT, which a bare name such as bg-brand resolves to. Built-in palettes set DEFAULT to their 500. DEFAULT is a config key only: bg-brand-DEFAULT reports unknown-theme-key.

An empty palette object throws Color palette normalization requires at least one shade value. That applies to a new family, or any family under a top-level theme.colors. Extending an existing palette with {}, as in theme.extend.colors: { blue: {} }, throws nothing and does nothing.

framework

The UI library to emit for: "react" (default) or "vide". It decides which runtime host the output imports, and the shape of the emitted code.

vela.config.ts
export default defineConfig({ framework: "vide" });

Most projects leave it unset. Vela then reads compilerOptions.jsxFactory from the nearest tsconfig.json, following relative extends up to eight levels. A factory starting with Vide. selects Vide. Setting the key to either value turns inference off, so framework: "react" pins React even under a Vide jsxFactory.

The Vide guide shows how the output differs.

preflight

Default true. Roblox draws every GuiObject as an opaque gray box with a 1px border. With preflight on, a supported element with a className starts at BackgroundTransparency = 1 and BorderSizePixel = 0:

<frame className="w-20 h-10" />
// → <frame Size={UDim2.fromOffset(80, 40)} BorderSizePixel={0} BackgroundTransparency={1} />
<frame className="w-20 h-10 bg-slate-800" />
// → <frame BackgroundColor3={Color3.fromRGB(29, 41, 61)} Size={UDim2.fromOffset(80, 40)} BorderSizePixel={0} />

The transparency is skipped when something else paints the element: a bg-*, a gradient stop, or your own transparency prop. BorderSizePixel is skipped if you set it. opacity-* alone does not count, so w-20 opacity-50 stays transparent. A bg-* under a variant paints the element at runtime.

Elements without a className, and components, are never touched.

Set it to false and Vela only adds the properties your classes name. The gray default shows wherever you do not paint over it:

vela.config.ts
export default defineConfig({ preflight: false });

Values are roblox-ts expression strings

Every theme value is a string of roblox-ts code, which Vela pastes into its output. It is not a hex string or a number:

vela.config.ts
export default defineConfig({
theme: {
extend: {
colors: { ink: "Color3.fromRGB(17, 17, 17)" },
radius: { pill: "new UDim(0.5, 0)" },
spacing: { gutter: "new UDim(0, 20)" },
},
},
});

4 is rejected when the config loads. "#111111" is accepted, then emitted as a string literal, which fails roblox-ts type checking on the next build. The theming guide compares the shapes.

Merge semantics

A top-level theme.radius, theme.spacing or theme.fontFamily replaces the whole scale. The theme.extend version merges over the defaults by key.

For colors, extend merges per family, and per shade when both sides are palettes. A literal and a palette replace each other.

The default theme

defaultConfig holds the built-in defaults. You get it when no config file is found.

Colors

Twenty-eight families. black and white are literals. The other twenty-six are palettes with all eleven shades (50 through 950), each with a DEFAULT equal to its 500:

slate, gray, zinc, neutral, stone, red, orange, amber, yellow, lime, green, emerald, teal, cyan, sky, blue, indigo, violet, purple, fuchsia, pink, rose, mauve, olive, mist, taupe.

The first twenty-two match Tailwind. mauve, olive, mist and taupe are Vela additions.

Radius

Ten named keys, plus a DEFAULT for bare rounded. There is no numeric fallback, so these are all the keys until you extend them.

KeyValue
DEFAULTnew UDim(0, 4)
nonenew UDim(0, 0)
xsnew UDim(0, 2)
smnew UDim(0, 4)
mdnew UDim(0, 6)
lgnew UDim(0, 8)
xlnew UDim(0, 12)
2xlnew UDim(0, 16)
3xlnew UDim(0, 24)
4xlnew UDim(0, 32)
fullnew UDim(0.5, 0)

Spacing

One key: "4", which is new UDim(0, 16).

Every other number comes from an arithmetic rule: any non-negative multiple of 0.5 becomes new UDim(0, key * 4). So p-2 is 8px. A negative number, a finer fraction or a word reports unknown-theme-key. See spacing values.

Use theme.extend.spacing for named tokens such as p-gutter.

fontFamily

Three keys. sans is the default when no font-{family} is set.

KeyValue
sansrbxasset://fonts/families/SourceSansPro.json
serifrbxasset://fonts/families/Merriweather.json
monorbxasset://fonts/families/RobotoMono.json

Any Roblox font family works, including one you uploaded:

vela.config.ts
export default defineConfig({
theme: {
extend: {
fontFamily: {
display: "rbxassetid://12345678",
body: "rbxasset://fonts/families/Nunito.json",
},
},
},
});

That gives font-display and font-body. Unlike other theme values, these are asset paths, not roblox-ts expressions. They go into Font’s first argument as written.

screens

The viewport widths, in pixels, that the responsive variants use.

KeyDefault
sm640
md768
lg1024
xl1280
2xl1536

Each key gives two prefixes, a minimum width and its max- complement:

vela.config.ts
export default defineConfig({
theme: { extend: { screens: { tablet: 900 } } },
});

That defines tablet: (≥ 900) and max-tablet: (< 900). A top-level theme.screens removes sm through 2xl, so any class still using one reports unknown-breakpoint.

rem

How many pixels one rem is worth. Every pixel offset a utility lowers is measured in rem. See the theming guide.

KeyDefaultWhat it is
base16Pixels per rem at baseResolution
min8Lower clamp, in pixels
max64Upper clamp, in pixels
baseResolution{ x: 1920, y: 1020 }The viewport base is calibrated against
pinnedUnder["surfacegui", "billboardgui"]Containers whose subtree keeps literal pixels
vela.config.ts
export default defineConfig({
theme: {
rem: { base: 16, min: 8, max: 64, baseResolution: { x: 1920, y: 1020 } },
},
});

theme.rem and theme.extend.rem do the same thing: they merge field by field. pinnedUnder is the exception. It replaces, and an empty list puts both containers back on the rem curve.

Elements written under a surfacegui or billboardgui in your JSX keep literal pixels, because those containers size from their part, not the viewport. A container Vela never sees is not covered. For that case, pin rem with rem: { min: 16, max: 16 }. An inverted clamp collapses onto min.

Plugins

A plugin is a function that registers utilities, variants or a motion driver. Wrap it in plugin() from @vela-rbxts/config, with an optional name:

vela.config.ts
import { defineConfig, plugin } from "@vela-rbxts/config";
export default defineConfig({
plugins: [
plugin(({ addUtilities, theme }) => {
addUtilities({
btn: "bg-blue-600 rounded-lg px-4 py-2",
panel: { BorderSizePixel: "0", BackgroundColor3: theme("colors.zinc.950") },
});
}, { name: "acme" }),
],
});

Plugins run when the config resolves, not per file. The compiler, the runtime host and the editor all see the same result.

addUtilities

A utility is either a class list or a Roblox property map.

FormExampleMeaning
Class listbtn: "bg-blue-600 rounded-lg px-4"Expands to those utilities
Property mappanel: { BorderSizePixel: "0" }Assigns those properties directly

Property-map values are roblox-ts expression strings, like theme values.

A registered utility:

  • Takes variants: hover:btn applies everything btn expands to on hover.
  • Works in dynamic className values.
  • Can use another: "btn-lg": "btn text-lg" expands btn too.
  • Sorts before plain utilities, so a bg-* beside it wins. className="btn bg-rose-600" is rose in either order.

addVariant

Registers a variant that matches a Roblox attribute on the styled instance:

vela.config.ts
plugin(({ addVariant }) => {
addVariant("open", { attribute: "State", equals: "open" });
addVariant("premium", { attribute: "Tier", equals: 3 });
});

open: then applies while instance:GetAttribute("State") is "open". equals takes a string, number or boolean. attr-[State=open]: writes the same condition inline. Both combine with every other variant and work in the editor.

A registered variant also works through a marker. group-open: matches while the nearest group ancestor has the attribute. peer-open: matches while any marked sibling does.

group, peer, and any name starting with group- or peer- are reserved. addVariant rejects them, and vela.config.json reports invalid-custom-variant.

theme()

theme("colors.blue.600") returns the roblox-ts expression string for that key in the resolved theme, with defaults and extend applied. A second argument is the fallback when the path is missing.

Motion driver

setMotionDriver replaces TweenService for transition and animate-*:

vela.config.ts
plugin(({ setMotionDriver }) => {
setMotionDriver({ module: "@acme/springs", export: "driver" });
});

The runtime host imports the module and calls its transition and animate methods. Each is optional: a driver with only transition leaves animate-* on TweenService. Omit export to use the module’s default export.

Write them as methods, not arrow-function properties. roblox-ts compiles the two differently, and the arrow form is a type error:

@acme/springs
export const driver = {
transition(instance: Instance, goal: object, spec: { time: number }) { … },
animate(instance: Instance, preset: string) { … },
};

Tweens on UICorner, UIStroke and UIShadow pass a fourth argument naming the helper. Tweens on a margin wrapper pass { owner, marginBox: true }. A three-argument driver still works.

Every transformed module that needs the driver imports it. So the module must be a package name or a path relative to your baseUrl. A ./ path is rejected at load:

plugins.motion set the motion driver module to "./driver". A relative path cannot resolve
from every module that imports the driver; use a package name or a baseUrl-relative path.

The JSON form

vela.config.json cannot hold functions, so you write the object that plugins would produce:

vela.config.json
{
"plugins": {
"utilities": {
"btn": "bg-blue-600 rounded-lg px-4 py-2",
"panel": { "BorderSizePixel": "0" }
},
"motion": { "module": "@acme/springs" }
}
}

You lose theme() and any logic, but no features.

Presets

A preset is a shareable piece of config: a design system’s theme, plugins, utilities and variants, added in one line.

vela.config.ts
import { defineConfig } from "vela-rbxts";
import { gameUiPreset } from "@acme/game-ui/vela";
export default defineConfig({
presets: [gameUiPreset()],
theme: { extend: { colors: { brand: { 500: "Color3.fromRGB(99, 102, 241)" } } } },
});

Presets apply after the built-in defaults and before your config, in array order. They merge as inputs, so a preset that replaces theme.radius can still be extended by your theme.extend.radius.

definePreset() types a preset without resolving it:

@acme/game-ui/vela.ts
import { definePreset } from "@vela-rbxts/config";
export const gameUiPreset = () =>
definePreset({
theme: { extend: { screens: { tablet: 900 } } },
});

A vela.config.json can inline a preset object but cannot import one from a package.

tsconfig plugin options

Options go on the plugin entry in tsconfig.json. These are the keys you can write in JSON.

PropTypeDescription
filter.skipNodeModulesbooleanDefault true. Skip any file whose path contains a node_modules segment.
filter.requireClassNamebooleanDefault true. Skip any file whose source text does not contain the substring className.
filter.requireJsxSyntaxbooleanDefault true. Skip any file whose source text does not match an opening-JSX-tag pattern.
diagnosticCodeBasenumberDefault 89000. The first numeric diagnostic code; each diagnostic in a file gets base + index.
projectRootstringDefaults to the program's current directory. Has no effect: config discovery walks up from each file.
configTailwindConfigA resolved config used for every file. It overrides the discovered config, but discovery still runs and can still fail the build.
tsconfig.json
{
"compilerOptions": {
"plugins": [
{
"transform": "vela-rbxts/transformer",
"filter": { "skipNodeModules": true },
"diagnosticCodeBase": 89000
}
]
}
}

File eligibility

Vela transforms a file only if it passes all five checks, in this order:

  1. The name ends in .tsx (any case). A .ts file is never transformed.
  2. It is not a declaration file (.d.ts or .d.tsx).
  3. Its path has no node_modules segment, unless filter.skipNodeModules is off.
  4. Its text contains className, unless filter.requireClassName is off.
  5. Its text contains an opening JSX tag, unless filter.requireJsxSyntax is off.

There are no globs. The three filter options are the only controls. Checks 4 and 5 are plain text scans, so className in a comment is enough to pass.

See also

  • Theming for a working walkthrough of extending the theme.
  • Utility reference for the classes that read these theme keys.
  • API for defineConfig and defaultConfig.