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.
{ "$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.jsonpaths. - The default export must be a resolved config or a
defineConfiginput. 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.
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:
@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:
| Written | Becomes |
|---|---|
--color-brand-500: #3b82f6 | colors.brand.500 = Color3.fromRGB(59, 130, 246) |
--color-ink: rgb(17 17 17) | colors.ink = Color3.fromRGB(17, 17, 17) |
--spacing-gutter: 20px | spacing.gutter = new UDim(0, 20) |
--radius-pill: 50% | radius.pill = new UDim(0.5, 0) |
--breakpoint-tv: 1920px | screens.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, likeaddUtilities..name { Property: value; }registers a property map. Values are roblox-ts expressions.@custom-variant selected (Selected = true);registers an attribute variant, likeaddVariant.@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.
After you edit vela.css or a file it imports, unchanged source files keep the old tokens until they are saved again. Restart the watcher, or use vela watch, which follows stylesheets.
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.
| Prop | Type | Description |
|---|---|---|
| presets | readonly (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. |
| preflight | boolean | Default 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.colors | Record<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.radius | Record<string, string> | Replaces the whole radius scale. Each value is a roblox-ts expression producing a UDim. |
| theme.spacing | Record<string, string> | Replaces the whole spacing scale. Each value is a roblox-ts expression producing a UDim. |
| theme.fontFamily | Record<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.screens | Record<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. |
| plugins | VelaPlugin[] | { 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.colors | Record<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.radius | Record<string, string> | Merges over the default radius scale by key. |
| theme.extend.spacing | Record<string, string> | Merges over the default spacing scale by key. |
| theme.extend.fontFamily | Record<string, string> | Merges over the default font family scale by key. |
| theme.extend.screens | Record<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.
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:
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:
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.
A class resolved at runtime accepts only Color3.fromRGB(r, g, b) and new UDim(a, b) with numeric arguments. Any other value compiles, then silently degrades at runtime with no diagnostic.
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.
If theme.colors is set, theme.extend.colors is ignored without warning, and the built-in palettes go with it. The same holds for radius, spacing and fontFamily, so add values with extend alone.
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.
| Key | Value |
|---|---|
DEFAULT | new UDim(0, 4) |
none | new UDim(0, 0) |
xs | new UDim(0, 2) |
sm | new UDim(0, 4) |
md | new UDim(0, 6) |
lg | new UDim(0, 8) |
xl | new UDim(0, 12) |
2xl | new UDim(0, 16) |
3xl | new UDim(0, 24) |
4xl | new UDim(0, 32) |
full | new 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.
| Key | Value |
|---|---|
sans | rbxasset://fonts/families/SourceSansPro.json |
serif | rbxasset://fonts/families/Merriweather.json |
mono | rbxasset://fonts/families/RobotoMono.json |
Any Roblox font family works, including one you uploaded:
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.
| Key | Default |
|---|---|
sm | 640 |
md | 768 |
lg | 1024 |
xl | 1280 |
2xl | 1536 |
Each key gives two prefixes, a minimum width and its max- complement:
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.
| Key | Default | What it is |
|---|---|---|
base | 16 | Pixels per rem at baseResolution |
min | 8 | Lower clamp, in pixels |
max | 64 | Upper clamp, in pixels |
baseResolution | { x: 1920, y: 1020 } | The viewport base is calibrated against |
pinnedUnder | ["surfacegui", "billboardgui"] | Containers whose subtree keeps literal pixels |
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:
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.
| Form | Example | Meaning |
|---|---|---|
| Class list | btn: "bg-blue-600 rounded-lg px-4" | Expands to those utilities |
| Property map | panel: { BorderSizePixel: "0" } | Assigns those properties directly |
Property-map values are roblox-ts expression strings, like theme values.
A registered utility:
- Takes variants:
hover:btnapplies everythingbtnexpands to on hover. - Works in dynamic
classNamevalues. - Can use another:
"btn-lg": "btn text-lg"expandsbtntoo. - Sorts before plain utilities, so a
bg-*beside it wins.className="btn bg-rose-600"is rose in either order.
A utility that refers back to itself, such as { a: "b", b: "a" }, applies none of its classes and reports nothing. If a plugin utility does nothing, check for a cycle.
addVariant
Registers a variant that matches a Roblox attribute on the styled instance:
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-*:
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:
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 resolvefrom 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:
{ "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.
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:
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.
| Prop | Type | Description |
|---|---|---|
| filter.skipNodeModules | boolean | Default true. Skip any file whose path contains a node_modules segment. |
| filter.requireClassName | boolean | Default true. Skip any file whose source text does not contain the substring className. |
| filter.requireJsxSyntax | boolean | Default true. Skip any file whose source text does not match an opening-JSX-tag pattern. |
| diagnosticCodeBase | number | Default 89000. The first numeric diagnostic code; each diagnostic in a file gets base + index. |
| projectRoot | string | Defaults to the program's current directory. Has no effect: config discovery walks up from each file. |
| config | TailwindConfig | A resolved config used for every file. It overrides the discovered config, but discovery still runs and can still fail the build. |
{ "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:
- The name ends in
.tsx(any case). A.tsfile is never transformed. - It is not a declaration file (
.d.tsor.d.tsx). - Its path has no
node_modulessegment, unlessfilter.skipNodeModulesis off. - Its text contains
className, unlessfilter.requireClassNameis off. - Its text contains an opening JSX tag, unless
filter.requireJsxSyntaxis 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
defineConfiganddefaultConfig.