A frontend repository and its model
A web frontend (React, Next.js, Vue, Nuxt, Angular, Svelte, SvelteKit) can be
read into an arche-lang model of its user interface: a ui { screens } in a
component Frontend (the importer). The model sits beside the
code: the repository stays the app, and nothing in it is rewritten. You add
screens, dialogs and elements in the model; archec gen writes them into the
repository as files of its own framework; archec conform --ui says where the
model and the code differ, both ways.
Round trip#
repo ──read──▶ ui.arche + .archec/frontend-map.json
▲ │ you add screens, elements
│ ▼
└──── archec gen --target ui-frontend ◀── the model
archec conform ui.arche --ui (both ways, in CI too)
The map#
.archec/frontend-map.json, beside the model, says where each thing of the
model came from (from: "Users", "element UserCard", "fn handleSave",
"message GET_users" → a file and a line of the repo) and which files archec
wrote (generated: a file → the model path it is for and the hash of what archec
wrote outside its USER CODE regions). You do not edit it. A screen or an element
in neither is new: one you added in the model.
Writing what you added: archec gen#
archec gen ui.arche --target ui-frontend # the framework the map names
archec gen ui.arche --target ui-react --diff # or name the family: ui-react, ui-vue, ui-angular, ui-svelte
archec gen ui.arche --target ui-frontend --check # exit 1 when something would be written
ui-frontend takes the framework from the map (else from the repo's
package.json). ui-react covers React and Next.js, ui-vue Vue and Nuxt,
ui-svelte Svelte and SvelteKit: which one is read from the map and the repo.
--framework next forces one. The files go into the repo the map names
(-o <repo> for another).
What each new thing becomes:
| In the model | React | Next.js | Vue | Nuxt | Angular | Svelte(Kit) |
|---|---|---|---|---|---|---|
screen Login "/login" |
<pages>/Login.tsx + a line in arche/routes.tsx |
app/login/page.tsx ('use client'), or pages/login.tsx |
src/views/Login.vue + arche/routes.ts |
pages/login.vue |
login/login.component.ts + arche/routes.ts |
src/routes/login/+page.svelte (Kit), else Login.svelte + arche/routes.ts |
element Badge(title: string) |
components/Badge.tsx, props |
the same | components/Badge.vue, defineProps |
the same | badge/badge.component.ts, @Input |
Badge.svelte, export let |
dialog Help |
a component with onClose; a screen that goto Help shows it |
emit('close') |
@Output() close |
dispatch('close') |
The pages and components go beside the ones the map traces (the folder most of
them are in), in TypeScript when the repo has a tsconfig.json, with Tailwind
classes when the repo uses Tailwind, else a class arche-<word> and an inline
style.
- Routes. With file-based routing (Next, Nuxt, SvelteKit) the page file is
the route. With a router configuration (react-router, Vue Router, Angular's
Routes, plain Svelte), archec writes one routes file (archeRoutes) that you include once in your router:createBrowserRouter([...yours, ...archeRoutes]),routes: [...yours, ...archeRoutes]. archec never edits your router file. - ui words → markup.
row/column/gridare flex/griddivs,labela<p>(<h2>,<h1>when large or huge),button,toggle(a checkbox),slider(range),stepper(number),input,select,image,list,table,gauge/bar(<meter>),telltale(arole="status"span shown while its condition holds),if/else,for(a map,v-for,@for,{#each}).chartandcustomare a<div>and a USER CODE region beside it (a note says so). - Bindings → state and props. A ui
varthe file uses is its state (useState,ref, a field, alet); a control bound to it sets it (onChange,v-model,[(ngModel)],bind:value). An element's parameters are its props; abindparameter is a prop and its change (on<Name>Change,update:<name>,<name>Change,bind:<name>). send api MSG(…)→ a typed fetch.arche/api.tshas one function per endpoint message the files send (postLogin, from"POST /api/login"), its request type from the message's fields, a GET's fields in the query string,:idin the path from the field of that name;API_BASEsets the server.goto→ navigation (navigate,router.push,navigateTo,router.navigateByUrl,goto),back→ the router's back (a dialog'sbackcloses it).fn x→ the repo's function, imported from the module the map traces it to. One that is not exported from a module (a component's method, a function only the model has) is a stub in the file, its body a USER CODE region.
Each file starts with a comment saying it is generated, and has USER CODE
regions: the imports, the body or fields, each handler (Login.row0.go.press),
the template. Written again, archec carries what you put in them. A file changed
outside its regions since archec wrote it is refused, left as it is
(move the change into a region, or make it in the model; delete the file for a
fresh one). A file of the repo archec did not write is never written, even
where a new screen would go: that is an error to settle (rename the screen, or
move the file). A file archec wrote for something the model no longer has is
said, never deleted.
Both ways: archec conform --ui#
archec conform ui.arche --ui [--src <repo>] [--json] [--junit report.xml]
The repo is read again and compared to the model through the map:
| Finding | Severity |
|---|---|
| a route the model has no screen for | error |
a screen, element, fn or endpoint message the map traces to the code, gone from it |
error |
| an endpoint whose method or path differs from its message | error |
| an endpoint the code calls that no message models | error |
| a generated file changed outside its USER CODE regions | error |
a screen or element only in the model (archec gen writes it) |
warning |
| a generated screen no route reaches (the routes file not included) | warning |
| a component of the code (not a page) no element models | warning |
| a generated file deleted | warning |
It exits 1 on an error. archec ci runs it as its conform-ui gate when the
model has a frontend map beside it.
In VS Code#
- Arche: Import Frontend Repository… picks the repo's folder and where the
model goes (a folder beside the repo by default), reads it with the same
readers, writes
ui.archeand its map, and opens the model and the coverage report. - Arche: Generate Frontend Code shows each file it would write in the diff editor (new, or changed with your regions carried), lists the refused ones, and writes after a yes. The Output (Arche) has the notes.
Limits#
- The ui's state is per file: two generated screens that use the same ui
vareach hold their own; share it through a store in a USER CODE region. - A value the model reads from elsewhere (a message's field, a part's state) is
written as
undefinedwith a note: fill it in a region. - The response of an endpoint is
unknown(the model's message is the request). - Angular: the components are standalone and use the control flow of Angular 17+
(
@if,@for); an older app needs*ngIfby hand. Svelte: Svelte 4 syntax, which Svelte 5 still reads. - A dialog opened by a condition (
dialog X when …) andoverlays are written as components; showing them is yours. - The generated code is checked by the tests with
tscagainst small type stubs, and read back by the template readers; it is not built against the real frameworks there.