@knitli/astro-docs-template 0.2.7 → 0.4.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@knitli/astro-docs-template",
-  "version": "0.2.7",
+  "version": "0.4.1",
   "description": "Opinionated Astro + Starlight docs site template with Knitli branding",
   "keywords": [
     "knitli",
@@ -38,22 +38,33 @@
     "clean": "rm -rf dist",
     "deploy": "bun publish --tag latest",
     "prepack": "bun run build",
-    "test": "vitest run",
+    "test": "vitest run src/index.test.ts",
+    "test:integration": "vitest run src/integration.test.ts",
+    "test:unit": "vitest run src/index.test.ts",
     "test:watch": "vitest"
   },
   "dependencies": {
-    "@astrojs/cloudflare": "^13.1.1",
+    "@astrojs/check": "^0.9.6",
+    "@astrojs/cloudflare": "^13.1.7",
+    "@astrojs/compiler-rs": "^0.1.6",
     "@astrojs/markdoc": "^1.0.0",
-    "@astrojs/mdx": "^5.0.0",
-    "@astrojs/sitemap": "^3.6.0",
-    "@astrojs/starlight": "^0.38.1",
+    "@astrojs/mdx": "^5.0.3",
+    "@astrojs/sitemap": "^3.7.2",
+    "@astrojs/starlight": "^0.38.2",
+    "@biomejs/biome": "^2.4.2",
     "@knitli/docs-components": "*",
-    "@nuasite/llm-enhancements": "^0.18.0",
-    "astro": "^6.0.4",
+    "@knitli/tsconfig": "*",
+    "@nuasite/llm-enhancements": "^0.19.1",
+    "@types/bun": "^1.3.4",
+    "@types/node": "^24.0.2",
+    "astro": "^6.1.4",
     "astro-cloudflare-pages-headers": "^1.7.7",
     "astro-d2": "^0.10.0",
     "astro-favicons": "3.1.6",
+    "bun": "^1.3.9",
+    "lightningcss": "^1.30.2",
     "rehype-external-links": "^3.0.0",
+    "sharp": "^0.34.5",
     "starlight-announcement": ">=0.1.1",
     "starlight-changelogs": " >=0.1.0",
     "starlight-heading-badges": ">=0.6.1",
@@ -64,18 +75,9 @@
     "starlight-scroll-to-top": ">=0.4.0",
     "starlight-sidebar-topics": ">=0.7.1",
     "starlight-tags": ">=0.4.0",
-    "vite-tsconfig-paths": "6.1.1",
-    "vite": "^7.0.0",
-    "@astrojs/compiler-rs": "^0.1.4",
-    "@biomejs/biome": "^2.4.2",
-    "@knitli/tsconfig": "*",
-    "@types/bun": "^1.3.4",
-    "@types/node": "^24.0.2",
-    "bun": "^1.3.9",
-    "lightningcss": "^1.30.2",
-    "sharp": "^0.34.5",
     "svgo": "^4.0.0",
-    "@astrojs/check": "^0.9.6"
+    "vite": "^7.3.1",
+    "vite-tsconfig-paths": "6.1.1"
   },
   "devDependencies": {
     "typescript": "^5.9.3",
@@ -93,5 +95,8 @@
     "provenance": false,
     "registry": "https://registry.npmjs.org/",
     "tag": "latest"
-  }
+  },
+  "trustedDependencies": [
+    "bun"
+  ]
 }

package/scaffolding/README.md

@@ -26,7 +26,7 @@ bun run deploy
 │   ├── styles/          # Site-specific CSS overrides
 │   └── content.config.ts
 ├── astro.config.ts      # Uses @knitli/astro-docs-template createConfig
-├── wrangler.jsonc       # Cloudflare Workers configuration
+├── wrangler.json        # Cloudflare Workers configuration
 └── package.json
 ```
 

package/src/config.ts

@@ -10,8 +10,10 @@ import markdoc from "@astrojs/markdoc";
 import mdx from "@astrojs/mdx";
 import sitemap from "@astrojs/sitemap";
 import starlight from "@astrojs/starlight";
+import type { StarlightPlugin } from "@astrojs/starlight/types";
 import { DocsAssets } from "@knitli/docs-components";
 import llmEnhancements from "@nuasite/llm-enhancements";
+import type { AstroIntegration } from "astro";
 import { defineConfig, fontProviders } from "astro/config";
 import cloudflarePagesHeaders from "astro-cloudflare-pages-headers";
 import astroD2 from "astro-d2";
@@ -39,6 +41,7 @@ type defaultIntegration =
   | "markdoc"
   | "mdx"
   | "favicons"
+  | "starlightIconsIntegration"
   | "cloudflare-pages-headers";
 
 function nonNullable<T>(value: T): value is NonNullable<T> {
@@ -194,6 +197,40 @@ const getIntegrations = (options: IntegrationOptions) => {
     integrationConfigs,
     unwantedIntegrations = [],
   } = options;
+  // Registry maps config keys (used in unwantedIntegrations and integrationConfigs)
+  // to actual runtime .name values and factory functions for overrides.
+  const integrationRegistry: Record<
+    string,
+    {
+      runtimeNames: string[];
+      // biome-ignore lint/suspicious/noExplicitAny: integration configs are opaque
+      create: (cfg: any) => AstroIntegration;
+    }
+  > = {
+    astroD2: { runtimeNames: ["astro-d2-integration"], create: astroD2 },
+    markdoc: { runtimeNames: ["@astrojs/markdoc"], create: markdoc },
+    mdx: { runtimeNames: ["@astrojs/mdx"], create: mdx },
+    favicons: { runtimeNames: ["astro-favicons"], create: favicons },
+    sitemap: { runtimeNames: ["@astrojs/sitemap"], create: sitemap },
+    starlightIconsIntegration: {
+      runtimeNames: ["starlight-plugin-icons"],
+      create: starlightIconsIntegration,
+    },
+    "cloudflare-pages-headers": {
+      runtimeNames: ["astroCloudflarePagesHeaders"],
+      create: cloudflarePagesHeaders,
+    },
+  };
+
+  // Resolve unwantedIntegrations config keys to runtime .name values
+  const unwantedRuntimeNames = new Set<string>();
+  for (const key of unwantedIntegrations) {
+    const entry = integrationRegistry[key];
+    if (entry) {
+      for (const n of entry.runtimeNames) unwantedRuntimeNames.add(n);
+    }
+  }
+
   const defaultIntegrations = [
     astroD2({ skipGeneration: true }),
     markdoc(),
@@ -220,33 +257,33 @@ const getIntegrations = (options: IntegrationOptions) => {
     }),
   ];
 
-  const filtered = defaultIntegrations.filter((integration) => {
-    const name = integration?.name;
-    return !name || !unwantedIntegrations.includes(name as defaultIntegration);
-  });
+  const filtered = defaultIntegrations.filter(
+    (integration) =>
+      !integration?.name || !unwantedRuntimeNames.has(integration.name),
+  );
 
   if (!integrationConfigs) return filtered;
 
+  // Collect runtime names that will be replaced by overrides
+  const replacedIntegrationNames = new Set<string>();
+  for (const key of Object.keys(integrationConfigs)) {
+    const entry = integrationRegistry[key];
+    if (entry) {
+      for (const n of entry.runtimeNames) replacedIntegrationNames.add(n);
+    }
+  }
+
+  // Remove defaults that will be replaced by overrides
+  const base = filtered.filter(
+    (integration) =>
+      !integration?.name || !replacedIntegrationNames.has(integration.name),
+  );
+
   const overrides = Object.entries(integrationConfigs)
-    .map(([integrationName, config]) => {
-      switch (integrationName) {
-        case "astroD2":
-          return astroD2(config);
-        case "markdoc":
-          return markdoc(config);
-        case "mdx":
-          return mdx(config);
-        case "favicons":
-          return favicons(config);
-        case "sitemap":
-          return sitemap(config);
-        default:
-          return null;
-      }
-    })
+    .map(([key, config]) => integrationRegistry[key]?.create(config) ?? null)
     .filter(nonNullable);
 
-  return [...filtered, ...overrides];
+  return [...base, ...overrides];
 };
 
 export type PluginOptions = Pick<
@@ -293,30 +330,59 @@ const get_plugins = (options: PluginOptions) => {
 
   if (!pluginConfigs) return filtered;
 
+  // Map config keys to factory functions and the actual plugin .name values.
+  // Note: starlightIconsIntegration is an Astro *integration* (in getIntegrations),
+  // not a Starlight plugin — it was incorrectly in the old plugin override switch.
+  const pluginRegistry: Record<
+    string,
+    {
+      pluginNames: string[];
+      // biome-ignore lint/suspicious/noExplicitAny: plugin configs are opaque
+      create: (cfg: any) => StarlightPlugin;
+    }
+  > = {
+    starlightAnnouncement: {
+      pluginNames: ["starlight-announcement"],
+      create: starlightAnnouncement,
+    },
+    starlightIconsPlugin: {
+      pluginNames: ["starlight-plugin-icons"],
+      create: starlightIconsPlugin,
+    },
+    starlightLinksValidator: {
+      pluginNames: ["starlight-links-validator-plugin"],
+      create: starlightLinksValidator,
+    },
+    starlightPageActions: {
+      pluginNames: ["starlight-page-actions"],
+      create: starlightPageActions,
+    },
+    starlightTags: { pluginNames: ["starlight-tags"], create: starlightTags },
+    starlightScrollToTop: {
+      pluginNames: ["starlight-scroll-to-top-plugin"],
+      create: starlightScrollToTop,
+    },
+  };
+
+  // Collect the actual plugin .name values that will be replaced
+  const replacedPluginNames = new Set<string>();
+  for (const key of Object.keys(pluginConfigs)) {
+    const entry = pluginRegistry[key];
+    if (entry) {
+      for (const n of entry.pluginNames) replacedPluginNames.add(n);
+    }
+  }
+
+  // Remove defaults that will be replaced by overrides
+  const base = filtered.filter(
+    (plugin) => !replacedPluginNames.has(plugin.name),
+  );
+
   const overrides = Object.entries(pluginConfigs)
-    .map(([pluginName, config]) => {
-      switch (pluginName) {
-        case "starlightAnnouncement":
-          return starlightAnnouncement(config);
-        case "starlightIconsIntegration":
-          return starlightIconsIntegration(config);
-        case "starlightIconsPlugin":
-          return starlightIconsPlugin(config);
-        case "starlightLinksValidator":
-          return starlightLinksValidator(config);
-        case "starlightPageActions":
-          return starlightPageActions(config);
-        case "starlightTags":
-          return starlightTags(config);
-        case "starlightScrollToTop":
-          return starlightScrollToTop(config);
-        default:
-          return null;
-      }
-    })
+    .map(([key, config]) => pluginRegistry[key]?.create(config) ?? null)
     .filter(nonNullable);
 
-  return [...filtered, ...overrides];
+  return [...base, ...overrides];
 };
 
 const defaultHeadersConfig: OutgoingHttpHeaders = {
@@ -354,11 +420,7 @@ export default function createConfig(options: DocsTemplateOptions) {
     site: "https://docs.knitli.com",
     base: `/${appName.toLowerCase()}/`,
     adapter: cloudflare({
-      prerenderEnvironment: "workerd",
-      experimental: {
-        headersAndRedirectsDevModeSupport: true,
-      },
-      configPath: `${rootDir}/wrangler.jsonc`,
+      configPath: `${rootDir}/wrangler.json`,
       imageService: "compile",
     }),
     // Image optimization
@@ -383,10 +445,10 @@ export default function createConfig(options: DocsTemplateOptions) {
         Object.entries(shikiConfig).filter(([key]) => key !== "bundledLangs"),
       ),
       rehypePlugins: [
-        rehypeExternalLinks({
-          content: { type: "text", value: " ↗" },
-          rel: ["nofollow"],
-        }),
+        [
+          rehypeExternalLinks,
+          { content: { type: "text", value: " ↗" }, rel: ["nofollow"] },
+        ],
       ],
     },
     server: {
@@ -413,7 +475,7 @@ export default function createConfig(options: DocsTemplateOptions) {
         "import.meta.env.PUBLIC_DOCS_PRODUCT": JSON.stringify(appName),
       },
       build: {
-        cssMinify: "lightningcss",
+        cssMinify: "esbuild",
         minify: "esbuild",
         cssCodeSplit: true,
         rollupOptions: {
@@ -445,9 +507,7 @@ export default function createConfig(options: DocsTemplateOptions) {
         },
         ssr: false,
       },
-      css: {
-        lightningcss: {},
-      },
+      css: {},
     },
     prefetch: {
       defaultStrategy: "viewport",
@@ -479,12 +539,8 @@ export default function createConfig(options: DocsTemplateOptions) {
     // Static site generation for Cloudflare
     output: "static",
     integrations: [
-      ...getIntegrations({
-        appName,
-        sitemapFilter,
-        integrationConfigs,
-        unwantedIntegrations,
-      }),
+      // Starlight must come before mdx() because it injects astro-expressive-code
+      // which requires being ordered before mdx in the integration array.
       starlight({
         title: `${appName} Docs`,
         pagefind: true,
@@ -558,6 +614,12 @@ export default function createConfig(options: DocsTemplateOptions) {
           },
         ],
       }),
+      ...getIntegrations({
+        appName,
+        sitemapFilter,
+        integrationConfigs,
+        unwantedIntegrations,
+      }),
     ],
   });
 }

package/src/index.test.ts

@@ -175,7 +175,7 @@ describe("initDocsTemplate", () => {
 
   it("substitutes {{appName}} in text files", () => {
     initDocsTemplate(tmpDir, BASE_OPTIONS);
-    const wrangler = readFileSync(join(tmpDir, "wrangler.jsonc"), "utf-8");
+    const wrangler = readFileSync(join(tmpDir, "wrangler.json"), "utf-8");
     expect(wrangler).toContain(BASE_OPTIONS.workerName);
     expect(wrangler).not.toContain("{{workerName}}");
   });
@@ -195,7 +195,7 @@ describe("initDocsTemplate", () => {
   it("creates all expected piece files", () => {
     initDocsTemplate(tmpDir, BASE_OPTIONS);
     expect(existsSync(join(tmpDir, "astro.config.ts"))).toBe(true);
-    expect(existsSync(join(tmpDir, "wrangler.jsonc"))).toBe(true);
+    expect(existsSync(join(tmpDir, "wrangler.json"))).toBe(true);
     expect(existsSync(join(tmpDir, "tsconfig.json"))).toBe(true);
     expect(existsSync(join(tmpDir, "package.json"))).toBe(true);
     expect(existsSync(join(tmpDir, "mise.toml"))).toBe(true);
@@ -258,7 +258,7 @@ describe("addPieces", () => {
 
   it("applies placeholder substitutions to added files", () => {
     addPieces(tmpDir, { ...BASE_OPTIONS, pieces: ["wrangler"] });
-    const content = readFileSync(join(tmpDir, "wrangler.jsonc"), "utf-8");
+    const content = readFileSync(join(tmpDir, "wrangler.json"), "utf-8");
     expect(content).not.toContain("{{workerName}}");
     expect(content).toContain(BASE_OPTIONS.workerName);
   });

package/src/index.ts

@@ -49,7 +49,7 @@ export const PIECES = {
   },
   wrangler: {
     description: "Cloudflare Worker deployment config",
-    paths: ["wrangler.jsonc"],
+    paths: ["wrangler.json"],
   },
   tsconfig: {
     description: "TypeScript config extending shared base",

package/src/integration.test.ts

@@ -0,0 +1,95 @@
+// SPDX-FileCopyrightText: 2026 Knitli Inc.
+//
+// SPDX-License-Identifier: Apache-2.0
+
+import { execFileSync, type SpawnSyncReturns } from "node:child_process";
+import { existsSync, readdirSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+
+const FIXTURE_DIR = join(import.meta.dirname, "../fixture");
+const DIST_DIR = join(FIXTURE_DIR, "dist");
+
+const CONFIG_VARIANTS = [
+  "astro.config.default.ts",
+  "astro.config.codeweaver.ts",
+  "astro.config.stripped.ts",
+  "astro.config.overrides.ts",
+  "astro.config.custom.ts",
+];
+
+/**
+ * Known non-fatal error from the Cloudflare adapter's post-build step.
+ * The adapter tries to read a wrangler.json from the prerender output
+ * directory, which doesn't exist in local builds. The Vite build phases
+ * all complete successfully — this error occurs after bundling is done.
+ */
+const KNOWN_WRANGLER_PRERENDER_ERROR = "Could not read file:" as const;
+const KNOWN_WRANGLER_PRERENDER_PATH =
+  "dist/server/.prerender/wrangler.json" as const;
+
+/**
+ * Run `astro build` for a given config file. Returns stdout+stderr.
+ *
+ * Tolerates the known wrangler prerender error (see above) but re-throws
+ * any other build failure.
+ */
+function astroBuild(configFile: string): { stdout: string; stderr: string } {
+  try {
+    const stdout = execFileSync(
+      "bunx",
+      ["astro", "build", "--config", configFile],
+      {
+        cwd: FIXTURE_DIR,
+        timeout: 120_000,
+        stdio: "pipe",
+        encoding: "utf-8",
+      },
+    );
+    return { stdout, stderr: "" };
+  } catch (err) {
+    const e = err as SpawnSyncReturns<string>;
+    const stderr = e.stderr ?? "";
+    const stdout = e.stdout ?? "";
+    const isKnownWranglerError =
+      stderr.includes(KNOWN_WRANGLER_PRERENDER_ERROR) &&
+      stderr.includes(KNOWN_WRANGLER_PRERENDER_PATH);
+    // Also check that Vite itself didn't report a build failure alongside
+    // the wrangler error — "Build failed" in stderr means a real problem.
+    const hasViteBuildFailure = stderr.includes("Build failed");
+    if (!isKnownWranglerError || hasViteBuildFailure) {
+      throw err;
+    }
+    console.warn(
+      `[${configFile}] tolerated known wrangler prerender error (non-fatal)`,
+    );
+    return { stdout, stderr };
+  }
+}
+
+describe("createConfig integration", { timeout: 180_000 }, () => {
+  afterEach(() => {
+    rmSync(DIST_DIR, { recursive: true, force: true });
+    // Clean up .astro cache between variants
+    rmSync(join(FIXTURE_DIR, ".astro"), { recursive: true, force: true });
+  });
+
+  for (const config of CONFIG_VARIANTS) {
+    const variant = config.replace("astro.config.", "").replace(".ts", "");
+
+    it(`builds successfully with ${variant} config`, () => {
+      astroBuild(config);
+
+      expect(existsSync(DIST_DIR)).toBe(true);
+      expect(existsSync(join(DIST_DIR, "_astro"))).toBe(true);
+
+      // The Cloudflare adapter places all output — including server entries
+      // and public/ files — inside dist/_astro/ (not dist/ root). This is
+      // specific to the @astrojs/cloudflare adapter's asset handling.
+      const astroDir = join(DIST_DIR, "_astro");
+      const files = readdirSync(astroDir);
+      expect(files).toContain("entry.mjs");
+      expect(files).toContain("robots.txt");
+    });
+  }
+});