odoro 1.0.9 → 2.1.0

package/templates/react-ts/src/background.tsx

@@ -0,0 +1,66 @@
+/**
+ * The decorative background of the page.
+ *
+ * ## Why it is not in `App.tsx`
+ *
+ * It is the only piece of the page that depends on what was ticked at
+ * creation: with the engine, this file is replaced by a version that opens an
+ * animated WebGL surface; without it, it is the gradient below.
+ *
+ * Keeping it apart avoids having two `App.tsx` files to maintain — one per
+ * case — which would diverge at the first change of wording. `App.tsx` places
+ * `<Background />` and asks for nothing more.
+ *
+ * ## Why the sizes are inline styles
+ *
+ * The style system **emits no arbitrary-value class**: `o-h-[42rem]` produces
+ * no rule at all, and a missing class paints nothing. The container ended up
+ * zero pixels tall, so did both glows, and the background was nowhere to be
+ * seen — with nothing to report it.
+ *
+ * The utilities cover the values on the scale; anything off the scale is
+ * written as a style, where it is safe.
+ *
+ * @module
+ */
+
+import type { ReactElement } from 'react'
+
+/** Two brand glows, heavily diluted, behind the top of the page. */
+export function Background(): ReactElement {
+  return (
+    <div
+      aria-hidden="true"
+      className="o-pointer-events-none o-absolute o-inset-x-0 o-top-0 o-overflow-hidden"
+      style={{ height: '42rem' }}
+    >
+      <div
+        className="o-absolute o-rounded-full"
+        style={{
+          left: '50%',
+          top: '-18rem',
+          width: '46rem',
+          height: '46rem',
+          transform: 'translateX(-50%)',
+          filter: 'blur(64px)',
+          opacity: 0.3,
+          background:
+            'radial-gradient(closest-side, var(--o-palette-brand-500), transparent)',
+        }}
+      />
+      <div
+        className="o-absolute o-rounded-full"
+        style={{
+          right: '-10rem',
+          top: '6rem',
+          width: '30rem',
+          height: '30rem',
+          filter: 'blur(64px)',
+          opacity: 0.18,
+          background:
+            'radial-gradient(closest-side, var(--o-palette-brand-400), transparent)',
+        }}
+      />
+    </div>
+  )
+}

package/templates/react-ts/src/entry-server.tsx

@@ -0,0 +1,85 @@
+/**
+ * The prerendering entry point.
+ *
+ * ## What it does, and why it exists
+ *
+ * `odoro build` renders each of the routes below to HTML, at build time, and
+ * writes one complete document per route. The site stays a set of static files
+ * — nothing runs in production — but a search engine, a link preview or a
+ * screen reader find text in the very first response, instead of an empty
+ * container.
+ *
+ * `src/main.tsx` then takes over: seeing a container already filled, it
+ * hydrates instead of rebuilding.
+ *
+ * ## Adding a route
+ *
+ * A single line in `routes`. The path becomes a directory in `dist/`:
+ * `/pricing` gives `dist/pricing/index.html`, which any host serves with no
+ * configuration.
+ *
+ * ## Doing without
+ *
+ * Remove `prerender` from `odoro.config.ts`. This file can then go: nothing
+ * else imports it.
+ *
+ * @module
+ */
+
+import { StrictMode } from 'react'
+import { renderToString } from 'react-dom/server'
+
+import { App } from '@/App'
+
+/** The routes rendered at build time. */
+export const routes = ['/', '/about']
+
+/** What a page brings to the head of the document. */
+const TITLES: Readonly<Record<string, { title: string; description: string }>> = {
+  '/': {
+    title: 'Odoro',
+    description: 'An Odoro project: in-house engine, generated styles, built-in router.',
+  },
+  '/about': {
+    title: 'About — Odoro',
+    description: 'What this project ships, and what each package does in it.',
+  },
+}
+
+/** Escapes what goes into an HTML attribute. */
+function escape(text: string): string {
+  return text
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+}
+
+/**
+ * Renders a route.
+ *
+ * @param url The requested path.
+ * @returns The HTML of the container, and the tags to add to the head.
+ */
+export function render(url: string): { html: string; head: string } {
+  const meta = TITLES[url] ?? TITLES['/']
+
+  const head = [
+    `<title>${escape(meta?.title ?? 'Odoro')}</title>`,
+    `<meta name="description" content="${escape(meta?.description ?? '')}">`,
+    `<meta property="og:title" content="${escape(meta?.title ?? 'Odoro')}">`,
+    `<meta property="og:description" content="${escape(meta?.description ?? '')}">`,
+  ].join('\n    ')
+
+  return {
+    // `StrictMode` is present on both sides: a tree rendered without it here
+    // and with it in the browser does not always produce the same markup, and
+    // hydration then reports a difference that is not one.
+    html: renderToString(
+      <StrictMode>
+        <App url={url} />
+      </StrictMode>,
+    ),
+    head,
+  }
+}

package/templates/react-ts/src/main.tsx

@@ -1,5 +1,5 @@
 import { StrictMode } from 'react'
-import { createRoot } from 'react-dom/client'
+import { createRoot, hydrateRoot } from 'react-dom/client'
 
 import { App } from '@/App'
 
@@ -8,11 +8,20 @@ import '@/styles.css'
 
 const container = document.getElementById('root')
 if (container === null) {
-  throw new Error('Element racine "#root" introuvable dans index.html.')
+  throw new Error('Root element "#root" not found in index.html.')
 }
 
-createRoot(container).render(
+const tree = (
   <StrictMode>
     <App />
-  </StrictMode>,
+  </StrictMode>
 )
+
+// A container that is already filled comes from prerendering: it has to be
+// **hydrated**, that is, taken over as it stands with the events attached.
+// Rebuilding it would throw away the page the visitor already sees only to draw
+// it again identically — a flicker, and the whole benefit of prerendering lost.
+//
+// Empty, it is an ordinary render.
+if (container.firstElementChild === null) createRoot(container).render(tree)
+else hydrateRoot(container, tree)

package/templates/react-ts/src/router.tsx

@@ -1,72 +1,92 @@
 /**
- * Le routeur du projet.
+ * The router of the project.
  *
- * ## Pourquoi il vit seul, dans son fichier
+ * ## Why it lives alone, in its own file
  *
- * C'est le seul endroit qui nomme la dependance de routage. Changer de routeur,
- * ajouter une route, en proteger une derriere une authentification : tout se
- * lit ici, et `App.tsx` n'a rien a en savoir au-dela de la ligne qui l'importe.
+ * This is the only place that names the routing dependency. Switching routers,
+ * adding a route, putting one behind authentication: it all reads here, and
+ * `App.tsx` needs to know nothing beyond the line that imports it.
  *
- * ## Pourquoi les pages sont passees, et non importees
+ * ## Why the pages are passed in, and not imported
  *
- * Ce fichier pourrait importer les pages depuis `App.tsx`. Les deux modules
- * s'importeraient alors l'un l'autre : cela fonctionne, mais l'ordre
- * d'evaluation devient une question a laquelle personne ne veut repondre le
- * jour ou quelque chose s'execute au chargement du module.
+ * This file could import the pages from `App.tsx`. The two modules would then
+ * import each other: that works, but evaluation order becomes a question
+ * nobody wants to answer the day something runs at module load.
  *
- * Les pages arrivent donc en proprietes. La dependance ne va que dans un sens —
- * `App.tsx` connait le routeur, le routeur ne connait que React — et la table
- * des routes reste lisible d'un coup d'oeil.
+ * So the pages arrive as properties. The dependency only goes one way —
+ * `App.tsx` knows the router, the router only knows React — and the route
+ * table stays readable at a glance.
  *
  * @module
  */
 
-import { Outlet, Route, Router, Routes } from '@odoro-cli/libs/router'
+import {
+  Outlet,
+  Route,
+  // Aliased: the component exported below is the one the application sees, and
+  // it takes the name `Router`.
+  Router as RouterProvider,
+  Routes,
+  createMemoryHistory,
+} from '@odoro-cli/libs/router'
 import type { ReactElement, ReactNode } from 'react'
 
 export { Link, useLocation } from '@odoro-cli/libs/router'
 
-/** Les pages que le routeur place. */
-export interface RouteurProps {
-  /** L'enveloppe commune : navigation, contenu, pied de page. */
-  readonly enveloppe: (contenu: ReactNode) => ReactElement
-  /** La page d'accueil. */
-  readonly accueil: ReactElement
-  /** La page « A propos ». */
-  readonly apropos: ReactElement
-  /** Ce qui s'affiche quand aucune route ne correspond. */
-  readonly introuvable: ReactElement
+/** The pages the router places. */
+export interface RouterProps {
+  /** The common shell: navigation, content, footer. */
+  readonly shell: (content: ReactNode) => ReactElement
+  /** The home page. */
+  readonly home: ReactElement
+  /** The "About" page. */
+  readonly about: ReactElement
+  /** What shows when no route matches. */
+  readonly notFound: ReactElement
+  /**
+   * The address to render, when there is no address bar.
+   *
+   * That is the case while prerendering: the page is made on the build
+   * machine, where `window` does not exist and nothing says which route is
+   * being asked for. The in-memory history takes over then.
+   *
+   * In the browser it stays absent and the router reads the real address.
+   */
+  readonly url?: string
 }
 
 /**
- * La table des routes.
+ * The route table.
  *
  * @example
- * <Routeur
- *   enveloppe={(contenu) => <Coquille>{contenu}</Coquille>}
- *   accueil={<Accueil />}
- *   apropos={<APropos />}
- *   introuvable={<Introuvable />}
+ * <Router
+ *   shell={(content) => <Shell>{content}</Shell>}
+ *   home={<Home />}
+ *   about={<About />}
+ *   notFound={<NotFound />}
  * />
  */
-export function Routeur({
-  enveloppe,
-  accueil,
-  apropos,
-  introuvable,
-}: RouteurProps): ReactElement {
+export function Router({
+  shell,
+  home,
+  about,
+  notFound,
+  url,
+}: RouterProps): ReactElement {
   return (
-    <Router>
+    <RouterProvider
+      history={url === undefined ? undefined : createMemoryHistory([url])}
+    >
       <Routes>
-        {/* `Outlet` marque l'endroit ou la page courante se rend : c'est ce
-            qui permet a la navigation et au pied de page de ne pas etre
-            remontes a chaque changement de route. */}
-        <Route path="/" element={enveloppe(<Outlet />)}>
-          <Route index element={accueil} />
-          <Route path="a-propos" element={apropos} />
-          <Route path="*" element={introuvable} />
+        {/* `Outlet` marks the place where the current page renders: that is
+            what keeps the navigation and the footer from being remounted on
+            every route change. */}
+        <Route path="/" element={shell(<Outlet />)}>
+          <Route index element={home} />
+          <Route path="about" element={about} />
+          <Route path="*" element={notFound} />
         </Route>
       </Routes>
-    </Router>
+    </RouterProvider>
   )
 }

package/templates/react-ts/src/styles.css

@@ -1,9 +1,9 @@
-/* Styles propres a l'application.
+/* Styles that belong to the application.
 
-   Tout le reste vient des jetons Odoro : surcharger une variable ci-dessous
-   retheme l'ensemble, composants de la librairie compris. La teinte de marque
-   est `--o-palette-brand-500` ; la remplacer suffit a changer la couleur de la
-   page, du signe et des boutons d'un seul coup. */
+   Everything else comes from the Odoro tokens: overriding a variable below
+   rethemes the whole thing, library components included. The brand hue is
+   `--o-palette-brand-500`; replacing it is enough to change the colour of the
+   page, of the mark and of the buttons in one go. */
 
 .app-shell {
   min-height: 100dvh;

package/templates/react-ts-server/Dockerfile

@@ -1,8 +1,8 @@
 # syntax=docker/dockerfile:1
 
-# --- Etape 1 : dependances -----------------------------------------------
-# Isolee pour que le cache de couches survive a toute modification du code :
-# seule une modification du manifeste relance l'installation.
+# --- Stage 1: dependencies -----------------------------------------------
+# Isolated so that the layer cache survives any change to the code: only a
+# change to the manifest re-runs the install.
 FROM node:22-alpine AS deps
 WORKDIR /app
 COPY package.json package-lock.json* pnpm-lock.yaml* yarn.lock* ./
@@ -14,28 +14,28 @@ RUN if [ -f pnpm-lock.yaml ]; then \
       npm ci; \
     fi
 
-# --- Etape 2 : compilation ------------------------------------------------
+# --- Stage 2: build -------------------------------------------------------
 FROM node:22-alpine AS build
 WORKDIR /app
 COPY --from=deps /app/node_modules ./node_modules
 COPY . .
 RUN npm run build
 
-# --- Etape 3 : dependances de production ----------------------------------
-# Reinstallees a part : l'image finale ne doit pas embarquer la chaine de
-# compilation, qui pese souvent plus que l'application elle-meme.
+# --- Stage 3: production dependencies -------------------------------------
+# Reinstalled separately: the final image must not carry the build chain,
+# which often weighs more than the application itself.
 FROM node:22-alpine AS runtime-deps
 WORKDIR /app
 COPY package.json package-lock.json* ./
 RUN npm ci --omit=dev || npm install --omit=dev
 
-# --- Etape 4 : image finale -----------------------------------------------
+# --- Stage 4: final image -------------------------------------------------
 FROM node:22-alpine AS runtime
 WORKDIR /app
 ENV NODE_ENV=production
 ENV PORT=3001
 
-# Un processus applicatif n'a aucune raison de tourner en root.
+# An application process has no reason to run as root.
 RUN addgroup -S odoro && adduser -S odoro -G odoro
 
 COPY --from=runtime-deps --chown=odoro:odoro /app/node_modules ./node_modules

package/templates/react-ts-server/README.md

@@ -1,16 +1,16 @@
-# Application Odoro — client et serveur
+# Odoro application — client and server
 
-Une application monopage React et une API bâtie sur `@odoro-cli/server`, dans le
-même dépôt.
+A React single-page application and an API built on `@odoro-cli/server`, in the
+same repository.
 
 ```
-client/            interface, servie par Odoro en developpement
+client/            interface, served by Odoro in development
 server/
-  src/main.ts      assemble les modules, rien d'autre
-  src/modules/     un dossier par module — commencez par `health/`
+  src/main.ts      assembles the modules, nothing else
+  src/modules/     one directory per module — start with `health/`
 ```
 
-## Demarrer
+## Getting started
 
 ```sh
 cp .env.example .env
@@ -18,30 +18,58 @@ npm install
 npm run dev
 ```
 
-Le client ecoute sur <http://localhost:5180> et transmet au serveur tout appel
-commencant par `/api`. Le navigateur ne voit donc qu'une seule origine, et
-aucune question de CORS ne se pose en developpement.
+The client listens on <http://localhost:5180> and forwards every call starting
+with `/api` to the server. The browser therefore only ever sees one origin, and
+no CORS question arises in development.
 
-## La base de donnees
+## Authentication, as a demonstration
 
-**PostgreSQL, heberge, et rien d'autre.** Il n'y a pas de base locale : l'URL
-pointe sur une base joignable par le reseau.
+The template ships a working account system: register, sign in, sign out,
+profile. Four routes under `/api/auth/`, three pages at `/sign-in`, `/register`
+and `/profile`.
+
+What it does, and how:
+
+- the password is hashed with **scrypt**, from the Node standard library — no
+  native module to compile. The cost parameters travel with the hash, so the
+  passwords already stored still verify the day the cost is raised;
+- the session lives in an **`httpOnly`** cookie: the browser sends it, no
+  script reads it. The table keeps only its fingerprint, never the identifier;
+- an unknown address and a wrong password give **the same answer**, after the
+  same delay. Telling them apart would turn the sign-in form into a way to ask
+  whether an address has an account here.
+
+What it does not do, and what you will have to add: email confirmation,
+password reset, a rate limit on sign-in attempts, a second factor. Naming them
+beats implying they are handled.
+
+It all lives in `server/src/modules/auth/` and `client/src/account.tsx`. If the
+project needs no accounts, delete those two and the `auth.module` line of
+`server/src/main.ts`.
+
+**A database is required.** Without `DATABASE_URL`, the four routes answer
+`503` saying what is missing — the interface still starts.
+
+## The database
+
+**PostgreSQL, hosted, and nothing else.** There is no local database: the URL
+points at one reachable over the network.
 
 ```sh
-odoro db:create            # provisionne une base et ecrit .env
-# ou collez votre propre URL dans .env :
-DATABASE_URL=postgres://utilisateur:motdepasse@hote:5432/base?sslmode=require
+odoro db:create            # provisions a database and writes .env
+# or paste your own URL into .env:
+DATABASE_URL=postgres://user:password@host:5432/database?sslmode=require
 ```
 
-Tant qu'elle est absente, **le client demarre quand meme** et le serveur repond
-`503` sur `/api/ready` en disant precisement ce qui manque. On voit donc
-l'interface des la premiere minute, et on sait ce qu'il reste a faire.
+While it is missing, **the client starts anyway** and the server answers `503`
+on `/api/ready` saying precisely what is absent. So you see the interface in
+the first minute, and you know what is left to do.
 
-## Ecrire un module
+## Writing a module
 
-`server/src/modules/health/` est l'exemple. Un module declare son nom, ce dont
-il a besoin, les services qu'il enregistre et les routes qu'il expose — et
-`main.ts` ne fait que dire lesquels sont actifs.
+`server/src/modules/health/` is the example. A module declares its name, what
+it needs, the services it registers and the routes it exposes — and `main.ts`
+does nothing but say which ones are active.
 
 ```ts
 export const billingModule = defineModule({
@@ -52,36 +80,60 @@ export const billingModule = defineModule({
 })
 ```
 
-Le noyau resout l'ordre de chargement depuis `requires`, detecte les cycles, et
-refuse de demarrer si une dependance manque. Activer ou desactiver un module
-tient donc en une ligne dans `main.ts`.
+The kernel resolves the load order from `requires`, detects cycles, and refuses
+to start if a dependency is missing. Enabling or disabling a module therefore
+takes one line in `main.ts`.
 
-## Deux points de controle, qui ne disent pas la meme chose
+## Two health endpoints, which do not say the same thing
 
-| Route         | Question                        | Qui l'interroge                                  |
-| ------------- | ------------------------------- | ------------------------------------------------ |
-| `/api/health` | Le processus vit-il ?           | L'orchestrateur, pour decider de redemarrer      |
-| `/api/ready`  | Le service peut-il travailler ? | Le repartiteur, pour decider d'envoyer du trafic |
+| Route         | Question                      | Who asks it                             |
+| ------------- | ----------------------------- | --------------------------------------- |
+| `/api/health` | Is the process alive?         | The orchestrator, to decide on a restart |
+| `/api/ready`  | Can the service do its work?  | The load balancer, to decide on traffic  |
 
-Les confondre donne l'un des deux defauts : un service qui redemarre en boucle
-pendant un incident de base, ou un repartiteur qui envoie du trafic a un
-service incapable de repondre.
+Confusing them gives one of two faults: a service restarting in a loop during a
+database incident, or a load balancer sending traffic to a service that cannot
+answer.
 
-## Compiler et deployer
+## Building and deploying
 
 ```sh
-npm run build      # client dans dist/client, serveur dans dist/server
-npm start          # sert les deux depuis un seul processus
+npm run build      # client into dist/client, server into dist/server
+npm start          # serves both from a single process
 ```
 
-Le `Dockerfile` est multi-etapes : les dependances de compilation ne se
-retrouvent pas dans l'image finale, qui tourne sous un utilisateur sans
-privileges.
+The `Dockerfile` is multi-stage: the build dependencies do not end up in the
+final image, which runs as an unprivileged user.
+
+## Prerendering
+
+`build.prerender` is on: every route of `client/src/entry-server.tsx` is
+rendered as a complete HTML document at build time, and the client hydrates it
+on load rather than rebuilding everything. That is what lets a search engine or
+a link preview find text in the very first response.
+
+The server serves those documents before falling back to the single-page
+document: a request for `/about` receives `dist/client/about/index.html`, with
+its own title and its own description.
+
+Adding a route: one line in `routes`, and the matching entry in
+`client/src/router.tsx`. Doing without: remove `prerender` from
+`odoro.config.ts`, then delete `client/src/entry-server.tsx`.
+
+## Environment variables
+
+See `.env.example`, commented line by line. In production, whatever is missing
+stops the startup with a message that **lists everything at once** — rather
+than a string of restarts, one variable at a time.
 
-## Variables d'environnement
+The files are read from the least specific to the most specific — `.env`,
+`.env.local`, `.env.<mode>`, `.env.<mode>.local` — and a variable already set
+in the environment is never overwritten by a file: on a host, whatever it
+injects wins.
 
-Voir `.env.example`, commente ligne par ligne. En production, ce qui manque
-arrete le demarrage avec un message qui **liste tout d'un coup** — plutot
-qu'une suite de redemarrages, une variable a la fois.
+**Only variables prefixed with `ODORO_` reach the browser.** The rest —
+`DATABASE_URL`, the session secrets, the API keys — never leaves the server.
+That is the only boundary that matters here, and it is held by the prefix, not
+by the file.
 
-`.env` n'est jamais versionne.
+`.env` is never committed.