blog-posts git:20261005.fdf521dA

Immutable. This exact content never changes and is served at /api/v1/blob/87b45ddb90549eb7.

---
description: Blog post structure, naming, migration guides, and component usage for release announcements
globs: website/blog/**
alwaysApply: false
---

## Naming Convention

Files: `YYYY-MM-DD-vX.Y-short-description.md`

## Frontmatter

- Title format: `vX.Y: Feature1, Feature2, Feature3` or `vX.Y Feature-focused Title`
- Include `releases` tag plus relevant feature tags from [tags.yml](./tags.yml)
- `draft: true` for unpublished/WIP posts

## Package Layers

Organize content by package layer. Both feature sections and migration guides follow this order:

| Layer | Packages | Content |
|-------|----------|---------|
| **Platforms** | Integration | NextJS, Expo, React Native, Vue, React versions |
| **Client/Platform** | react, vue, core | Hooks, composables, Controller, Managers, Provider |
| **API Definition** | rest, endpoint, graphql | Resource, RestEndpoint, Entity, Collection, schemas |
| **Internal** | normalizr, core | State structure, normalization, typing |

## Blog Structure

**Summary (before `{/* truncate */}`):**
1. Platforms/major features (highest visibility)
2. Package consolidations (import path changes)
3. New APIs (hooks, controller methods, schemas)
4. Other Improvements (bulleted list)
5. Breaking Changes (with anchor links to migration sections)

**Details (after truncate):**
1. Major features (with `<StackBlitz>`, `<HooksPlayground>` demos)
2. New/changed APIs (with `<TypeScriptEditor>` examples)
3. Performance (with `<PerfChart>` if benchmarked)
4. Other improvements
5. Migration guide

Within each section: explanation → code example → PR/commit links

## Migration Guide

Start with `<PkgTabs pkgs="..." upgrade />`, end with Upgrade support blurb.

**By Package** - Group changes by package when multiple packages have breaking changes:
- `### @data-client/react X.Y` - Client/Platform changes
- `### @data-client/rest X.Y` - API Definition changes

**By Audience** - Within packages (or standalone), group by who's affected:
- `### For all users` / `#### For all users`
- `### For custom Manager authors {#custom-managers}` - Action/middleware changes
- `### For custom Schema authors {#custom-schemas}` - normalize/denormalize changes

Add skip guidance for specialized sections: "Skip this section if you don't have custom [Managers](/docs/concepts/managers)."

Use `<DiffEditor>` for before/after. End with:

```md
### Upgrade support

As usual, if you have any troubles or questions, feel free to join our [![Chat](https://img.shields.io/discord/768254430381735967.svg?style=flat-square&colorB=758ED3)](https://discord.gg/wXGV27xm6t) or [file a bug](https://github.com/reactive/data-client/issues/new/choose)
```

## Components

| Component | Use For |
|-----------|---------|
| `<HooksPlayground>` | Interactive demos with fixtures |
| `<StackBlitz>` | Embedded app demos (todo-app, coin-app) |
| `<TypeScriptEditor>` | Type-safe code examples |
| `<DiffEditor>` | Before/After migration changes |
| `<PkgTabs pkgs="..." upgrade />` | Package installation |
| `<AutoPlayVideo>` | Recorded clips (SSR/navigation, DevTools). Record with [scripts/videos](../../scripts/videos/README.md); pass `alt` and put the code it shows in a fenced block next to it |

## Performance Sections

1. Explain what was optimized
2. Quantify with multipliers ("2x", "16x")
3. Link PR and docs
4. Visualize with `<PerfChart>`, not mermaid `xychart-beta` (it has no legend, so overlaid bars are unlabeled)
5. Link to [benchmarks](https://reactive.github.io/data-client/dev/bench/)

`<PerfChart>` renders a crawlable table of the raw numbers plus a bar chart of each row's speedup. Pass raw
measurements, not percentages; the component computes the multiplier.

```mdx
import PerfChart from '@site/src/components/PerfChart';

<PerfChart
  title="Writing rows into a 500-entity store"
  baselineLabel="One set() per row"
  valueLabel="set([Ticker], rows)"
  rows={[
    { label: '50 rows', baseline: 10.8, value: 0.54 },
    { label: '500 rows', baseline: 103, value: 1.08 },
  ]}
/>
```

`unit` defaults to `ms`, with lower being better; set `higherIsBetter` and `unit="ops/sec"` for throughput.
Bar lengths switch to a log scale on their own when speedups differ by more than 10x, and the chart labels it.

## Conventions

- Each change links to PR `[#1234](https://github.com/reactive/data-client/pull/1234)` and relevant docs
- Use `:::note` / `:::tip` / `:::warning` for callouts
- Use `// highlight-next-line` for code emphasis
- Imports go after frontmatter; place migration-only imports after truncate