Autres pages › frontend-roundtrip

Autres pages

Cette page n’est pas encore traduite : voici la version anglaise.

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/grid are flex/grid divs, label a <p> (<h2>, <h1> when large or huge), button, toggle (a checkbox), slider (range), stepper (number), input, select, image, list, table, gauge/bar (<meter>), telltale (a role="status" span shown while its condition holds), if/else, for (a map, v-for, @for, {#each}). chart and custom are a <div> and a USER CODE region beside it (a note says so).
  • Bindings → state and props. A ui var the file uses is its state (useState, ref, a field, a let); a control bound to it sets it (onChange, v-model, [(ngModel)], bind:value). An element's parameters are its props; a bind parameter is a prop and its change (on<Name>Change, update:<name>, <name>Change, bind:<name>).
  • send api MSG(…) → a typed fetch. arche/api.ts has 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, :id in the path from the field of that name; API_BASE sets the server.
  • goto → navigation (navigate, router.push, navigateTo, router.navigateByUrl, goto), back → the router's back (a dialog's back closes 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.arche and 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 var each 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 undefined with 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 *ngIf by hand. Svelte: Svelte 4 syntax, which Svelte 5 still reads.
  • A dialog opened by a condition (dialog X when …) and overlays are written as components; showing them is yours.
  • The generated code is checked by the tests with tsc against small type stubs, and read back by the template readers; it is not built against the real frameworks there.