Configuration
A configuration file lets a design system say once which frameworks it ships to, where its components live and where each framework's output goes, so that every unframework build and unframework check agrees. Without one, it's easy to build four targets on your machine and seven in CI, to point outDir at a folder that holds your sources, or to misspell svelte and wonder why no Svelte output appears.
The file is unframework.config.ts, at the root of your project. The CLI reads it. The bundler plugin doesn't: in an app, the plugin takes its options in your bundler's configuration instead.
Write a config
unframework init writes this one, which names all seven targets and the default directories:
import { defineConfig } from "@uxfront/unframework/config";
export default defineConfig({
targets: ["react", "vue", "svelte", "solid", "angular", "qwik", "astro"],
srcDir: "src",
outDir: "dist",
});
defineConfig returns what you pass it. It's there for its types, so your editor flags a wrong field or an unknown target as you type. @uxfront/unframework/config imports nothing but types, so loading the config loads no compiler.
Every field is optional. A project with no config file at all takes the defaults below.
Fields
| Field | Default | What it sets |
|---|---|---|
targets | all seven | The frameworks to compile to: react, vue, svelte, solid, angular, qwik and astro, and solid@2, which is opt-in |
srcDir | src | Where the .uf.tsx and .uf.ts sources are, relative to the config's directory |
outDir | dist | Where each target's tree is written, as <outDir>/<target>, relative to the config's directory |
targetOptions | {} | Options for each target, checked against that target's schema |
typeOracle | syntactic | How props types are read across files: syntactic, or tsgo for TypeScript's own checker, which also checks directives' values |
strict | false | With true, a portability warning (UF4xxx) counts as an error in the CLI |
package.targets | targets | Which targets build --package packages. Each must also be in targets |
package.resolveFrom | the root | Where each target's packager and test toolchain are installed: one directory, or one per target, like { angular: "…" } |
vite | none | A function that returns a partial Vite config for each server the test and preview commands start, like a styling engine's plugin |
liveFonts | [] | The font families that may draw text when pixels compare live, besides the bundled Inter |
targets needs at least one name, with none repeated. srcDir and outDir can't be empty.
solid@2 compiles to Solid 2. solid means solid@1, the Solid 1.9 target, so solid and solid@1 together name one target twice. The default stays the seven targets without solid@2, since a project that builds both Solid majors needs both installed. Its tree and its package subpath are named solid2. A project that has both majors keeps Solid 2 in a directory of its own and points package.resolveFrom.solid2 there, where unframework test and unframework preview load Solid 2 for that target.
strict turns only portability warnings into errors. Info diagnostics stay as they are, so a stylesheet's UF4002 on Angular and Qwik never fails a strict build.
typeOracle: "tsgo" loads @unframework.dev/type-oracle-tsgo only when you choose it. It also checks each directive's value against the directive's type (UF6007), which the syntactic oracle doesn't. unframework build --type-oracle and unframework check --type-oracle override the field for one run.
vite and liveFonts are read by unframework test, unframework visual and unframework preview, never by build or check.
package.resolveFrom is for tools that you keep somewhere other than the project's root. It has two jobs: build --package finds each target's packager there, and unframework test and unframework preview find each target's compiler stack there, like Angular's. Our sample design system keeps the TypeScript 6 tools of Angular, Vue and Svelte in the repository's toolchains, so its config points those three targets there:
import { defineConfig } from "@uxfront/unframework/config";
export default defineConfig({
targets: ["react", "vue", "svelte", "solid", "angular", "qwik", "astro"],
package: {
// Their packagers need TypeScript 6, which the workspace keeps in the toolchains (AGENTS.md).
resolveFrom: {
angular: "../../toolchains/angular",
vue: "../../toolchains/vue",
svelte: "../../toolchains/svelte",
},
},
});
Target options
targetOptions holds an entry per target, and each target declares the options it takes with a Standard Schema. What the schema returns replaces what you wrote, so a schema can fill in defaults.
No built-in target declares options yet. A target that declares none takes none, so any key under it is an error rather than a setting nobody reads: targetOptions: { react: { compiler: true } } reports UF7004 until React declares that option.
How the file loads
The CLI looks in the directory it runs in, and loads the first of these it finds: unframework.config.ts, unframework.config.mts, unframework.config.js and unframework.config.mjs. It doesn't search the directories above.
Node loads a TypeScript config by stripping its types, so you don't need a loader. That also means the file can't use syntax that needs compiling, like an enum or a parameter property.
The config is an ES module. In a project whose package.json sets "type": "commonjs", which npm init -y writes, Node loads unframework.config.ts as CommonJS and it fails to load. Set "type": "module", or name the file unframework.config.mts. A package.json with no type works, with a warning from Node.
When it's wrong
A config that can't load, or doesn't fit the fields above, stops the command before anything compiles. build and check exit 2, and print the problem as a diagnostic:
| Code | When |
|---|---|
UF7001 | Node couldn't import the file, or it has no default export |
UF7002 | A field has the wrong shape, or isn't a field the config has |
UF7003 | A name isn't a built-in target. Where one is close, the message suggests it |
UF7004 | A target's options don't pass its schema, or the target declares no options |
UF7001 names the file. The others name the field by its JSON pointer, since the problem is in a value, not at a line. A misspelt target reads like this:
error[UF7003]: The configuration at "/targets/2" names the unknown target "svelt". Did you mean `svelte`?
--> unframework.config.ts:1:1
The decision behind this page is ADR-0076.
Semantics
The semantics contract, version 1: what every target guarantees, from setup and state to events and rendering, and the corpus case that checks each rule.
CLI
The unframework command builds every target's source tree, checks a project and prints its diagnostics, explains a diagnostic code and scaffolds a project.