@websline/cms-view-utils 1.7.2 → 1.8.0

package/package.json

@@ -1,43 +1,48 @@
 {
-	"name": "@websline/cms-view-utils",
-	"version": "1.7.2",
-	"type": "module",
-	"files": [
-		"src",
-		"dist"
-	],
-	"exports": {
-		".": "./src/index.js",
-		"./server": "./src/server.js",
-		"./components/*": "./src/components/*",
-		"./preview-bridge": "./dist/previewBridge.global.js",
-		"./edit-scroll": "./dist/editScroll.global.js",
-		"./dist/*": "./dist/*"
-	},
-	"dependencies": {
-		"jsonwebtoken": "^9.0.3",
-		"tailwind-merge": "^3.6.0"
-	},
-	"devDependencies": {
-		"@eslint/compat": "^2.1.0",
-		"@eslint/js": "^10.0.1",
-		"eslint": "^10.9.0",
-		"eslint-config-prettier": "^10.1.8",
-		"eslint-plugin-svelte": "^3.23.0",
-		"globals": "^17.11.0",
-		"prettier": "^3.9.6",
-		"prettier-plugin-svelte": "^4.1.1",
-		"prettier-plugin-tailwindcss": "^0.8.1",
-		"tsup": "^8.5.1"
-	},
-	"peerDependencies": {
-		"svelte": "^5.0.0"
-	},
-	"scripts": {
-		"build": "tsup",
-		"prepublishOnly": "pnpm build",
-		"format": "prettier --write .",
-		"lint": "prettier --check . && eslint ."
-	},
-	"sideEffects": false
-}
+  "name": "@websline/cms-view-utils",
+  "version": "1.8.0",
+  "type": "module",
+  "files": [
+    "src",
+    "dist",
+    "!src/**/*.test.js"
+  ],
+  "exports": {
+    ".": "./src/index.js",
+    "./server": "./src/server.js",
+    "./integration": "./src/integration/cmsRoutes.js",
+    "./routes/*": "./src/routes/*",
+    "./components/*": "./src/components/*",
+    "./preview-bridge": "./dist/previewBridge.global.js",
+    "./edit-scroll": "./dist/editScroll.global.js",
+    "./dist/*": "./dist/*"
+  },
+  "dependencies": {
+    "jsonwebtoken": "^9.0.3",
+    "tailwind-merge": "^3.7.0"
+  },
+  "devDependencies": {
+    "@eslint/compat": "^2.1.1",
+    "@eslint/js": "^10.0.1",
+    "eslint": "^10.11.0",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-svelte": "^3.23.0",
+    "globals": "^17.12.0",
+    "prettier": "^3.9.8",
+    "prettier-plugin-svelte": "^4.1.1",
+    "prettier-plugin-tailwindcss": "^0.8.1",
+    "tsup": "^8.5.1",
+    "vitest": "^5.0.1"
+  },
+  "peerDependencies": {
+    "astro": ">=5",
+    "svelte": "^5.0.0"
+  },
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsup",
+    "format": "prettier --write .",
+    "lint": "prettier --check . && eslint .",
+    "test": "vitest run"
+  }
+}

package/src/integration/cmsRoutes.js

@@ -0,0 +1,62 @@
+import { CMS_ROUTE_PATTERN } from "../shared/routes.js";
+
+/**
+ * Astro integration that ships the CMS-backed routes every website needs, so a
+ * site repository does not have to re-declare them. A project file of the same
+ * pattern wins over the injected route; `exclude` makes that intent explicit.
+ */
+
+const INJECTED_ROUTES = {
+	"/robots.txt": "@websline/cms-view-utils/routes/robots.txt.js",
+	"/sitemap.xml": "@websline/cms-view-utils/routes/sitemap.xml.js",
+	"/llms.txt": "@websline/cms-view-utils/routes/llms.txt.js",
+	"/api/cms/[...path]": "@websline/cms-view-utils/routes/cmsProxy.js",
+};
+
+/**
+ * @param {object} [options]
+ * @param {string[]} [options.exclude] - route patterns the project provides itself
+ * @param {string} [options.cmsRoutePattern] - route pattern of the CMS catch-all page
+ */
+const cmsRoutes = (options = {}) => {
+	const { exclude = [], cmsRoutePattern = CMS_ROUTE_PATTERN } = options;
+
+	return {
+		name: "@websline/cms-view-utils",
+		hooks: {
+			"astro:config:setup": ({ injectRoute }) => {
+				for (const [pattern, entrypoint] of Object.entries(INJECTED_ROUTES)) {
+					if (exclude.includes(pattern)) continue;
+
+					injectRoute({ pattern, entrypoint });
+				}
+			},
+			"astro:routes:resolved": ({ routes, logger }) => {
+				const hasCmsRoute = routes.some((route) => route.pattern === cmsRoutePattern);
+
+				if (!hasCmsRoute) {
+					throw new Error(
+						`@websline/cms-view-utils: no route matches "${cmsRoutePattern}". ` +
+							"The CMS middleware only runs for that route, so every page would " +
+							"render without CMS data. Add src/pages/[...path].astro or pass " +
+							"cmsRoutePattern to cmsRoutes() and createCmsMiddleware().",
+					);
+				}
+
+				for (const pattern of Object.keys(INJECTED_ROUTES)) {
+					const origins = routes
+						.filter((route) => route.pattern === pattern)
+						.map((route) => route.origin);
+
+					if (origins.includes("project") && origins.includes("external")) {
+						logger.info(
+							`Project route "${pattern}" overrides the injected one. Pass it in cmsRoutes({ exclude }) to make that explicit.`,
+						);
+					}
+				}
+			},
+		},
+	};
+};
+
+export { cmsRoutes };

package/src/middleware/createCmsMiddleware.js

@@ -1,5 +1,7 @@
 import { withRequestFilter } from "./withRequestFilter.js";
 import { withCmsFetch } from "./withCmsFetch.js";
+import { CMS_ROUTE_PATTERN } from "../shared/routes.js";
+import { HttpError } from "../shared/errors.js";
 
 const defaultErrorHandler = (context, error, wrap) => {
 	const status = error?.status ?? 500;
@@ -11,7 +13,12 @@ const defaultErrorHandler = (context, error, wrap) => {
 /**
  * Composes the standard CMS middleware pipeline.
  *
+ * The CMS catch-all route renders CMS data and nothing else, so a request that
+ * reaches it without running the pipeline is answered 404 instead of rendering
+ * an empty page.
+ *
  * @param {object} [options]
+ * @param {string} [options.cmsRoutePattern] - route pattern of the CMS catch-all page
  * @param {(context: import("astro").APIContext) => boolean} [options.shouldSkip] - filter that decides if request bypasses the pipeline
  * @param {(context: import("astro").APIContext) => Promise<void>} [options.fetch] - CMS fetch step
  * @param {(context: import("astro").APIContext, handler: () => any) => Promise<Response>} [options.paraglide] - i18n wrapper (optional)
@@ -21,7 +28,8 @@ const defaultErrorHandler = (context, error, wrap) => {
  */
 const createCmsMiddleware = (options = {}) => {
 	const {
-		shouldSkip = withRequestFilter(),
+		cmsRoutePattern = CMS_ROUTE_PATTERN,
+		shouldSkip = withRequestFilter({ cmsRoutePattern }),
 		fetch = withCmsFetch(),
 		paraglide,
 		beforeFetch,
@@ -33,6 +41,10 @@ const createCmsMiddleware = (options = {}) => {
 
 	return async (context, next) => {
 		if (shouldSkip(context)) {
+			if (context.routePattern === cmsRoutePattern) {
+				return onError(context, new HttpError(404, "Not Found"), wrap);
+			}
+
 			return next();
 		}
 

package/src/middleware/withRequestFilter.js

@@ -1,33 +1,39 @@
+import { CMS_ROUTE_PATTERN } from "../shared/routes.js";
+
 /**
- * Default request filter — skips internal Astro routes, error routes
- * and asset paths (by file extension).
+ * Default request filter — the CMS pipeline runs for the catch-all route only.
+ *
+ * Every other route Astro matched is its own (a project page, an endpoint, an
+ * injected route) and must not be fed CMS data. Static files never get here:
+ * Astro drops them before route matching, and the server in front serves them.
+ *
+ * Requires `context.routePattern` (Astro 5 or newer).
  *
  * @param {object} [options]
+ * @param {string} [options.cmsRoutePattern] - route pattern of the CMS catch-all page
  * @param {string[]} [options.additionalExcludePaths] - extra path prefixes to skip
  * @param {(context: import("astro").APIContext) => boolean} [options.customFilter] - additional skip predicate
  */
-
 const withRequestFilter = (options = {}) => {
-	const { additionalExcludePaths = [], customFilter } = options;
+	const {
+		cmsRoutePattern = CMS_ROUTE_PATTERN,
+		additionalExcludePaths = [],
+		customFilter,
+	} = options;
 
 	return (context) => {
-		const { request, url } = context;
+		const { request, url, routePattern } = context;
 
-		const isAstroInternal = url.pathname.startsWith("/_astro");
-		const isErrorRoute = url.pathname.startsWith("/errors/");
-		const hasFileExtension = /\.[a-zA-Z0-9]+$/.test(url.pathname);
+		const isNonGet = request.method !== "GET";
+		const isOwnAstroRoute = routePattern !== cmsRoutePattern;
 		const isExcludedPath = additionalExcludePaths.some((p) =>
 			url.pathname.startsWith(p),
 		);
-		const isAstroApiCall = url.pathname.startsWith("/api/");
 
 		return (
-			request.method !== "GET" ||
-			isAstroInternal ||
-			isErrorRoute ||
-			hasFileExtension ||
+			isNonGet ||
+			isOwnAstroRoute ||
 			isExcludedPath ||
-			isAstroApiCall ||
 			customFilter?.(context) === true
 		);
 	};

package/src/routes/cmsProxy.js

@@ -0,0 +1,5 @@
+import { createCmsProxyHandler } from "../cms/proxyToCms.js";
+
+export const prerender = false;
+
+export const GET = createCmsProxyHandler();

package/src/routes/llms.txt.js

@@ -0,0 +1,5 @@
+import { createLlmsTxtHandler } from "../handlers/llmsTxtHandler.js";
+
+export const prerender = false;
+
+export const GET = createLlmsTxtHandler();

package/src/routes/robots.txt.js

@@ -0,0 +1,5 @@
+import { createRobotsHandler } from "../handlers/robotsHandler.js";
+
+export const prerender = false;
+
+export const GET = createRobotsHandler();

package/src/routes/sitemap.xml.js

@@ -0,0 +1,5 @@
+import { createSitemapHandler } from "../handlers/sitemapHandler.js";
+
+export const prerender = false;
+
+export const GET = createSitemapHandler();

package/src/server.js

@@ -8,3 +8,4 @@ export { createSitemapHandler } from "./handlers/sitemapHandler.js";
 export { createRobotsHandler } from "./handlers/robotsHandler.js";
 export { createLlmsTxtHandler } from "./handlers/llmsTxtHandler.js";
 export { createCmsProxyHandler } from "./cms/proxyToCms.js";
+export { CMS_ROUTE_PATTERN } from "./shared/routes.js";

package/src/shared/routes.js

@@ -0,0 +1,7 @@
+/**
+ * The route pattern of the CMS catch-all page. The middleware pipeline and the
+ * injected routes both key off it, so it lives in one place.
+ */
+const CMS_ROUTE_PATTERN = "/[...path]";
+
+export { CMS_ROUTE_PATTERN };