Use when writing or editing files in src/content/blog/. Provides blog post structure and conventions.
Blog Post Writer
Persona
Voice: Official React team voice
Tone: Accurate, professional, forward-looking
Voice & Style
For tone, capitalization, jargon, and prose patterns, invoke /docs-voice.
Frontmatter Schema
All blog posts use this YAML frontmatter structure:
---title:"Title in Quotes"author:AuthorName(s)date:YYYY/MM/DDdescription:Oneortwosentencesummary.---
Field Details
Field
Format
Example
title
Quoted string
"React v19", "React Conf 2024 Recap"
author
Unquoted, comma + "and" for multiple
The React Team, Dan Abramov and Lauren Tan
date
YYYY/MM/DD with forward slashes
2024/12/05
description
1-2 sentences, often mirrors intro
Summarizes announcement or content
Title Patterns by Post Type
Type
Pattern
Example
Release
"React vX.Y" or "React X.Y"
"React v19"
Upgrade
"React [VERSION] Upgrade Guide"
"How to Upgrade to React 18"
Labs
"React Labs: [Topic] – [Month Year]"
"React Labs: What We've Been Working On – February 2024"
Conf
"React Conf [YEAR] Recap"
"React Conf 2024 Recap"
Feature
"Introducing [Feature]" or descriptive
"Introducing react.dev"
Security
"[Severity] Security Vulnerability in [Component]"
"Critical Security Vulnerability in React Server Components"
Author Byline
Immediately after frontmatter, add a byline:
---
Month DD, YYYY by [Author Name](social-link)
---
Conventions
Full date spelled out: December 05, 2024
Team posts link to /community/team: [The React Team](/community/team)
Individual authors link to Twitter/X or Bluesky
Multiple authors: Oxford comma before "and"
Followed by horizontal rule ---
Examples:
December 05, 2024 by [The React Team](/community/team)
---
May 3, 2023 by [Dan Abramov](https://bsky.app/profile/danabra.mov), [Sophie Alpert](https://twitter.com/sophiebits), and [Andrew Clark](https://twitter.com/acdlite)
---
Universal Post Structure
All blog posts follow this structure:
Frontmatter (YAML)
Author byline with date
Horizontal rule (---)
<Intro> component (1-3 sentences)
Horizontal rule (---) (optional)
Main content sections (H2 with IDs)
Closing section (Changelog, Thanks, etc.)
Post Type Templates
Major Release Announcement
---
title: "React vX.Y"
author: The React Team
date: YYYY/MM/DD
description: React X.Y is now available on npm! In this post, we'll give an overview of the new features.
---
Month DD, YYYY by [The React Team](/community/team)
---
<Intro>
React vX.Y is now available on npm!
</Intro>
In our [Upgrade Guide](/blog/YYYY/MM/DD/react-xy-upgrade-guide), we shared step-by-step instructions for upgrading. In this post, we'll give an overview of what's new.
- [What's new in React X.Y](#whats-new)
- [Improvements](#improvements)
- [How to upgrade](#how-to-upgrade)
---
## What's new in React X.Y {/*whats-new*/}### Feature Name {/*feature-name*/}
[Problem this solves. Before/after code examples.]
For more information, see the docs for [`Feature`](/reference/react/Feature).
---
## Improvements in React X.Y {/*improvements*/}### Improvement Name {/*improvement-name*/}
[Description of improvement.]
---
## How to upgrade {/*how-to-upgrade*/}
See [How to Upgrade to React X.Y](/blog/YYYY/MM/DD/react-xy-upgrade-guide) for step-by-step instructions.
---
## Changelog {/*changelog*/}### React {/*react*/}* Add `useNewHook` for [purpose]. ([#12345](https://github.com/react/react/pull/12345) by [@contributor](https://github.com/contributor))
---
_Thanks to [Name](url) for reviewing this post._
Upgrade Guide
---
title: "React [VERSION] Upgrade Guide"
author: Author Name
date: YYYY/MM/DD
description: Step-by-step instructions for upgrading to React [VERSION].
---
Month DD, YYYY by [Author Name](social-url)
---
<Intro>
[Summary of upgrade and what this guide covers.]
</Intro><Note>#### Stepping stone version {/*stepping-stone*/}
[If applicable, describe intermediate upgrade steps.]
</Note>
In this post, we will guide you through the steps for upgrading:
- [Installing](#installing)
- [Codemods](#codemods)
- [Breaking changes](#breaking-changes)
- [New deprecations](#new-deprecations)
---
## Installing {/*installing*/}```bash
npm install --save-exact react@^X.Y.Z react-dom@^X.Y.Z
Codemods {/codemods/}
Run all React [VERSION] codemods {/run-all-codemods/}
### React Labs Research Update
```markdown
---
title: "React Labs: What We've Been Working On – [Month Year]"
author: Author1, Author2, and Author3
date: YYYY/MM/DD
description: In React Labs posts, we write about projects in active research and development.
---
Month DD, YYYY by [Author1](url), [Author2](url), and [Author3](url)
---
<Intro>
In React Labs posts, we write about projects in active research and development. We've made significant progress since our [last update](/blog/previous-labs-post), and we'd like to share our progress.
</Intro>
[Optional: Roadmap disclaimer about timelines]
---
## Feature Name {/*feature-name*/}
<Note>
`<FeatureName />` is now available in React's Canary channel.
</Note>
[Description of feature, motivation, current status.]
### Subsection {/*subsection*/}
[Details, examples, use cases.]
---
## Research Area {/*research-area*/}
[Problem space description. Status communication.]
This research is still early. We'll share more when we're further along.
---
_Thanks to [Reviewer](url) for reviewing this post._
Thanks for reading, and see you in the next update!
React Conf Recap
---
title: "React Conf [YEAR] Recap"
author: Author1 and Author2
date: YYYY/MM/DD
description: Last week we hosted React Conf [YEAR]. In this post, we'll summarize the talks and announcements.
---
Month DD, YYYY by [Author1](url) and [Author2](url)
---
<Intro>
Last week we hosted React Conf [YEAR] [where we announced [key announcements]].
</Intro>
---
The entire [day 1](youtube-url) and [day 2](youtube-url) streams are available online.
## Day 1 {/*day-1*/}_[Watch the full day 1 stream here.](youtube-url)_
[Description of day 1 opening and keynote highlights.]
Watch the full day 1 keynote here:
<YouTubeIframesrc="https://www.youtube.com/embed/VIDEO_ID" />## Day 2 {/*day-2*/}_[Watch the full day 2 stream here.](youtube-url)_
[Day 2 summary.]
<YouTubeIframesrc="https://www.youtube.com/embed/VIDEO_ID" />## Q&A {/*q-and-a*/}* [Q&A Title](youtube-url) hosted by [Host](url)
## And more... {/*and-more*/}
We also heard talks including:
* [Talk Title](youtube-url) by [Speaker](url)
## Thank you {/*thank-you*/}
Thank you to all the staff, speakers, and participants who made React Conf [YEAR] possible.
See you next time!
Feature/Tool Announcement
---
title: "Introducing [Feature Name]"
author: Author Name
date: YYYY/MM/DD
description: Today we are announcing [feature]. In this post, we'll explain [what this post covers].
---
Month DD, YYYY by [Author Name](url)
---
<Intro>
Today we are [excited/thrilled] to announce [feature]. [What this means for users.]
</Intro>
---
## tl;dr {/*tldr*/}* Key announcement point with [relevant link](/path).
* What users can do now.
* Availability or adoption information.
## What is [Feature]? {/*what-is-feature*/}
[Explanation of the feature/tool.]
## Why we built this {/*why-we-built-this*/}
[Motivation, history, problem being solved.]
## Getting started {/*getting-started*/}
To install [feature]:
<TerminalBlock>
npm install package-name
</TerminalBlock>
[You can find more documentation here.](/path/to/docs)
## What's next {/*whats-next*/}
[Future plans and next steps.]
## Thank you {/*thank-you*/}
[Acknowledgments to contributors.]
---
Thanks to [Reviewer](url) for reviewing this post.
Security Announcement
---
title: "[Severity] Security Vulnerability in [Component]"
author: The React Team
date: YYYY/MM/DD
description: Brief summary of the vulnerability. A fix has been published. We recommend upgrading immediately.
---
Month DD, YYYY by [The React Team](/community/team)
---
<Intro>
[One or two sentences summarizing the vulnerability.]
We recommend upgrading immediately.
</Intro>
---
On [date], [researcher] reported a security vulnerability that allows [description].
This vulnerability was disclosed as [CVE-YYYY-NNNNN](https://www.cve.org/CVERecord?id=CVE-YYYY-NNNNN) and is rated CVSS [score].
The vulnerability is present in versions [list] of:
* [package-name](https://www.npmjs.com/package/package-name)
## Immediate Action Required {/*immediate-action-required*/}
A fix was introduced in versions [linked versions]. Upgrade immediately.
### Affected frameworks {/*affected-frameworks*/}
[List of affected frameworks with npm links.]
### Vulnerability overview {/*vulnerability-overview*/}
[Technical explanation of the vulnerability.]
## Update Instructions {/*update-instructions*/}### Framework Name {/*update-framework-name*/}```bash
npm install package@version
Timeline {/timeline/}
November 29th: [Researcher] reported the vulnerability.
December 1st: Fix was created and validated.
December 3rd: Fix published and CVE disclosed.
Attribution {/attribution/}
Thank you to Researcher Name for discovering and reporting this vulnerability.
---
## Heading Conventions
### ID Syntax
All headings require IDs using CSS comment syntax:
```markdown
## Heading Text {/*heading-id*/}
ID Rules
Lowercase
Kebab-case (hyphens for spaces)
Remove special characters (apostrophes, colons, backticks)
Concise but descriptive
Heading Patterns
Context
Example
Feature section
## New Feature: Automatic Batching {/*new-feature-automatic-batching*/}
New hook
### New hook: \useActionState` {/new-hook-useactionstate/}`
API in backticks
### \` {/activity/}`
Removed API
#### Removed: \propTypes` {/removed-proptypes/}`
tl;dr section
## tl;dr {/*tldr*/}
Component Usage Guide
Blog-Appropriate Components
Component
Usage in Blog
<Intro>
Required - Opening summary after byline
<Note>
Callouts, caveats, important clarifications
<Pitfall>
Warnings about common mistakes
<DeepDive>
Optional technical deep dives (use sparingly)
<TerminalBlock>
CLI/installation commands
<ConsoleBlock>
Console error/warning output
<ConsoleBlockMulti>
Multi-line console output
<YouTubeIframe>
Conference video embeds
<Diagram>
Visual explanations
<InlineToc />
Auto-generated table of contents
<Intro> Pattern
Always wrap opening paragraph:
<Intro>
React 19 is now available on npm!
</Intro>
<Note> Patterns
Simple note:
<Note>
For React Native users, React 18 ships with the New Architecture.
</Note>
Titled note (H4 inside):
<Note>#### React 18.3 has also been published {/*react-18-3*/}
To help with the upgrade, we've published `react@18.3`...
</Note>
