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

package/dist/index.js

@@ -542,6 +542,14 @@ async function createApps(projectRoot, targets) {
           join4(projectRoot, target.directory)
         );
       });
+      await runStep(
+        "Adding the shared web-kit components",
+        async () => runCommandQuiet(
+          "npm",
+          ["install", "@smi-digital/web-kit"],
+          join4(projectRoot, target.directory)
+        )
+      );
     }
     await runSequentially(index + 1);
   };
@@ -659,9 +667,11 @@ async function createIntegrations(options, projectRoot, templatesDir) {
       await runCommandQuiet("npx", ["astro", "add", "node", "-y"], frontendDir);
       const astroConfigPath = join5(frontendDir, "astro.config.mjs");
       let astroConfig = await readFile3(astroConfigPath, "utf8");
+      const viteBlock = /(^|\n)\s*vite\s*:/v.test(astroConfig) ? "" : "\n  vite: { ssr: { noExternal: ['@smi-digital/web-kit'] } },";
       astroConfig = astroConfig.replace(
         /export default defineConfig\s*\(\s*\{/v,
-        "export default defineConfig({\n  output: 'server',"
+        `export default defineConfig({
+  output: 'server',${viteBlock}`
       );
       await writeFile3(astroConfigPath, astroConfig);
     } catch (error) {

package/package.json

@@ -1,7 +1,11 @@
 {
   "name": "@smi-digital/create-smi-app",
-  "version": "2.14.1",
+  "version": "2.15.0",
   "description": "",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/SMI-Digital/create-smi-app.git"
+  },
   "main": "dist/index.js",
   "bin": {
     "create-smi-app": "./bin/cli.js"
@@ -42,8 +46,11 @@
     "@commitlint/config-conventional": "^20.4.4",
     "@eslint/js": "^10.0.1",
     "@eslint/json": "^1.1.0",
+    "@semantic-release/changelog": "^6.0.3",
+    "@semantic-release/git": "^10.0.1",
     "@types/chalk-animation": "^1.6.3",
     "@types/node": "^25.5.0",
+    "conventional-changelog-conventionalcommits": "^9.3.1",
     "dependency-cruiser": "^17.3.9",
     "eslint": "^10.0.3",
     "eslint-config-prettier": "^10.1.8",
@@ -53,6 +60,7 @@
     "knip": "^5.86.0",
     "lint-staged": "^16.3.3",
     "prettier": "3.8.1",
+    "semantic-release": "^25.0.9",
     "tsup": "^8.5.1",
     "tsx": "^4.21.0",
     "typescript": "^5.9.3",

package/templates/base/gitignore.template

@@ -4,4 +4,7 @@ node_modules
 !production.*.env
 
 # Ansible Vault Password (NEVER COMMIT THIS)
-.vault-password
+.vault-password
+
+# Jetbrains IDE
+.idea

package/templates/integrations/strapi-astro/AGENTS.md.template

@@ -1,5 +1,74 @@
 # Working in this project
 
+## What this is
+
+Astro SSR (`output: "server"`, Node adapter) consuming Strapi 5 over REST at
+request time. Two independent workspaces: `frontend/` and `backend/`. There is no
+static prerendering — every page renders on demand from live CMS data, behind an
+nginx stale-while-revalidate cache.
+
+**This architecture is fixed.** If something cannot be built within it, stop and
+ask rather than changing it.
+
+## Layout
+
+```
+frontend/src/
+  components/  sections/ (static .astro)  islands/ (interactive)  ui/ (primitives)
+  layouts/     lib/     styles/     pages/     types/     assets/
+backend/src/
+  api/    extensions/    scripts/    config/
+```
+
+Each component lives in its own folder with a co-located `.module.scss`.
+Anything not listed here, read from the directory — do not assume it exists.
+
+## Running things
+
+```bash
+cd frontend   npm test | run test:watch | run lint | run build   ·  npx astro check
+cd backend    npm run develop | run build                        ·  npx tsc --noEmit
+root          npx prettier --check .                             ·  npx eslint .
+```
+
+## Non-negotiables
+
+- **CMS images go through `<CmsImage>`, local images through `<Image>`** from
+  `astro:assets`. A raw `<img>` needs a comment saying why nothing else worked.
+  → `docs/performance.md` §1
+- **Never copy code out of `@smi-digital/web-kit` into this repo.** If the shared
+  version is wrong, change the shared version. → `docs/performance.md` §7
+- **Verify against the built output, never `astro dev`.** Code splitting, CSS
+  inlining and asset optimisation only exist at build.
+- **Never commit or push.** Leave changes in the working tree.
+
+## Where to look
+
+Read the relevant file **before** starting, not after.
+
+| When you are about to… | Read |
+|---|---|
+| touch an image, font, animation, or anything that loads | `docs/performance.md` |
+| build UI — spacing, type, colour, hierarchy | `docs/design.md` |
+| disagree with a performance rule, or wonder why a budget is that number | `docs/performance-why.md` |
+| need a fact about *this* site that is not in the code | `MEMORY.md` |
+
+## Coding style
+
+- TypeScript strict everywhere; always type function return values explicitly
+- `const` over `let`, never `var`; early returns over nested conditionals
+- camelCase for variables and functions, PascalCase for components
+- SCSS Modules for component styles; never ad-hoc font sizes or colours — use the
+  scales in `frontend/src/styles/`
+- Formatting is Prettier's job, per `.prettierrc`. Do not hand-format.
+- `@/` maps to `frontend/src/`
+
+## Before assuming a library exists
+
+Read `package.json`. This is a scaffolded fleet and sites diverge — a library
+used on one site is not necessarily present on another. The same applies to
+files: check the directory rather than trusting a path you have seen elsewhere.
+
 ## The two checks that gate a pull request
 
 **The A/B visual check** builds the frontend twice — once from the merge-base,
@@ -91,6 +160,10 @@ it, and they are not interchangeable:
 
 The element is still captured and compared; freezing only pins where it sits.
 
+Separately: an animation that runs **on load** is a performance problem as well as
+an A/B one — it competes with the browser's first paint. See `docs/performance.md`
+§5.6, which is the rule that nothing may animate *into* position.
+
 ## Adding a hydration probe
 
 A screenshot cannot tell you an island stopped mounting — the server-rendered
@@ -101,13 +174,3 @@ The shared ones are `faq-accordion`, `mobile-nav` and `consent-banner`. Remove
 any this project does not have: a probe that never matches anything is reported
 as a configuration error rather than passing quietly. A project-specific probe
 means extending the shared action in `ci-library`.
-
-## Running things
-
-```bash
-npm test          # unit tests, once
-npm run test:watch
-npm run lint
-npx astro check   # types, including .astro files
-npm run build
-```

package/templates/integrations/strapi-astro/Dockerfile.backend.template

@@ -43,5 +43,25 @@ COPY docker-entrypoint.sh /usr/local/bin/docker-entrypoint.sh
 RUN chmod +x /usr/local/bin/docker-entrypoint.sh
 
 EXPOSE 1337
+
+# KNOWN GAP — this image runs as root, unlike frontend/Dockerfile.
+#
+# Strapi writes into /opt/app/public, which is a mounted volume at runtime, and
+# the entrypoint reseeds it on every start. The deploy provisions that volume
+# owned by root, so adding `USER node` here leaves the container unable to write
+# to it and the entrypoint fails on boot. Making this non-root is a change to how
+# the volume is provisioned — cd-library and the Ansible role — not a Dockerfile
+# edit, so it cannot be fixed in this template alone.
+#
+# Every backend in the fleet carries this same suppression. It is here so a new
+# project starts consistent with them rather than failing its first Semgrep run,
+# not because running as root is intended. If the provisioning side is ever
+# changed to create the volume as uid 1000, delete these two lines and add
+# `USER node` — this template is the right place to start that.
+#
+# Suppressed narrowly, by rule and on these two lines only, so that a NEW
+# root-running image elsewhere in the project still fails the scan.
+# nosemgrep: dockerfile.security.missing-user-entrypoint.missing-user-entrypoint
 ENTRYPOINT ["docker-entrypoint.sh"]
+# nosemgrep: dockerfile.security.missing-user.missing-user
 CMD ["npm", "run", "start"]

package/templates/integrations/strapi-astro/backend/config/plugins.ts.template

@@ -1,4 +1,48 @@
 export default ({ env }) => ({
+    // Media pipeline. Editors upload whatever their camera or designer produced;
+    // everything that makes it web-ready happens here, once, on upload.
+    //
+    // `breakpoints` is read by Strapi itself. The stock defaults stop at 1000px,
+    // so any viewport wider than that is handed the untouched original — which is
+    // how camera JPEGs end up in hero slots.
+    //
+    // NOTE: this applies only to NEWLY uploaded files. Existing media keeps the
+    // derivatives it was created with and must be re-processed before anything
+    // improves — see src/scripts/reprocess-media.ts.
+    upload: {
+        config: {
+            breakpoints: {
+                xsmall: 320,
+                small: 640,
+                medium: 1024,
+                large: 1600,
+                xlarge: 2400,
+            },
+            // Read by src/extensions/upload/strapi-server.ts.
+            smiImagePipeline: {
+                // Strapi never resizes the original, so a 6000x4000 upload stays
+                // 6000x4000 on disk — and is a candidate in the srcset. Cap it
+                // just above the largest breakpoint.
+                maxOriginalWidth: 2560,
+                // Most modern first. Each gets a COMPLETE ladder: a browser
+                // commits to the first <picture> source type it supports and then
+                // selects within it, so a partial AVIF ladder would hand a phone a
+                // desktop-sized file rather than falling through to a small WebP.
+                formats: [
+                    {
+                        ext: '.avif',
+                        mime: 'image/avif',
+                        options: { quality: 60, effort: 4 },
+                    },
+                    {
+                        ext: '.webp',
+                        mime: 'image/webp',
+                        options: { quality: 80 },
+                    },
+                ],
+            },
+        },
+    },
     email: {
         config: {
             provider: 'nodemailer',

package/templates/integrations/strapi-astro/backend/src/extensions/upload/strapi-server.ts.template

@@ -0,0 +1,253 @@
+/**
+ * Media pipeline: cap the original, and emit a complete AVIF + WebP ladder.
+ *
+ * Strapi resizes but never converts — JPEG in, JPEG out — so the format a
+ * visitor downloads used to be decided by whatever an editor happened to drag
+ * into the CMS. It also never touches the original, so an 11424x7616 camera
+ * file stayed 11424x7616 on disk and remained a candidate in the srcset.
+ *
+ * Two overrides on the upload plugin's image-manipulation service:
+ *
+ *   optimize()                 caps the original at maxOriginalWidth, keeping
+ *                              its source format so it stays the compatibility
+ *                              fallback on the <img>.
+ *   generateResponsiveFormats() replaces the same-format ladder with one
+ *                              COMPLETE ladder per configured format.
+ *
+ * `generateThumbnail` is a separate method and is left alone — the admin media
+ * library reads `formats.thumbnail`, so renaming ladder keys here is safe.
+ *
+ * Format keys are `<breakpoint>_<ext>` (e.g. `large_avif`). Nothing downstream
+ * parses those names: CmsImage groups derivatives by the `mime` Strapi stores
+ * on each entry, so this naming is free to change.
+ */
+import fs from 'fs';
+import path from 'path';
+import sharp, { type OutputInfo } from 'sharp';
+
+// For animated images sharp reports the true frame height as `pageHeight`, and
+// `height` is every frame stacked; without this `height` would be wildly wrong
+// on a GIF.
+//
+// Unlike the other sites in the fleet, this one does NOT need the declaration:
+// sharp 0.35 declares `pageHeight` on its own exported `OutputInfo`, and those
+// typings are in the program because this file imports the module. It is kept
+// anyway, as a no-op that costs nothing and survives a sharp downgrade — 0.33
+// and earlier have no such member, and Strapi's pinned sharp version moves.
+//
+// Note 0.35 also moved the typings entry to dist/index.d.mts, which is an ES
+// module with named exports and no `declare namespace sharp`. That is why
+// `OutputInfo` is imported as a type here rather than written `sharp.OutputInfo`
+// as the other sites do — on this version that spelling does not resolve at all.
+declare module 'sharp' {
+    interface OutputInfo {
+        pageHeight?: number;
+    }
+}
+
+interface PipelineFormat {
+    ext: string;
+    mime: string;
+    options?: Record<string, unknown>;
+}
+
+interface PipelineConfig {
+    maxOriginalWidth: number;
+    formats: PipelineFormat[];
+}
+
+const DEFAULTS: PipelineConfig = {
+    maxOriginalWidth: 2560,
+    formats: [{ ext: '.webp', mime: 'image/webp', options: { quality: 80 } }],
+};
+
+const bytesToKbytes = (bytes: number): number =>
+    Math.round((bytes / 1000) * 100) / 100;
+
+/** Sharp's method name for an extension, e.g. ".avif" -> "avif". */
+const encoderFor = (ext: string): 'avif' | 'webp' | 'jpeg' | 'png' => {
+    const name = ext.replace('.', '').toLowerCase();
+    if (name === 'jpg') return 'jpeg';
+    return name as 'avif' | 'webp' | 'jpeg' | 'png';
+};
+
+const getConfig = (): PipelineConfig => ({
+    ...DEFAULTS,
+    ...(strapi.config.get(
+        'plugin::upload.smiImagePipeline',
+        {},
+    ) as Partial<PipelineConfig>),
+});
+
+/**
+ * Resize and re-encode a file, mirroring the shape the upload plugin's own
+ * `resizeFileTo` returns. `ext`/`mime` are overridden rather than inherited,
+ * which is the whole point — the plugin's version keeps the source format.
+ */
+async function transformFile(
+    file: any,
+    {
+        resize,
+        format,
+        name,
+        hash,
+    }: {
+        resize?: { width: number; height: number };
+        format?: PipelineFormat;
+        name: string;
+        hash: string;
+    },
+): Promise<any> {
+    const filePath = file.tmpWorkingDirectory
+        ? path.join(file.tmpWorkingDirectory, hash)
+        : hash;
+
+    const build = (input?: string) => {
+        let pipeline = input
+            ? sharp(input, { animated: true })
+            : sharp({ animated: true });
+        if (resize)
+            pipeline = pipeline.resize({
+                ...resize,
+                fit: 'inside',
+                withoutEnlargement: true,
+            });
+        if (format)
+            pipeline = pipeline[encoderFor(format.ext)](format.options ?? {});
+        return pipeline;
+    };
+
+    let info: OutputInfo | undefined;
+
+    if (!file.filepath) {
+        const transform = build().on('info', (i) => {
+            info = i as OutputInfo;
+        });
+        await new Promise<void>((resolve, reject) => {
+            const writeStream = fs.createWriteStream(filePath);
+            file.getStream()
+                .pipe(transform)
+                .pipe(writeStream)
+                .on('close', resolve)
+                .on('error', reject);
+        });
+        // The `info` event does not report final byte size for a streamed encode.
+        if (info && !info.size) info.size = fs.statSync(filePath).size;
+    } else {
+        info = await build(file.filepath).toFile(filePath);
+    }
+
+    const { width, height, size, pageHeight } = (info ?? {}) as OutputInfo;
+
+    return {
+        name,
+        hash,
+        ext: format?.ext ?? file.ext,
+        mime: format?.mime ?? file.mime,
+        filepath: filePath,
+        path: file.path || null,
+        getStream: () => fs.createReadStream(filePath),
+        width,
+        height: pageHeight ?? height,
+        size: size ? bytesToKbytes(size) : 0,
+        sizeInBytes: size,
+    };
+}
+
+/** Strips the extension so a new one can be appended. */
+const baseName = (name: string, ext: string): string =>
+    name.endsWith(ext) ? name.slice(0, -ext.length) : name;
+
+export default (plugin: any) => {
+    const service = plugin.services['image-manipulation'];
+    const originalOptimize = service.optimize;
+
+    /**
+     * Cap the original. Format is deliberately preserved: with AVIF and WebP
+     * ladders in front of it, the original is what a browser supporting neither
+     * falls back to on the <img>.
+     */
+    service.optimize = async (file: any) => {
+        const optimized = await originalOptimize.call(service, file);
+        const { maxOriginalWidth } = getConfig();
+
+        if (!optimized?.width || optimized.width <= maxOriginalWidth)
+            return optimized;
+
+        const capped = await transformFile(optimized, {
+            resize: { width: maxOriginalWidth, height: maxOriginalWidth },
+            name: optimized.name,
+            hash: optimized.hash,
+        });
+
+        strapi.log.info(
+            `[media] capped ${optimized.name}: ${optimized.width}px -> ${capped.width}px`,
+        );
+        return { ...optimized, ...capped };
+    };
+
+    /**
+     * One complete ladder per configured format, replacing Strapi's
+     * same-format ladder.
+     */
+    service.generateResponsiveFormats = async (file: any) => {
+        const { responsiveDimensions = false } =
+            (await strapi.plugin('upload').service('upload').getSettings()) ??
+            {};
+        if (!responsiveDimensions) return [];
+
+        const breakpoints = strapi.config.get(
+            'plugin::upload.breakpoints',
+            {},
+        ) as Record<string, number>;
+        const { formats } = getConfig();
+        const dimensions = await service.getDimensions(file);
+        const longestEdge = Math.max(
+            dimensions.width ?? 0,
+            dimensions.height ?? 0,
+        );
+
+        const results: { key: string; file: any }[] = [];
+
+        // Every rung the original can fill, PLUS one at the original's own size.
+        //
+        // `full` is not optional. The original is stored only in its SOURCE format,
+        // so without it each converted ladder stops at the largest breakpoint below
+        // the original — and a browser that commits to the AVIF <source> can then
+        // never reach the source resolution, because <picture> never falls through
+        // to a later source. Measured on team-aha before this existed: the AVIF
+        // ladder topped out 5-29% short of the fallback on every image, worst on a
+        // 1446px-wide hero that stopped at 1024 and looked soft on a 4K display.
+        //
+        // `file` here is already the output of optimize(), so its longest edge is
+        // at most maxOriginalWidth — `full` inherits the cap rather than undoing it.
+        const rungs: { key: string; edge: number }[] = [
+            ...Object.entries(breakpoints)
+                // Skip rungs the original cannot fill — upscaling costs bytes and loses
+                // quality. Every format still gets the same set of widths, which is what
+                // <picture> selection requires.
+                .filter(([, bp]) => bp < longestEdge)
+                .map(([key, bp]) => ({ key, edge: bp })),
+            { key: 'full', edge: longestEdge },
+        ];
+
+        for (const { key, edge } of rungs) {
+            for (const format of formats) {
+                const ext = format.ext.replace('.', '');
+                results.push({
+                    key: `${key}_${ext}`,
+                    file: await transformFile(file, {
+                        resize: { width: edge, height: edge },
+                        format,
+                        name: `${key}_${baseName(file.name, file.ext)}${format.ext}`,
+                        hash: `${key}_${file.hash}_${ext}`,
+                    }),
+                });
+            }
+        }
+
+        return results;
+    };
+
+    return plugin;
+};