eddev 2.3.12 → 2.3.13

package/skills/eddev/docs/serverless.mdx

@@ -0,0 +1,202 @@
+# Serverless (/docs/serverless)
+
+**Run the public eddev frontend on Vercel while WordPress owns content and routing.**
+
+eddev serverless mode runs the public React frontend on a JavaScript host such as Vercel, while WordPress remains the CMS and routing authority.
+
+In production, the usual shape is:
+
+* `cms.website.com` points at the WordPress origin, usually behind Cloudflare.
+* `website.com` points at the Vercel deployment.
+* Vercel receives public page requests, asks WordPress for the matched route data, then server-renders the React view.
+* WordPress still resolves the route, executes the view/block GraphQL files, owns `/wp-admin`, and provides runtime query and mutation endpoints.
+
+The Vercel app is not a separate router. It is a rendering and API layer in front of the WordPress origin.
+
+## Deploying To Vercel [#deploying-to-vercel]
+
+For a normal project:
+
+1. Import the site's GitHub repository into Vercel.
+2. Add `SITE_URL` in Vercel project environment variables.
+3. Set `SITE_URL` to the WordPress origin, including the protocol, for example `https://cms.staging.sff.org.au/`.
+4. If the WordPress origin uses eddev Access Control, add `SITE_API_KEY` in Vercel as well.
+5. Deploy.
+
+During the build, eddev reads `SITE_URL` and uses it as the origin for WordPress route data, global app data, named GraphQL query hooks, mutations, plugin assets, uploads, and proxied WordPress/admin requests.
+
+<Callout type="warning">
+  Do not point `SITE_URL` at the Vercel frontend. It should point at the WordPress origin, usually the `cms.` host.
+</Callout>
+
+## Request Flow [#request-flow]
+
+When a visitor requests a page from the Vercel deployment:
+
+1. The serverless app normalizes the URL and asks WordPress for route data with `?_props=1` and `_ssr=1`.
+2. WordPress resolves the request through the normal template hierarchy, runs the paired view GraphQL file, and returns the JSON route payload.
+3. The serverless app replaces origin URLs where configured, fetches app data, and renders the matching React view.
+4. Browser navigation continues through eddev's route data endpoints instead of loading a whole WordPress HTML page.
+
+Runtime GraphQL hooks follow the same split:
+
+* browser-side query hooks on Vercel call `/_data/query/{queryName}`
+* browser-side mutations on Vercel call `/_data/mutation/{mutationName}`
+* the serverless app forwards those to the WordPress REST endpoints under `/wp-json/ed/v1/query/` and `/wp-json/ed/v1/mutation/`
+
+Server routes from `server/routes/` are deployed with the serverless app. See [RPC Functions](./functions) for route authoring and React usage.
+
+## Basic Configuration [#basic-configuration]
+
+Serverless behaviour is configured in `ed.config.json`. The `serverless` key controls deployment and routing behaviour, while the `cache` key controls how both the WordPress and JavaScript server sides cache data.
+
+```json filename="ed.config.json"
+{
+  "$schema": ".ed.config.schema.json",
+  "version": "2",
+  "serverless": {
+    "enabled": true,
+    "uploads": "remote",
+    "plugins": "remote",
+    "admin": "hide",
+    "themeAssets": ["assets/**/*"],
+    "originProtection": {
+      "requireLogin": false
+    },
+    "endpoints": {
+      "cms.website.com": "website.com"
+    }
+  },
+  "cache": {
+    "*": {
+      "serverless": {
+        "isr": true,
+        "dataCache": "in-memory"
+      },
+      "wordpress": {
+        "cacheHeaders": true,
+        "transients": true
+      },
+      "pageDataTTL": 300,
+      "appDataTTL": 300,
+      "queryHooksTTL": 300
+    }
+  }
+}
+```
+
+### `serverless` [#serverless]
+
+| Option                          | What It Does                                                                                                                                                                                           |
+| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `enabled`                       | Enables serverless deployment support. This is normally `true`.                                                                                                                                        |
+| `uploads`                       | Controls whether `/wp-content/uploads/**` URLs are left as remote origin URLs or proxied through the serverless deployment. Use `remote` by default.                                                   |
+| `plugins`                       | Controls whether `/wp-content/plugins/**` URLs are left as remote origin URLs or proxied through the serverless deployment. Use `remote` by default.                                                   |
+| `admin`                         | `proxy` forwards WordPress admin/API URLs through the deployment. `hide` returns a 404 for `/wp-admin`, `/wp-json`, `/wp-login.php`, GraphQL, and PHP-style URLs in production.                        |
+| `originProtection.requireLogin` | Force-enables origin protection from config. This prevents non-logged-in visitors from accessing the WordPress origin frontend, while still allowing the serverless frontend to fetch with an API key. |
+| `themeAssets`                   | Static theme asset folders to include in the serverless deployment. The starter theme uses `["assets/**/*"]`.                                                                                          |
+| `endpoints`                     | Maps WordPress hostnames to serverless hostnames. This tells the WordPress-hosted SPA/admin where to call serverless endpoints such as RPC functions.                                                  |
+| `cors.origins`                  | Additional allowed CORS origins. WordPress and serverless hosts from `endpoints` are already allowed.                                                                                                  |
+| `csp`                           | Content Security Policy settings for the serverless app, including autodetected origins, common origins, nonces, and directive values.                                                                 |
+
+`serverless.endpoints` values are hostnames, not full URLs:
+
+```json filename="ed.config.json"
+{
+  "serverless": {
+    "endpoints": {
+      "cms.staging.sff.org.au": "sff-staging.vercel.app",
+      "cms.sff.org.au": "www.sff.org.au"
+    }
+  }
+}
+```
+
+You can use `"*"` as a fallback key, but explicit hostnames are better for production and staging because they make the CMS-to-frontend relationship clear.
+
+<Callout type="info">
+  The WordPress PHP layer injects `window.SERVERLESS_ENDPOINT` into the WordPress frontend and admin when it can match the current WordPress host in `serverless.endpoints`. The RPC client uses that value when the site is running in WordPress-hosted SPA mode, so incorrect endpoint mappings usually show up as RPC calls going to the wrong host.
+</Callout>
+
+### `cache` [#cache]
+
+The `cache` object is a map of WordPress origin hostnames to cache settings. Use `"*"` for the default, and add host-specific entries when staging and production need different behaviour.
+
+Cache host keys are matched as hostnames. Ports are ignored, exact hostnames win over wildcard patterns, wildcard patterns like `"*.website.com"` are supported, and `"*"` is used as the fallback.
+
+| Option                   | What It Does                                                                                                                                                         |
+| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `pageDataTTL`            | Seconds to cache route data and rendered page responses.                                                                                                             |
+| `appDataTTL`             | Seconds to cache global app data from `views/_app.graphql`.                                                                                                          |
+| `queryHooksTTL`          | Seconds to cache named runtime GraphQL query hook responses.                                                                                                         |
+| `serverless.isr`         | Enables serverless response caching/ISR for rendered pages, route data, and named query data. Set it to `false` for dynamic, no-store serverless responses.          |
+| `serverless.dataCache`   | Controls the serverless origin-data cache. Use `in-memory` for the normal LRU/SWR cache, or `none` to fetch WordPress every time the serverless function needs data. |
+| `wordpress.cacheHeaders` | Allows WordPress data responses to emit cache headers.                                                                                                               |
+| `wordpress.transients`   | Allows WordPress to cache data in transients.                                                                                                                        |
+
+`serverless.isr` and `serverless.dataCache` control different cache layers:
+
+| Configuration                          | Behaviour                                                                                                                                       |
+| -------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
+| `isr: true`, `dataCache: "in-memory"`  | Normal production mode. Serverless responses can be cached, and serverless revalidation/data requests are protected by an in-memory data cache. |
+| `isr: true`, `dataCache: "none"`       | Serverless responses can still be cached, but every revalidation fetch goes back to WordPress.                                                  |
+| `isr: false`, `dataCache: "in-memory"` | Serverless responses are dynamic/no-store, but repeated WordPress data fetches can still use the serverless in-memory cache.                    |
+| `isr: false`, `dataCache: "none"`      | Fully dynamic serverless mode. Responses are no-store and serverless data fetches go back to WordPress every time.                              |
+
+Queries and mutations are handled differently:
+
+* route data and app data use the page/app TTLs
+* named query hooks use `queryHooksTTL`
+* mutation responses are not cached
+* requests with varied auth/session headers avoid the shared named-query data cache
+
+Individual GraphQL query files can still set `# ttl: 300` or `# nocache`; see [GraphQL caching](/docs/graphql#caching).
+
+## Origin Access Control [#origin-access-control]
+
+Use eddev's Access Control feature to protect the WordPress origin. Do not use WP Engine's password protection for this, because Vercel still needs to fetch WordPress route data, GraphQL results, uploads, and REST endpoints without receiving a human password prompt.
+
+In WordPress:
+
+1. Open **Settings → Access Control**.
+2. Generate an API key.
+3. Enable API key protection if it is not force-enabled by config.
+4. Optionally enable simple password protection for people who should be able to preview the CMS-hosted frontend directly.
+5. Add the generated key to Vercel as `SITE_API_KEY`.
+
+When `SITE_API_KEY` is set, eddev adds it to server-to-server WordPress requests as the `x-ed-api-key` header. The PHP origin checks that header before allowing access.
+
+Access Control allows:
+
+* logged-in WordPress users
+* requests with a valid eddev API key
+* users with the configured basic-auth credentials, when password protection is enabled
+
+Everyone else receives an Access Denied page or a password prompt, depending on the settings.
+
+<Callout type="info">
+  An API key only allows a request to reach the origin. It does not grant WordPress permissions or log the request in as a user.
+</Callout>
+
+For stricter projects, set `serverless.originProtection.requireLogin` to `true`. That force-enables API-key protection from committed config, so the WordPress origin cannot accidentally be left public through an admin setting.
+
+## Domain Setup [#domain-setup]
+
+The common production setup is:
+
+| Host                              | Points To                                                             | Purpose                                                                     |
+| --------------------------------- | --------------------------------------------------------------------- | --------------------------------------------------------------------------- |
+| `cms.website.com`                 | WP Engine or another WordPress host, often proxied through Cloudflare | WordPress admin, CMS preview, GraphQL, REST, uploads, and route data origin |
+| `website.com` / `www.website.com` | Vercel                                                                | Public server-rendered frontend and serverless routes                       |
+
+Keep the WordPress origin reachable by the Vercel deployment. If Cloudflare sits in front of `cms.website.com`, make sure it passes the `x-ed-api-key` header and does not add its own interactive challenge to server-to-server requests.
+
+## Deployment Checklist [#deployment-checklist]
+
+* `SITE_URL` in Vercel points to the WordPress origin, for example `https://cms.website.com/`.
+* `SITE_API_KEY` is set in Vercel when Access Control is enabled.
+* The same API key exists in WordPress under **Settings → Access Control**.
+* `serverless.endpoints` maps each WordPress hostname to the correct Vercel/public hostname.
+* `serverless.admin` is set intentionally, usually `hide` for public deployments.
+* `cache["*"]` or a host-specific cache entry sets realistic TTLs for route data, app data, and runtime query hooks.
+* Cloudflare or host-level protection does not block Vercel's server-to-server origin requests.

package/skills/eddev/docs/snippets/automated-block-layouts.mdx

@@ -0,0 +1,97 @@
+# Automated Block Layouts (/docs/snippets/automated-block-layouts)
+
+**Use block flags and wrapBlock to keep layout rules out of every block**
+
+Use this when the page layout should automatically wrap blocks based on block metadata, rather than making every block render its own page grid.
+
+For the underlying APIs, see [Block Flags](/docs/blocks/block-definition#block-flags), [Querying Blocks From Views](/docs/blocks/data-and-editing#querying-blocks-from-views), and [Nested Blocks](/docs/blocks/nested-blocks).
+
+## Put Layout Hints In Block Metadata [#put-layout-hints-in-block-metadata]
+
+Keep flags small. They are copied into the block payload and are available to `ContentBlocks`.
+
+```tsx filename="blocks/content/accordion.tsx"
+import { defineBlock, EditableText, InnerBlocks } from "eddev/blocks"
+
+export const meta: BlockMeta = {
+  title: "Accordion",
+  icon: "info",
+  tags: ["#subpage"],
+  flags: {
+    contentWidth: true,
+    marginRule: "long-card",
+  },
+}
+
+export default defineBlock("content/accordion", () => {
+  return (
+    <section>
+      <EditableText as="h3" store="title" defaultValue="Enter a title" plainText />
+      <InnerBlocks allowedBlocks={["core/paragraph", "core/list", "content/button-row"]} />
+    </section>
+  )
+})
+```
+
+```tsx filename="blocks/content/card-row.tsx"
+import { defineBlock, InnerBlocks } from "eddev/blocks"
+
+export const meta: BlockMeta = {
+  title: "Card Row",
+  category: "layouts",
+  icon: "slides",
+  tags: ["#subpage"],
+  flags: {
+    fullWidth: true,
+    marginRule: "featured-card",
+  },
+}
+
+export default defineBlock("content/card-row", () => {
+  return <InnerBlocks allowedBlocks={["content/card-row-item"]} />
+})
+```
+
+## Wrap Blocks In One Place [#wrap-blocks-in-one-place]
+
+Use `wrapBlock` on a shared `ContentBlocks` wrapper so page grid rules live in one component.
+
+```tsx filename="features/layout/SubpageContentBlocks.tsx"
+import { BlocksContext, ContentBlocks } from "eddev/blocks"
+import { ComponentProps, ReactNode } from "react"
+
+function wrapBlock(children: ReactNode, ctx: BlocksContext) {
+  const marginClass = ctx.current.flags?.marginRule
+    ? `block-margins-${ctx.current.flags.marginRule}`
+    : ""
+
+  if (ctx.current.blockName === "core/rich-text" || ctx.current.flags?.contentWidth) {
+    return <div className={`col-subpage-content ${marginClass}`}>{children}</div>
+  }
+
+  if (ctx.current.flags?.fullWidth) {
+    return <div className={`full-width-block ${marginClass}`}>{children}</div>
+  }
+
+  return <div className={marginClass}>{children}</div>
+}
+
+type Props = Omit<ComponentProps<typeof ContentBlocks>, "wrapBlock">
+
+export function SubpageContentBlocks(props: Props) {
+  return <ContentBlocks {...props} wrapBlock={wrapBlock} />
+}
+```
+
+## Use The Wrapper In Views [#use-the-wrapper-in-views]
+
+```tsx filename="views/page.tsx"
+import { SubpageContentBlocks } from "@features/layout/SubpageContentBlocks"
+import { defineView } from "eddev/views"
+
+export default defineView("page", (props) => {
+  return <SubpageContentBlocks blocks={props.page?.contentBlocks} />
+})
+```
+
+This works well when blocks need to stay reusable across different views, but each view has its own layout rules.

package/skills/eddev/docs/snippets/custom-routes-and-urls.mdx

@@ -0,0 +1,91 @@
+# Custom Routes And URLs (/docs/snippets/custom-routes-and-urls)
+
+**Map fixed URLs to views and keep generated WordPress links aligned**
+
+Use these when a route is not a normal WordPress single/archive URL, or when WordPress should generate a custom URL for a post type.
+
+For the full routing docs, see [Custom Routes](/docs/routing/custom) and [WordPress Routing](/docs/routing/wordpress).
+
+## Fixed Route With A Query Variable [#fixed-route-with-a-query-variable]
+
+```php filename="backend/routes.php"
+<?php
+
+ED()->addCustomRoute('form/([0-9]+)/?$', [
+  'template' => 'views/single-form.tsx',
+  'title' => 'Get in touch',
+  'queryVars' => [
+    'formId' => '$1',
+  ],
+]);
+```
+
+```graphql filename="views/single-form.graphql"
+query SingleForm($formId: Int!) {
+  gravityForm(id: $formId) {
+    title
+  }
+}
+```
+
+## Route Slugs Back To A Post ID [#route-slugs-back-to-a-post-id]
+
+Use `extraVars` when the URL contains slugs but the GraphQL view should receive the resolved WordPress post ID.
+
+```php filename="backend/routes.php"
+<?php
+
+ED()->addCustomRoute('program/event/([a-z0-9-]+)/?$', [
+  'template' => 'views/single-film.tsx',
+  'queryVars' => [
+    'filmSlug' => '$1',
+  ],
+  'extraVars' => function ($vars) {
+    global $post;
+    global $wp_query;
+
+    $film = get_page_by_path($vars['filmSlug'], OBJECT, 'film');
+    if (!$film) return [];
+
+    $wp_query->queried_object_id = $film->ID;
+    $wp_query->queried_object = $film;
+    $post = $film;
+
+    return [
+      'postId' => $film->ID,
+    ];
+  },
+  'is404' => function ($params) {
+    return empty($params['postId']);
+  },
+]);
+```
+
+## Generate Matching WordPress URLs [#generate-matching-wordpress-urls]
+
+A custom route handles incoming URLs. It does not automatically change URLs generated by WordPress, WPGraphQL, menus, or blocks. Use `post_type_link` for that.
+
+```php filename="backend/post-types/services.php"
+<?php
+
+ED()->registerPostType('service', [
+  'label' => 'Services',
+  'rewrite' => false,
+  'public' => false,
+  'show_ui' => true,
+  'publicly_queryable' => true,
+  'show_in_graphql' => true,
+  'graphql_single_name' => 'service',
+  'graphql_plural_name' => 'services',
+]);
+
+add_filter('post_type_link', function ($url, $post) {
+  if ($post->post_type === 'service') {
+    return '/services/#' . $post->post_name;
+  }
+
+  return $url;
+}, 10, 2);
+```
+
+For taxonomy URLs, use the matching WordPress filter, such as `term_link`.

package/skills/eddev/docs/snippets/multiple-editable-zones.mdx

@@ -0,0 +1,87 @@
+# Multiple Editable Zones (/docs/snippets/multiple-editable-zones)
+
+**Use SlotBlocks when one block needs more than one child area**
+
+WordPress only allows one `InnerBlocks` area per block. Use `SlotBlocks` when a single block needs multiple independent editable zones, such as footer columns, mega menu regions, or a header with separate navigation and CTA areas.
+
+For normal nested blocks, start with [Nested Blocks](/docs/blocks/nested-blocks). Reach for `SlotBlocks` only when one `InnerBlocks` area cannot model the layout.
+
+## Create Named Slots [#create-named-slots]
+
+Each `SlotBlocks` call creates or renders a hidden `core/slot-group` for the given `id`.
+
+```tsx filename="blocks/parts/footer.tsx"
+import { defineBlock, EditableText, SlotBlocks } from "eddev/blocks"
+
+export const meta: BlockMeta = {
+  title: "Site Footer",
+  inserter: false,
+  templatePart: {
+    area: "footer",
+    slug: "siteFooter",
+  },
+}
+
+export default defineBlock("parts/footer", () => {
+  return (
+    <footer>
+      <section>
+        <EditableText
+          as="h2"
+          store="subscribe-heading"
+          defaultValue="Stay in the loop"
+          plainText
+        />
+        <SlotBlocks
+          id="subscribe-text"
+          title="Subscribe Text"
+          allowedBlocks={["core/paragraph"]}
+          appender={{ type: "button2" }}
+          orientation="vertical"
+        />
+      </section>
+
+      <nav>
+        <SlotBlocks
+          id="footer-primary-links"
+          title="Primary Footer Links"
+          allowedBlocks={["core/navigation-link"]}
+          appender={{ type: "button2" }}
+          orientation="vertical"
+        />
+      </nav>
+
+      <div>
+        <SlotBlocks
+          id="footer-legal"
+          title="Footer Legal"
+          allowedBlocks={["core/navigation-link"]}
+          appender={{ type: "button2" }}
+          orientation="horizontal"
+        />
+      </div>
+    </footer>
+  )
+})
+```
+
+Use stable slot IDs. Changing an `id` later creates a different editable region, so existing content will not appear in the renamed slot.
+
+## Add Editor Layout Classes [#add-editor-layout-classes]
+
+Use `adminClassName` when the editor needs layout hints that are different from the frontend wrapper.
+
+```tsx filename="blocks/parts/footer.tsx"
+<SlotBlocks
+  id="footer-columns"
+  title="Footer Columns"
+  allowedBlocks={["parts/footer-group-main"]}
+  adminClassName="grid grid-cols-1 md:grid-cols-3 gap-4"
+  appender={{ type: "button2" }}
+  orientation="vertical"
+/>
+```
+
+## When Not To Use It [#when-not-to-use-it]
+
+Do not use slots for ordinary sections, accordions, cards, or button rows. A normal `InnerBlocks` container is simpler, easier to query, and should be the default. See [Nested Blocks](/docs/blocks/nested-blocks) for the simpler pattern.

package/skills/eddev/docs/snippets/querying-specific-blocks.mdx

@@ -0,0 +1,164 @@
+# Querying Specific Blocks (/docs/snippets/querying-specific-blocks)
+
+**Select, split, and render only the block content you need**
+
+Use these patterns when a view or block needs a targeted block selection instead of every `contentBlocks` item.
+
+For the broader data model, see [Block Data](/docs/blocks/data-and-editing), [View Data](/docs/views/queries), and [Template Parts](/docs/blocks/template-parts).
+
+## Pull One Block Type From Another Post [#pull-one-block-type-from-another-post]
+
+Use `contentBlocks(include: [...])` when you want a specific block from related posts. Sol People uses this shape for a hero block that pulls only `services/service-card` blocks from Service posts.
+
+```graphql filename="blocks/hero/services-hero.graphql"
+query ServicesHero {
+  block {
+    hero_services_hero {
+      theme
+    }
+  }
+  services(where: { orderby: [{ field: MENU_ORDER, order: ASC }] }) {
+    nodes {
+      contentBlocks(include: ["services/service-card"], limit: 1)
+    }
+  }
+}
+```
+
+```tsx filename="blocks/hero/services-hero.tsx"
+import { ContentBlocks, defineBlock } from "eddev/blocks"
+
+export default defineBlock("hero/services-hero", (props) => {
+  const cards =
+    props.services?.nodes
+      .flatMap((service) => service?.contentBlocks ?? [])
+      .filter(Boolean) ?? []
+
+  return <ContentBlocks blocks={cards} />
+})
+```
+
+`include` accepts block names, tags, flags, and wildcards. Add `limit: 1` when you only expect one matching block per post.
+
+## Exclude A Block From Related Posts [#exclude-a-block-from-related-posts]
+
+Use `exclude` when related posts should render their body content but skip the block that is used somewhere else.
+
+```graphql filename="views/archive-services.graphql"
+query ServicesArchive($postId: ID!) {
+  page(id: $postId, idType: DATABASE_ID) {
+    contentBlocks
+  }
+  services(where: { orderby: [{ field: MENU_ORDER, order: ASC }] }) {
+    nodes {
+      contentBlocks(exclude: ["services/service-card"])
+    }
+  }
+}
+```
+
+```tsx filename="views/archive-services.tsx"
+import { ContentBlocks } from "eddev/blocks"
+import { defineView } from "eddev/views"
+
+export default defineView("archive-services", (props) => {
+  return (
+    <>
+      <ContentBlocks blocks={props.page?.contentBlocks} />
+      {props.services?.nodes.map((service, index) => (
+        <ContentBlocks key={index} blocks={service?.contentBlocks} />
+      ))}
+    </>
+  )
+})
+```
+
+## Pull One Page Header From A Known Page [#pull-one-page-header-from-a-known-page]
+
+When an archive or app-like route has a fixed CMS page backing its intro content, query that page by URI and include just the header block.
+
+```graphql filename="views/archive-blog.graphql"
+query ArchiveBlog {
+  blogPosts(first: 9999, where: { orderby: [{ field: DATE, order: DESC }] }) {
+    nodes {
+      title
+      uri
+    }
+  }
+  page(id: "blog", idType: URI) {
+    title
+    contentBlocks(include: ["page/page-header"], limit: 1)
+  }
+}
+```
+
+```tsx filename="views/archive-blog.tsx"
+import { ContentBlocks } from "eddev/blocks"
+import { defineView } from "eddev/views"
+
+export default defineView("archive-blog", (props) => {
+  return (
+    <>
+      <ContentBlocks blocks={props.page?.contentBlocks} />
+      {/* Render the listing UI below the page header. */}
+    </>
+  )
+})
+```
+
+## Split A Hero From The Rest [#split-a-hero-from-the-rest]
+
+If the current page stores the hero in normal `contentBlocks`, find it in React and render the remainder separately.
+
+```tsx filename="views/template-home.tsx"
+import { ContentBlocks, SingleContentBlock } from "eddev/blocks"
+import { defineView } from "eddev/views"
+
+export default defineView("template-home", (props) => {
+  const blocks = props.page?.contentBlocks ?? []
+  const hero = blocks.find((block) => block.slug === "homepage/homepage-carousel")
+  const rest = blocks.filter((block) => block.slug !== "homepage/homepage-carousel")
+
+  return (
+    <>
+      {hero && <SingleContentBlock block={hero} />}
+      <ContentBlocks blocks={rest} />
+    </>
+  )
+})
+```
+
+Use this when the split is mostly presentational. If the split affects payload size or repeated related posts, prefer `include` and `exclude` in GraphQL.
+
+## Query A Template Part Subset [#query-a-template-part-subset]
+
+Use aliases plus `contentBlocks` filters when `_app.graphql` needs both a whole template part and a small subset.
+
+```graphql filename="views/_app.graphql"
+query CommonData {
+  templateParts {
+    siteHeader {
+      contentBlocks
+    }
+    headerButtons: siteHeader {
+      contentBlocks(flattenExcluded: true, include: ["parts/header-button"])
+    }
+    siteFooter {
+      contentBlocks
+    }
+  }
+}
+```
+
+```tsx filename="features/header/MobileMenu.tsx"
+import { ContentBlocks } from "eddev/blocks"
+import { useAppData } from "eddev/hooks"
+
+export function MobileMenuButtons() {
+  const blocks = useAppData((data) => data.templateParts?.headerButtons?.contentBlocks)
+
+  return <ContentBlocks blocks={blocks} />
+}
+```
+
+`flattenExcluded: true` is useful when the matching blocks may sit inside layout wrappers that you do not want to render.