@smi-digital/create-smi-app 2.14.1 → 2.15.0

package/templates/integrations/strapi-astro/docs/performance.md.template

@@ -0,0 +1,191 @@
+# Performance rules — the card
+
+Every rule for an SMI website project (Astro + Strapi), one line each. **This is the
+file to read at the start of a session and keep in context.** The reasoning, the
+failure modes and the worked examples live in
+**[PERFORMANCE-WHY.md](./PERFORMANCE-WHY.md)** — go there when a rule bites, when you
+want to argue with one, or when a case is not literally covered. Numbers match in both
+directions: rule 5.6 here is rule 5.6 there.
+
+Ordered by **decision point** — the question you are actually facing.
+
+Tags mark where a rule is meant to be caught: `[scaffold]` `[web-kit]` `[eslint]`
+`[ci]` `[review]`. `[review]` means nothing enforces it but a human noticing.
+
+**If you remember nothing else:** weight is 95% of it, and it is fonts and images.
+
+---
+
+## 0. Budgets — mobile Lighthouse, per page
+
+| Budget | Limit |
+|---|---|
+| Total page weight | ≤ 1 MB |
+| All fonts on one page | ≤ 400 KB |
+| Any single font file | ≤ 100 KB |
+| Any single image | ≤ 200 KB |
+| JS on a marketing page | 0 framework bytes |
+| CSS per page | ≤ 15 KB |
+| `priority` / eager images per page | exactly 1 |
+| LCP · TBT · CLS | < 2.5 s · < 200 ms · < 0.1 |
+
+---
+
+## 1. Images
+
+**Where it comes from decides what you use.** Strapi → `<CmsImage media sizes />` ·
+Strapi + local fallback → `<CmsImage media fallback sizes />` · a local `import` →
+`<Image />` from `astro:assets` · an icon or shape → inline SVG · rich text → the
+renderer maps `img` → `<CmsImage>` · none of the above → raw `<img>` **+ a written
+reason**.
+
+- **1.1** Every CMS image goes through `<CmsImage>`. Every local image goes through `<Image>`. `[web-kit]` `[eslint]`
+- **1.2** A raw `<img>` requires a comment explaining why nothing else was possible. `[eslint]` `[review]`
+- **1.3** `<Image src={x} />`, never `<img src={x.src} />`. `[eslint]`
+- **1.4** `sizes` is required, and it describes the CSS box — not the image. `[web-kit]`
+- **1.5** Always emit `width` and `height` from the media metadata. `[web-kit]`
+- **1.6** Lazy by default. Exactly one `priority` image per page, and it must be the LCP. `[web-kit]` `[review]`
+- **1.7** `fetchpriority="high"` is for the LCP element only. Never a logo. `[review]`
+- **1.8** There is a third state: eager but not urgent — `loading="eager"` + `fetchpriority="low"`. `[review]`
+- **1.9** `loading="lazy"` is about layout position, not visibility. Any layout showing one of N things in one box owns its own loading schedule. `[review]`
+- **1.10** Never upscale. `[review]`
+- **1.11** Optimise before committing. Source files are not build artifacts. `[ci]`
+- **1.12** Rich-text renderers must map `img` → `<CmsImage>`. `[review]`
+- **1.13** A browser commits to the first `<source>` type it supports and never falls through: every format needs a complete width ladder, a rung at source resolution, and `sizes` on every `<source>`. `[web-kit]`
+- **1.14** Group derivatives by their `mime`, not by key name. `[web-kit]`
+- **1.15** `picture { display: contents }` in the global reset. `[scaffold]`
+- **1.16** The derivative ladder must reach your largest display size — stock Strapi stops at 1000px. `[scaffold]`
+- **1.17** Convert format at upload, not at request. `[scaffold]`
+- **1.18** Ship the upload pipeline with a re-processing script that walks the whole library by default, dry-run first, after a backup. `[scaffold]` `[review]`
+- **1.19** Do not compensate in the frontend for media the pipeline has not processed. `[review]`
+
+**Format:** AVIF photos and gradients · WebP the safer fallback · JPEG photos without
+transparency · PNG flat-colour graphics only · SVG shapes, logos, icons.
+
+---
+
+## 2. Fonts
+
+- **2.1** No icon fonts. Ever. Inline SVG. `[scaffold]` `[review]`
+- **2.2** Never download a font file by hand when Fontsource has it. `[scaffold]`
+- **2.3** Import font CSS in `Layout.astro` frontmatter, not in SCSS. `[review]`
+- **2.4** Subsetting: prefer `unicode-range` slices. Check the licence first — subsetting *is* modification. `[review]`
+- **2.5** Declare only the weights you use. `[review]`
+- **2.6** Five or more weights → variable font. Two or three → statics. One strategy per family. `[review]`
+- **2.7** Preload only the weights that render above the fold — verified by looking. `[review]`
+- **2.8** woff2 only. `font-display: swap` always.
+- **2.9** `font-display: swap` protects rendering, not bandwidth. `[review]`
+- **2.10** A custom or licensed face has failure modes a Fontsource package does not — read **Appendix B** of the why-doc before subsetting one, trimming baselines against its metrics, or rasterising its text into a canvas. `[review]`
+
+---
+
+## 3. JavaScript & hydration
+
+- **3.1** Prefer the platform: `<details>`, `<dialog>`, CSS `:hover` / `:focus-within`, CSS transitions. `[review]`
+- **3.2** Never re-implement in JavaScript what CSS does natively — especially breakpoints. `[review]`
+- **3.3** The three-question test: state surviving interactions? re-render from changing data? genuinely worse without a framework? All three "no" means it is not an island. `[review]`
+- **3.4** Marketing pages target zero islands — the first island pays a fixed framework runtime the second one does not. `[review]`
+- **3.5** Tool and app pages may use a framework freely.
+- **3.6** Adding an island to a page that had none is a bigger change than it looks. Say so in the PR. `[review]`
+- **3.7** `client:visible` is the default. `client:load` needs a written justification. `[review]`
+- **3.8** Use `client:media` for anything that exists at only one breakpoint or capability. `[review]`
+- **3.9** `client:only` is a last resort, and never above the fold. `[review]`
+- **3.10** An island can only be as lazy as its most urgent job. `[review]`
+- **3.11** Islands are leaves, not trunks. `[review]`
+- **3.12** One island, one job.
+- **3.13** Never gate visible content behind an async operation. `[review]`
+- **3.14** Never duplicate a decision already made server-side or in an inline script. `[review]`
+- **3.15** No unused or duplicate dependencies. `[ci]`
+- **3.16** Delete dead islands. `[ci]`
+
+---
+
+## 4. CSS
+
+- **4.1** A dynamic block renderer must import blocks dynamically — CSS follows the import graph, not the render output. `[review]`
+- **4.2** Adding a section type must not make every existing page heavier. `[review]`
+- **4.3** Co-located CSS modules only pay off if the imports are per-page. `[review]`
+- **4.4** Below-the-fold CSS must never block the first paint. `[review]`
+- **4.5** Choose the inlining threshold deliberately. `"auto"` is a default, not a decision. `[scaffold]`
+- **4.6** Shrink before you inline. `[review]`
+- **4.7** Match the strategy to the visit pattern, measure through brotli, and record the numbers in the commit message. `[review]`
+- **4.8** If CSS is too big to inline, make it smaller — do not load it more cleverly.
+- **4.9** PurgeCSS is a safety net, not a fix. `[review]`
+- **4.10** If you run PurgeCSS, the safelist must cover every class name the scanner cannot see as a literal string. `[review]`
+- **4.11** Verify against the built output, never the dev server. `[review]`
+- **4.12** Every site runs the same CSS pipeline. `[scaffold]`
+
+---
+
+## 5. Animation & the main thread
+
+Each frame is 16 ms of `Style → Layout → Paint → Composite`. `transform` and `opacity`
+reach only Composite; `filter` / `box-shadow` / `background` / `border-radius` repaint;
+`width` / `height` / `top` / `left` / `margin` re-run layout.
+
+- **5.1** Animate `transform` and `opacity`. Nothing else. `[review]`
+- **5.2** For a shadow, glow or colour transition, move it to a pseudo-element and transition that element's `opacity`. `[review]`
+- **5.3** Never transition a layout property. Use `transform: scale()` / `translate()`.
+- **5.4** In any scroll or resize handler: all reads first, then all writes. `[review]`
+- **5.5** Nothing above the fold may depend on JavaScript to become visible. `[review]`
+- **5.6** Nothing may animate *into position* on load. Snap on the first reading via a `primed` flag, animate on every one after. `[review]`
+- **5.7** `will-change` is temporary. Add before, remove after. `[review]`
+- **5.8** One animation system per site. `[review]`
+- **5.9** Every animation has a `prefers-reduced-motion` path.
+
+---
+
+## 6. Delivery
+
+- **6.1** Every site's router must include `compress@file`. `[scaffold]`
+- **6.2** The site's own nginx must not compress — `gzip off`. 6.1 and 6.2 do not work alone. `[scaffold]`
+- **6.3** `add_header` appends, it does not replace: uploads need `proxy_hide_header Cache-Control` plus a one-year `immutable` header. `[scaffold]`
+- **6.4** Preconnect to the CMS origin in the base layout, in `<head>` before the stylesheets. Maximum four. `[scaffold]`
+- **6.5** Preload the LCP image — once per page, and only if it is late-discovered. Preload fixes discovery, never weight. `[review]`
+
+---
+
+## 7. Shared code — `@smi-digital/web-kit`
+
+- **7.1** Never copy code out of web-kit into a site. `[review]`
+- **7.2** Extend upstream with an optional parameter that defaults to current behaviour. `[review]`
+- **7.3** A site may use the helper instead of the component — but never its own copy of the logic. `[review]`
+- **7.4** web-kit ships source, not a build: `vite: { ssr: { noExternal: ['@smi-digital/web-kit'] } }`. `[scaffold]`
+
+---
+
+## 8. Verification
+
+| Check | How | Expect |
+|---|---|---|
+| Fonts | DevTools → Network, filter `font` | **1** file on a German page |
+| Font metrics | read `hhea`, `sTypo`, `fsSelection` bit 7 from the binary | table matches the browser |
+| Brotli | `curl -sI -H "Accept-Encoding: br" <url>` | `content-encoding: br` |
+| Cache headers | `curl -sI <cms>/uploads/<file>` | **one** `Cache-Control`, `immutable` |
+| Preconnect | Lighthouse → "Preconnected origins" | your CMS origin listed |
+| Modern formats | page HTML | `avif` before `webp` before `<img>` |
+| Image sizing | Lighthouse → "Improve image delivery" | no entries |
+| Eager images | grep `priority` / `fetchpriority` per page | **1** high, and it is the LCP |
+| Render-blocking | Lighthouse | 0 stylesheets |
+| Forced reflow | DevTools → Performance, 4× CPU throttle | no purple layout bars in scroll |
+| Layout-defeated lazy | Network tab while **not** scrolling | only above-fold images |
+| Load-time animation | trace → count `DroppedFrame` before first paint | **0** |
+
+- **8.1** Verify on the built output, not `astro dev`.
+- **8.2** Verify on a throttled device profile.
+- **8.3** Speed Index is bimodal. Take the median of five runs. `[review]`
+- **8.4** Measure the rendered output, not the intended arithmetic. `[review]`
+- **8.5** When first paint is late, check whether anything was still loading — if load finished and paint did not follow, it is the main thread, not the network. `[review]`
+
+---
+
+## The sentences worth remembering
+
+1. **Weight is 95% of the problem.** Fonts and images.
+2. **Icons are graphics, not typography.**
+3. **A raw `<img>` is banned because it is incomplete by default**, not because it is wrong.
+4. **The first island costs a whole framework runtime** (3.4 — measure it, do not quote it). Astro will happily sell you zero.
+5. **`transform` and `opacity` are the only two free properties** — and nothing should be using them during the first paint.
+6. **`<picture>` never falls through.** Every format needs a complete ladder.
+7. **A shared component copied into a site is a fork**, however correct the copy is.
+8. **Measure the pixels, not the formula**, and take the median of five.

package/templates/integrations/strapi-astro/integration.config.json

@@ -86,6 +86,26 @@
     {
       "template": "CLAUDE.md.template",
       "target": "CLAUDE.md"
+    },
+    {
+      "template": "docs/performance.md.template",
+      "target": "docs/performance.md"
+    },
+    {
+      "template": "docs/performance-why.md.template",
+      "target": "docs/performance-why.md"
+    },
+    {
+      "template": "docs/design.md.template",
+      "target": "docs/design.md"
+    },
+    {
+      "template": "backend/src/extensions/upload/strapi-server.ts.template",
+      "target": "backend/src/extensions/upload/strapi-server.ts"
+    },
+    {
+      "template": "backend/src/scripts/reprocess-media.ts.template",
+      "target": "backend/src/scripts/reprocess-media.ts"
     }
   ],
   "cdFiles": [

package/templates/integrations/strapi-astro/nginx-cache.conf.template

@@ -23,8 +23,11 @@ map $http_upgrade $connection_upgrade {
     ''      close;
 }
 
-gzip on;
-gzip_types text/plain text/css application/json application/javascript text/xml application/xml application/xml+rss text/javascript;
+# Compression is Traefik's job, not ours. The `compress@file` middleware
+# negotiates br > zstd > gzip, but it SKIPS any response that already carries a
+# Content-Encoding — so gzipping here would silently disable Brotli at the edge
+# for every asset and every document, with no error anywhere.
+gzip off;
 
 # ── Frontend: Astro SSR ───────────────────────────────────────────────────
 # default_server so the container healthcheck (Host: 127.0.0.1) and any
@@ -83,8 +86,15 @@ server {
 
         # Media is static: ignore any cookie/cache headers Strapi attaches so
         # the response is always cacheable, and never relay a Set-Cookie.
+        # proxy_ignore_headers governs only what NGINX caches for itself; the
+        # upstream header still reaches the client, and add_header APPENDS rather
+        # than replaces. Without proxy_hide_header the response carries two
+        # contradictory Cache-Control values (Strapi's own, and ours below),
+        # browsers resolve conservatively, and every upload is re-fetched on
+        # every visit — invisible in Lighthouse, which only measures a cold load.
         proxy_ignore_headers Set-Cookie Cache-Control Expires;
         proxy_hide_header Set-Cookie;
+        proxy_hide_header Cache-Control;
 
         proxy_pass http://__APP_NAME__-strapi:1337;
 
@@ -93,7 +103,7 @@ server {
         proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
         proxy_set_header X-Forwarded-Proto $scheme;
 
-        add_header Cache-Control "public, max-age=2592000";
+        add_header Cache-Control "public, max-age=31536000, immutable";
         add_header X-Cache-Status $upstream_cache_status;
     }