@decocms/apps-blog 7.2.0

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@decocms/apps-blog",
+  "version": "7.2.0",
+  "type": "module",
+  "description": "Deco app: blog content and CMS integration",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/decocms/blocks.git",
+    "directory": "packages/apps-blog"
+  },
+  "main": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./mod": "./src/mod.ts",
+    "./types": "./src/types.ts",
+    "./loaderMap": "./src/loaderMap.ts",
+    "./loaders/*": "./src/loaders/*.ts",
+    "./core/*": "./src/core/*.ts",
+    "./registry": "./src/registry.ts"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run --root ../.. packages/apps-blog/",
+    "typecheck": "tsc --noEmit",
+    "lint:unused": "knip"
+  },
+  "dependencies": {
+    "@decocms/blocks": "7.2.0",
+    "@decocms/apps-commerce": "7.2.0",
+    "@decocms/apps-website": "7.2.0"
+  },
+  "peerDependencies": {
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
+  },
+  "devDependencies": {
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "knip": "^5.86.0",
+    "typescript": "^5.9.0"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  }
+}

package/src/__tests__/handlePosts.test.ts

@@ -0,0 +1,285 @@
+import { describe, expect, it } from "vitest";
+import handlePosts, {
+	filterPostsByCategory,
+	filterPostsBySlugs,
+	filterPostsByTerm,
+	filterRelatedPosts,
+	slicePosts,
+	sortPosts,
+} from "../core/handlePosts";
+import type { BlogPost, SortBy } from "../types";
+
+function makePost(overrides: Partial<BlogPost> = {}): BlogPost {
+	return {
+		title: "Test Post",
+		slug: "test-post",
+		date: "2024-06-01",
+		excerpt: "A test post",
+		content: "Full content here",
+		categories: [{ name: "News", slug: "news" }],
+		authors: [{ name: "Author", email: "a@b.com" }],
+		...overrides,
+	};
+}
+
+// ---------------------------------------------------------------------------
+// sortPosts
+// ---------------------------------------------------------------------------
+describe("sortPosts", () => {
+	const posts = [
+		makePost({ title: "Alpha", slug: "a", date: "2024-01-01" }),
+		makePost({ title: "Charlie", slug: "c", date: "2024-03-01" }),
+		makePost({ title: "Bravo", slug: "b", date: "2024-02-01" }),
+	];
+
+	it("sorts date_desc — most recent first", () => {
+		const sorted = sortPosts(posts, "date_desc");
+		expect(sorted.map((p) => p.slug)).toEqual(["c", "b", "a"]);
+	});
+
+	it("sorts date_asc — oldest first", () => {
+		const sorted = sortPosts(posts, "date_asc");
+		expect(sorted.map((p) => p.slug)).toEqual(["a", "b", "c"]);
+	});
+
+	it("sorts title_asc", () => {
+		const sorted = sortPosts(posts, "title_asc");
+		// localeCompare(a,b) is negated for asc → Z-A
+		expect(sorted.map((p) => p.title)).toEqual(["Charlie", "Bravo", "Alpha"]);
+	});
+
+	it("sorts title_desc", () => {
+		const sorted = sortPosts(posts, "title_desc");
+		// localeCompare(a,b) kept as-is for desc → A-Z
+		expect(sorted.map((p) => p.title)).toEqual(["Alpha", "Bravo", "Charlie"]);
+	});
+
+	it("falls back to date for invalid sort field", () => {
+		const sorted = sortPosts(posts, "invalid_desc" as SortBy);
+		expect(sorted.map((p) => p.slug)).toEqual(["c", "b", "a"]);
+	});
+
+	it("falls back to desc for invalid sort order", () => {
+		const sorted = sortPosts(posts, "date_wrong" as SortBy);
+		expect(sorted.map((p) => p.slug)).toEqual(["c", "b", "a"]);
+	});
+
+	it("sorts posts with missing date to end", () => {
+		const withMissing = [
+			makePost({ slug: "no-date", date: undefined as unknown as string }),
+			makePost({ slug: "has-date", date: "2024-06-01" }),
+		];
+		const sorted = sortPosts(withMissing, "date_desc");
+		expect(sorted[0].slug).toBe("has-date");
+		expect(sorted[1].slug).toBe("no-date");
+	});
+
+	it("throws on empty array (accesses blogPosts[0])", () => {
+		expect(() => sortPosts([], "date_desc")).toThrow();
+	});
+
+	it("does not mutate original array", () => {
+		const original = [...posts];
+		sortPosts(posts, "date_asc");
+		expect(posts).toEqual(original);
+	});
+});
+
+// ---------------------------------------------------------------------------
+// filterPostsByCategory
+// ---------------------------------------------------------------------------
+describe("filterPostsByCategory", () => {
+	const posts = [
+		makePost({ slug: "a", categories: [{ name: "News", slug: "news" }] }),
+		makePost({
+			slug: "b",
+			categories: [
+				{ name: "News", slug: "news" },
+				{ name: "Tech", slug: "tech" },
+			],
+		}),
+		makePost({ slug: "c", categories: [{ name: "Tech", slug: "tech" }] }),
+	];
+
+	it("returns all posts when no slug provided", () => {
+		expect(filterPostsByCategory(posts)).toHaveLength(3);
+	});
+
+	it("filters by matching slug", () => {
+		const result = filterPostsByCategory(posts, "tech");
+		expect(result.map((p) => p.slug)).toEqual(["b", "c"]);
+	});
+
+	it("returns empty when no match", () => {
+		expect(filterPostsByCategory(posts, "sports")).toEqual([]);
+	});
+
+	it("excludes posts with no categories", () => {
+		const withNone = [...posts, makePost({ slug: "d", categories: undefined })];
+		expect(filterPostsByCategory(withNone, "news").map((p) => p.slug)).toEqual(["a", "b"]);
+	});
+
+	it("includes post when one of multiple categories matches", () => {
+		const result = filterPostsByCategory(posts, "tech");
+		expect(result.find((p) => p.slug === "b")).toBeTruthy();
+	});
+});
+
+// ---------------------------------------------------------------------------
+// filterPostsBySlugs
+// ---------------------------------------------------------------------------
+describe("filterPostsBySlugs", () => {
+	const posts = [makePost({ slug: "a" }), makePost({ slug: "b" }), makePost({ slug: "c" })];
+
+	it("filters to only matching slugs", () => {
+		expect(filterPostsBySlugs(posts, ["a", "c"]).map((p) => p.slug)).toEqual(["a", "c"]);
+	});
+
+	it("returns empty for empty slugs array", () => {
+		expect(filterPostsBySlugs(posts, [])).toEqual([]);
+	});
+});
+
+// ---------------------------------------------------------------------------
+// filterPostsByTerm
+// ---------------------------------------------------------------------------
+describe("filterPostsByTerm", () => {
+	const posts = [
+		makePost({ slug: "a", title: "Hello World", excerpt: "intro", content: "body" }),
+		makePost({ slug: "b", title: "Goodbye", excerpt: "farewell world", content: "end" }),
+		makePost({ slug: "c", title: "Nothing", excerpt: "nope", content: "empty" }),
+	];
+
+	it("matches in title", () => {
+		expect(filterPostsByTerm(posts, "Hello").map((p) => p.slug)).toEqual(["a"]);
+	});
+
+	it("matches in excerpt", () => {
+		expect(filterPostsByTerm(posts, "farewell").map((p) => p.slug)).toEqual(["b"]);
+	});
+
+	it("matches in content", () => {
+		expect(filterPostsByTerm(posts, "empty").map((p) => p.slug)).toEqual(["c"]);
+	});
+
+	it("is case-insensitive", () => {
+		expect(filterPostsByTerm(posts, "hELLo")).toHaveLength(1);
+	});
+
+	it("returns empty when no match", () => {
+		expect(filterPostsByTerm(posts, "zzz")).toEqual([]);
+	});
+});
+
+// ---------------------------------------------------------------------------
+// filterRelatedPosts
+// ---------------------------------------------------------------------------
+describe("filterRelatedPosts", () => {
+	const posts = [
+		makePost({ slug: "a", categories: [{ name: "News", slug: "news" }] }),
+		makePost({ slug: "b", categories: [{ name: "Tech", slug: "tech" }] }),
+		makePost({ slug: "c", categories: undefined }),
+	];
+
+	it("includes post with category overlap", () => {
+		expect(filterRelatedPosts(posts, ["news"]).map((p) => p.slug)).toEqual(["a"]);
+	});
+
+	it("excludes post with no overlap", () => {
+		expect(filterRelatedPosts(posts, ["sports"])).toEqual([]);
+	});
+
+	it("excludes post with no categories", () => {
+		const result = filterRelatedPosts(posts, ["news"]);
+		expect(result.find((p) => p.slug === "c")).toBeUndefined();
+	});
+});
+
+// ---------------------------------------------------------------------------
+// slicePosts
+// ---------------------------------------------------------------------------
+describe("slicePosts", () => {
+	const posts = Array.from({ length: 5 }, (_, i) => makePost({ slug: `p${i + 1}` }));
+
+	it("page 1 returns first N", () => {
+		expect(slicePosts(posts, 1, 2).map((p) => p.slug)).toEqual(["p1", "p2"]);
+	});
+
+	it("page 2 returns next N", () => {
+		expect(slicePosts(posts, 2, 2).map((p) => p.slug)).toEqual(["p3", "p4"]);
+	});
+
+	it("last page with fewer items", () => {
+		expect(slicePosts(posts, 3, 2).map((p) => p.slug)).toEqual(["p5"]);
+	});
+
+	it("page beyond total returns empty", () => {
+		expect(slicePosts(posts, 10, 2)).toEqual([]);
+	});
+});
+
+// ---------------------------------------------------------------------------
+// handlePosts (composition pipeline)
+// ---------------------------------------------------------------------------
+describe("handlePosts", () => {
+	const posts = [
+		makePost({
+			slug: "a",
+			title: "Alpha",
+			date: "2024-01-01",
+			categories: [{ name: "News", slug: "news" }],
+		}),
+		makePost({
+			slug: "b",
+			title: "Bravo",
+			date: "2024-02-01",
+			categories: [{ name: "Tech", slug: "tech" }],
+		}),
+		makePost({
+			slug: "c",
+			title: "Charlie",
+			date: "2024-03-01",
+			categories: [
+				{ name: "News", slug: "news" },
+				{ name: "Tech", slug: "tech" },
+			],
+		}),
+	];
+
+	it("slug string + postSlugs — uses slug filtering", () => {
+		const result = handlePosts(posts, "date_desc", "news", ["a", "c"]);
+		// sorted by date_desc: c (March) before a (Jan)
+		expect(result?.map((p) => p.slug)).toEqual(["c", "a"]);
+	});
+
+	it("slug string + term — chains category + term filters", () => {
+		const result = handlePosts(posts, "date_desc", "news", undefined, "Alpha");
+		expect(result?.map((p) => p.slug)).toEqual(["a"]);
+	});
+
+	it("slug as string[] — triggers related posts path", () => {
+		const result = handlePosts(posts, "date_desc", ["tech"]);
+		expect(result?.map((p) => p.slug)).toEqual(["c", "b"]);
+	});
+
+	it("no slug + term — term-only filtering", () => {
+		const result = handlePosts(posts, "date_asc", undefined, undefined, "Bravo");
+		expect(result).toHaveLength(1);
+		expect(result![0].slug).toBe("b");
+	});
+
+	it("excludePostSlug removes matching post", () => {
+		const result = handlePosts(posts, "date_desc", undefined, undefined, undefined, "b");
+		expect(result?.find((p) => p.slug === "b")).toBeUndefined();
+	});
+
+	it("returns null when result is empty", () => {
+		expect(handlePosts(posts, "date_desc", "nonexistent")).toBeNull();
+	});
+
+	it("returns all posts sorted when no filters given", () => {
+		const result = handlePosts(posts, "date_desc");
+		expect(result).toHaveLength(3);
+		expect(result![0].slug).toBe("c");
+	});
+});

package/src/__tests__/loaders.test.ts

@@ -0,0 +1,207 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+vi.mock("../core/records", () => ({
+	getRecordsByPath: vi.fn(),
+}));
+
+import { getRecordsByPath } from "../core/records";
+import BlogPostItem from "../loaders/BlogPostItem";
+import BlogPostPageLoader from "../loaders/BlogPostPage";
+import BlogpostListing from "../loaders/BlogpostListing";
+import BlogRelatedPostsLoader from "../loaders/BlogRelatedPosts";
+import GetCategories from "../loaders/GetCategories";
+import type { BlogPost, Category } from "../types";
+
+const mockGetRecords = getRecordsByPath as ReturnType<typeof vi.fn>;
+
+function makePost(overrides: Partial<BlogPost> = {}): BlogPost {
+	return {
+		title: "Test Post",
+		slug: "test-post",
+		date: "2024-06-01",
+		excerpt: "A test post",
+		content: "Full content here",
+		categories: [{ name: "News", slug: "news" }],
+		authors: [{ name: "Author", email: "a@b.com" }],
+		...overrides,
+	};
+}
+
+const samplePosts: BlogPost[] = [
+	makePost({ slug: "post-a", title: "Alpha", date: "2024-01-01" }),
+	makePost({ slug: "post-b", title: "Bravo", date: "2024-02-01" }),
+	makePost({ slug: "post-c", title: "Charlie", date: "2024-03-01" }),
+];
+
+beforeEach(() => {
+	vi.clearAllMocks();
+	mockGetRecords.mockReturnValue(samplePosts);
+});
+
+// ---------------------------------------------------------------------------
+// BlogpostListing
+// ---------------------------------------------------------------------------
+describe("BlogpostListing", () => {
+	it("returns paginated listing with defaults (page=1, count=12, sortBy=date_desc)", () => {
+		const result = BlogpostListing({});
+		expect(result).not.toBeNull();
+		expect(result!.posts).toHaveLength(3);
+		expect(result!.pageInfo.currentPage).toBe(1);
+		expect(result!.pageInfo.recordPerPage).toBe(12);
+		// date_desc: most recent first
+		expect(result!.posts[0].slug).toBe("post-c");
+	});
+
+	it("URL search params override props", () => {
+		const req = new Request("http://localhost/blog?page=2&count=1");
+		const result = BlogpostListing({}, req);
+		expect(result).not.toBeNull();
+		expect(result!.pageInfo.currentPage).toBe(2);
+		expect(result!.posts).toHaveLength(1);
+		expect(result!.posts[0].slug).toBe("post-b"); // second page of date_desc
+	});
+
+	it("computes nextPage / previousPage correctly", () => {
+		const result = BlogpostListing({ count: 1, page: 2 });
+		expect(result).not.toBeNull();
+		expect(result!.pageInfo.nextPage).toContain("page=3");
+		expect(result!.pageInfo.previousPage).toContain("page=1");
+	});
+
+	it("returns null when no posts match", () => {
+		mockGetRecords.mockReturnValue([]);
+		expect(BlogpostListing({})).toBeNull();
+	});
+
+	it("SEO canonical strips query params", () => {
+		const req = new Request("http://localhost/blog?page=1&count=1");
+		const result = BlogpostListing({}, req);
+		expect(result).not.toBeNull();
+		expect(result!.seo.canonical).toBe("http://localhost/blog");
+	});
+});
+
+// ---------------------------------------------------------------------------
+// BlogRelatedPosts
+// ---------------------------------------------------------------------------
+describe("BlogRelatedPostsLoader", () => {
+	it("excludes current post via excludePostSlug", () => {
+		const result = BlogRelatedPostsLoader({ excludePostSlug: "post-a" });
+		expect(result).not.toBeNull();
+		expect(result!.find((p) => p.slug === "post-a")).toBeUndefined();
+	});
+
+	it("returns BlogPost[] (not BlogPostListingPage)", () => {
+		const result = BlogRelatedPostsLoader({});
+		expect(Array.isArray(result)).toBe(true);
+	});
+
+	it("returns null when empty", () => {
+		mockGetRecords.mockReturnValue([]);
+		expect(BlogRelatedPostsLoader({})).toBeNull();
+	});
+});
+
+// ---------------------------------------------------------------------------
+// BlogPostPage
+// ---------------------------------------------------------------------------
+describe("BlogPostPageLoader", () => {
+	it("returns BlogPostPage with correct @type", () => {
+		const result = BlogPostPageLoader({ slug: "post-a" });
+		expect(result).not.toBeNull();
+		expect(result!["@type"]).toBe("BlogPostPage");
+		expect(result!.post.slug).toBe("post-a");
+	});
+
+	it("returns null when post not found", () => {
+		expect(BlogPostPageLoader({ slug: "nonexistent" })).toBeNull();
+	});
+
+	it("SEO fields fall back to post fields", () => {
+		mockGetRecords.mockReturnValue([
+			makePost({
+				slug: "no-seo",
+				title: "Fallback Title",
+				excerpt: "Fallback Desc",
+				image: "img.png",
+				seo: undefined,
+			}),
+		]);
+
+		const result = BlogPostPageLoader({ slug: "no-seo" });
+		expect(result).not.toBeNull();
+		expect(result!.seo?.title).toBe("Fallback Title");
+		expect(result!.seo?.description).toBe("Fallback Desc");
+		expect(result!.seo?.image).toBe("img.png");
+	});
+
+	it("uses SEO fields when present", () => {
+		mockGetRecords.mockReturnValue([
+			makePost({
+				slug: "has-seo",
+				title: "Post Title",
+				seo: { title: "SEO Title", description: "SEO Desc" },
+			}),
+		]);
+
+		const result = BlogPostPageLoader({ slug: "has-seo" });
+		expect(result!.seo?.title).toBe("SEO Title");
+		expect(result!.seo?.description).toBe("SEO Desc");
+	});
+});
+
+// ---------------------------------------------------------------------------
+// GetCategories
+// ---------------------------------------------------------------------------
+describe("GetCategories", () => {
+	const categories: Category[] = [
+		{ name: "Beta", slug: "beta" },
+		{ name: "Alpha", slug: "alpha" },
+		{ name: "Charlie", slug: "charlie" },
+	];
+
+	beforeEach(() => {
+		mockGetRecords.mockReturnValue([...categories]);
+	});
+
+	it("sorts by name (title_desc default)", () => {
+		const result = GetCategories({});
+		expect(result).not.toBeNull();
+		expect(result!.map((c) => c.name)).toEqual(["Alpha", "Beta", "Charlie"]);
+	});
+
+	it("filters by slug when provided", () => {
+		const result = GetCategories({ slug: "alpha" });
+		expect(result).toHaveLength(1);
+		expect(result![0].slug).toBe("alpha");
+	});
+
+	it("slices by count", () => {
+		const result = GetCategories({ count: 2 });
+		expect(result).toHaveLength(2);
+	});
+
+	it("returns null when no categories", () => {
+		mockGetRecords.mockReturnValue([]);
+		expect(GetCategories({})).toBeNull();
+	});
+});
+
+// ---------------------------------------------------------------------------
+// BlogPostItem
+// ---------------------------------------------------------------------------
+describe("BlogPostItem", () => {
+	it("returns post by slug", () => {
+		const result = BlogPostItem({ slug: "post-b" });
+		expect(result).not.toBeNull();
+		expect(result!.slug).toBe("post-b");
+	});
+
+	it("returns null when no slug provided", () => {
+		expect(BlogPostItem({ slug: "" })).toBeNull();
+	});
+
+	it("returns null when post not found", () => {
+		expect(BlogPostItem({ slug: "nonexistent" })).toBeNull();
+	});
+});

package/src/__tests__/mod.test.ts

@@ -0,0 +1,11 @@
+import { describe, expect, it } from "vitest";
+import { configure } from "../mod";
+
+describe("blog module", () => {
+	it("returns AppDefinition with name 'blog' and manifest", async () => {
+		const app = await configure({}, async () => null);
+		expect(app.name).toBe("blog");
+		expect(app.manifest).toBeDefined();
+		expect(app.state).toEqual({});
+	});
+});

package/src/__tests__/records.test.ts

@@ -0,0 +1,92 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+vi.mock("@decocms/blocks/cms", () => ({
+	loadBlocks: vi.fn(),
+}));
+
+import { loadBlocks } from "@decocms/blocks/cms";
+import { getRecordsByPath } from "../core/records";
+
+const mockLoadBlocks = loadBlocks as ReturnType<typeof vi.fn>;
+
+beforeEach(() => {
+	vi.clearAllMocks();
+});
+
+describe("getRecordsByPath", () => {
+	it("extracts records matching path prefix", () => {
+		mockLoadBlocks.mockReturnValue({
+			"collections/blog/posts/hello": {
+				name: "collections/blog/posts/hello",
+				post: { title: "Hello", slug: "hello" },
+			},
+			"collections/blog/posts/world": {
+				name: "collections/blog/posts/world",
+				post: { title: "World", slug: "world" },
+			},
+		});
+
+		const result = getRecordsByPath("collections/blog/posts", "post");
+		expect(result).toHaveLength(2);
+		expect(result).toEqual(
+			expect.arrayContaining([
+				expect.objectContaining({ title: "Hello", slug: "hello" }),
+				expect.objectContaining({ title: "World", slug: "world" }),
+			]),
+		);
+	});
+
+	it("skips non-object blocks", () => {
+		mockLoadBlocks.mockReturnValue({
+			"collections/blog/posts/a": "not-an-object",
+			"collections/blog/posts/b": null,
+			"collections/blog/posts/c": {
+				name: "collections/blog/posts/c",
+				post: { title: "C" },
+			},
+		});
+
+		const result = getRecordsByPath("collections/blog/posts", "post");
+		expect(result).toHaveLength(1);
+		expect(result[0]).toEqual(expect.objectContaining({ title: "C" }));
+	});
+
+	it("skips blocks without the accessor field", () => {
+		mockLoadBlocks.mockReturnValue({
+			"collections/blog/posts/x": {
+				name: "collections/blog/posts/x",
+				other: { title: "X" },
+			},
+		});
+
+		const result = getRecordsByPath("collections/blog/posts", "post");
+		expect(result).toEqual([]);
+	});
+
+	it("derives id from block name", () => {
+		mockLoadBlocks.mockReturnValue({
+			"collections/blog/posts/my-post": {
+				name: "collections/blog/posts/my-post",
+				post: { title: "My Post" },
+			},
+		});
+
+		const result = getRecordsByPath<{ title: string; id?: string }>(
+			"collections/blog/posts",
+			"post",
+		);
+		expect(result[0].id).toBe("my-post");
+	});
+
+	it("returns empty array when no blocks match", () => {
+		mockLoadBlocks.mockReturnValue({
+			"collections/blog/categories/cat": {
+				name: "collections/blog/categories/cat",
+				category: { name: "Cat" },
+			},
+		});
+
+		const result = getRecordsByPath("collections/blog/posts", "post");
+		expect(result).toEqual([]);
+	});
+});

package/src/core/handlePosts.ts

@@ -0,0 +1,88 @@
+import type { BlogPost, SortBy } from "../types";
+
+const VALID_SORT_ORDERS = ["asc", "desc"];
+
+/**
+ * Sort posts by the given criteria.
+ * Skips view-based sorting (no Drizzle in this port).
+ */
+export const sortPosts = (blogPosts: BlogPost[], sortBy: SortBy): BlogPost[] => {
+	const parts = sortBy.split("_");
+	const sortMethod = (parts[0] in blogPosts[0] ? parts[0] : "date") as keyof BlogPost;
+	const sortOrder = VALID_SORT_ORDERS.includes(parts[1]) ? parts[1] : "desc";
+
+	return [...blogPosts].sort((a, b) => {
+		if (!a[sortMethod] && !b[sortMethod]) return 0;
+		if (!a[sortMethod]) return 1;
+		if (!b[sortMethod]) return -1;
+
+		const comparison =
+			sortMethod === "date"
+				? new Date(`${b.date}T00:00:00`).getTime() - new Date(`${a.date}T00:00:00`).getTime()
+				: (a[sortMethod]?.toString().localeCompare(b[sortMethod]?.toString() ?? "") ?? 0);
+
+		return sortOrder === "desc" ? comparison : -comparison;
+	});
+};
+
+/** Filter posts by a single category slug. */
+export const filterPostsByCategory = (posts: BlogPost[], slug?: string): BlogPost[] =>
+	slug ? posts.filter(({ categories }) => categories?.find((c) => c.slug === slug)) : posts;
+
+/** Filter posts whose slug is in the given list. */
+export const filterPostsBySlugs = (posts: BlogPost[], postSlugs: string[]): BlogPost[] =>
+	posts.filter(({ slug }) => postSlugs.includes(slug));
+
+/** Filter posts matching a search term (title, excerpt, content). */
+export const filterPostsByTerm = (posts: BlogPost[], term: string): BlogPost[] =>
+	posts.filter(({ content, excerpt, title }) =>
+		[content, excerpt, title].some((field) => field?.toLowerCase().includes(term.toLowerCase())),
+	);
+
+/** Filter posts whose categories overlap with the given slug array. */
+export const filterRelatedPosts = (posts: BlogPost[], slugs: string[]): BlogPost[] =>
+	posts.filter(({ categories }) => categories?.find((c) => slugs.includes(c.slug)));
+
+/** Slice posts for pagination. */
+export const slicePosts = (
+	posts: BlogPost[],
+	pageNumber: number,
+	postsPerPage: number,
+): BlogPost[] => {
+	const startIndex = (pageNumber - 1) * postsPerPage;
+	return posts.slice(startIndex, startIndex + postsPerPage);
+};
+
+/**
+ * Combined filter & sort pipeline (no slice).
+ */
+export default function handlePosts(
+	posts: BlogPost[],
+	sortBy: SortBy,
+	slug?: string | string[],
+	postSlugs?: string[],
+	term?: string,
+	excludePostSlug?: string,
+): BlogPost[] | null {
+	let filtered: BlogPost[];
+
+	if (typeof slug === "string") {
+		filtered =
+			postSlugs && postSlugs.length > 0
+				? filterPostsBySlugs(posts, postSlugs)
+				: filterPostsByCategory(posts, slug);
+		if (term) filtered = filterPostsByTerm(filtered, term);
+	} else if (Array.isArray(slug)) {
+		filtered = filterRelatedPosts(posts, slug);
+	} else {
+		filtered = term ? filterPostsByTerm(posts, term) : posts;
+	}
+
+	if (excludePostSlug) {
+		filtered = filtered.filter(({ slug: s }) => s !== excludePostSlug);
+	}
+
+	if (!filtered || filtered.length === 0) return null;
+
+	return sortPosts(filtered, sortBy);
+}

package/src/core/records.ts

@@ -0,0 +1,30 @@
+import { loadBlocks } from "@decocms/blocks/cms";
+
+/**
+ * Retrieve records from CMS blocks by path prefix.
+ *
+ * Scans the decofile blocks whose key starts with `path` and extracts the
+ * nested value at `accessor` from each matching block.
+ *
+ * Equivalent to the Deno `getRecordsByPath(ctx, path, accessor)` but uses
+ * `loadBlocks()` from `@decocms/blocks/cms` instead of `ctx.get(resolvables)`.
+ */
+export function getRecordsByPath<T>(path: string, accessor: string): T[] {
+	const blocks = loadBlocks() as Record<string, Record<string, unknown>>;
+	const results: T[] = [];
+
+	for (const [key, value] of Object.entries(blocks)) {
+		if (!key.startsWith(path) || !value || typeof value !== "object") {
+			continue;
+		}
+
+		const record = value[accessor] as T | undefined;
+		if (!record) continue;
+
+		const id = (value.name as string | undefined)?.split(path)[1]?.replace("/", "");
+
+		results.push({ ...record, id } as T);
+	}
+
+	return results;
+}

package/src/index.ts

@@ -0,0 +1,24 @@
+/**
+ * Public API for the blog app.
+ */
+
+export { getRecordsByPath } from "./core/records";
+/** @deprecated Use `createBlogLoaders` instead. */
+export {
+	createBlogLoaders,
+	createBlogLoaders as createBlogCommerceLoaders,
+} from "./loaderMap";
+export { configure } from "./mod";
+
+// Types
+export type {
+	Author,
+	BlogPost,
+	BlogPostListingPage,
+	BlogPostPage,
+	Category,
+	ExtraProps,
+	PageInfo,
+	Seo,
+	SortBy,
+} from "./types";

package/src/loaderMap.ts

@@ -0,0 +1,57 @@
+/**
+ * Blog loader map factory for CMS block resolution.
+ *
+ * Returns a `Record<string, LoaderFn>` that the site spreads into its
+ * block loader registry.
+ */
+
+import AuthorLoader from "./loaders/Author";
+import BlogPostItemLoader from "./loaders/BlogPostItem";
+import BlogPostPageLoader from "./loaders/BlogPostPage";
+import BlogpostLoader from "./loaders/Blogpost";
+import BlogpostListingLoader from "./loaders/BlogpostListing";
+import BlogRelatedPostsLoader from "./loaders/BlogRelatedPosts";
+import CategoryLoader from "./loaders/Category";
+import GetCategoriesLoader from "./loaders/GetCategories";
+
+// biome-ignore lint/suspicious/noExplicitAny: loader props/returns vary per block
+export type LoaderFn = (props: any, request?: Request) => Promise<any> | any;
+
+/**
+ * Create the blog loader map.
+ *
+ * @example
+ * ```ts
+ * import { createBlogLoaders } from "@decocms/apps/blog";
+ *
+ * const COMMERCE_LOADERS = {
+ *   ...createVtexCommerceLoaders(),
+ *   ...createBlogLoaders(),
+ * };
+ * ```
+ */
+export function createBlogLoaders(): Record<string, LoaderFn> {
+	return {
+		// Loader keys match the Deno app's __resolveType paths
+		"blog/loaders/BlogPostPage.ts": BlogPostPageLoader,
+		"blog/loaders/BlogPostPage": BlogPostPageLoader,
+		"blog/loaders/BlogpostListing.ts": BlogpostListingLoader,
+		"blog/loaders/BlogpostListing": BlogpostListingLoader,
+		"blog/loaders/BlogRelatedPosts.ts": BlogRelatedPostsLoader,
+		"blog/loaders/BlogRelatedPosts": BlogRelatedPostsLoader,
+		"blog/loaders/GetCategories.ts": GetCategoriesLoader,
+		"blog/loaders/GetCategories": GetCategoriesLoader,
+		"blog/loaders/Blogpost.ts": BlogpostLoader,
+		"blog/loaders/Blogpost": BlogpostLoader,
+		"blog/loaders/Category.ts": CategoryLoader,
+		"blog/loaders/Category": CategoryLoader,
+		"blog/loaders/Author.ts": AuthorLoader,
+		"blog/loaders/Author": AuthorLoader,
+
+		// BlogPostItem: looks up a single post by slug, returns BlogPost
+		"blog/loaders/BlogPostItem.ts": BlogPostItemLoader,
+		"blog/loaders/BlogPostItem": BlogPostItemLoader,
+		"blog/loaders/BlogpostList.ts": BlogpostListingLoader,
+		"blog/loaders/BlogpostList": BlogpostListingLoader,
+	};
+}

package/src/loaders/Author.ts

@@ -0,0 +1,9 @@
+import type { Author } from "../types";
+
+/**
+ * @title Author
+ * @description Defines a blog post author.
+ */
+const loader = ({ author }: { author: Author }): Author => author;
+
+export default loader;

package/src/loaders/BlogPostItem.ts

@@ -0,0 +1,19 @@
+import { getRecordsByPath } from "../core/records";
+import type { BlogPost } from "../types";
+
+export interface Props {
+	slug: string;
+}
+
+/**
+ * @title BlogPostItem
+ * @description Fetches a single blog post by slug. Returns the BlogPost
+ * directly (not wrapped in BlogPostPage).
+ */
+export default function BlogPostItem(props: Props & { __pageUrl?: string }): BlogPost | null {
+	const { slug } = props;
+	if (!slug) return null;
+
+	const posts = getRecordsByPath<BlogPost>("collections/blog/posts", "post");
+	return posts.find((p) => p?.slug === slug) ?? null;
+}

package/src/loaders/BlogPostPage.ts

@@ -0,0 +1,39 @@
+import { getRecordsByPath } from "../core/records";
+import type { BlogPost, BlogPostPage } from "../types";
+
+const COLLECTION_PATH = "collections/blog/posts";
+const ACCESSOR = "post";
+
+export interface Props {
+	slug: string;
+}
+
+/**
+ * @title BlogPostPage
+ * @description Fetches a specific blog post page by its slug.
+ */
+export default function BlogPostPageLoader(
+	props: Props & { __pageUrl?: string },
+	req?: Request,
+): BlogPostPage | null {
+	const { slug } = props;
+	const posts = getRecordsByPath<BlogPost>(COLLECTION_PATH, ACCESSOR);
+
+	const rawUrl = req?.url ?? props.__pageUrl ?? "http://localhost/";
+	const url = new URL(rawUrl);
+	const post = posts.find((p) => p?.slug === slug);
+
+	if (!post) return null;
+
+	return {
+		"@type": "BlogPostPage",
+		post,
+		seo: {
+			title: post?.seo?.title || post?.title,
+			description: post?.seo?.description || post?.excerpt,
+			canonical: post?.seo?.canonical || url.href,
+			image: post?.seo?.image || post?.image,
+			noIndexing: post?.seo?.noIndexing || false,
+		},
+	};
+}

package/src/loaders/BlogRelatedPosts.ts

@@ -0,0 +1,66 @@
+import handlePosts, { slicePosts } from "../core/handlePosts";
+import { getRecordsByPath } from "../core/records";
+import type { BlogPost, SortBy } from "../types";
+
+const COLLECTION_PATH = "collections/blog/posts";
+const ACCESSOR = "post";
+
+export interface Props {
+	/**
+	 * @title Items per page
+	 * @description Number of posts per page to display.
+	 */
+	count?: number;
+	/**
+	 * @title Page query parameter
+	 * @description The current page number. Defaults to 1.
+	 */
+	page?: number;
+	/**
+	 * @title Category Slug
+	 * @description Filter by a specific category slug.
+	 */
+	slug?: string | string[];
+	/**
+	 * @title Page sorting parameter
+	 * @description The sorting option. Default is "date_desc"
+	 */
+	sortBy?: SortBy;
+	/**
+	 * @description Overrides the query term at url
+	 */
+	query?: string;
+	/**
+	 * @title Exclude Post Slug
+	 * @description Excludes a post slug from the list
+	 */
+	excludePostSlug?: string;
+}
+
+export type BlogRelatedPosts = BlogPost[] | null;
+
+/**
+ * @title BlogRelatedPosts
+ * @description Retrieves a list of blog related posts.
+ */
+export default function BlogRelatedPostsLoader(
+	props: Props & { __pageUrl?: string },
+	req?: Request,
+): BlogRelatedPosts {
+	const { page, count, slug, sortBy, query, excludePostSlug } = props;
+	const rawUrl = req?.url ?? props.__pageUrl ?? "http://localhost/";
+	const url = new URL(rawUrl);
+	const postsPerPage = Number(count ?? url.searchParams.get("count") ?? 12);
+	const pageNumber = Number(page ?? url.searchParams.get("page") ?? 1);
+	const pageSort = sortBy ?? (url.searchParams.get("sortBy") as SortBy) ?? "date_desc";
+	const term = query ?? url.searchParams.get("q") ?? undefined;
+
+	const posts = getRecordsByPath<BlogPost>(COLLECTION_PATH, ACCESSOR);
+
+	const handledPosts = handlePosts(posts, pageSort, slug, undefined, term, excludePostSlug);
+
+	if (!handledPosts) return null;
+
+	const slicedPosts = slicePosts(handledPosts, pageNumber, postsPerPage);
+	return slicedPosts.length > 0 ? slicedPosts : null;
+}

package/src/loaders/Blogpost.ts

@@ -0,0 +1,9 @@
+import type { BlogPost } from "../types";
+
+/**
+ * @title Blogpost
+ * @description Defines a blog post.
+ */
+const loader = ({ post }: { post: BlogPost }): BlogPost => post;
+
+export default loader;

package/src/loaders/BlogpostListing.ts

@@ -0,0 +1,101 @@
+import handlePosts, { slicePosts } from "../core/handlePosts";
+import { getRecordsByPath } from "../core/records";
+import type { BlogPost, BlogPostListingPage, PageInfo, SortBy } from "../types";
+
+const COLLECTION_PATH = "collections/blog/posts";
+const ACCESSOR = "post";
+
+export interface Props {
+	/**
+	 * @title Category Slug
+	 * @description Filter by a specific category slug.
+	 */
+	slug?: string;
+	/**
+	 * @title Items per page
+	 * @description Number of posts per page to display.
+	 */
+	count?: number;
+	/**
+	 * @title Page query parameter
+	 * @description The current page number. Defaults to 1.
+	 */
+	page?: number;
+	/**
+	 * @title Page sorting parameter
+	 * @description The sorting option. Default is "date_desc"
+	 */
+	sortBy?: SortBy;
+	/**
+	 * @description Overrides the query term at url
+	 */
+	query?: string;
+}
+
+/**
+ * @title BlogPostList
+ * @description Retrieves a paginated list of blog posts.
+ */
+export default function BlogPostList(
+	props: Props & { __pageUrl?: string },
+	req?: Request,
+): BlogPostListingPage | null {
+	const { page, count, slug, sortBy, query } = props;
+	const rawUrl = req?.url ?? props.__pageUrl ?? "http://localhost/";
+	const url = new URL(rawUrl);
+	const params = url.searchParams;
+	const postsPerPage = Number(count ?? params.get("count") ?? 12);
+	const pageNumber = Number(page ?? params.get("page") ?? 1);
+	const pageSort = sortBy ?? (params.get("sortBy") as SortBy) ?? "date_desc";
+	const term = query ?? params.get("q") ?? undefined;
+
+	const posts = getRecordsByPath<BlogPost>(COLLECTION_PATH, ACCESSOR);
+
+	try {
+		const handledPosts = handlePosts(posts, pageSort, slug, undefined, term);
+
+		if (!handledPosts) return null;
+
+		const slicedPosts = slicePosts(handledPosts, pageNumber, postsPerPage);
+		if (slicedPosts.length === 0) return null;
+
+		const category = slicedPosts[0].categories?.find((c) => c.slug === slug);
+
+		return {
+			posts: slicedPosts,
+			pageInfo: toPageInfo(handledPosts, postsPerPage, pageNumber, params),
+			seo: {
+				title: category?.name ?? "",
+				canonical: new URL(url.pathname, url.origin).href,
+			},
+		};
+	} catch (e) {
+		console.error("[BlogpostListing]", e);
+		return null;
+	}
+}
+
+function toPageInfo(
+	posts: BlogPost[],
+	postsPerPage: number,
+	pageNumber: number,
+	params: URLSearchParams,
+): PageInfo {
+	const totalPosts = posts.length;
+	const totalPages = Math.ceil(totalPosts / postsPerPage);
+	const hasNextPage = totalPages > pageNumber;
+	const hasPrevPage = pageNumber > 1;
+	const nextPage = new URLSearchParams(params);
+	const previousPage = new URLSearchParams(params);
+
+	if (hasNextPage) nextPage.set("page", (pageNumber + 1).toString());
+	if (hasPrevPage) previousPage.set("page", (pageNumber - 1).toString());
+
+	return {
+		nextPage: hasNextPage ? `?${nextPage}` : undefined,
+		previousPage: hasPrevPage ? `?${previousPage}` : undefined,
+		currentPage: pageNumber,
+		records: totalPosts,
+		recordPerPage: postsPerPage,
+	};
+}

package/src/loaders/Category.ts

@@ -0,0 +1,9 @@
+import type { Category } from "../types";
+
+/**
+ * @title Category
+ * @description Defines a blog post category.
+ */
+const loader = ({ category }: { category: Category }): Category => category;
+
+export default loader;

package/src/loaders/GetCategories.ts

@@ -0,0 +1,48 @@
+import { getRecordsByPath } from "../core/records";
+import type { Category } from "../types";
+
+const COLLECTION_PATH = "collections/blog/categories";
+const ACCESSOR = "category";
+
+export interface Props {
+	/**
+	 * @title Category Slug
+	 * @description Get the category data from a specific slug.
+	 */
+	slug?: string;
+	/**
+	 * @title Items count
+	 * @description Number of categories to return
+	 */
+	count?: number;
+	/**
+	 * @title Sort
+	 * @description The sorting option. Default is "title_desc"
+	 */
+	sortBy?: "title_asc" | "title_desc";
+}
+
+/**
+ * @title GetCategories
+ * @description Retrieves a list of blog categories.
+ */
+export default function GetCategories({
+	count,
+	slug,
+	sortBy = "title_desc",
+}: Props): Category[] | null {
+	const categories = getRecordsByPath<Category>(COLLECTION_PATH, ACCESSOR);
+
+	if (!categories?.length) return null;
+
+	if (slug) {
+		return categories.filter((c) => c.slug === slug);
+	}
+
+	const sortedCategories = categories.sort((a, b) => {
+		const comparison = a.name.localeCompare(b.name);
+		return sortBy.endsWith("_desc") ? comparison : -comparison;
+	});
+
+	return count ? sortedCategories.slice(0, count) : sortedCategories;
+}

package/src/mod.ts

@@ -0,0 +1,55 @@
+/**
+ * Blog app module — standard autoconfig contract.
+ *
+ * Exports `configure` following the AppModContract pattern.
+ * Provides blog post, category, and author loaders for the site.
+ */
+
+import type {
+	AppDefinition,
+	ResolveSecretFn,
+} from "@decocms/apps-commerce/app-types";
+import manifest from "./manifest.gen";
+
+// -------------------------------------------------------------------------
+// CMS Props
+// -------------------------------------------------------------------------
+
+/** @title Deco Blog */
+export interface Props {
+	/**
+	 * @title Page Slug
+	 * @description The slug of the BlogPostPage to embed. Use :category and :slug.
+	 */
+	pageSlug?: string;
+}
+
+export type BlogState = Props;
+
+// -------------------------------------------------------------------------
+// Configure
+// -------------------------------------------------------------------------
+
+/**
+ * Configure the Blog app from CMS block data.
+ * Always returns an AppDefinition (no required fields).
+ */
+export async function configure(
+	// biome-ignore lint/suspicious/noExplicitAny: block data comes from CMS with no fixed schema
+	_block: any,
+	_resolveSecret: ResolveSecretFn,
+): Promise<AppDefinition<BlogState>> {
+	return {
+		name: "blog",
+		manifest,
+		state: { pageSlug: _block?.pageSlug },
+	};
+}
+
+/** Placeholder preview for CMS editor. */
+export const preview = undefined;
+
+/** Default export for schema generation and Deno-style app bridges. */
+export default function Blog(state: Props) {
+	return { state };
+}

package/src/registry.ts

@@ -0,0 +1,9 @@
+import type { AppRegistryEntry } from "@decocms/apps-commerce/registry";
+
+export const BLOG_REGISTRY_ENTRY: AppRegistryEntry = {
+	blockKey: "deco-blog",
+	module: () => import("./mod"),
+	displayName: "Blog",
+	category: "content",
+	description: "Blog posts, categories, and authors from CMS collections",
+};

package/src/types.ts

@@ -0,0 +1,105 @@
+import type { ImageWidget } from "@decocms/apps-website/types";
+
+/**
+ * @titleBy name
+ * @widget author
+ */
+export interface Author {
+	name: string;
+	email: string;
+	avatar?: ImageWidget;
+	jobTitle?: string;
+	company?: string;
+}
+
+export interface Category {
+	name: string;
+	slug: string;
+}
+
+export interface BlogPost {
+	title: string;
+	excerpt: string;
+	/**
+	 * @title Main image
+	 */
+	image?: ImageWidget;
+	/**
+	 * @title Alt text for the image
+	 */
+	alt?: string;
+	/**
+	 * @widget blog
+	 * @collection authors
+	 */
+	authors?: Author[];
+	/**
+	 * @widget blog
+	 * @collection categories
+	 */
+	categories?: Category[];
+	/**
+	 * @format date
+	 */
+	date: string;
+	slug: string;
+	/**
+	 * @title Post Content
+	 * @format rich-text
+	 */
+	content?: string;
+	/**
+	 * @title Sections
+	 * @label hidden
+	 * @changeable true
+	 */
+	sections?: unknown[];
+	/**
+	 * @title SEO
+	 */
+	seo?: Seo;
+	/**
+	 * @title ReadTime in minutes
+	 */
+	readTime?: number;
+	/**
+	 * @title Extra Props
+	 */
+	extraProps?: ExtraProps[];
+	id?: string;
+}
+
+export interface ExtraProps {
+	key: string;
+	value: string;
+}
+
+export interface Seo {
+	title?: string;
+	description?: string;
+	image?: ImageWidget;
+	canonical?: string;
+	noIndexing?: boolean;
+}
+
+export interface BlogPostPage {
+	"@type": "BlogPostPage";
+	post: BlogPost;
+	seo?: Seo | null;
+}
+
+export type SortBy = "date_desc" | "date_asc" | "title_asc" | "title_desc";
+
+export interface PageInfo {
+	nextPage?: string;
+	previousPage?: string;
+	currentPage: number;
+	records?: number;
+	recordPerPage?: number;
+}
+
+export interface BlogPostListingPage {
+	posts: BlogPost[];
+	pageInfo: PageInfo;
+	seo: Seo;
+}

package/tsconfig.json

@@ -0,0 +1,7 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "dist"
+  },
+  "include": ["src/**/*"]
+}