@evinvest/kitstart 0.1.0

package/template/src/shared/config/env.ts

@@ -0,0 +1,17 @@
+import "server-only";
+import { createPlaceSource, createServerEnv, leadNotifier, type LeadNotifier } from "@evinvest/kitstart/server";
+import { site } from "./site";
+
+/** Parsed once, lazily: `next build` imports this and must need no secrets. */
+export const serverEnv = createServerEnv(site);
+
+/** The live place data, when `LOCATIONS_API_URL` is set; baked otherwise. */
+export const places = createPlaceSource(site, { baseUrl: () => serverEnv().locationsApiUrl });
+
+let built: LeadNotifier | undefined;
+
+/** Built at boot (`instrumentation.ts`), so SMTP with no sender fails startup. */
+export function notifier(): LeadNotifier {
+  built ??= leadNotifier(site, serverEnv());
+  return built;
+}

package/template/src/shared/config/i18n.ts

@@ -0,0 +1,15 @@
+import { createLocaleRegistry } from "@evinvest/kitstart";
+
+/**
+ * Every language carries a prefix: a new site launches with no legacy URLs to
+ * keep. The default is what a header-less crawler is sent to.
+ */
+export const i18n = createLocaleRegistry({
+  locales: ["fr", "en"],
+  labels: { fr: "Français", en: "English" },
+  default: "fr",
+  prefixDefaultLocale: true,
+  hreflang: { fr: "fr-FR" },
+});
+
+export type Locale = (typeof i18n.locales)[number];

package/template/src/shared/config/lead.ts

@@ -0,0 +1,15 @@
+import type { LeadSchema } from "@evinvest/kitstart";
+
+export const SUBJECTS = ["standard", "deep", "other"] as const;
+export type Subject = (typeof SUBJECTS)[number];
+
+/**
+ * What the quote form asks, and the one rule worth enforcing: a lead with no
+ * way to reach the customer is not a lead. The reason is for the log only.
+ */
+export const LEAD: LeadSchema<Subject> = {
+  subjects: SUBJECTS,
+  wire: { subject: "subject", locality: "locality", mobile: "mobile" },
+  extras: [{ name: "surface_m2", max: 6 }],
+  validate: lead => (lead.mobile.replace(/\D/g, "").length < 10 ? "a mobile number" : null),
+};

package/template/src/shared/config/places.ts

@@ -0,0 +1,20 @@
+import type { Place } from "@evinvest/kitstart";
+import type { Locale } from "./i18n";
+
+/**
+ * The baked half of every place: what the site says when the live source is
+ * absent or unreachable. A service-area business has no address in its type;
+ * a storefront would be `{ kind: "storefront", address, geo, … }`.
+ */
+export const PLACES: readonly Place<Locale>[] = [
+  {
+    slug: "paris",
+    gbpName: "Brand — Paris",
+    name: { fr: "Paris", en: "Paris" },
+    presence: { kind: "service-area" },
+    serviceArea: [{ kind: "localities", names: ["Paris"] }],
+    channels: { phone: null, whatsapp: null },
+    hours: [{ days: ["Monday", "Tuesday", "Wednesday", "Thursday", "Friday"], opens: "08:00", closes: "19:00" }],
+    rating: null,
+  },
+];

package/template/src/shared/config/public.ts

@@ -0,0 +1,11 @@
+import { cardFact } from "@evinvest/kitstart";
+
+/**
+ * The brand facts a client component may know — the error boundary prints
+ * the name and the phone, and must not import the whole site config (and its
+ * places) to do it. Inlined at build from `assets/card.toml`.
+ */
+export const BRAND_PUBLIC = {
+  name: "Brand",
+  phone: cardFact("SITE_CARD_PHONE", process.env.SITE_CARD_PHONE),
+} as const;

package/template/src/shared/config/site.ts

@@ -0,0 +1,39 @@
+import { cardFact, defineSite, SERVICE_AREA_GATE, type OwnerTodo } from "@evinvest/kitstart";
+import { i18n } from "./i18n";
+import { LEAD } from "./lead";
+import { PLACES } from "./places";
+
+/**
+ * The brand as the machinery sees it — routing, the lead funnel, schema.org,
+ * analytics and mail read their facts from this one object. Placeholders the
+ * owner has not supplied are listed in `OWNER_TODO`, once, rather than found
+ * on the page.
+ */
+export const site = defineSite({
+  brand: {
+    id: "brand",
+    name: "Brand",
+    legalName: "Brand SAS",
+    email: cardFact("SITE_CARD_EMAIL", process.env.SITE_CARD_EMAIL),
+    phone: cardFact("SITE_CARD_PHONE", process.env.SITE_CARD_PHONE),
+    // `null` until the card has a `site`: noindex everywhere.
+    domain: cardFact("SITE_CARD_SITE", process.env.SITE_CARD_SITE),
+    businessType: "LocalBusiness",
+  },
+  i18n,
+  ogLocale: { fr: "fr_FR", en: "en_GB" },
+  // One place, served at the apex. A network of places is
+  // `{ kind: "subdomains", apex: "directory" }` — `<slug>.<domain>` each.
+  topology: { kind: "single", place: "paris" },
+  pages: { home: "", prices: "/prices" },
+  places: PLACES,
+  publication: SERVICE_AREA_GATE,
+  lead: LEAD,
+});
+
+export type PageKey = (typeof site.pageKeys)[number];
+
+export const OWNER_TODO: readonly OwnerTodo[] = [
+  { field: "site.brand.legalName", why: "raison sociale as registered", blocksLaunch: true },
+  { field: "assets/card.toml phone", why: "the public number", blocksLaunch: false },
+];

package/template/src/shared/ui/fonts.ts

@@ -0,0 +1,15 @@
+import localFont from "next/font/local";
+
+/**
+ * The brand's faces, served from the site itself: no request to a font CDN,
+ * and no layout shift once they load. Paths must be literals — Next reads
+ * this call statically. The shipped face is Inter, cut to the Latin range the
+ * copy uses; replace it with the brand's (and re-cut to the copy's glyphs).
+ */
+export const text = localFont({
+  src: "../../../assets/fonts/Inter-Regular.woff2",
+  weight: "400",
+  style: "normal",
+  display: "swap",
+  variable: "--font-sans",
+});

package/template/src/views/home/index.ts

@@ -0,0 +1 @@
+export { PlaceHome } from "./ui/PlaceHome";

package/template/src/views/home/ui/PlaceHome.tsx

@@ -0,0 +1,76 @@
+import { contactOf, placeGraph, type PlaceView } from "@evinvest/kitstart";
+import {
+  Button,
+  CallBar,
+  Coverage,
+  Display,
+  Faq,
+  Field,
+  FieldLabel,
+  Input,
+  JsonLd,
+  NativeSelect,
+  NativeSelectOption,
+  PHONE_INPUT_PROPS,
+  QuoteFormShell,
+  Section,
+} from "@evinvest/kitstart/react";
+import type { Copy } from "@/entities/content";
+import type { Locale } from "@/shared/config/i18n";
+import { LEAD } from "@/shared/config/lead";
+import { site } from "@/shared/config/site";
+
+/**
+ * A place's home page: the brand's own hero, the package's structural
+ * widgets, and the JSON-LD derived from the same copy. Replace the hero with
+ * the brand's sections; keep the form's field names on `site.lead.wire`.
+ */
+export function PlaceHome({ view, copy, renderedAt }: { view: PlaceView<Locale>; copy: Copy; renderedAt: number }) {
+  const { t, f } = copy;
+  const contact = contactOf(site, view.place);
+  const graph = placeGraph(site, view, "home", { placeName: f.place, title: t.pages.home.title(f), description: t.pages.home.description(f) }, new Date(renderedAt));
+  return (
+    <>
+      <JsonLd data={graph} />
+      <main>
+        <Section>
+          <Display>{t.hero.title(f)}</Display>
+          <p className="mt-4 text-lg text-ink-soft">{t.hero.lede}</p>
+        </Section>
+        <Section surface="card" id="quote-band">
+          <QuoteFormShell placeSlug={view.place.slug} locale={view.locale} renderedAt={renderedAt} honeypotLabel={t.quoteForm.honeypotLabel} className="max-w-md">
+            <p className="font-display text-2xl font-bold text-ink">{t.quoteForm.title}</p>
+            <Field className="flex flex-col gap-2">
+              <FieldLabel>{t.quoteLabels.subject}</FieldLabel>
+              <NativeSelect name={LEAD.wire.subject} size="lg" defaultValue={LEAD.subjects[0]}>
+                {LEAD.subjects.map(s => (
+                  <NativeSelectOption key={s} value={s}>
+                    {t.subjects[s]}
+                  </NativeSelectOption>
+                ))}
+              </NativeSelect>
+            </Field>
+            <Field className="flex flex-col gap-2">
+              <FieldLabel>{t.quoteLabels.locality}</FieldLabel>
+              <Input name={LEAD.wire.locality} size="lg" autoComplete="postal-code" required />
+            </Field>
+            <Field className="flex flex-col gap-2">
+              <FieldLabel>{t.quoteLabels.mobile}</FieldLabel>
+              <Input name={LEAD.wire.mobile} size="lg" {...PHONE_INPUT_PROPS} required />
+            </Field>
+            <Button type="submit" size="xl">
+              {t.quoteForm.submit}
+            </Button>
+          </QuoteFormShell>
+        </Section>
+        <Section id="areas">
+          <Coverage place={view.place} locale={view.locale} head={<Display>{t.coverageTitle}</Display>} />
+        </Section>
+        <Section>
+          <Faq items={t.faqs} />
+        </Section>
+      </main>
+      <CallBar id="callbar" label={t.contactLabel} copy={copy} phone={contact.phone} whatsapp={contact.whatsapp} quoteHref={view.href("#quote")} />
+    </>
+  );
+}

package/template/src/views/not-found/index.ts

@@ -0,0 +1 @@
+export { NotFound } from "./ui/NotFound";

package/template/src/views/not-found/server.ts

@@ -0,0 +1 @@
+export { Gone } from "./ui/Gone";

package/template/src/views/not-found/ui/Gone.tsx

@@ -0,0 +1,29 @@
+import "server-only";
+import { statusTarget } from "@evinvest/kitstart";
+import { StatusScreen } from "@evinvest/kitstart/react";
+import { copyFor } from "@/entities/content";
+import type { Locale } from "@/shared/config/i18n";
+import { site } from "@/shared/config/site";
+
+/**
+ * The 404 for a dead path the proxy recognised, rendered on the server into
+ * the response: a visitor without JavaScript and a crawler get the offer and
+ * the right place's phone, in the path's language.
+ */
+export function Gone({ locale, location }: { locale: Locale; location: string | null }) {
+  const target = statusTarget(site, { locale, location: location ?? undefined });
+  const copy = copyFor(target.locale, { place: target.place?.name[target.locale] ?? site.brand.name, phone: target.phone });
+  return (
+    <>
+      <title>{`${copy.t.notFound.title} · ${site.brand.name}`}</title>
+      <StatusScreen
+        copy={copy}
+        status={copy.t.notFound}
+        target={target}
+        locales={site.i18n.locales}
+        labels={site.i18n.labels}
+        brandName={site.brand.name}
+      />
+    </>
+  );
+}

package/template/src/views/not-found/ui/NotFound.tsx

@@ -0,0 +1,27 @@
+"use client";
+
+import { brandStatusTarget } from "@evinvest/kitstart";
+import { StatusScreen } from "@evinvest/kitstart/react";
+import { useParams } from "next/navigation";
+import { copyFor } from "@/entities/content";
+import { i18n } from "@/shared/config/i18n";
+import { BRAND_PUBLIC } from "@/shared/config/public";
+
+/**
+ * The `notFound()` boundary, for what the proxy could not foresee — a place
+ * the live source withdrew. It speaks for the brand: the site config (and its
+ * places) must not ride into every page's bundle. Every dead path the proxy
+ * does know is rendered on the server by `app/global-not-found.tsx` instead.
+ */
+export function NotFound() {
+  const params = useParams<{ locale?: string }>();
+  const locale = i18n.isLocale(params?.locale) ? params.locale : i18n.defaultLocale;
+  const target = brandStatusTarget({ locales: i18n.locales, phone: BRAND_PUBLIC.phone }, locale);
+  const copy = copyFor(locale, { place: BRAND_PUBLIC.name, phone: BRAND_PUBLIC.phone });
+  return (
+    <>
+      <title>{`${copy.t.notFound.title} · ${BRAND_PUBLIC.name}`}</title>
+      <StatusScreen copy={copy} status={copy.t.notFound} target={target} locales={i18n.locales} labels={i18n.labels} brandName={BRAND_PUBLIC.name} />
+    </>
+  );
+}

package/template/src/views/place/server.ts

@@ -0,0 +1,13 @@
+import "server-only";
+import { contactOf, type PlaceView } from "@evinvest/kitstart";
+import { copyFor, type Copy } from "@/entities/content";
+import { loadPlaceView } from "@/entities/place/server";
+import type { Locale } from "@/shared/config/i18n";
+import { site } from "@/shared/config/site";
+
+/** A place page's view and its words: the entity and the copy, composed here. */
+export async function loadPlace(params: Promise<{ locale: string; location: string }>): Promise<{ view: PlaceView<Locale>; copy: Copy; renderedAt: number }> {
+  const view = await loadPlaceView(params);
+  // The time trap's stamp: when this render (under ISR, this cache fill) happened.
+  return { view, renderedAt: Date.now(), copy: copyFor(view.locale, { place: view.place.name[view.locale], phone: contactOf(site, view.place).phone }) };
+}

package/template/src/views/server-error/index.ts

@@ -0,0 +1 @@
+export { ServerError } from "./ui/ServerError";

package/template/src/views/server-error/ui/ServerError.tsx

@@ -0,0 +1,24 @@
+"use client";
+
+import { brandStatusTarget } from "@evinvest/kitstart";
+import { StatusScreen } from "@evinvest/kitstart/react";
+import { useParams, usePathname } from "next/navigation";
+import { copyFor } from "@/entities/content";
+import { i18n } from "@/shared/config/i18n";
+import { BRAND_PUBLIC } from "@/shared/config/public";
+
+/**
+ * The 500. Client-only by Next's contract, and it imports `BRAND_PUBLIC`, not
+ * the site config: the name and the phone are all it prints, and the phone
+ * works whatever broke.
+ */
+export function ServerError() {
+  const params = useParams<{ locale?: string }>();
+  const pathname = usePathname();
+  const locale = i18n.isLocale(params?.locale) ? params.locale : i18n.defaultLocale;
+  const target = brandStatusTarget({ locales: i18n.locales, phone: BRAND_PUBLIC.phone }, locale, { retry: pathname });
+  const copy = copyFor(locale, { place: BRAND_PUBLIC.name, phone: BRAND_PUBLIC.phone });
+  return (
+    <StatusScreen copy={copy} status={copy.t.serverError} target={target} locales={i18n.locales} labels={i18n.labels} brandName={BRAND_PUBLIC.name} />
+  );
+}

package/template/steiger.config.ts

@@ -0,0 +1,26 @@
+import fsd from "@feature-sliced/steiger-plugin";
+import { defineConfig } from "steiger";
+
+// The FSD layers of the brand's `src/`. A slice exports through `index.ts`,
+// and its server half through `server.ts`.
+export default defineConfig([
+  ...fsd.configs.recommended,
+  {
+    // A skeleton has one page of each kind; a real brand's slices earn their
+    // keep. Turn this back on once there are a few.
+    rules: { "fsd/insignificant-slice": "off" },
+  },
+  {
+    // `shared/config` is read file by file on purpose: `public.ts` must reach a
+    // client boundary without `site.ts` (every place) riding along, which a
+    // barrel would not guarantee.
+    files: ["./src/shared/config/**"],
+    rules: { "fsd/public-api": "off" },
+  },
+  {
+    // The same reason for the sidestep rule, which cannot tell a layer apart:
+    // everything reaching `shared/config/<file>` would trip it. Slices above
+    // `shared` still export through `index.ts` / `server.ts`.
+    rules: { "fsd/no-public-api-sidestep": "off" },
+  },
+]);

package/template/tests/bundle_budget.txt

@@ -0,0 +1,8 @@
+# Maximum gzip bytes of first-load JavaScript on a place page
+# (`/[locale]/[location]`), checked by `kitstart-size` after `next build`
+# (and by `mkLanding`'s bundle-budget check on the Nix build).
+#
+# Measured on the untouched template: 152,780 B gz (Next 16.3.6, Turbopack),
+# about 70 KB of it react-dom and 43 KB the app-router runtime. Set from the
+# first measurement plus a few percent; raise it only in a commit that says why.
+158000

package/template/tests/contract.test.ts

@@ -0,0 +1,14 @@
+import { readFileSync } from "node:fs";
+import { describeLandingContract } from "@evinvest/kitstart/testing";
+import { TEXT } from "@/entities/content";
+import { OWNER_TODO, site } from "@/shared/config/site";
+
+// A domain in card.toml is the launch; `ownerTodo` refuses it while a
+// blocking owner fact is open.
+describeLandingContract(site, {
+  globalsCss: readFileSync("app/globals.css", "utf8"),
+  proxySource: readFileSync("proxy.ts", "utf8"),
+  root: process.cwd(),
+  text: TEXT,
+  ownerTodo: OWNER_TODO,
+});

package/template/tests/e2e/playwright.config.ts

@@ -0,0 +1,26 @@
+import { defineConfig, devices } from "@playwright/test";
+import { BREAKPOINTS } from "@evinvest/kitstart/testing/e2e";
+
+// The standalone server under test, never `next dev`. Baselines are Linux's
+// (CI's); elsewhere the pixel comparison is skipped.
+const PORT = Number(process.env["E2E_PORT"] ?? 59089);
+const linux = process.platform === "linux";
+
+export default defineConfig({
+  testDir: ".",
+  snapshotPathTemplate: "{testDir}/__screenshots__/{arg}{ext}",
+  ignoreSnapshots: !linux,
+  retries: 0,
+  expect: { toHaveScreenshot: { maxDiffPixelRatio: 0.01, animations: "disabled", stylePath: "./screenshot-section.css" } },
+  use: { baseURL: `http://localhost:${PORT}`, deviceScaleFactor: 1, colorScheme: "light", locale: "fr-FR" },
+  projects: BREAKPOINTS.map(b => ({ name: b.name, use: { ...devices["Desktop Chrome"], viewport: b.viewport } })),
+  webServer: {
+    command: "node .next/standalone/server.js",
+    cwd: "../..",
+    url: `http://localhost:${PORT}/health`,
+    reuseExistingServer: false,
+    // The prod server refuses to boot without these (instrumentation.ts); on
+    // loopback the one hop is the runner itself.
+    env: { PORT: String(PORT), HOSTNAME: "127.0.0.1", LEADS_DB_PATH: `/tmp/brand-e2e-${PORT}/leads.db`, TRUSTED_PROXY: "xff:1" },
+  },
+});

package/template/tests/e2e/screenshot-section.css

@@ -0,0 +1,5 @@
+/* The call bar rides the viewport, so it lands inside every tall section's
+ * crop at a scroll-dependent place; it is shot on its own instead. */
+#callbar {
+  display: none !important;
+}

package/template/tests/e2e/sections.spec.ts

@@ -0,0 +1,12 @@
+import { expect, test } from "@playwright/test";
+import { defineSectionSuite } from "@evinvest/kitstart/testing/e2e";
+
+// One visual baseline per section at both breakpoints; adding a section is one
+// line. Each is reached by a `#` the site links to, never by scrolling. The
+// runner is ours — the package only borrows it.
+defineSectionSuite({ test, expect }, [
+  { name: "hero", url: "/fr", selector: "main > section >> nth=0" },
+  { name: "quote", url: "/fr#quote", selector: "#quote-band" },
+  { name: "areas", url: "/fr#areas", selector: "#areas" },
+  { name: "callbar", url: "/fr", selector: "#callbar", mobileOnly: true, bare: true },
+]);

package/template/tests/e2e/tsconfig.json

@@ -0,0 +1,11 @@
+{
+  // Its own project because `@playwright/test` is not an npm dependency: the
+  // flake supplies it with the pinned browsers, and `nix run .#test` links it
+  // into tests/e2e/node_modules before checking these files.
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "plugins": []
+  },
+  "include": ["**/*.ts"],
+  "exclude": ["node_modules"]
+}

package/template/tests/empty.ts

@@ -0,0 +1 @@
+export {};

package/template/tsconfig.json

@@ -0,0 +1,23 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["dom", "dom.iterable", "ES2023"],
+    "allowJs": false,
+    "skipLibCheck": true,
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "exactOptionalPropertyTypes": true,
+    "noEmit": true,
+    "esModuleInterop": true,
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "jsx": "react-jsx",
+    "incremental": false,
+    "plugins": [{ "name": "next" }],
+    "paths": { "@/*": ["./src/*"] }
+  },
+  "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx", ".next/types/**/*.ts", ".next/dev/types/**/*.ts"],
+  "exclude": ["node_modules", "tests/e2e", "steiger.config.ts"]
+}

package/template/vitest.config.ts

@@ -0,0 +1,20 @@
+import { fileURLToPath } from "node:url";
+import { buildEnv } from "@evinvest/kitstart/next/config";
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  resolve: {
+    alias: {
+      "@": fileURLToPath(new URL("./src", import.meta.url)),
+      // The marker throws outside a React Server bundle; tests call the
+      // server modules directly, which is the point.
+      "server-only": fileURLToPath(new URL("./tests/empty.ts", import.meta.url)),
+    },
+  },
+  test: {
+    environment: "node",
+    include: ["tests/**/*.test.ts"],
+    // The facts `next.config.ts` inlines, so the site reads the card here too.
+    env: buildEnv(fileURLToPath(new URL(".", import.meta.url))),
+  },
+});