@wix/agent-skills 1.26.0 → 1.27.0

package/skills/wix-headless-templates/blog/app-astro/pages/blog/category/[slug].astro

@@ -0,0 +1,97 @@
+---
+// Category page — the feed filtered to one category, with the category's header.
+//
+// This is a Wix ITEM PAGE too: the wixMetadata export + <SEO.Tags> (BLOG_CATEGORY) let the site
+// owner edit its title/description in the dashboard and register the route in the sitemap. Keep
+// the SEO pieces and this frontmatter; restyle the template. The first page is fetched
+// SERVER-SIDE with the category filter and seeded into the island together with the filter id, so
+// the island trusts it and fetches nothing on load. An unknown slug is a real 404 (Wix's own router
+// answers 200 with an empty feed; on a headless site a page that exists for no category is a 404).
+import SiteLayout from "../../../layouts/SiteLayout.astro";
+import BlogFeedView from "../../../components/blog/BlogFeedView";
+import { categoryPath, fetchPosts } from "../../../wix/blog/posts";
+import { fetchBlogCategories, fetchBlogTags, fetchCategoryBySlug } from "../../../wix/blog/taxonomy";
+import type { BlogCategory, BlogTag, PostPage } from "../../../wix/blog/types";
+import { WIX_APPS } from "@wix/essentials";
+import { SEO } from "@wix/seo/components";
+import { loadSEOTagsServiceConfig } from "@wix/seo/services";
+import { seoTags } from "@wix/seo";
+
+export const wixMetadata = {
+  appDefId: WIX_APPS.blogs.id,
+  pageIdentifier: WIX_APPS.blogs.categoryPageMetadata.pageIdentifier,
+  identifiers: {
+    slug: WIX_APPS.blogs.categoryPageMetadata.identifiers.slug,
+  },
+};
+
+const slug = Astro.params.slug;
+if (!slug) {
+  return new Response(null, { status: 404 });
+}
+
+// Behind Wix's proxy the request URL is internal — the real public page URL arrives on
+// x-wix-forwarded-url; the SEO service needs the public one.
+const forwardedUrl = Astro.request.headers.get("x-wix-forwarded-url");
+const pageUrl =
+  forwardedUrl && URL.canParse(forwardedUrl) && /^https?:$/.test(new URL(forwardedUrl).protocol)
+    ? forwardedUrl
+    : Astro.url.href;
+
+let category: BlogCategory | null = null;
+let page: PostPage | undefined;
+let categories: BlogCategory[] = [];
+let tags: BlogTag[] = [];
+let seoTagsServiceConfig = null;
+try {
+  [category, categories, tags, seoTagsServiceConfig] = await Promise.all([
+    fetchCategoryBySlug(slug),
+    fetchBlogCategories(),
+    fetchBlogTags(),
+    loadSEOTagsServiceConfig({
+      pageUrl,
+      itemType: seoTags.ItemType.BLOG_CATEGORY,
+      itemData: { slug },
+    }).catch(() => null),
+  ]);
+  if (category) page = await fetchPosts({ categoryId: category.id });
+} catch {
+  // Guarded: an unhandled SSR throw truncates the response mid-stream. With no seed the island
+  // fetches the filtered page client-side and shows its own error state.
+}
+
+if (!category) {
+  return new Response(null, { status: 404 });
+}
+
+// One source of head tags: the SEO service when it resolved; else the category's own SEO title
+// (the dashboard's title tag) → its label, and its description.
+const head = seoTagsServiceConfig ? {} : { title: category.title || category.label, description: category.description || undefined };
+---
+
+<SiteLayout {...head}>
+  <SEO.Tags seoTagsServiceConfig={seoTagsServiceConfig} slot="seo-tags" />
+
+  <header class="mb-10">
+    {
+      category.coverUrl && (
+        <div class="mb-6 aspect-[16/9] max-h-[40vh] overflow-hidden rounded-xl bg-secondary">
+          <img src={category.coverUrl} alt={category.label} class="h-full w-full object-cover" />
+        </div>
+      )
+    }
+    <p class="eyebrow">Category</p>
+    <h1 class="mt-2 text-2xl font-semibold tracking-tight">{category.label}</h1>
+    {category.description && <p class="mt-3 max-w-2xl text-muted-foreground">{category.description}</p>}
+  </header>
+
+  <BlogFeedView
+    client:load
+    initialPage={page}
+    initialCategoryId={category.id}
+    initialCategories={categories}
+    initialTags={tags}
+    categoryHref={categoryPath}
+    emptyMessage="No posts in this category yet."
+  />
+</SiteLayout>

package/skills/wix-headless-templates/blog/app-astro/pages/blog/tag/[slug].astro

@@ -0,0 +1,51 @@
+---
+// Tag page — the feed filtered to one tag, with the tag's label as its header (a tag carries no
+// description or cover). No SEO item type exists for tags (the enum has BLOG_POST and BLOG_CATEGORY
+// only) and Wix's own sitemap lists no tag pages, so this page is a plain page: the layout's
+// title comes from the tag's label. Keep the frontmatter; restyle the template. The first page is
+// fetched SERVER-SIDE with the tag filter and seeded together with the filter id. An unknown slug is
+// a real 404 (Wix's router answers 200 + empty feed; on a headless site that page does not exist).
+import SiteLayout from "../../../layouts/SiteLayout.astro";
+import BlogFeedView from "../../../components/blog/BlogFeedView";
+import { categoryPath, fetchPosts } from "../../../wix/blog/posts";
+import { fetchBlogCategories, fetchBlogTags, fetchTagBySlug } from "../../../wix/blog/taxonomy";
+import type { BlogCategory, BlogTag, PostPage } from "../../../wix/blog/types";
+
+const slug = Astro.params.slug;
+if (!slug) {
+  return new Response(null, { status: 404 });
+}
+
+let tag: BlogTag | null = null;
+let page: PostPage | undefined;
+let categories: BlogCategory[] = [];
+let tags: BlogTag[] = [];
+try {
+  [tag, categories, tags] = await Promise.all([fetchTagBySlug(slug), fetchBlogCategories(), fetchBlogTags()]);
+  if (tag) page = await fetchPosts({ tagId: tag.id });
+} catch {
+  // Guarded: an unhandled SSR throw truncates the response mid-stream. With no seed the island
+  // fetches the filtered page client-side and shows its own error state.
+}
+
+if (!tag) {
+  return new Response(null, { status: 404 });
+}
+---
+
+<SiteLayout title={tag.label}>
+  <header class="mb-10">
+    <p class="eyebrow">Tag</p>
+    <h1 class="mt-2 text-2xl font-semibold tracking-tight">{tag.label}</h1>
+  </header>
+
+  <BlogFeedView
+    client:load
+    initialPage={page}
+    initialTagId={tag.id}
+    initialCategories={categories}
+    initialTags={tags}
+    categoryHref={categoryPath}
+    emptyMessage="No posts with this tag yet."
+  />
+</SiteLayout>

package/skills/wix-headless-templates/blog/app-astro/pages/blog.astro

@@ -0,0 +1,34 @@
+---
+// Blog index — data fetched SERVER-SIDE (SEO) and handed to the island as DTO props.
+// Keep this frontmatter; swap the island import to YOUR feed component. The category pills link
+// to the category pages (/blog/category/<slug>) so every filter has a URL; pass no `categoryHref`
+// for client-side filtering instead.
+import SiteLayout from "../layouts/SiteLayout.astro";
+import BlogFeedView from "../components/blog/BlogFeedView";
+import { categoryPath, fetchPosts } from "../wix/blog/posts";
+import { fetchBlogCategories, fetchBlogTags } from "../wix/blog/taxonomy";
+import type { BlogCategory, BlogTag, PostPage } from "../wix/blog/types";
+
+let page: PostPage | undefined;
+let categories: BlogCategory[] = [];
+let tags: BlogTag[] = [];
+let failed = false;
+try {
+  [page, categories, tags] = await Promise.all([fetchPosts(), fetchBlogCategories(), fetchBlogTags()]);
+} catch {
+  // An unguarded SSR throw truncates the response mid-stream. With no seed the island fetches
+  // client-side and shows its own error state — never "No posts yet" for a failed read.
+  failed = true;
+}
+---
+
+<SiteLayout title="Blog">
+  <h1 class="mb-8 text-2xl font-semibold tracking-tight">Blog</h1>
+  <BlogFeedView
+    client:load
+    initialPage={failed ? undefined : page}
+    initialCategories={categories}
+    initialTags={tags}
+    categoryHref={categoryPath}
+  />
+</SiteLayout>

package/skills/wix-headless-templates/blog/project/README.md

@@ -0,0 +1,15 @@
+# Wix Astro Blank Template
+
+**[Live demo](https://h6s-1a31f9730cd85b-headlessstack.wix-site-host.com)**
+
+Our Astro templates are still in development and subject to change.
+
+To use a template, follow the [Wix CLI for Headless Quick Start](https://dev.wix.com/docs/go-headless/get-started/quick-starts/wix-managed-headless/quick-start-with-the-wix-cli), and select the desired template during the setup process.
+
+## Need help?
+
+For documentation and support, check out:
+
+- [Wix Headless Documentation](https://dev.wix.com/docs/go-headless)
+- [Wix SDK Documentation](https://dev.wix.com/docs/sdk)
+- [Community on Discord](https://discord.gg/n6TBrSnYTp)

package/skills/wix-headless-templates/blog/project/astro.config.mjs

@@ -0,0 +1,22 @@
+import tailwindcss from "@tailwindcss/vite";
+// @ts-check
+import { defineConfig } from 'astro/config';
+import wix from "@wix/astro";
+import wixPages from "@wix/astro-pages";
+
+import react from "@astrojs/react";
+import wixHostingAdapter from "@wix/astro-wix-hosting-adapter";
+
+// https://astro.build/config
+export default defineConfig({
+  vite: { plugins: [tailwindcss()] },
+  integrations: [wix(), wixPages(), react()],
+  security: { checkOrigin: false },
+  adapter: wixHostingAdapter(),
+
+  image: {
+    domains: ["static.wixstatic.com"],
+  },
+
+  output: "server",
+});