diff --git a/.babelrc b/.babelrc deleted file mode 100644 index a8b9b8bbcd3..00000000000 --- a/.babelrc +++ /dev/null @@ -1,4 +0,0 @@ -{ - "presets": ['react', 'es2015', 'stage-1'], - "plugins": ['add-module-exports'] -} diff --git a/.circleci/config.yml b/.circleci/config.yml deleted file mode 100644 index 16c83a61d69..00000000000 --- a/.circleci/config.yml +++ /dev/null @@ -1,22 +0,0 @@ -version: 2 -jobs: - build: - docker: - - image: circleci/node:latest - steps: - - checkout - - restore_cache: - keys: - - dependencies-{{ checksum "package.json" }} - # fallback to using the latest cache if no exact match is found - - dependencies- - - run: - name: Install - command: yarn install - - save_cache: - paths: - - node_modules - key: dependencies-{{ checksum "package.json" }} - - run: - name: Check Prettier, ESLint, Flow - command: yarn ci-check diff --git a/.claude/agents/docs-reviewer.md b/.claude/agents/docs-reviewer.md new file mode 100644 index 00000000000..af0a856e452 --- /dev/null +++ b/.claude/agents/docs-reviewer.md @@ -0,0 +1,28 @@ +--- +name: docs-reviewer +description: "Lean docs reviewer that dispatches reviews docs for a particular skill." +model: opus +color: cyan +--- + +You are a direct, critical, expert reviewer for React documentation. + +Your role is to use given skills to validate given doc pages for consistency, correctness, and adherence to established patterns. + +Complete this process: + +## Phase 1: Task Creation +1. CRITICAL: Read the skill requested. +2. Understand the skill's requirements. +3. Create a task list to validate skills requirements. + +## Phase 2: Validate + +1. Read the docs files given. +2. Review each file with the task list to verify. + +## Phase 3: Respond + +You must respond with a checklist of the issues you identified, and line number. + +DO NOT respond with passed validations, ONLY respond with the problems. diff --git a/.claude/settings.json b/.claude/settings.json new file mode 100644 index 00000000000..11140318370 --- /dev/null +++ b/.claude/settings.json @@ -0,0 +1,32 @@ +{ + "skills": { + "suggest": [ + { + "pattern": "src/content/learn/**/*.md", + "skill": "docs-writer-learn" + }, + { + "pattern": "src/content/reference/**/*.md", + "skill": "docs-writer-reference" + } + ] + }, + "permissions": { + "allow": [ + "Skill(docs-voice)", + "Skill(docs-components)", + "Skill(docs-sandpack)", + "Skill(docs-rsc-sandpack)", + "Skill(docs-writer-learn)", + "Skill(docs-writer-reference)", + "Bash(yarn lint:*)", + "Bash(yarn lint-heading-ids:*)", + "Bash(yarn lint:fix:*)", + "Bash(yarn tsc:*)", + "Bash(yarn check-all:*)", + "Bash(yarn fix-headings:*)", + "Bash(yarn deadlinks:*)", + "Bash(yarn prettier:diff:*)" + ] + } +} diff --git a/.claude/skills/docs-components/SKILL.md b/.claude/skills/docs-components/SKILL.md new file mode 100644 index 00000000000..4b75f27a12d --- /dev/null +++ b/.claude/skills/docs-components/SKILL.md @@ -0,0 +1,518 @@ +--- +name: docs-components +description: Comprehensive MDX component patterns (Note, Pitfall, DeepDive, Recipes, etc.) for all documentation types. Authoritative source for component usage, examples, and heading conventions. +--- + +# MDX Component Patterns + +## Quick Reference + +### Component Decision Tree + +| Need | Component | +|------|-----------| +| Helpful tip or terminology | `` | +| Common mistake warning | `` | +| Advanced technical explanation | `` | +| Canary-only feature | `` or `` | +| Server Components only | `` | +| Deprecated API | `` | +| Experimental/WIP | `` | +| Visual diagram | `` | +| Multiple related examples | `` | +| Interactive code | `` (see `/docs-sandpack`) | +| Console error display | `` | +| End-of-page exercises | `` (Learn pages only) | + +### Heading Level Conventions + +| Component | Heading Level | +|-----------|---------------| +| DeepDive title | `####` (h4) | +| Titled Pitfall | `#####` (h5) | +| Titled Note | `####` (h4) | +| Recipe items | `####` (h4) | +| Challenge items | `####` (h4) | + +### Callout Spacing Rules + +Callout components (Note, Pitfall, DeepDive) require a **blank line after the opening tag** before content begins. + +**Never place consecutively:** +- `` followed by `` - Combine into one with titled subsections, or separate with prose +- `` followed by `` - Combine into one, or separate with prose + +**Allowed consecutive patterns:** +- `` followed by `` - OK for multi-part explorations (see useMemo.md) +- `` followed by `` - OK when DeepDive explains "why" behind the Pitfall + +**Separation content:** Prose paragraphs, code examples (Sandpack), or section headers. + +**Why:** Consecutive warnings create a "wall of cautions" that overwhelms readers and causes important warnings to be skimmed. + +**Incorrect:** +```mdx + +Don't do X. + + + +Don't do Y. + +``` + +**Correct - combined:** +```mdx + + +##### Don't do X {/*pitfall-x*/} +Explanation. + +##### Don't do Y {/*pitfall-y*/} +Explanation. + + +``` + +**Correct - separated:** +```mdx + +Don't do X. + + +This leads to another common mistake: + + +Don't do Y. + +``` + +--- + +## `` + +Important clarifications, conventions, or tips. Less severe than Pitfall. + +### Simple Note + +```mdx + + +The optimization of caching return values is known as [_memoization_](https://en.wikipedia.org/wiki/Memoization). + + +``` + +### Note with Title + +Use `####` (h4) heading with an ID. + +```mdx + + +#### There is no directive for Server Components. {/*no-directive*/} + +A common misunderstanding is that Server Components are denoted by `"use server"`, but there is no directive for Server Components. The `"use server"` directive is for Server Functions. + + +``` + +### Version-Specific Note + +```mdx + + +Starting in React 19, you can render `` as a provider. + +In older versions of React, use ``. + + +``` + +--- + +## `` + +Common mistakes that cause bugs. Use for errors readers will likely make. + +### Simple Pitfall + +```mdx + + +We recommend defining components as functions instead of classes. [See how to migrate.](#alternatives) + + +``` + +### Titled Pitfall + +Use `#####` (h5) heading with an ID. + +```mdx + + +##### Calling different memoized functions will read from different caches. {/*pitfall-different-caches*/} + +To access the same cache, components must call the same memoized function. + + +``` + +### Pitfall with Wrong/Right Code + +```mdx + + +##### `useFormStatus` will not return status information for a `
` rendered in the same component. {/*pitfall-same-component*/} + +```js +function Form() { + // 🔴 `pending` will never be true + const { pending } = useFormStatus(); + return
; +} +``` + +Instead call `useFormStatus` from inside a component located inside `
`. + + +``` + +--- + +## `` + +Optional deep technical content. **First child must be `####` heading with ID.** + +### Standard DeepDive + +```mdx + + +#### Is using an updater always preferred? {/*is-updater-preferred*/} + +You might hear a recommendation to always write code like `setAge(a => a + 1)` if the state you're setting is calculated from the previous state. There's no harm in it, but it's also not always necessary. + +In most cases, there is no difference between these two approaches. React always makes sure that for intentional user actions, like clicks, the `age` state variable would be updated before the next click. + + +``` + +### Comparison DeepDive + +For comparing related concepts: + +```mdx + + +#### When should I use `cache`, `memo`, or `useMemo`? {/*cache-memo-usememo*/} + +All mentioned APIs offer memoization but differ in what they memoize, who can access the cache, and when their cache is invalidated. + +#### `useMemo` {/*deep-dive-usememo*/} + +In general, you should use `useMemo` for caching expensive computations in Client Components across renders. + +#### `cache` {/*deep-dive-cache*/} + +In general, you should use `cache` in Server Components to memoize work that can be shared across components. + + +``` + +--- + +## `` + +Multiple related examples showing variations. Each recipe needs ``. + +```mdx + + +#### Counter (number) {/*counter-number*/} + +In this example, the `count` state variable holds a number. + + +{/* code */} + + + + +#### Text field (string) {/*text-field-string*/} + +In this example, the `text` state variable holds a string. + + +{/* code */} + + + + + +``` + +**Common titleText/titleId combinations:** +- "Basic [hookName] examples" / `examples-basic` +- "Examples of [concept]" / `examples-[concept]` +- "The difference between [A] and [B]" / `examples-[topic]` + +--- + +## `` + +End-of-page exercises. **Learn pages only.** Each challenge needs problem + solution Sandpack. + +```mdx + + +#### Fix the bug {/*fix-the-bug*/} + +Problem description... + + +Optional hint text. + + + +{/* problem code */} + + + + +Explanation... + + +{/* solution code */} + + + + + +``` + +**Guidelines:** +- Only at end of standard Learn pages +- No Challenges in chapter intros or tutorials +- Each challenge has `####` heading with ID + +--- + +## `` + +For deprecated APIs. Content should explain what to use instead. + +### Page-Level Deprecation + +```mdx + + +In React 19, `forwardRef` is no longer necessary. Pass `ref` as a prop instead. + +`forwardRef` will be deprecated in a future release. Learn more [here](/blog/2024/04/25/react-19#ref-as-a-prop). + + +``` + +### Method-Level Deprecation + +```mdx +### `componentWillMount()` {/*componentwillmount*/} + + + +This API has been renamed from `componentWillMount` to [`UNSAFE_componentWillMount`.](#unsafe_componentwillmount) + +Run the [`rename-unsafe-lifecycles` codemod](codemod-link) to automatically update. + + +``` + +--- + +## `` + +For APIs that only work with React Server Components. + +### Basic RSC + +```mdx + + +`cache` is only for use with [React Server Components](/reference/rsc/server-components). + + +``` + +### Extended RSC (for Server Functions) + +```mdx + + +Server Functions are for use in [React Server Components](/reference/rsc/server-components). + +**Note:** Until September 2024, we referred to all Server Functions as "Server Actions". + + +``` + +--- + +## `` and `` + +For features only available in Canary releases. + +### Canary Wrapper (inline in Intro) + +```mdx + + +`` lets you group elements without a wrapper node. + +Fragments can also accept refs, enabling interaction with underlying DOM nodes. + + +``` + +### CanaryBadge in Section Headings + +```mdx +### FragmentInstance {/*fragmentinstance*/} +``` + +### CanaryBadge in Props Lists + +```mdx +* **optional** `ref`: A ref object from `useRef` or callback function. +``` + +### CanaryBadge in Caveats + +```mdx +* If you want to pass `ref` to a Fragment, you can't use the `<>...` syntax. +``` + +--- + +## `` + +Visual explanations of module dependencies, render trees, or data flow. + +```mdx + +`'use client'` segments the module dependency tree, marking `InspirationGenerator.js` and all dependencies as client-rendered. + +``` + +**Attributes:** +- `name`: Diagram identifier (used for image file) +- `height`: Height in pixels +- `width`: Width in pixels +- `alt`: Accessible description of the diagram + +--- + +## `` (Use Sparingly) + +Numbered callouts in prose. Pairs with code block annotations. + +### Syntax + +In code blocks: +```mdx +```js [[1, 4, "age"], [2, 4, "setAge"], [3, 4, "42"]] +import { useState } from 'react'; + +function MyComponent() { + const [age, setAge] = useState(42); +} +``` +``` + +Format: `[[step_number, line_number, "text_to_highlight"], ...]` + +In prose: +```mdx +1. The current state initially set to the initial value. +2. The `set` function that lets you change it. +``` + +### Guidelines + +- Maximum 2-3 different colors per explanation +- Don't highlight every keyword - only key concepts +- Use for terms in prose, not entire code blocks +- Maintain consistent usage within a section + +✅ **Good use** - highlighting key concepts: +```mdx +React will compare the dependencies with the dependencies you passed... +``` + +🚫 **Avoid** - excessive highlighting: +```mdx +When an Activity boundary is hidden during its initial render... +``` + +--- + +## `` + +Display console output (errors, warnings, logs). + +```mdx + +Uncaught Error: Too many re-renders. + +``` + +**Levels:** `error`, `warning`, `info` + +--- + +## Component Usage by Page Type + +### Reference Pages + +For component placement rules specific to Reference pages, invoke `/docs-writer-reference`. + +Key placement patterns: +- `` goes before `` at top of page +- `` goes after `` for page-level deprecation +- `` goes after method heading for method-level deprecation +- `` wrapper goes inline within `` +- `` appears in headings, props lists, and caveats + +### Learn Pages + +For Learn page structure and patterns, invoke `/docs-writer-learn`. + +Key usage patterns: +- Challenges only at end of standard Learn pages +- No Challenges in chapter intros or tutorials +- DeepDive for optional advanced content +- CodeStep should be used sparingly + +### Blog Pages + +For Blog page structure and patterns, invoke `/docs-writer-blog`. + +Key usage patterns: +- Generally avoid deep technical components +- Note and Pitfall OK for clarifications +- Prefer inline explanations over DeepDive + +--- + +## Other Available Components + +**Version/Status:** ``, ``, ``, ``, `` + +**Visuals:** ``, ``, ``, ``, `` + +**Console:** ``, `` + +**Specialized:** ``, ``, ``, ``, ``, ``, ``, ``, `` + +See existing docs for usage examples of these components. diff --git a/.claude/skills/docs-rsc-sandpack/SKILL.md b/.claude/skills/docs-rsc-sandpack/SKILL.md new file mode 100644 index 00000000000..42aba08afb4 --- /dev/null +++ b/.claude/skills/docs-rsc-sandpack/SKILL.md @@ -0,0 +1,277 @@ +--- +name: docs-rsc-sandpack +description: Use when adding interactive RSC (React Server Components) code examples to React docs using , or when modifying the RSC sandpack infrastructure. +--- + +# RSC Sandpack Patterns + +For general Sandpack conventions (code style, naming, file naming, line highlighting, hidden files, CSS guidelines), see `/docs-sandpack`. This skill covers only RSC-specific patterns. + +## Quick Start Template + +Minimal single-file `` example: + +```mdx + + +` ` `js src/App.js +export default function App() { + return

Hello from a Server Component!

; +} +` ` ` + + +``` + +--- + +## How It Differs from `` + +| Feature | `` | `` | +|---------|-------------|-----------------| +| Execution model | All code runs in iframe | Server code runs in Web Worker, client code in iframe | +| `'use client'` directive | Ignored (everything is client) | Required to mark client components | +| `'use server'` directive | Not supported | Marks Server Functions callable from client | +| `async` components | Not supported | Supported (server components can be async) | +| External dependencies | Supported via `package.json` | Not supported (only React + react-dom) | +| Entry point | `App.js` with `export default` | `src/App.js` with `export default` | +| Component tag | `` | `` | + +--- + +## File Directives + +Files are classified by the directive at the top of the file: + +| Directive | Where it runs | Rules | +|-----------|--------------|-------| +| (none) | Web Worker (server) | Default. Can be `async`. Can import other server files. Cannot use hooks, event handlers, or browser APIs. | +| `'use client'` | Sandpack iframe (browser) | Must be first statement. Can use hooks, event handlers, browser APIs. Cannot be `async`. Cannot import server files. | +| `'use server'` | Web Worker (server) | Marks Server Functions. Can be module-level (all exports are actions) or function-level. Callable from client via props or form `action`. | + +--- + +## Common Patterns + +### 1. Server + Client Components + +```mdx + + +` ` `js src/App.js +import Counter from './Counter'; + +export default function App() { + return ( +
+

Server-rendered heading

+ +
+ ); +} +` ` ` + +` ` `js src/Counter.js +'use client'; + +import { useState } from 'react'; + +export default function Counter() { + const [count, setCount] = useState(0); + return ( + + ); +} +` ` ` + + +``` + +### 2. Async Server Component with Suspense + +```mdx + + +` ` `js src/App.js +import { Suspense } from 'react'; +import Albums from './Albums'; + +export default function App() { + return ( + Loading...

}> + + + ); +} +` ` ` + +` ` `js src/Albums.js +async function fetchAlbums() { + await new Promise(resolve => setTimeout(resolve, 1000)); + return ['Abbey Road', 'Let It Be', 'Revolver']; +} + +export default async function Albums() { + const albums = await fetchAlbums(); + return ( +
    + {albums.map(album => ( +
  • {album}
    • + ))} +
+ ); +} +` ` ` + + +``` + +### 3. Server Functions (Actions) + +```mdx + + +` ` `js src/App.js +import { addLike, getLikeCount } from './actions'; +import LikeButton from './LikeButton'; + +export default async function App() { + const count = await getLikeCount(); + return ( +
+

Likes: {count}

+ +
+ ); +} +` ` ` + +` ` `js src/actions.js +'use server'; + +let count = 0; + +export async function addLike() { + count++; +} + +export async function getLikeCount() { + return count; +} +` ` ` + +` ` `js src/LikeButton.js +'use client'; + +export default function LikeButton({ addLike }) { + return ( + + + + ); +} +` ` ` + + +``` + +--- + +## File Structure Requirements + +### Entry Point + +- **`src/App.js` is required** as the main entry point +- Must have `export default` (function component) +- Case-insensitive fallback: `src/app.js` also works + +### Auto-Injected Infrastructure Files + +These files are automatically injected by `sandpack-rsc-setup.ts` and should never be included in MDX: + +| File | Purpose | +|------|---------| +| `/src/index.js` | Bootstraps the RSC pipeline | +| `/src/rsc-client.js` | Client bridge — creates Worker, consumes Flight stream | +| `/src/rsc-server.js` | Wraps pre-bundled worker runtime as ES module | +| `/node_modules/__webpack_shim__/index.js` | Minimal webpack compatibility layer | +| `/node_modules/__rsdw_client__/index.js` | `react-server-dom-webpack/client` as local dependency | + +### No External Dependencies + +`` does not support external npm packages. Only `react` and `react-dom` are available. Do not include `package.json` in RSC examples. + +--- + +## Architecture Reference + +### Three-Layer Architecture + +``` +react.dev page (Next.js) + ┌─────────────────────────────────────────┐ + │ │ + │ ┌─────────┐ ┌──────────────────────┐ │ + │ │ Editor │ │ Preview (iframe) │ │ + │ │ App.js │ │ Client React app │ │ + │ │ (edit) │ │ consumes Flight │ │ + │ │ │ │ stream from Worker │ │ + │ └─────────┘ └──────────┬───────────┘ │ + └───────────────────────────┼─────────────┘ + │ postMessage + ┌───────────────────────────▼─────────────┐ + │ Web Worker (Blob URL) │ + │ - React server build (pre-bundled) │ + │ - react-server-dom-webpack/server │ + │ - webpack shim │ + │ - User server code (Sucrase → CJS) │ + └─────────────────────────────────────────┘ +``` + +### Key Source Files + +| File | Purpose | +|-----------------------------------------------------------------|--------------------------------------------------------------------------------| +| `src/components/MDX/Sandpack/sandpack-rsc/RscFileBridge.tsx` | Monitors Sandpack; posts raw files to iframe | +| `src/components/MDX/Sandpack/SandpackRSCRoot.tsx` | SandpackProvider setup, custom bundler URL, UI layout | +| `src/components/MDX/Sandpack/templateRSC.ts` | RSC template files | +| `.../sandbox-code/src/__react_refresh_init__.js` | React Refresh shim | +| `.../sandbox-code/src/rsc-server.js` | Worker runtime: module system, Sucrase compilation, `renderToReadableStream()` | +| `.../sandbox-code/src/rsc-client.source.js` | Client bridge: Worker creation, file classification, Flight stream consumption | +| `.../sandbox-code/src/webpack-shim.js` | Minimal `__webpack_require__` / `__webpack_module_cache__` shim | +| `.../sandbox-code/src/worker-bundle.dist.js` | Pre-bundled IIFE (generated): React server + RSDW/server + Sucrase | +| `scripts/buildRscWorker.mjs` | esbuild script: bundles rsc-server.js into worker-bundle.dist.js | + +--- + +## Build System + +### Rebuilding the Worker Bundle + +After modifying `rsc-server.js` or `webpack-shim.js`: + +```bash +node scripts/buildRscWorker.mjs +``` + +This runs esbuild with: +- `format: 'iife'`, `platform: 'browser'` +- `conditions: ['react-server', 'browser']` (activates React server export conditions) +- `minify: true` +- Prepends `webpack-shim.js` to the output + +### Raw-Loader Configuration + +In `templateRSC.js` files are loaded as raw strings with the `!raw-loader`. + +The strings are necessary to provide to Sandpack as local files (skips Sandpack bundling). + + +### Development Commands + +```bash +node scripts/buildRscWorker.mjs # Rebuild worker bundle after source changes +yarn dev # Start dev server to test examples +``` \ No newline at end of file diff --git a/.claude/skills/docs-sandpack/SKILL.md b/.claude/skills/docs-sandpack/SKILL.md new file mode 100644 index 00000000000..0904a98c096 --- /dev/null +++ b/.claude/skills/docs-sandpack/SKILL.md @@ -0,0 +1,447 @@ +--- +name: docs-sandpack +description: Use when adding interactive code examples to React docs. +--- + +# Sandpack Patterns + +## Quick Start Template + +Most examples are single-file. Copy this and modify: + +```mdx + + +` ` `js +import { useState } from 'react'; + +export default function Example() { + const [value, setValue] = useState(0); + + return ( + + ); +} +` ` ` + + +``` + +--- + +## File Naming + +| Pattern | Usage | +|---------|-------| +| ` ```js ` | Main file (no prefix) | +| ` ```js src/FileName.js ` | Supporting files | +| ` ```js src/File.js active ` | Active file (reference pages) | +| ` ```js src/data.js hidden ` | Hidden files | +| ` ```css ` | CSS styles | +| ` ```json package.json ` | External dependencies | + +**Critical:** Main file must have `export default`. + +## Line Highlighting + +```mdx +```js {2-4} +function Example() { + // Lines 2-4 + // will be + // highlighted + return null; +} +``` + +## Code References (numbered callouts) + +```mdx +```js [[1, 4, "age"], [2, 4, "setAge"]] +// Creates numbered markers pointing to "age" and "setAge" on line 4 +``` + +## Expected Errors (intentionally broken examples) + +```mdx +```js {expectedErrors: {'react-compiler': [7]}} +// Line 7 shows as expected error +``` + +## Multi-File Example + +```mdx + + +```js src/App.js +import Gallery from './Gallery.js'; + +export default function App() { + return ; +} +``` + +```js src/Gallery.js +export default function Gallery() { + return

Gallery

; +} +``` + +```css +h1 { color: purple; } +``` + + +``` + +## External Dependencies + +```mdx + + +```js +import { useImmer } from 'use-immer'; +// ... +``` + +```json package.json +{ + "dependencies": { + "immer": "1.7.3", + "use-immer": "0.5.1", + "react": "latest", + "react-dom": "latest", + "react-scripts": "latest" + } +} +``` + + +``` + +## Code Style in Sandpack (Required) + +Sandpack examples are held to strict code style standards: + +1. **Function declarations** for components (not arrows) +2. **`e`** for event parameters +3. **Single quotes** in JSX +4. **`const`** unless reassignment needed +5. **Spaces in destructuring**: `({ props })` not `({props})` +6. **Two-line createRoot**: separate declaration and render call +7. **Multiline if statements**: always use braces + +### Don't Create Hydration Mismatches + +Sandpack examples must produce the same output on server and client: + +```js +// 🚫 This will cause hydration warnings +export default function App() { + const isClient = typeof window !== 'undefined'; + return
{isClient ? 'Client' : 'Server'}
; +} +``` + +### Use Ref for Non-Rendered State + +```js +// 🚫 Don't trigger re-renders for non-visual state +const [mounted, setMounted] = useState(false); +useEffect(() => { setMounted(true); }, []); + +// ✅ Use ref instead +const mounted = useRef(false); +useEffect(() => { mounted.current = true; }, []); +``` + +## forwardRef and memo Patterns + +### forwardRef - Use Named Function +```js +// ✅ Named function for DevTools display name +const MyInput = forwardRef(function MyInput(props, ref) { + return ; +}); + +// 🚫 Anonymous loses name +const MyInput = forwardRef((props, ref) => { ... }); +``` + +### memo - Use Named Function +```js +// ✅ Preserves component name +const Greeting = memo(function Greeting({ name }) { + return

Hello, {name}

; +}); +``` + +## Line Length + +- Prose: ~80 characters +- Code: ~60-70 characters +- Break long lines to avoid horizontal scrolling + +## Anti-Patterns + +| Pattern | Problem | Fix | +|---------|---------|-----| +| `const Comp = () => {}` | Not standard | `function Comp() {}` | +| `onClick={(event) => ...}` | Conflicts with global | `onClick={(e) => ...}` | +| `useState` for non-rendered values | Re-renders | Use `useRef` | +| Reading `window` during render | Hydration mismatch | Check in useEffect | +| Single-line if without braces | Harder to debug | Use multiline with braces | +| Chained `createRoot().render()` | Less clear | Two statements | +| `//...` without space | Inconsistent | `// ...` with space | +| Tabs | Inconsistent | 2 spaces | +| `ReactDOM.render` | Deprecated | Use `createRoot` | +| Fake package names | Confusing | Use `'./your-storage-layer'` | +| `PropsWithChildren` | Outdated | `children?: ReactNode` | +| Missing `key` in lists | Warnings | Always include key | + +## Additional Code Quality Rules + +### Always Include Keys in Lists +```js +// ✅ Correct +{items.map(item =>
  • {item.name}
    • )} + +// 🚫 Wrong - missing key +{items.map(item =>
  • {item.name}
    • )} +``` + +### Use Realistic Import Paths +```js +// ✅ Correct - descriptive path +import { fetchData } from './your-data-layer'; + +// 🚫 Wrong - looks like a real npm package +import { fetchData } from 'cool-data-lib'; +``` + +### Console.log Labels +```js +// ✅ Correct - labeled for clarity +console.log('User:', user); +console.log('Component Stack:', errorInfo.componentStack); + +// 🚫 Wrong - unlabeled +console.log(user); +``` + +### Keep Delays Reasonable +```js +// ✅ Correct - 1-1.5 seconds +setTimeout(() => setLoading(false), 1000); + +// 🚫 Wrong - too long, feels sluggish +setTimeout(() => setLoading(false), 3000); +``` + +## Updating Line Highlights + +When modifying code in examples with line highlights (`{2-4}`), **always update the highlight line numbers** to match the new code. Incorrect line numbers cause rendering crashes. + +## File Name Conventions + +- Capitalize file names for component files: `Gallery.js` not `gallery.js` +- After initially explaining files are in `src/`, refer to files by name only: `Gallery.js` not `src/Gallery.js` + +## Naming Conventions in Code + +**Components:** PascalCase +- `Profile`, `Avatar`, `TodoList`, `PackingList` + +**State variables:** Destructured pattern +- `const [count, setCount] = useState(0)` +- Booleans: `[isOnline, setIsOnline]`, `[isPacked, setIsPacked]` +- Status strings: `'typing'`, `'submitting'`, `'success'`, `'error'` + +**Event handlers:** +- `handleClick`, `handleSubmit`, `handleAddTask` + +**Props for callbacks:** +- `onClick`, `onChange`, `onAddTask`, `onSelect` + +**Custom Hooks:** +- `useOnlineStatus`, `useChatRoom`, `useFormInput` + +**Reducer actions:** +- Past tense: `'added'`, `'changed'`, `'deleted'` +- Snake_case compounds: `'changed_selection'`, `'sent_message'` + +**Updater functions:** Single letter +- `setCount(n => n + 1)` + +### Pedagogical Code Markers + +**Wrong vs right code:** +```js +// 🔴 Avoid: redundant state and unnecessary Effect +// ✅ Good: calculated during rendering +``` + +**Console.log for lifecycle teaching:** +```js +console.log('✅ Connecting...'); +console.log('❌ Disconnected.'); +``` + +### Server/Client Labeling + +```js +// Server Component +async function Notes() { + const notes = await db.notes.getAll(); +} + +// Client Component +"use client" +export default function Expandable({children}) { + const [expanded, setExpanded] = useState(false); +} +``` + +### Bundle Size Annotations + +```js +import marked from 'marked'; // 35.9K (11.2K gzipped) +import sanitizeHtml from 'sanitize-html'; // 206K (63.3K gzipped) +``` + +--- + +## Sandpack Example Guidelines + +### Package.json Rules + +**Include package.json when:** +- Using external npm packages (immer, remarkable, leaflet, toastify-js, etc.) +- Demonstrating experimental/canary React features +- Requiring specific React versions (`react: beta`, `react: 19.0.0-rc-*`) + +**Omit package.json when:** +- Example uses only built-in React features +- No external dependencies needed +- Teaching basic hooks, state, or components + +**Always mark package.json as hidden:** +```mdx +```json package.json hidden +{ + "dependencies": { + "react": "latest", + "react-dom": "latest", + "react-scripts": "latest", + "immer": "1.7.3" + } +} +``` +``` + +**Version conventions:** +- Use `"latest"` for stable features +- Use exact versions only when compatibility requires it +- Include minimal dependencies (just what the example needs) + +### Hidden File Patterns + +**Always hide these file types:** + +| File Type | Reason | +|-----------|--------| +| `package.json` | Configuration not the teaching point | +| `sandbox.config.json` | Sandbox setup is boilerplate | +| `public/index.html` | HTML structure not the focus | +| `src/data.js` | When it contains sample/mock data | +| `src/api.js` | When showing API usage, not implementation | +| `src/styles.css` | When styling is not the lesson | +| `src/router.js` | Supporting infrastructure | +| `src/actions.js` | Server action implementation details | + +**Rationale:** +- Reduces cognitive load +- Keeps focus on the primary concept +- Creates cleaner, more focused examples + +**Example:** +```mdx +```js src/data.js hidden +export const items = [ + { id: 1, name: 'Item 1' }, + { id: 2, name: 'Item 2' }, +]; +``` +``` + +### Active File Patterns + +**Mark as active when:** +- File contains the primary teaching concept +- Learner should focus on this code first +- Component demonstrates the hook/pattern being taught + +**Effect of the `active` marker:** +- Sets initial editor tab focus when Sandpack loads +- Signals "this is what you should study" +- Works with hidden files to create focused examples + +**Most common active file:** `src/index.js` or `src/App.js` + +**Example:** +```mdx +```js src/App.js active +// This file will be focused when example loads +export default function App() { + // ... +} +``` +``` + +### File Structure Guidelines + +| Scenario | Structure | Reason | +|----------|-----------|--------| +| Basic hook usage | Single file | Simple, focused | +| Teaching imports | 2-3 files | Shows modularity | +| Context patterns | 4-5 files | Realistic structure | +| Complex state | 3+ files | Separation of concerns | + +**Single File Examples (70% of cases):** +- Use for simple concepts +- 50-200 lines typical +- Best for: Counter, text inputs, basic hooks + +**Multi-File Examples (30% of cases):** +- Use when teaching modularity/imports +- Use for context patterns (4-5 files) +- Use when component is reused + +**File Naming:** +- Main component: `App.js` (capitalized) +- Component files: `Gallery.js`, `Button.js` (capitalized) +- Data files: `data.js` (lowercase) +- Utility files: `utils.js` (lowercase) +- Context files: `TasksContext.js` (named after what they provide) + +### Code Size Limits + +- Single file: **<200 lines** +- Multi-file total: **150-300 lines** +- Main component: **100-150 lines** +- Supporting files: **20-40 lines each** + +### CSS Guidelines + +**Always:** +- Include minimal CSS for demo interactivity +- Use semantic class names (`.panel`, `.button-primary`, `.panel-dark`) +- Support light/dark themes when showing UI concepts +- Keep CSS visible (never hidden) + +**Size Guidelines:** +- Minimal (5-10 lines): Basic button styling, spacing +- Medium (15-30 lines): Panel styling, form layouts +- Complex (40+ lines): Only for layout-focused examples diff --git a/.claude/skills/docs-voice/SKILL.md b/.claude/skills/docs-voice/SKILL.md new file mode 100644 index 00000000000..124e5f048fc --- /dev/null +++ b/.claude/skills/docs-voice/SKILL.md @@ -0,0 +1,137 @@ +--- +name: docs-voice +description: Use when writing any React documentation. Provides voice, tone, and style rules for all doc types. +--- + +# React Docs Voice & Style + +## Universal Rules + +- **Capitalize React terms** when referring to the React concept in headings or as standalone concepts: + - Core: Hook, Effect, State, Context, Ref, Component, Fragment + - Concurrent: Transition, Action, Suspense + - Server: Server Component, Client Component, Server Function, Server Action + - Patterns: Error Boundary + - Canary: Activity, View Transition, Transition Type + - **In prose:** Use lowercase when paired with descriptors: "state variable", "state updates", "event handler". Capitalize when the concept stands alone or in headings: "State is isolated and private" + - General usage stays lowercase: "the page transitions", "takes an action" +- **Product names:** ESLint, TypeScript, JavaScript, Next.js (not lowercase) +- **Bold** for key concepts: **state variable**, **event handler** +- **Italics** for new terms being defined: *event handlers* +- **Inline code** for APIs: `useState`, `startTransition`, `` +- **Avoid:** "simple", "easy", "just", time estimates +- Frame differences as "capabilities" not "advantages/disadvantages" +- Avoid passive voice and jargon + +## Tone by Page Type + +| Type | Tone | Example | +|------|------|---------| +| Learn | Conversational | "Here's what that looks like...", "You might be wondering..." | +| Reference | Technical | "Call `useState` at the top level...", "This Hook returns..." | +| Blog | Accurate | Focus on facts, not marketing | + +**Note:** Pitfall and DeepDive components can use slightly more conversational phrasing ("You might wonder...", "It might be tempting...") even in Reference pages, since they're explanatory asides. + +## Avoiding Jargon + +**Pattern:** Explain behavior first, then name it. + +✅ "React waits until all code in event handlers runs before processing state updates. This is called *batching*." + +❌ "React uses batching to process state updates atomically." + +**Terms to avoid or explain:** +| Jargon | Plain Language | +|--------|----------------| +| atomic | all-or-nothing, batched together | +| idempotent | same inputs, same output | +| deterministic | predictable, same result every time | +| memoize | remember the result, skip recalculating | +| referentially transparent | (avoid - describe the behavior) | +| invariant | rule that must always be true | +| reify | (avoid - describe what's being created) | + +**Allowed technical terms in Reference pages:** +- "stale closures" - standard JS/React term, can be used in Caveats +- "stable identity" - React term for consistent object references across renders +- "reactive" - React term for values that trigger re-renders when changed +- These don't need explanation in Reference pages (readers are expected to know them) + +**Use established analogies sparingly—once when introducing a concept, not repeatedly:** + +| Concept | Analogy | +|---------|---------| +| Components/React | Kitchen (components as cooks, React as waiter) | +| Render phases | Restaurant ordering (trigger/render/commit) | +| State batching | Waiter collecting full order before going to kitchen | +| State behavior | Snapshot/photograph in time | +| State storage | React storing state "on a shelf" | +| State purpose | Component's memory | +| Pure functions | Recipes (same ingredients → same dish) | +| Pure functions | Math formulas (y = 2x) | +| Props | Adjustable "knobs" | +| Children prop | "Hole" to be filled by parent | +| Keys | File names in a folder | +| Curly braces in JSX | "Window into JavaScript" | +| Declarative UI | Taxi driver (destination, not turn-by-turn) | +| Imperative UI | Turn-by-turn navigation | +| State structure | Database normalization | +| Refs | "Secret pocket" React doesn't track | +| Effects/Refs | "Escape hatch" from React | +| Context | CSS inheritance / "Teleportation" | +| Custom Hooks | Design system | + +## Common Prose Patterns + +**Wrong vs Right code:** +```mdx +\`\`\`js +// 🚩 Don't mutate state: +obj.x = 10; +\`\`\` + +\`\`\`js +// ✅ Replace with new object: +setObj({ ...obj, x: 10 }); +\`\`\` +``` + +**Table comparisons:** +```mdx +| passing a function | calling a function | +| `onClick={handleClick}` | `onClick={handleClick()}` | +``` + +**Linking:** +```mdx +[Read about state](/learn/state-a-components-memory) +[See `useState` reference](/reference/react/useState) +``` + +## Code Style + +- Prefer JSX over createElement +- Use const/let, never var +- Prefer named function declarations for top-level functions +- Arrow functions for callbacks that need `this` preservation + +## Version Documentation + +When APIs change between versions: + +```mdx +Starting in React 19, render `` as a provider: +\`\`\`js +{children} +\`\`\` + +In older versions: +\`\`\`js +{children} +\`\`\` +``` + +Patterns: +- "Starting in React 19..." for new APIs +- "In older versions of React..." for legacy patterns diff --git a/.claude/skills/docs-writer-blog/SKILL.md b/.claude/skills/docs-writer-blog/SKILL.md new file mode 100644 index 00000000000..baa21c34d9a --- /dev/null +++ b/.claude/skills/docs-writer-blog/SKILL.md @@ -0,0 +1,756 @@ +--- +name: docs-writer-blog +description: 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: + +```yaml +--- +title: "Title in Quotes" +author: Author Name(s) +date: YYYY/MM/DD +description: One or two sentence summary. +--- +``` + +### 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: + +```markdown +--- + +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:** + +```markdown +December 05, 2024 by [The React Team](/community/team) + +--- +``` + +```markdown +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: + +1. **Frontmatter** (YAML) +2. **Author byline** with date +3. **Horizontal rule** (`---`) +4. **`` component** (1-3 sentences) +5. **Horizontal rule** (`---`) (optional) +6. **Main content sections** (H2 with IDs) +7. **Closing section** (Changelog, Thanks, etc.) + +--- + +## Post Type Templates + +### Major Release Announcement + +```markdown +--- +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) + +--- + + + +React vX.Y is now available on npm! + + + +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 + +```markdown +--- +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) + +--- + + + +[Summary of upgrade and what this guide covers.] + + + + + +#### Stepping stone version {/*stepping-stone*/} + +[If applicable, describe intermediate upgrade steps.] + + + +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*/} + +```bash +npx codemod@latest react/[VERSION]/migration-recipe +``` + + + +## Breaking changes {/*breaking-changes*/} + +### Removed: `apiName` {/*removed-api-name*/} + +`apiName` was deprecated in [Month YYYY (vX.X.X)](link). + +```js +// Before +[old code] + +// After +[new code] +``` + + + +Codemod [description]: + +```bash +npx codemod@latest react/[VERSION]/codemod-name +``` + + + +## New deprecations {/*new-deprecations*/} + +### Deprecated: `apiName` {/*deprecated-api-name*/} + +[Explanation and migration path.] + +--- + +Thanks to [Contributor](link) for reviewing this post. +``` + +### 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) + +--- + + + +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. + + + +[Optional: Roadmap disclaimer about timelines] + +--- + +## Feature Name {/*feature-name*/} + + + +`` is now available in React's Canary channel. + + + +[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 + +```markdown +--- +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) + +--- + + + +Last week we hosted React Conf [YEAR] [where we announced [key announcements]]. + + + +--- + +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: + + + +## Day 2 {/*day-2*/} + +_[Watch the full day 2 stream here.](youtube-url)_ + +[Day 2 summary.] + + + +## 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 + +```markdown +--- +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) + +--- + + + +Today we are [excited/thrilled] to announce [feature]. [What this means for users.] + + + +--- + +## 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]: + + +npm install package-name + + +[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 + +```markdown +--- +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) + +--- + + + +[One or two sentences summarizing the vulnerability.] + +We recommend upgrading immediately. + + + +--- + +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](url) 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 | +|-----------|---------------| +| `` | **Required** - Opening summary after byline | +| `` | Callouts, caveats, important clarifications | +| `` | Warnings about common mistakes | +| `` | Optional technical deep dives (use sparingly) | +| `` | CLI/installation commands | +| `` | Console error/warning output | +| `` | Multi-line console output | +| `` | Conference video embeds | +| `` | Visual explanations | +| `` | Auto-generated table of contents | + +### `` Pattern + +Always wrap opening paragraph: + +```markdown + + +React 19 is now available on npm! + + +``` + +### `` Patterns + +**Simple note:** +```markdown + + +For React Native users, React 18 ships with the New Architecture. + + +``` + +**Titled note (H4 inside):** +```markdown + + +#### React 18.3 has also been published {/*react-18-3*/} + +To help with the upgrade, we've published `react@18.3`... + + +``` + +### `` Pattern + +```markdown + +npm install react@latest react-dom@latest + +``` + +### `` Pattern + +```markdown + +``` + +--- + +## Link Patterns + +### Internal Links + +| Type | Pattern | Example | +|------|---------|---------| +| Blog post | `/blog/YYYY/MM/DD/slug` | `/blog/2024/12/05/react-19` | +| API reference | `/reference/react/HookName` | `/reference/react/useState` | +| Learn section | `/learn/topic-name` | `/learn/react-compiler` | +| Community | `/community/team` | `/community/team` | + +### External Links + +| Type | Pattern | +|------|---------| +| GitHub PR | `[#12345](https://github.com/react/react/pull/12345)` | +| GitHub user | `[@username](https://github.com/username)` | +| Twitter/X | `[@username](https://x.com/username)` | +| Bluesky | `[Name](https://bsky.app/profile/handle)` | +| CVE | `[CVE-YYYY-NNNNN](https://www.cve.org/CVERecord?id=CVE-YYYY-NNNNN)` | +| npm package | `[package](https://www.npmjs.com/package/package)` | + +### "See docs" Pattern + +```markdown +For more information, see the docs for [`useActionState`](/reference/react/useActionState). +``` + +--- + +## Changelog Format + +### Bullet Pattern + +```markdown +* Add `useTransition` for concurrent rendering. ([#10426](https://github.com/react/react/pull/10426) by [@acdlite](https://github.com/acdlite)) +* Fix `useReducer` observing incorrect props. ([#22445](https://github.com/react/react/pull/22445) by [@josephsavona](https://github.com/josephsavona)) +``` + +**Structure:** `Verb` + backticked API + description + `([#PR](url) by [@user](url))` + +**Verbs:** Add, Fix, Remove, Make, Improve, Allow, Deprecate + +### Section Organization + +```markdown +## Changelog {/*changelog*/} + +### React {/*react*/} + +* [changes] + +### React DOM {/*react-dom*/} + +* [changes] +``` + +--- + +## Acknowledgments Format + +### Post-closing Thanks + +```markdown +--- + +Thanks to [Name](url), [Name](url), and [Name](url) for reviewing this post. +``` + +Or italicized: + +```markdown +_Thanks to [Name](url) for reviewing this post._ +``` + +### Update Notes + +For post-publication updates: + +```markdown + + +[Updated content] + +----- + +_Updated January 26, 2026._ + + +``` + +--- + +## Tone & Length by Post Type + +| Type | Tone | Length | Key Elements | +|------|------|--------|--------------| +| Release | Celebratory, informative | Medium-long | Feature overview, upgrade link, changelog | +| Upgrade | Instructional, precise | Long | Step-by-step, codemods, breaking changes | +| Labs | Transparent, exploratory | Medium | Status updates, roadmap disclaimers | +| Conf | Enthusiastic, community-focused | Medium | YouTube embeds, speaker credits | +| Feature | Excited, explanatory | Medium | tl;dr, "why", getting started | +| Security | Urgent, factual | Short-medium | Immediate action, timeline, CVE | + +--- + +## Do's and Don'ts + +**Do:** +- Focus on facts over marketing +- Say "upcoming" explicitly for unreleased features +- Include FAQ sections for major announcements +- Credit contributors and link to GitHub +- Use "we" voice for team posts +- Link to upgrade guides from release posts +- Include table of contents for long posts +- End with acknowledgments + +**Don't:** +- Promise features not yet available +- Rewrite history (add update notes instead) +- Break existing URLs +- Use hyperbolic language ("revolutionary", "game-changing") +- Skip the `` component +- Forget heading IDs +- Use heavy component nesting in blogs +- Make time estimates or predictions + +--- + +## Updating Old Posts + +- Never break existing URLs; add redirects when URLs change +- Don't rewrite history; add update notes instead: + ```markdown + + + [Updated information] + + ----- + + _Updated Month Year._ + + + ``` + +--- + +## Critical Rules + +1. **Heading IDs required:** `## Title {/*title-id*/}` +2. **`` required:** Every post starts with `` component +3. **Byline required:** Date + linked author(s) after frontmatter +4. **Date format:** Frontmatter uses `YYYY/MM/DD`, byline uses `Month DD, YYYY` +5. **Link to docs:** New APIs must link to reference documentation +6. **Security posts:** Always include "We recommend upgrading immediately" + +--- + +## Components Reference + +For complete MDX component patterns, invoke `/docs-components`. + +Blog posts commonly use: ``, ``, ``, ``, ``, ``, ``, ``. + +Prefer inline explanations over heavy component usage. diff --git a/.claude/skills/docs-writer-learn/SKILL.md b/.claude/skills/docs-writer-learn/SKILL.md new file mode 100644 index 00000000000..57dc9ef745c --- /dev/null +++ b/.claude/skills/docs-writer-learn/SKILL.md @@ -0,0 +1,299 @@ +--- +name: docs-writer-learn +description: Use when writing or editing files in src/content/learn/. Provides Learn page structure and tone. +--- + +# Learn Page Writer + +## Persona + +**Voice:** Patient teacher guiding a friend through concepts +**Tone:** Conversational, warm, encouraging + +## Voice & Style + +For tone, capitalization, jargon, and prose patterns, invoke `/docs-voice`. + +## Page Structure Variants + +### 1. Standard Learn Page (Most Common) + +```mdx +--- +title: Page Title +--- + + +1-3 sentences introducing the concept. Use *italics* for new terms. + + + + +* Learning outcome 1 +* Learning outcome 2 +* Learning outcome 3-5 + + + +## Section Name {/*section-id*/} + +Content with Sandpack examples, Pitfalls, Notes, DeepDives... + +## Another Section {/*another-section*/} + +More content... + + + +* Summary point 1 +* Summary point 2 +* Summary points 3-9 + + + + + +#### Challenge title {/*challenge-id*/} + +Description... + + +Optional guidance (single paragraph) + + + +{/* Starting code */} + + + +Explanation... + + +{/* Fixed code */} + + + + +``` + +### 2. Chapter Introduction Page + +For pages that introduce a chapter (like describing-the-ui.md, managing-state.md): + +```mdx + + +* [Sub-page title](/learn/sub-page-name) to learn... +* [Another page](/learn/another-page) to learn... + + + +## Preview Section {/*section-id*/} + +Preview description with mini Sandpack example + + + +Read **[Page Title](/learn/sub-page-name)** to learn how to... + + + +## What's next? {/*whats-next*/} + +Head over to [First Page](/learn/first-page) to start reading this chapter page by page! +``` + +**Important:** Chapter intro pages do NOT include `` or `` sections. + +### 3. Tutorial Page + +For step-by-step tutorials (like tutorial-tic-tac-toe.md): + +```mdx + +Brief statement of what will be built + + + +Alternative learning path offered + + +Table of contents (prose listing of major sections) + +## Setup {/*setup*/} +... + +## Main Content {/*main-content*/} +Progressive code building with ### subsections + +No YouWillLearn, Recap, or Challenges + +Ends with ordered list of "extra credit" improvements +``` + +### 4. Reference-Style Learn Page + +For pages with heavy API documentation (like typescript.md): + +```mdx + + +* [Link to section](#section-anchor) +* [Link to another section](#another-section) + + + +## Sections with ### subsections + +## Further learning {/*further-learning*/} + +No Recap or Challenges +``` + +## Heading ID Conventions + +All headings require IDs in `{/*kebab-case*/}` format: + +```markdown +## Section Title {/*section-title*/} +### Subsection Title {/*subsection-title*/} +#### DeepDive Title {/*deepdive-title*/} +``` + +**ID Generation Rules:** +- Lowercase everything +- Replace spaces with hyphens +- Remove apostrophes, quotes +- Remove or convert special chars (`:`, `?`, `!`, `.`, parentheses) + +**Examples:** +- "What's React?" → `{/*whats-react*/}` +- "Step 1: Create the context" → `{/*step-1-create-the-context*/}` +- "Conditional (ternary) operator (? :)" → `{/*conditional-ternary-operator--*/}` + +## Teaching Patterns + +### Problem-First Teaching + +Show broken/problematic code BEFORE the solution: + +1. Present problematic approach with `// 🔴 Avoid:` comment +2. Explain WHY it's wrong (don't just say it is) +3. Show the solution with `// ✅ Good:` comment +4. Invite experimentation + +### Progressive Complexity + +Build understanding in layers: +1. Show simplest working version +2. Identify limitation or repetition +3. Introduce solution incrementally +4. Show complete solution +5. Invite experimentation: "Try changing..." + +### Numbered Step Patterns + +For multi-step processes: + +**As section headings:** +```markdown +### Step 1: Action to take {/*step-1-action*/} +### Step 2: Next action {/*step-2-next-action*/} +``` + +**As inline lists:** +```markdown +To implement this: +1. **Declare** `inputRef` with the `useRef` Hook. +2. **Pass it** as ``. +3. **Read** the input DOM node from `inputRef.current`. +``` + +### Interactive Invitations + +After Sandpack examples, encourage experimentation: +- "Try changing X to Y. See how...?" +- "Try it in the sandbox above!" +- "Click each button separately:" +- "Have a guess!" +- "Verify that..." + +### Decision Questions + +Help readers build intuition: +> "When you're not sure whether some code should be in an Effect or in an event handler, ask yourself *why* this code needs to run." + +## Component Placement Order + +1. `` - First after frontmatter +2. `` - After Intro (standard/chapter pages) +3. Body content with ``, ``, `` placed contextually +4. `` - Before Challenges (standard pages only) +5. `` - End of page (standard pages only) + +For component structure and syntax, invoke `/docs-components`. + +## Code Examples + +For Sandpack file structure, naming conventions, code style, and pedagogical markers, invoke `/docs-sandpack`. + +## Cross-Referencing + +### When to Link + +**Link to /learn:** +- Explaining concepts or mental models +- Teaching how things work together +- Tutorials and guides +- "Why" questions + +**Link to /reference:** +- API details, Hook signatures +- Parameter lists and return values +- Rules and restrictions +- "What exactly" questions + +### Link Formats + +```markdown +[concept name](/learn/page-name) +[`useState`](/reference/react/useState) +[section link](/learn/page-name#section-id) +[MDN](https://developer.mozilla.org/...) +``` + +## Section Dividers + +**Important:** Learn pages typically do NOT use `---` dividers. The heading hierarchy provides sufficient structure. Only consider dividers in exceptional cases like separating main content from meta/contribution sections. + +## Do's and Don'ts + +**Do:** +- Use "you" to address the reader +- Show broken code before fixes +- Explain behavior before naming concepts +- Build concepts progressively +- Include interactive Sandpack examples +- Use established analogies consistently +- Place Pitfalls AFTER explaining concepts +- Invite experimentation with "Try..." phrases + +**Don't:** +- Use "simple", "easy", "just", or time estimates +- Reference concepts not yet introduced +- Skip required components for page type +- Use passive voice without reason +- Place Pitfalls before teaching the concept +- Use `---` dividers between sections +- Create unnecessary abstraction in examples +- Place consecutive Pitfalls or Notes without separating prose (combine or separate) + +## Critical Rules + +1. **All headings require IDs:** `## Title {/*title-id*/}` +2. **Chapter intros use `isChapter={true}` and ``** +3. **Tutorial pages omit YouWillLearn/Recap/Challenges** +4. **Problem-first teaching:** Show broken → explain → fix +5. **No consecutive Pitfalls/Notes:** See `/docs-components` Callout Spacing Rules + +For component patterns, invoke `/docs-components`. For Sandpack patterns, invoke `/docs-sandpack`. diff --git a/.claude/skills/docs-writer-reference/SKILL.md b/.claude/skills/docs-writer-reference/SKILL.md new file mode 100644 index 00000000000..e63c00fcaae --- /dev/null +++ b/.claude/skills/docs-writer-reference/SKILL.md @@ -0,0 +1,885 @@ +--- +name: docs-writer-reference +description: Reference page structure, templates, and writing patterns for src/content/reference/. For components, see /docs-components. For code examples, see /docs-sandpack. +--- + +# Reference Page Writer + +## Quick Reference + +### Page Type Decision Tree + +1. Is it a Hook? Use **Type A (Hook/Function)** +2. Is it a React component (``)? Use **Type B (Component)** +3. Is it a compiler configuration option? Use **Type C (Configuration)** +4. Is it a directive (`'use something'`)? Use **Type D (Directive)** +5. Is it an ESLint rule? Use **Type E (ESLint Rule)** +6. Is it listing multiple APIs? Use **Type F (Index/Category)** + +### Component Selection + +For component selection and patterns, invoke `/docs-components`. + +--- + +## Voice & Style + +**Voice:** Authoritative technical reference writer +**Tone:** Precise, comprehensive, neutral + +For tone, capitalization, jargon, and prose patterns, invoke `/docs-voice`. + +**Do:** +- Start with single-line description: "`useState` is a React Hook that lets you..." +- Include Parameters, Returns, Caveats sections for every API +- Document edge cases most developers will encounter +- Use section dividers between major sections +- Include "See more examples below" links +- Be assertive, not hedging - "This is designed for..." not "This helps avoid issues with..." +- State facts, not benefits - "The callback always accesses the latest values" not "This helps avoid stale closures" +- Use minimal but meaningful names - `onEvent` or `onTick` over `onSomething` + +**Don't:** +- Skip the InlineToc component +- Omit error cases or caveats +- Use conversational language +- Mix teaching with reference (that's Learn's job) +- Document past bugs or fixed issues +- Include niche edge cases (e.g., `this` binding, rare class patterns) +- Add phrases explaining "why you'd want this" - the Usage section examples do that +- Exception: Pitfall and DeepDive asides can use slightly conversational phrasing + +--- + +## Page Templates + +### Type A: Hook/Function + +**When to use:** Documenting React hooks and standalone functions (useState, useEffect, memo, lazy, etc.) + +```mdx +--- +title: hookName +--- + + + +`hookName` is a React Hook that lets you [brief description]. + +```js +const result = hookName(arg) +``` + + + + + +--- + +## Reference {/*reference*/} + +### `hookName(arg)` {/*hookname*/} + +Call `hookName` at the top level of your component to... + +```js +[signature example with annotations] +``` + +[See more examples below.](#usage) + +#### Parameters {/*parameters*/} +* `arg`: Description of the parameter. + +#### Returns {/*returns*/} +Description of return value. + +#### Caveats {/*caveats*/} +* Important caveat about usage. + +--- + +## Usage {/*usage*/} + +### Common Use Case {/*common-use-case*/} +Explanation with Sandpack examples... + +--- + +## Troubleshooting {/*troubleshooting*/} + +### Common Problem {/*common-problem*/} +How to solve it... +``` + +--- + +### Type B: Component + +**When to use:** Documenting React components (Suspense, Fragment, Activity, StrictMode) + +```mdx +--- +title: +--- + + + +`` lets you [primary action]. + +```js + + + +``` + + + + + +--- + +## Reference {/*reference*/} + +### `` {/*componentname*/} + +[Component purpose and behavior] + +#### Props {/*props*/} + +* `propName`: Description of the prop... +* **optional** `optionalProp`: Description... + +#### Caveats {/*caveats*/} + +* [Caveats specific to this component] +``` + +**Key differences from Hook pages:** +- Title uses JSX syntax: `` +- Uses `#### Props` instead of `#### Parameters` +- Reference heading uses JSX: `` ### `` `` + +--- + +### Type C: Configuration + +**When to use:** Documenting React Compiler configuration options + +```mdx +--- +title: optionName +--- + + + +The `optionName` option [controls/specifies/determines] [what it does]. + + + +```js +{ + optionName: 'value' // Quick example +} +``` + + + +--- + +## Reference {/*reference*/} + +### `optionName` {/*optionname*/} + +[Description of the option's purpose] + +#### Type {/*type*/} + +``` +'value1' | 'value2' | 'value3' +``` + +#### Default value {/*default-value*/} + +`'value1'` + +#### Options {/*options*/} + +- **`'value1'`** (default): Description +- **`'value2'`**: Description +- **`'value3'`**: Description + +#### Caveats {/*caveats*/} + +* [Usage caveats] +``` + +--- + +### Type D: Directive + +**When to use:** Documenting directives like 'use server', 'use client', 'use memo' + +```mdx +--- +title: "'use directive'" +titleForTitleTag: "'use directive' directive" +--- + + + +`'use directive'` is for use with [React Server Components](/reference/rsc/server-components). + + + + + +`'use directive'` marks [what it marks] for [purpose]. + +```js {1} +function MyComponent() { + 'use directive'; + // ... +} +``` + + + + + +--- + +## Reference {/*reference*/} + +### `'use directive'` {/*use-directive*/} + +Add `'use directive'` at the beginning of [location] to [action]. + +#### Caveats {/*caveats*/} + +* `'use directive'` must be at the very beginning... +* The directive must be written with single or double quotes, not backticks. +* [Other placement/syntax caveats] +``` + +**Key characteristics:** +- Title includes quotes: `title: "'use server'"` +- Uses `titleForTitleTag` for browser tab title +- `` block appears before `` +- Caveats focus on placement and syntax requirements + +--- + +### Type E: ESLint Rule + +**When to use:** Documenting ESLint plugin rules + +```mdx +--- +title: rule-name +--- + + +Validates that [what the rule checks]. + + +## Rule Details {/*rule-details*/} + +[Explanation of why this rule exists and React's underlying assumptions] + +## Common Violations {/*common-violations*/} + +[Description of violation patterns] + +### Invalid {/*invalid*/} + +Examples of incorrect code for this rule: + +```js +// X Missing dependency +useEffect(() => { + console.log(count); +}, []); // Missing 'count' +``` + +### Valid {/*valid*/} + +Examples of correct code for this rule: + +```js +// checkmark All dependencies included +useEffect(() => { + console.log(count); +}, [count]); +``` + +## Troubleshooting {/*troubleshooting*/} + +### [Problem description] {/*problem-slug*/} + +[Solution] + +## Options {/*options*/} + +[Configuration options if applicable] +``` + +**Key characteristics:** +- Intro is a single "Validates that..." sentence +- Uses "Invalid"/"Valid" sections with emoji-prefixed code comments +- Rule Details explains "why" not just "what" + +--- + +### Type F: Index/Category + +**When to use:** Overview pages listing multiple APIs in a category + +```mdx +--- +title: "Built-in React [Type]" +--- + + + +*Concept* let you [purpose]. Brief scope statement. + + + +--- + +## Category Name {/*category-name*/} + +*Concept* explanation with [Learn section link](/learn/topic). + +To [action], use one of these [Type]: + +* [`apiName`](/reference/react/apiName) lets you [action]. +* [`apiName`](/reference/react/apiName) declares [thing]. + +```js +function Example() { + const value = useHookName(args); +} +``` + +--- + +## Your own [Type] {/*your-own-type*/} + +You can also [define your own](/learn/topic) as JavaScript functions. +``` + +**Key characteristics:** +- Title format: "Built-in React [Type]" +- Italicized concept definitions +- Horizontal rules between sections +- Closes with "Your own [Type]" section + +--- + +## Advanced Patterns + +### Multi-Function Documentation + +**When to use:** When a hook returns a function that needs its own documentation (useState's setter, useReducer's dispatch) + +```md +### `hookName(args)` {/*hookname*/} + +[Main hook documentation] + +#### Parameters {/*parameters*/} +#### Returns {/*returns*/} +#### Caveats {/*caveats*/} + +--- + +### `set` functions, like `setSomething(nextState)` {/*setstate*/} + +The `set` function returned by `hookName` lets you [action]. + +#### Parameters {/*setstate-parameters*/} +#### Returns {/*setstate-returns*/} +#### Caveats {/*setstate-caveats*/} +``` + +**Key conventions:** +- Horizontal rule (`---`) separates main hook from returned function +- Heading IDs include prefix: `{/*setstate-parameters*/}` vs `{/*parameters*/}` +- Use generic names: "set functions" not "setCount" + +--- + +### Compound Return Objects + +**When to use:** When a function returns an object with multiple properties/methods (createContext) + +```md +### `createContext(defaultValue)` {/*createcontext*/} + +[Main function documentation] + +#### Returns {/*returns*/} + +`createContext` returns a context object. + +**The context object itself does not hold any information.** It represents... + +* `SomeContext` lets you provide the context value. +* `SomeContext.Consumer` is an alternative way to read context. + +--- + +### `SomeContext` Provider {/*provider*/} + +[Documentation for Provider] + +#### Props {/*provider-props*/} + +--- + +### `SomeContext.Consumer` {/*consumer*/} + +[Documentation for Consumer] + +#### Props {/*consumer-props*/} +``` + +--- + +## Writing Patterns + +### Opening Lines by Page Type + +| Page Type | Pattern | Example | +|-----------|---------|---------| +| Hook | `` `hookName` is a React Hook that lets you [action]. `` | "`useState` is a React Hook that lets you add a state variable to your component." | +| Component | `` `` lets you [action]. `` | "`` lets you display a fallback until its children have finished loading." | +| API | `` `apiName` lets you [action]. `` | "`memo` lets you skip re-rendering a component when its props are unchanged." | +| Configuration | `` The `optionName` option [controls/specifies/determines] [what]. `` | "The `target` option specifies which React version the compiler generates code for." | +| Directive | `` `'directive'` [marks/opts/prevents] [what] for [purpose]. `` | "`'use server'` marks a function as callable from the client." | +| ESLint Rule | `` Validates that [condition]. `` | "Validates that dependency arrays for React hooks contain all necessary dependencies." | + +--- + +### Parameter Patterns + +**Simple parameter:** +```md +* `paramName`: Description of what it does. +``` + +**Optional parameter:** +```md +* **optional** `paramName`: Description of what it does. +``` + +**Parameter with special function behavior:** +```md +* `initialState`: The value you want the state to be initially. It can be a value of any type, but there is a special behavior for functions. This argument is ignored after the initial render. + * If you pass a function as `initialState`, it will be treated as an _initializer function_. It should be pure, should take no arguments, and should return a value of any type. +``` + +**Callback parameter with sub-parameters:** +```md +* `subscribe`: A function that takes a single `callback` argument and subscribes it to the store. When the store changes, it should invoke the provided `callback`. The `subscribe` function should return a function that cleans up the subscription. +``` + +**Nested options object:** +```md +* **optional** `options`: An object with options for this React root. + * **optional** `onCaughtError`: Callback called when React catches an error in an Error Boundary. + * **optional** `onUncaughtError`: Callback called when an error is thrown and not caught. + * **optional** `identifierPrefix`: A string prefix React uses for IDs generated by `useId`. +``` + +--- + +### Return Value Patterns + +**Single value return:** +```md +`hookName` returns the current value. The value will be the same as `initialValue` during the first render. +``` + +**Array return (numbered list):** +```md +`useState` returns an array with exactly two values: + +1. The current state. During the first render, it will match the `initialState` you have passed. +2. The [`set` function](#setstate) that lets you update the state to a different value and trigger a re-render. +``` + +**Object return (bulleted list):** +```md +`createElement` returns a React element object with a few properties: + +* `type`: The `type` you have passed. +* `props`: The `props` you have passed except for `ref` and `key`. +* `ref`: The `ref` you have passed. If missing, `null`. +* `key`: The `key` you have passed, coerced to a string. If missing, `null`. +``` + +**Promise return:** +```md +`prerender` returns a Promise: +- If rendering is successful, the Promise will resolve to an object containing: + - `prelude`: a [Web Stream](MDN-link) of HTML. + - `postponed`: a JSON-serializable object for resumption. +- If rendering fails, the Promise will be rejected. +``` + +**Wrapped function return:** +```md +`cache` returns a cached version of `fn` with the same type signature. It does not call `fn` in the process. + +When calling `cachedFn` with given arguments, it first checks if a cached result exists. If cached, it returns the result. If not, it calls `fn`, stores the result, and returns it. +``` + +--- + +### Caveats Patterns + +**Standard Hook caveat (almost always first for Hooks):** +```md +* `useXxx` is a Hook, so you can only call it **at the top level of your component** or your own Hooks. You can't call it inside loops or conditions. If you need that, extract a new component and move the state into it. +``` + +**Stable identity caveat (for returned functions):** +```md +* The `set` function has a stable identity, so you will often see it omitted from Effect dependencies, but including it will not cause the Effect to fire. +``` + +**Strict Mode caveat:** +```md +* In Strict Mode, React will **call your render function twice** in order to help you find accidental impurities. This is development-only behavior and does not affect production. +``` + +**Caveat with code example:** +```md +* It's not recommended to _suspend_ a render based on a store value returned by `useSyncExternalStore`. For example, the following is discouraged: + + ```js + const selectedProductId = useSyncExternalStore(...); + const data = use(fetchItem(selectedProductId)) // X Don't suspend based on store value + ``` +``` + +**Canary caveat:** +```md +* If you want to pass `ref` to a Fragment, you can't use the `<>...` syntax. +``` + +--- + +### Troubleshooting Patterns + +**Heading format (first person problem statements):** +```md +### I've updated the state, but logging gives me the old value {/*old-value*/} + +### My initializer or updater function runs twice {/*runs-twice*/} + +### I want to read the latest state from a callback {/*read-latest-state*/} +``` + +**Error message format:** +```md +### I'm getting an error: "Too many re-renders" {/*too-many-rerenders*/} + +### I'm getting an error: "Rendered more hooks than during the previous render" {/*more-hooks*/} +``` + +**Lint error format:** +```md +### I'm getting a lint error: "[exact error message]" {/*lint-error-slug*/} +``` + +**Problem-solution structure:** +1. State the problem with code showing the issue +2. Explain why it happens +3. Provide the solution with corrected code +4. Link to Learn section for deeper understanding + +--- + +### Code Comment Conventions + +For code comment conventions (wrong/right, legacy/recommended, server/client labeling, bundle size annotations), invoke `/docs-sandpack`. + +--- + +### Link Description Patterns + +| Pattern | Example | +|---------|---------| +| "lets you" + action | "`memo` lets you skip re-rendering when props are unchanged." | +| "declares" + thing | "`useState` declares a state variable that you can update directly." | +| "reads" + thing | "`useContext` reads and subscribes to a context." | +| "connects" + thing | "`useEffect` connects a component to an external system." | +| "Used with" | "Used with [`useContext`.](/reference/react/useContext)" | +| "Similar to" | "Similar to [`useTransition`.](/reference/react/useTransition)" | + +--- + +## Component Patterns + +For comprehensive MDX component patterns (Note, Pitfall, DeepDive, Recipes, Deprecated, RSC, Canary, Diagram, Code Steps), invoke `/docs-components`. + +For Sandpack-specific patterns and code style, invoke `/docs-sandpack`. + +### Reference-Specific Component Rules + +**Component placement in Reference pages:** +- `` goes before `` at top of page +- `` goes after `` for page-level deprecation +- `` goes after method heading for method-level deprecation +- `` wrapper goes inline within `` +- `` appears in headings, props lists, and caveats + +**Troubleshooting-specific components:** +- Use first-person problem headings +- Cross-reference Pitfall IDs when relevant + +**Callout spacing:** +- Never place consecutive Pitfalls or consecutive Notes +- Combine related warnings into one with titled subsections, or separate with prose/code +- Consecutive DeepDives OK for multi-part explorations +- See `/docs-components` Callout Spacing Rules + +--- + +## Content Principles + +### Intro Section +- **One sentence, ~15 words max** - State what the Hook does, not how it works +- ✅ "`useEffectEvent` is a React Hook that lets you separate events from Effects." +- ❌ "`useEffectEvent` is a React Hook that lets you extract non-reactive logic from your Effects into a reusable function called an Effect Event." + +### Reference Code Example +- Show just the API call (5-10 lines), not a full component +- Move full component examples to Usage section + +### Usage Section Structure +1. **First example: Core mental model** - Show the canonical use case with simplest concrete example +2. **Subsequent examples: Canonical use cases** - Name the *why* (e.g., "Avoid reconnecting to external systems"), show a concrete *how* + - Prefer broad canonical use cases over multiple narrow concrete examples + - The section title IS the teaching - "When would I use this?" should be answered by the heading + +### What to Include vs. Exclude +- **Never** document past bugs or fixed issues +- **Include** edge cases most developers will encounter +- **Exclude** niche edge cases (e.g., `this` binding, rare class patterns) + +### Caveats Section +- Include rules the linter enforces or that cause immediate errors +- Include fundamental usage restrictions +- Exclude implementation details unless they affect usage +- Exclude repetition of things explained elsewhere +- Keep each caveat to one sentence when possible + +### Troubleshooting Section +- Error headings only: "I'm getting an error: '[message]'" format +- Never document past bugs - if it's fixed, it doesn't belong here +- Focus on errors developers will actually encounter today + +### DeepDive Content +- **Goldilocks principle** - Deep enough for curious developers, short enough to not overwhelm +- Answer "why is it designed this way?" - not exhaustive technical details +- Readers who skip it should miss nothing essential for using the API +- If the explanation is getting long, you're probably explaining too much + +--- + +## Domain-Specific Guidance + +### Hooks + +**Returned function documentation:** +- Document setter/dispatch functions as separate `###` sections +- Use generic names: "set functions" not "setCount" +- Include stable identity caveat for returned functions + +**Dependency array documentation:** +- List what counts as reactive values +- Explain when dependencies are ignored +- Link to removing effect dependencies guide + +**Recipes usage:** +- Group related examples with meaningful titleText +- Each recipe has brief intro, Sandpack, and `` + +--- + +### Components + +**Props documentation:** +- Use `#### Props` instead of `#### Parameters` +- Mark optional props with `**optional**` prefix +- Use `` inline for canary-only props + +**JSX syntax in titles/headings:** +- Frontmatter title: `title: ` +- Reference heading: `` ### `` {/*suspense*/} `` + +--- + +### React-DOM + +**Common props linking:** +```md +`` supports all [common element props.](/reference/react-dom/components/common#common-props) +``` + +**Props categorization:** +- Controlled vs uncontrolled props grouped separately +- Form-specific props documented with action patterns +- MDN links for standard HTML attributes + +**Environment-specific notes:** +```mdx + + +This API is specific to Node.js. Environments with [Web Streams](MDN-link), like Deno and modern edge runtimes, should use [`renderToReadableStream`](/reference/react-dom/server/renderToReadableStream) instead. + + +``` + +**Progressive enhancement:** +- Document benefits for users without JavaScript +- Explain Server Function + form action integration +- Show hidden form field and `.bind()` patterns + +--- + +### RSC + +**RSC banner (before Intro):** +Always place `` component before `` for Server Component-only APIs. + +**Serialization type lists:** +When documenting Server Function arguments, list supported types: +```md +Supported types for Server Function arguments: + +* Primitives + * [string](MDN-link) + * [number](MDN-link) +* Iterables containing serializable values + * [Array](MDN-link) + * [Map](MDN-link) + +Notably, these are not supported: +* React elements, or [JSX](/learn/writing-markup-with-jsx) +* Functions (other than Server Functions) +``` + +**Bundle size comparisons:** +- Show "Not included in bundle" for server-only imports +- Annotate client bundle sizes with gzip: `// 35.9K (11.2K gzipped)` + +--- + +### Compiler + +**Configuration page structure:** +- Type (union type or interface) +- Default value +- Options/Valid values with descriptions + +**Directive documentation:** +- Placement requirements are critical +- Mode interaction tables showing combinations +- "Use sparingly" + "Plan for removal" patterns for escape hatches + +**Library author guides:** +- Audience-first intro +- Benefits/Why section +- Numbered step-by-step setup + +--- + +### ESLint + +**Rule Details section:** +- Explain "why" not just "what" +- Focus on React's underlying assumptions +- Describe consequences of violations + +**Invalid/Valid sections:** +- Standard intro: "Examples of [in]correct code for this rule:" +- Use X emoji for invalid, checkmark for valid +- Show inline comments explaining the violation + +**Configuration options:** +- Show shared settings (preferred) +- Show rule-level options (backward compatibility) +- Note precedence when both exist + +--- + +## Edge Cases + +For deprecated, canary, and version-specific component patterns (placement, syntax, examples), invoke `/docs-components`. + +**Quick placement rules:** +- `` after `` for page-level, after heading for method-level +- `` wrapper inline in Intro, `` in headings/props/caveats +- Version notes use `` with "Starting in React 19..." pattern + +**Removed APIs on index pages:** +```md +## Removed APIs {/*removed-apis*/} + +These APIs were removed in React 19: + +* [`render`](https://18.react.dev/reference/react-dom/render): use [`createRoot`](/reference/react-dom/client/createRoot) instead. +``` + +Link to previous version docs (18.react.dev) for removed API documentation. + +--- + +## Critical Rules + +1. **Heading IDs required:** `## Title {/*title-id*/}` (lowercase, hyphens) +2. **Sandpack main file needs `export default`** +3. **Active file syntax:** ` ```js src/File.js active ` +4. **Error headings in Troubleshooting:** Use `### I'm getting an error: "[message]" {/*id*/}` +5. **Section dividers (`---`)** required between headings (see Section Dividers below) +6. **InlineToc required:** Always include `` after Intro +7. **Consistent parameter format:** Use `* \`paramName\`: description` with `**optional**` prefix for optional params +8. **Numbered lists for array returns:** When hooks return arrays, use numbered lists in Returns section +9. **Generic names for returned functions:** Use "set functions" not "setCount" +10. **Props vs Parameters:** Use `#### Props` for Components (Type B), `#### Parameters` for Hooks/APIs (Type A) +11. **RSC placement:** `` component goes before ``, not after +12. **Canary markers:** Use `` wrapper inline in Intro, `` in headings/props +13. **Deprecated placement:** `` goes after `` for page-level, after heading for method-level +14. **Code comment emojis:** Use X for wrong, checkmark for correct in code examples +15. **No consecutive Pitfalls/Notes:** Combine into one component with titled subsections, or separate with prose/code (see `/docs-components`) + +For component heading level conventions (DeepDive, Pitfall, Note, Recipe headings), see `/docs-components`. + +### Section Dividers + +Use `---` horizontal rules to visually separate major sections: + +- **After ``** - Before `## Reference` heading +- **Between API subsections** - Between different function/hook definitions (e.g., between `useState()` and `set functions`) +- **Before `## Usage`** - Separates API reference from examples +- **Before `## Troubleshooting`** - Separates content from troubleshooting +- **Between EVERY Usage subsections** - When switching to a new major use case + +Always have a blank line before and after `---`. + +### Section ID Conventions + +| Section | ID Format | +|---------|-----------| +| Main function | `{/*functionname*/}` | +| Returned function | `{/*setstate*/}`, `{/*dispatch*/}` | +| Sub-section of returned function | `{/*setstate-parameters*/}` | +| Troubleshooting item | `{/*problem-description-slug*/}` | +| Pitfall | `{/*pitfall-description*/}` | +| Deep dive | `{/*deep-dive-topic*/}` | diff --git a/.claude/skills/react-expert/SKILL.md b/.claude/skills/react-expert/SKILL.md new file mode 100644 index 00000000000..c252f6ce0ae --- /dev/null +++ b/.claude/skills/react-expert/SKILL.md @@ -0,0 +1,335 @@ +--- +name: react-expert +description: Use when researching React APIs or concepts for documentation. Use when you need authoritative usage examples, caveats, warnings, or errors for a React feature. +--- + +# React Expert Research Skill + +## Overview + +This skill produces exhaustive documentation research on any React API or concept by searching authoritative sources (tests, source code, PRs, issues) rather than relying on LLM training knowledge. + + +**Skepticism Mandate:** You must be skeptical of your own knowledge. Claude is often trained on outdated or incorrect React patterns. Treat source material as the sole authority. If findings contradict your prior understanding, explicitly flag this discrepancy. + +**Red Flags - STOP if you catch yourself thinking:** +- "I know this API does X" → Find source evidence first +- "Common pattern is Y" → Verify in test files +- Generating example code → Must have source file reference + + +## Invocation + +``` +/react-expert useTransition +/react-expert suspense boundaries +/react-expert startTransition +``` + +## Sources (Priority Order) + +1. **React Repo Tests** - Most authoritative for actual behavior +2. **React Source Code** - Warnings, errors, implementation details +3. **Git History** - Commit messages with context +4. **GitHub PRs & Comments** - Design rationale (via `gh` CLI) +5. **GitHub Issues** - Confusion/questions (react/react + reactjs/react.dev) +6. **React Working Group** - Design discussions for newer APIs +7. **Flow Types** - Source of truth for type signatures +8. **TypeScript Types** - Note discrepancies with Flow +9. **Current react.dev docs** - Baseline (not trusted as complete) + +**No web search** - No Stack Overflow, blog posts, or web searches. GitHub API via `gh` CLI is allowed. + +## Workflow + +### Step 1: Setup React Repo + +First, ensure the React repo is available locally: + +```bash +# Check if React repo exists, clone or update +if [ -d ".claude/react" ]; then + cd .claude/react && git pull origin main +else + git clone --depth=100 https://github.com/react/react.git .claude/react +fi +``` + +Get the current commit hash for the research document: +```bash +cd .claude/react && git rev-parse --short HEAD +``` + +### Step 2: Dispatch 6 Parallel Research Agents + +Spawn these agents IN PARALLEL using the Task tool. Each agent receives the skepticism preamble: + +> "You are researching React's ``. CRITICAL: Do NOT rely on your prior knowledge about this API. Your training may contain outdated or incorrect patterns. Only report what you find in the source files. If your findings contradict common understanding, explicitly highlight this discrepancy." + +| Agent | subagent_type | Focus | Instructions | +|-------|---------------|-------|--------------| +| test-explorer | Explore | Test files for usage patterns | Search `.claude/react/packages/*/src/__tests__/` for test files mentioning the topic. Extract actual usage examples WITH file paths and line numbers. | +| source-explorer | Explore | Warnings/errors in source | Search `.claude/react/packages/*/src/` for console.error, console.warn, and error messages mentioning the topic. Document trigger conditions. | +| git-historian | Explore | Commit messages | Run `git log --all --grep="" --oneline -50` in `.claude/react`. Read full commit messages for context. | +| pr-researcher | Explore | PRs introducing/modifying API | Run `gh pr list -R react/react --search "" --state all --limit 20`. Read key PR descriptions and comments. | +| issue-hunter | Explore | Issues showing confusion | Search issues in both `react/react` and `reactjs/react.dev` repos. Look for common questions and misunderstandings. | +| types-inspector | Explore | Flow + TypeScript signatures | Find Flow types in `.claude/react/packages/*/src/*.js` (look for `@flow` annotations). Find TS types in `.claude/react/packages/*/index.d.ts`. Note discrepancies. | + +### Step 3: Agent Prompts + +Use these exact prompts when spawning agents: + +#### test-explorer +``` +You are researching React's . + +CRITICAL: Do NOT rely on your prior knowledge about this API. Your training may contain outdated or incorrect patterns. Only report what you find in the source files. + +Your task: Find test files in .claude/react that demonstrate usage. + +1. Search for test files: Glob for `**/__tests__/**/**` and `**/__tests__/**/*.js` then grep for +2. For each relevant test file, extract: + - The test description (describe/it blocks) + - The actual usage code + - Any assertions about behavior + - Edge cases being tested +3. Report findings with exact file paths and line numbers + +Format your output as: +## Test File: +### Test: "" +```javascript + +``` +**Behavior:** +``` + +#### source-explorer +``` +You are researching React's . + +CRITICAL: Do NOT rely on your prior knowledge about this API. Only report what you find in the source files. + +Your task: Find warnings, errors, and implementation details for . + +1. Search .claude/react/packages/*/src/ for: + - console.error mentions of + - console.warn mentions of + - Error messages mentioning + - The main implementation file +2. For each warning/error, document: + - The exact message text + - The condition that triggers it + - The source file and line number + +Format your output as: +## Warnings & Errors +| Message | Trigger Condition | Source | +|---------|------------------|--------| +| "" | | | + +## Implementation Notes + +``` + +#### git-historian +``` +You are researching React's . + +CRITICAL: Do NOT rely on your prior knowledge. Only report what you find in git history. + +Your task: Find commit messages that explain design decisions. + +1. Run: cd .claude/react && git log --all --grep="" --oneline -50 +2. For significant commits, read full message: git show --stat +3. Look for: + - Initial introduction of the API + - Bug fixes (reveal edge cases) + - Behavior changes + - Deprecation notices + +Format your output as: +## Key Commits +### - +**Date:** +**Context:** +**Impact:** +``` + +#### pr-researcher +``` +You are researching React's . + +CRITICAL: Do NOT rely on your prior knowledge. Only report what you find in PRs. + +Your task: Find PRs that introduced or modified . + +1. Run: gh pr list -R react/react --search "" --state all --limit 20 --json number,title,url +2. For promising PRs, read details: gh pr view -R react/react +3. Look for: + - The original RFC/motivation + - Design discussions in comments + - Alternative approaches considered + - Breaking changes + +Format your output as: +## Key PRs +### PR #: +**URL:** <url> +**Summary:** <what it introduced/changed> +**Design Rationale:** <why this approach> +**Discussion Highlights:** <key points from comments> +``` + +#### issue-hunter +``` +You are researching React's <TOPIC>. + +CRITICAL: Do NOT rely on your prior knowledge. Only report what you find in issues. + +Your task: Find issues that reveal common confusion about <TOPIC>. + +1. Search react/react: gh issue list -R react/react --search "<topic>" --state all --limit 20 --json number,title,url +2. Search reactjs/react.dev: gh issue list -R reactjs/react.dev --search "<topic>" --state all --limit 20 --json number,title,url +3. For each issue, identify: + - What the user was confused about + - What the resolution was + - Any gotchas revealed + +Format your output as: +## Common Confusion +### Issue #<number>: <title> +**Repo:** <react/react or reactjs/react.dev> +**Confusion:** <what they misunderstood> +**Resolution:** <correct understanding> +**Gotcha:** <if applicable> +``` + +#### types-inspector +``` +You are researching React's <TOPIC>. + +CRITICAL: Do NOT rely on your prior knowledge. Only report what you find in type definitions. + +Your task: Find and compare Flow and TypeScript type signatures for <TOPIC>. + +1. Flow types (source of truth): Search .claude/react/packages/*/src/*.js for @flow annotations related to <topic> +2. TypeScript types: Search .claude/react/packages/*/index.d.ts and @types/react +3. Compare and note any discrepancies + +Format your output as: +## Flow Types (Source of Truth) +**File:** <path> +```flow +<exact type definition> +``` + +## TypeScript Types +**File:** <path> +```typescript +<exact type definition> +``` + +## Discrepancies +<any differences between Flow and TS definitions> +``` + +### Step 4: Synthesize Results + +After all agents complete, combine their findings into a single research document. + +**DO NOT add information from your own knowledge.** Only include what agents found in sources. + +### Step 5: Save Output + +Write the final document to `.claude/research/<topic>.md` + +Replace spaces in topic with hyphens (e.g., "suspense boundaries" → "suspense-boundaries.md") + +## Output Document Template + +```markdown +# React Research: <topic> + +> Generated by /react-expert on YYYY-MM-DD +> Sources: React repo (commit <hash>), N PRs, M issues + +## Summary + +[Brief summary based SOLELY on source findings, not prior knowledge] + +## API Signature + +### Flow Types (Source of Truth) + +[From types-inspector agent] + +### TypeScript Types + +[From types-inspector agent] + +### Discrepancies + +[Any differences between Flow and TS] + +## Usage Examples + +### From Tests + +[From test-explorer agent - with file:line references] + +### From PRs/Issues + +[Real-world patterns from discussions] + +## Caveats & Gotchas + +[Each with source link] + +- **<gotcha>** - Source: <link> + +## Warnings & Errors + +| Message | Trigger Condition | Source File | +|---------|------------------|-------------| +[From source-explorer agent] + +## Common Confusion + +[From issue-hunter agent] + +## Design Decisions + +[From git-historian and pr-researcher agents] + +## Source Links + +### Commits +- <hash>: <description> + +### Pull Requests +- PR #<number>: <title> - <url> + +### Issues +- Issue #<number>: <title> - <url> +``` + +## Common Mistakes to Avoid + +1. **Trusting prior knowledge** - If you "know" something about the API, find the source evidence anyway +2. **Generating example code** - Every code example must come from an actual source file +3. **Skipping agents** - All 6 agents must run; each provides unique perspective +4. **Summarizing without sources** - Every claim needs a file:line or PR/issue reference +5. **Using web search** - No Stack Overflow, no blog posts, no social media + +## Verification Checklist + +Before finalizing the research document: + +- [ ] React repo is at `.claude/react` with known commit hash +- [ ] All 6 agents were spawned in parallel +- [ ] Every code example has a source file reference +- [ ] Warnings/errors table has source locations +- [ ] No claims made without source evidence +- [ ] Discrepancies between Flow/TS types documented +- [ ] Source links section is complete diff --git a/.claude/skills/review-docs/SKILL.md b/.claude/skills/review-docs/SKILL.md new file mode 100644 index 00000000000..61a6a0e05c6 --- /dev/null +++ b/.claude/skills/review-docs/SKILL.md @@ -0,0 +1,20 @@ +--- +name: review-docs +description: Use when reviewing React documentation for structure, components, and style compliance +--- +CRITICAL: do not load these skills yourself. + +Run these tasks in parallel for the given file(s). Each agent checks different aspects—not all apply to every file: + +- [ ] Ask docs-reviewer agent to review {files} with docs-writer-learn (only for files in src/content/learn/). +- [ ] Ask docs-reviewer agent to review {files} with docs-writer-reference (only for files in src/content/reference/). +- [ ] Ask docs-reviewer agent to review {files} with docs-writer-blog (only for files in src/content/blog/). +- [ ] Ask docs-reviewer agent to review {files} with docs-voice (all documentation files). +- [ ] Ask docs-reviewer agent to review {files} with docs-components (all documentation files). +- [ ] Ask docs-reviewer agent to review {files} with docs-sandpack (files containing Sandpack examples). + +If no file is specified, check git status for modified MDX files in `src/content/`. + +The docs-reviewer will return a checklist of the issues it found. Respond with the full checklist and line numbers from all agents, and prompt the user to create a plan to fix these issues. + + diff --git a/.claude/skills/write/SKILL.md b/.claude/skills/write/SKILL.md new file mode 100644 index 00000000000..3099b3a0c08 --- /dev/null +++ b/.claude/skills/write/SKILL.md @@ -0,0 +1,176 @@ +--- +name: write +description: Use when creating new React documentation pages or updating existing ones. Accepts instructions like "add optimisticKey reference docs", "update ViewTransition with Activity", or "transition learn docs". +--- + +# Documentation Writer + +Orchestrates research, writing, and review for React documentation. + +## Invocation + +``` +/write add optimisticKey → creates new reference docs +/write update ViewTransition Activity → updates ViewTransition docs to cover Activity +/write transition learn docs → creates new learn docs for transitions +/write blog post for React 20 → creates a new blog post +``` + +## Workflow + +```dot +digraph write_flow { + rankdir=TB; + "Parse intent" [shape=box]; + "Research (parallel)" [shape=box]; + "Synthesize plan" [shape=box]; + "Write docs" [shape=box]; + "Review docs" [shape=box]; + "Issues found?" [shape=diamond]; + "Done" [shape=doublecircle]; + + "Parse intent" -> "Research (parallel)"; + "Research (parallel)" -> "Synthesize plan"; + "Synthesize plan" -> "Write docs"; + "Write docs" -> "Review docs"; + "Review docs" -> "Issues found?"; + "Issues found?" -> "Write docs" [label="yes - fix"]; + "Issues found?" -> "Done" [label="no"]; +} +``` + +### Step 1: Parse Intent + +Determine from the user's instruction: + +| Field | How to determine | +|-------|------------------| +| **Action** | "add"/"create"/"new" = new page; "update"/"edit"/"with" = modify existing | +| **Topic** | The React API or concept (e.g., `optimisticKey`, `ViewTransition`, `transitions`) | +| **Doc type** | "reference" (default for APIs/hooks/components), "learn" (for concepts/guides), "blog" (for announcements) | +| **Target file** | For updates: find existing file in `src/content/`. For new: determine path from doc type | + +If the intent is ambiguous, ask the user to clarify before proceeding. + +### Step 2: Research (Parallel Agents) + +Spawn these agents **in parallel**: + +#### Agent 1: React Expert Research + +Use a Task agent (subagent_type: `general-purpose`) to invoke `/react-expert <topic>`. This researches the React source code, tests, PRs, issues, and type signatures. + +**Prompt:** +``` +Invoke the /react-expert skill for <TOPIC>. Follow the skill's full workflow: +setup the React repo, dispatch all 6 research agents in parallel, synthesize +results, and save to .claude/research/<topic>.md. Return the full research document. +``` + +#### Agent 2: Existing Docs Audit + +Use a Task agent (subagent_type: `Explore`) to find and read existing documentation for the topic. + +**Prompt:** +``` +Find all existing documentation related to <TOPIC> in this repo: +1. Search src/content/ for files mentioning <TOPIC> +2. Read any matching files fully +3. For updates: identify what sections exist and what's missing +4. For new pages: identify related pages to understand linking/cross-references +5. Check src/sidebarLearn.json and src/sidebarReference.json for navigation placement + +Return: list of existing files with summaries, navigation structure, and gaps. +``` + +#### Agent 3: Use Case Research + +Use a Task agent (subagent_type: `general-purpose`) with web search to find common use cases and patterns. + +**Prompt:** +``` +Search the web for common use cases and patterns for React's <TOPIC>. +Focus on: +1. Real-world usage patterns developers actually need +2. Common mistakes or confusion points +3. Migration patterns (if replacing an older API) +4. Framework integration patterns (Next.js, Remix, etc.) + +Return a summary of the top 5-8 use cases with brief code sketches. +Do NOT search Stack Overflow. Focus on official docs, GitHub discussions, +and high-quality technical blogs. +``` + +### Step 3: Synthesize Writing Plan + +After all research agents complete, create a writing plan that includes: + +1. **Page type** (from docs-writer-reference decision tree or learn/blog type) +2. **File path** for the new or updated file +3. **Outline** with section headings matching the appropriate template +4. **Content notes** for each section, drawn from research: + - API signature and parameters (from react-expert types) + - Usage examples (from react-expert tests + use case research) + - Caveats and pitfalls (from react-expert warnings/errors/issues) + - Cross-references to related pages (from docs audit) +5. **Navigation changes** needed (sidebar JSON updates) + +Present this plan to the user and confirm before proceeding. + +### Step 4: Write Documentation + +Dispatch a Task agent (subagent_type: `general-purpose`) to write the documentation. + +**The agent prompt MUST include:** + +1. The full writing plan from Step 3 +2. An instruction to invoke the appropriate skill: + - `/docs-writer-reference` for reference pages + - `/docs-writer-learn` for learn pages + - `/docs-writer-blog` for blog posts +3. An instruction to invoke `/docs-components` for MDX component patterns +4. An instruction to invoke `/docs-sandpack` if adding interactive code examples +5. The research document content (key findings, not the full dump) + +**Prompt template:** +``` +You are writing React documentation. Follow these steps: + +1. Invoke /docs-writer-<TYPE> to load the page template and conventions +2. Invoke /docs-components to load MDX component patterns +3. Invoke /docs-sandpack if you need interactive code examples +4. Write the documentation following the plan below + +PLAN: +<writing plan from Step 3> + +RESEARCH FINDINGS: +<key findings from Step 2 agents> + +Write the file to: <target file path> +Also update <sidebar JSON> if adding a new page. +``` + +### Step 5: Review Documentation + +Invoke `/review-docs` on the written files. This dispatches parallel review agents checking: +- Structure compliance (docs-writer-*) +- Voice and style (docs-voice) +- Component usage (docs-components) +- Sandpack patterns (docs-sandpack) + +### Step 6: Fix Issues + +If the review finds issues: +1. Present the review checklist to the user +2. Fix the issues identified +3. Re-run `/review-docs` on the fixed files +4. Repeat until clean + +## Important Rules + +- **Always research before writing.** Never write docs from LLM knowledge alone. +- **Always confirm the plan** with the user before writing. +- **Always review** with `/review-docs` after writing. +- **Match existing patterns.** Read neighboring docs to match style and depth. +- **Update navigation.** New pages need sidebar entries. diff --git a/.claude/skills/write/diagrams/write_flow.svg b/.claude/skills/write/diagrams/write_flow.svg new file mode 100644 index 00000000000..49056ef11ab --- /dev/null +++ b/.claude/skills/write/diagrams/write_flow.svg @@ -0,0 +1,100 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" + "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd"> +<!-- Generated by graphviz version 14.1.2 (20260124.0452) + --> +<!-- Title: write_flow Pages: 1 --> +<svg width="182pt" height="531pt" + viewBox="0.00 0.00 182.00 531.00" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink"> +<g id="graph0" class="graph" transform="scale(1 1) rotate(0) translate(4 527.26)"> +<title>write_flow + + + +Parse intent + +Parse intent + + + +Research (parallel) + +Research (parallel) + + + +Parse intent->Research (parallel) + + + + + +Synthesize plan + +Synthesize plan + + + +Research (parallel)->Synthesize plan + + + + + +Write docs + +Write docs + + + +Synthesize plan->Write docs + + + + + +Review docs + +Review docs + + + +Write docs->Review docs + + + + + +Issues found? + +Issues found? + + + +Review docs->Issues found? + + + + + +Issues found?->Write docs + + +yes - fix + + + +Done + + +Done + + + +Issues found?->Done + + +no + + + diff --git a/.env.development b/.env.development new file mode 100644 index 00000000000..e69de29bb2d diff --git a/.env.production b/.env.production new file mode 100644 index 00000000000..e403f96b683 --- /dev/null +++ b/.env.production @@ -0,0 +1 @@ +NEXT_PUBLIC_GA_TRACKING_ID = 'G-B1E83PJ3RT' \ No newline at end of file diff --git a/.eslintignore b/.eslintignore index 9425417154d..ae0737173e3 100644 --- a/.eslintignore +++ b/.eslintignore @@ -1,10 +1,5 @@ -node_modules/* - -# Ignore markdown files and examples -content/* - -# Ignore built files -public/* - -# Ignore examples -examples/* \ No newline at end of file +scripts +plugins +next.config.js +.claude/ +worker-bundle.dist.js \ No newline at end of file diff --git a/.eslintrc b/.eslintrc index a51454ef284..935fa2f2343 100644 --- a/.eslintrc +++ b/.eslintrc @@ -1,18 +1,38 @@ { - "extends": [ - "fbjs" - ], - "plugins": [ - "prettier", - "react" - ], - "parser": "babel-eslint", + "root": true, + "extends": "next/core-web-vitals", + "parser": "@typescript-eslint/parser", + "plugins": ["@typescript-eslint", "eslint-plugin-react-compiler", "local-rules"], "rules": { - "relay/graphql-naming": 0, - "max-len": 0 + "no-unused-vars": "off", + "@typescript-eslint/no-unused-vars": ["error", {"varsIgnorePattern": "^_"}], + "react-hooks/exhaustive-deps": "error", + "react/no-unknown-property": ["error", {"ignore": ["meta"]}], + "react-compiler/react-compiler": "error", + "local-rules/lint-markdown-code-blocks": "error", + "no-trailing-spaces": "error" }, "env": { "node": true, - "browser": true - } + "commonjs": true, + "browser": true, + "es6": true + }, + "overrides": [ + { + "files": ["src/content/**/*.md"], + "parser": "./eslint-local-rules/parser", + "parserOptions": { + "sourceType": "module" + }, + "rules": { + "no-unused-vars": "off", + "@typescript-eslint/no-unused-vars": "off", + "react-hooks/exhaustive-deps": "off", + "react/no-unknown-property": "off", + "react-compiler/react-compiler": "off", + "local-rules/lint-markdown-code-blocks": "error" + } + } + ] } diff --git a/.flowconfig b/.flowconfig deleted file mode 100644 index 836f6ec1eb0..00000000000 --- a/.flowconfig +++ /dev/null @@ -1,35 +0,0 @@ -[ignore] - -/content/.* -/node_modules/.* -/public/.* - -[include] - -[libs] -./node_modules/fbjs/flow/lib/dev.js -./flow - -[options] -module.system=haste -module.system.node.resolve_dirname=node_modules -module.system.node.resolve_dirname=src - -esproposal.class_static_fields=enable -esproposal.class_instance_fields=enable -unsafe.enable_getters_and_setters=true - -munge_underscores=false - -suppress_type=$FlowIssue -suppress_type=$FlowFixMe -suppress_type=$FixMe -suppress_type=$FlowExpectedError - -suppress_comment=\\(.\\|\n\\)*\\$FlowFixMe\\($\\|[^(]\\|(\\(>=0\\.\\(3[0-3]\\|[1-2][0-9]\\|[0-9]\\).[0-9]\\)? *\\(site=[a-z,_]*www[a-z,_]*\\)?)\\) -suppress_comment=\\(.\\|\n\\)*\\$FlowIssue\\((\\(>=0\\.\\(3[0-3]\\|[1-2][0-9]\\|[0-9]\\).[0-9]\\)? *\\(site=[a-z,_]*www[a-z,_]*\\)?)\\)?:? #[0-9]+ -suppress_comment=\\(.\\|\n\\)*\\$FlowFixedInNextDeploy -suppress_comment=\\(.\\|\n\\)*\\$FlowExpectedError - -[version] -^0.56.0 diff --git a/.github/ISSUE_TEMPLATE/0-bug.yml b/.github/ISSUE_TEMPLATE/0-bug.yml new file mode 100644 index 00000000000..56d2e8540f6 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/0-bug.yml @@ -0,0 +1,34 @@ +name: "🐛 Report a bug" +description: "Report a problem on the website." +title: "[Bug]: " +labels: ["bug: unconfirmed"] +body: + - type: textarea + attributes: + label: Summary + description: | + A clear and concise summary of what the bug is. + placeholder: | + Example bug report: + When I click the "Submit" button on "Feedback", nothing happens. + validations: + required: true + - type: input + attributes: + label: Page + description: | + What page(s) did you encounter this bug on? + placeholder: | + https://react.dev/ + validations: + required: true + - type: textarea + attributes: + label: Details + description: | + Please provide any additional details about the bug. + placeholder: | + Example details: + The "Submit" button is unresponsive. I've tried refreshing the page and using a different browser, but the issue persists. + validations: + required: false diff --git a/.github/ISSUE_TEMPLATE/1-typo.yml b/.github/ISSUE_TEMPLATE/1-typo.yml new file mode 100644 index 00000000000..c86557a1160 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/1-typo.yml @@ -0,0 +1,34 @@ +name: "🤦 Typo or mistake" +description: "Report a typo or mistake in the docs." +title: "[Typo]: " +labels: ["type: typos"] +body: + - type: textarea + attributes: + label: Summary + description: | + A clear and concise summary of what the mistake is. + placeholder: | + Example: + The code example on the "useReducer" page includes an unused variable `nextId`. + validations: + required: true + - type: input + attributes: + label: Page + description: | + What page is the typo on? + placeholder: | + https://react.dev/ + validations: + required: true + - type: textarea + attributes: + label: Details + description: | + Please provide a explanation for why this is a mistake. + placeholder: | + Example mistake: + In the "useReducer" section of the "API Reference" page, the code example under "Writing a reducer function" includes an unused variable `nextId` that should be removed. + validations: + required: false diff --git a/.github/ISSUE_TEMPLATE/2-suggestion.yml b/.github/ISSUE_TEMPLATE/2-suggestion.yml new file mode 100644 index 00000000000..ac0b480fe9f --- /dev/null +++ b/.github/ISSUE_TEMPLATE/2-suggestion.yml @@ -0,0 +1,34 @@ +name: "💡 Suggestions" +description: "Suggest a new page, section, or edit for an existing page." +title: "[Suggestion]: " +labels: ["type: documentation"] +body: + - type: textarea + attributes: + label: Summary + description: | + A clear and concise summary of what we should add. + placeholder: | + Example: + Add a new page for how to use React with TypeScript. + validations: + required: true + - type: input + attributes: + label: Page + description: | + What page is this about? + placeholder: | + https://react.dev/ + validations: + required: false + - type: textarea + attributes: + label: Details + description: | + Please provide a explanation for what you're suggesting. + placeholder: | + Example: + I think it would be helpful to have a page that explains how to use React with TypeScript. This could include a basic example of a component written in TypeScript, and a link to the TypeScript documentation. + validations: + required: true diff --git a/.github/ISSUE_TEMPLATE/3-framework.yml b/.github/ISSUE_TEMPLATE/3-framework.yml new file mode 100644 index 00000000000..87f03a660b5 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/3-framework.yml @@ -0,0 +1,116 @@ +name: "📄 Suggest new framework" +description: "I am a framework author applying to be included as a recommended framework." +title: "[Framework]: " +labels: ["type: framework"] +body: + - type: markdown + attributes: + value: | + ## Apply to be included as a recommended React framework + + _This form is for framework authors to apply to be included as a recommended [React framework](https://react.dev/learn/creating-a-react-app). If you are not a framework author, please contact the authors before submitting._ + + Our goal when recommending a framework is to start developers with a React project that solves common problems like code splitting, data fetching, routing, and HTML generation without any extra work later. We believe this will allow users to get started quickly with React, and scale their app to production. + + While we understand that many frameworks may want to be featured, this page is not a place to advertise every possible React framework or all frameworks that you can add React to. There are many great frameworks that offer support for React that are not listed in our guides. The frameworks we recommend have invested significantly in the React ecosystem, and collaborated with the React team to be compatible with our [full-stack React architecture vision](https://react.dev/learn/creating-a-react-app#which-features-make-up-the-react-teams-full-stack-architecture-vision). + + To be included, frameworks must meet the following criteria: + + - **Free & open-source**: must be open source and free to use. + - **Well maintained**. must be actively maintained, providing bug fixes and improvements. + - **Active community**: must have a sufficiently large and active community to support users. + - **Clear onboarding**: must have clear install steps to install the React version of the framework. + - **Ecosystem compatibility**: must support using the full range of libraries and tools in the React ecosystem. + - **Self-hosting option**: must support an option to self-host applications without losing access to features. + - **Developer experience**. must allow developers to be productive by supporting features like Fast Refresh. + - **User experience**. must provide built-in support for common problems like routing and data-fetching. + - **Compatible with our future vision for React**. React evolves over time, and frameworks that do not align with React’s direction risk isolating their users from the main React ecosystem over time. To be included on this page we must feel confident that the framework is setting its users up for success with React over time. + + Please note, we have reviewed most of the popular frameworks available today, so it is unlikely we have not considered your framework already. But if you think we missed something, please complete the application below. + - type: input + attributes: + label: Name + description: | + What is the name of your framework? + validations: + required: true + - type: input + attributes: + label: Homepage + description: | + What is the URL of your homepage? + validations: + required: true + - type: input + attributes: + label: Install instructions + description: | + What is the URL of your getting started guide? + validations: + required: true + - type: dropdown + attributes: + label: Is your framework open source? + description: | + We only recommend free and open source frameworks. + options: + - 'No' + - 'Yes' + validations: + required: true + - type: textarea + attributes: + label: Well maintained + description: | + Please describe how your framework is actively maintained. Include recent releases, bug fixes, and improvements as examples. + validations: + required: true + - type: textarea + attributes: + label: Active community + description: | + Please describe your community. Include the size of your community, and links to community resources. + validations: + required: true + - type: textarea + attributes: + label: Clear onboarding + description: | + Please describe how a user can install your framework with React. Include links to any relevant documentation. + validations: + required: true + - type: textarea + attributes: + label: Ecosystem compatibility + description: | + Please describe any limitations your framework has with the React ecosystem. Include any libraries or tools that are not compatible with your framework. + validations: + required: true + - type: textarea + attributes: + label: Self-hosting option + description: | + Please describe how your framework supports self-hosting. Include any limitations to features when self-hosting. Also include whether you require a server to deploy your framework. + validations: + required: true + - type: textarea + attributes: + label: Developer Experience + description: | + Please describe how your framework provides a great developer experience. Include any limitations to React features like React DevTools, Chrome DevTools, and Fast Refresh. + validations: + required: true + - type: textarea + attributes: + label: User Experience + description: | + Please describe how your framework helps developers create high quality user experiences by solving common use-cases. Include specifics for how your framework offers built-in support for code-splitting, routing, HTML generation, and data-fetching in a way that avoids client/server waterfalls by default. Include details on how you offer features such as SSG and SSR. + validations: + required: true + - type: textarea + attributes: + label: Compatible with our future vision for React + description: | + Please describe how your framework aligns with our future vision for React. Include how your framework will evolve with React over time, and your plans to support future React features like React Server Components. + validations: + required: true diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 00000000000..de2bfc3625e --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,7 @@ +contact_links: + - name: 📃 Bugs in React + url: https://github.com/react/react/issues/new/choose + about: This issue tracker is not for bugs in React. Please file React issues here. + - name: 🤔 Questions and Help + url: https://reactjs.org/community/support.html + about: This issue tracker is not for support questions. Please refer to the React community's help and discussion forums. diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 00000000000..7e4f6d2f2cb --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,11 @@ + diff --git a/.github/dependabot.yml b/.github/dependabot.yml new file mode 100644 index 00000000000..97f2a39ea0d --- /dev/null +++ b/.github/dependabot.yml @@ -0,0 +1,8 @@ +version: 2 +updates: + - package-ecosystem: "npm" + directory: "/" + schedule: + interval: "weekly" + # Disable Dependabot. Doing it here so it propagates to translation forks. + open-pull-requests-limit: 0 diff --git a/.github/workflows/analyze.yml b/.github/workflows/analyze.yml new file mode 100644 index 00000000000..83e7f2e8a9c --- /dev/null +++ b/.github/workflows/analyze.yml @@ -0,0 +1,101 @@ +name: Analyze Bundle + +on: + pull_request: + push: + branches: + - main # change this if your default branch is named differently + workflow_dispatch: + +permissions: {} + +jobs: + analyze: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + + - name: Set up node + uses: actions/setup-node@v4 + with: + node-version: '20.x' + cache: yarn + cache-dependency-path: yarn.lock + + - name: Restore cached node_modules + uses: actions/cache@v4 + with: + path: '**/node_modules' + key: node_modules-${{ runner.arch }}-${{ runner.os }}-${{ hashFiles('yarn.lock') }} + + - name: Install deps + run: yarn install --frozen-lockfile + + - name: Restore next build + uses: actions/cache@v4 + id: restore-build-cache + env: + cache-name: cache-next-build + with: + path: .next/cache + # change this if you prefer a more strict cache + key: ${{ runner.os }}-build-${{ env.cache-name }} + + - name: Build next.js app + # change this if your site requires a custom build command + run: ./node_modules/.bin/next build + + # Here's the first place where next-bundle-analysis' own script is used + # This step pulls the raw bundle stats for the current bundle + - name: Analyze bundle + run: npx -p nextjs-bundle-analysis@0.5.0 report + + - name: Upload bundle + uses: actions/upload-artifact@v4 + with: + path: .next/analyze/__bundle_analysis.json + name: bundle_analysis.json + + - name: Download base branch bundle stats + uses: dawidd6/action-download-artifact@268677152d06ba59fcec7a7f0b5d961b6ccd7e1e + if: success() && github.event.number + with: + workflow: analyze.yml + branch: ${{ github.event.pull_request.base.ref }} + name: bundle_analysis.json + path: .next/analyze/base/bundle + + # And here's the second place - this runs after we have both the current and + # base branch bundle stats, and will compare them to determine what changed. + # There are two configurable arguments that come from package.json: + # + # - budget: optional, set a budget (bytes) against which size changes are measured + # it's set to 350kb here by default, as informed by the following piece: + # https://infrequently.org/2021/03/the-performance-inequality-gap/ + # + # - red-status-percentage: sets the percent size increase where you get a red + # status indicator, defaults to 20% + # + # Either of these arguments can be changed or removed by editing the `nextBundleAnalysis` + # entry in your package.json file. + - name: Compare with base branch bundle + if: success() && github.event.number + run: ls -laR .next/analyze/base && npx -p nextjs-bundle-analysis compare + + - name: Upload analysis comment + uses: actions/upload-artifact@v4 + with: + name: analysis_comment.txt + path: .next/analyze/__bundle_analysis_comment.txt + + - name: Save PR number + run: echo ${{ github.event.number }} > ./pr_number + + - name: Upload PR number + uses: actions/upload-artifact@v4 + with: + name: pr_number + path: ./pr_number + + # The actual commenting happens in the other action, matching the guidance in + # https://securitylab.github.com/research/github-actions-preventing-pwn-requests/ diff --git a/.github/workflows/analyze_comment.yml b/.github/workflows/analyze_comment.yml new file mode 100644 index 00000000000..fcac3773869 --- /dev/null +++ b/.github/workflows/analyze_comment.yml @@ -0,0 +1,60 @@ +name: Analyze Bundle (Comment) + +on: + workflow_run: + workflows: ['Analyze Bundle'] + types: + - completed + +permissions: + contents: read + issues: write + pull-requests: write + +jobs: + comment: + runs-on: ubuntu-latest + if: > + ${{ github.event.workflow_run.event == 'pull_request' && + github.event.workflow_run.conclusion == 'success' }} + steps: + - name: Download base branch bundle stats + uses: dawidd6/action-download-artifact@268677152d06ba59fcec7a7f0b5d961b6ccd7e1e + with: + workflow: analyze.yml + run_id: ${{ github.event.workflow_run.id }} + name: analysis_comment.txt + path: analysis_comment.txt + + - name: Download PR number + uses: dawidd6/action-download-artifact@268677152d06ba59fcec7a7f0b5d961b6ccd7e1e + with: + workflow: analyze.yml + run_id: ${{ github.event.workflow_run.id }} + name: pr_number + path: pr_number + + - name: Get comment body + id: get-comment-body + if: success() + run: | + echo 'body<> $GITHUB_OUTPUT + echo '' >> $GITHUB_OUTPUT + echo '## Size changes' >> $GITHUB_OUTPUT + echo '' >> $GITHUB_OUTPUT + echo '
    ' >> $GITHUB_OUTPUT + echo '' >> $GITHUB_OUTPUT + cat analysis_comment.txt/__bundle_analysis_comment.txt >> $GITHUB_OUTPUT + echo '' >> $GITHUB_OUTPUT + echo '
    ' >> $GITHUB_OUTPUT + echo '' >> $GITHUB_OUTPUT + echo 'EOF' >> $GITHUB_OUTPUT + pr_number=$(cat pr_number/pr_number) + echo "pr-number=$pr_number" >> $GITHUB_OUTPUT + + - name: Comment + uses: marocchino/sticky-pull-request-comment@52423e01640425a022ef5fd42c6fb5f633a02728 + with: + header: next-bundle-analysis + number: ${{ steps.get-comment-body.outputs.pr-number }} + message: ${{ steps.get-comment-body.outputs.body }} diff --git a/.github/workflows/discord_notify.yml b/.github/workflows/discord_notify.yml new file mode 100644 index 00000000000..97f8d183b15 --- /dev/null +++ b/.github/workflows/discord_notify.yml @@ -0,0 +1,32 @@ +name: Discord Notify + +on: + pull_request_target: + types: [opened, ready_for_review] + +permissions: {} + +jobs: + check_maintainer: + uses: react/react/.github/workflows/shared_check_maintainer.yml@main + permissions: + # Used by check_maintainer + contents: read + with: + actor: ${{ github.event.pull_request.user.login }} + + notify: + if: ${{ needs.check_maintainer.outputs.is_core_team == 'true' }} + needs: check_maintainer + runs-on: ubuntu-latest + steps: + - name: Discord Webhook Action + uses: tsickert/discord-webhook@v6.0.0 + with: + webhook-url: ${{ secrets.DISCORD_WEBHOOK_URL }} + embed-author-name: ${{ github.event.pull_request.user.login }} + embed-author-url: ${{ github.event.pull_request.user.html_url }} + embed-author-icon-url: ${{ github.event.pull_request.user.avatar_url }} + embed-title: '#${{ github.event.number }} (+${{github.event.pull_request.additions}} -${{github.event.pull_request.deletions}}): ${{ github.event.pull_request.title }}' + embed-description: ${{ github.event.pull_request.body }} + embed-url: ${{ github.event.pull_request.html_url }} diff --git a/.github/workflows/label_core_team_prs.yml b/.github/workflows/label_core_team_prs.yml new file mode 100644 index 00000000000..4cb6fbc7128 --- /dev/null +++ b/.github/workflows/label_core_team_prs.yml @@ -0,0 +1,41 @@ +name: Label Core Team PRs + +on: + pull_request_target: + +permissions: {} + +env: + TZ: /usr/share/zoneinfo/America/Los_Angeles + # https://github.com/actions/cache/blob/main/tips-and-workarounds.md#cache-segment-restore-timeout + SEGMENT_DOWNLOAD_TIMEOUT_MINS: 1 + +jobs: + check_maintainer: + uses: react/react/.github/workflows/shared_check_maintainer.yml@main + permissions: + # Used by check_maintainer + contents: read + with: + actor: ${{ github.event.pull_request.user.login }} + + label: + if: ${{ needs.check_maintainer.outputs.is_core_team == 'true' }} + runs-on: ubuntu-latest + needs: check_maintainer + permissions: + # Used to add labels on issues + issues: write + # Used to add labels on PRs + pull-requests: write + steps: + - name: Label PR as React Core Team + uses: actions/github-script@v7 + with: + script: | + github.rest.issues.addLabels({ + owner: context.repo.owner, + repo: context.repo.repo, + issue_number: ${{ github.event.number }}, + labels: ['React Core Team'] + }); diff --git a/.github/workflows/site_lint.yml b/.github/workflows/site_lint.yml new file mode 100644 index 00000000000..81a04601c21 --- /dev/null +++ b/.github/workflows/site_lint.yml @@ -0,0 +1,37 @@ +name: Site Lint / Heading ID check + +on: + push: + branches: + - main # change this if your default branch is named differently + pull_request: + types: [opened, synchronize, reopened] + +permissions: {} + +jobs: + lint: + runs-on: ubuntu-latest + + name: Lint on node 20.x and ubuntu-latest + + steps: + - uses: actions/checkout@v4 + - name: Use Node.js 20.x + uses: actions/setup-node@v4 + with: + node-version: 20.x + cache: yarn + cache-dependency-path: yarn.lock + + - name: Restore cached node_modules + uses: actions/cache@v4 + with: + path: '**/node_modules' + key: node_modules-${{ runner.arch }}-${{ runner.os }}-${{ hashFiles('yarn.lock') }} + + - name: Install deps + run: yarn install --frozen-lockfile + + - name: Lint codebase + run: yarn ci-check diff --git a/.gitignore b/.gitignore index dbe72d17694..ed9efe38d02 100644 --- a/.gitignore +++ b/.gitignore @@ -1,5 +1,51 @@ -.cache -.DS_STORE -.idea +# See https://help.github.com/articles/ignoring-files/ for more about ignoring files. + +# dependencies node_modules -public +/.pnp +.pnp.js + +# testing +/coverage + +# next.js +/.next/ +/out/ + +# production +/build + +# misc +.DS_Store +*.pem +tsconfig.tsbuildinfo + +# debug +npm-debug.log* +yarn-debug.log* +yarn-error.log* + +# local env files +.env.local +.env.development.local +.env.test.local +.env.production.local + +# vercel +.vercel + +# external fonts +public/fonts/**/Optimistic_*.woff2 + +# rss +public/rss.xml + +# claude local settings +.claude/*.local.* +.claude/react/ + +# worktrees +.worktrees/ + +# Generated OG images (scripts/generateOgImages.mjs) +public/images/og/ diff --git a/.husky/pre-commit b/.husky/pre-commit new file mode 100755 index 00000000000..dc0378c3488 --- /dev/null +++ b/.husky/pre-commit @@ -0,0 +1,4 @@ +#!/bin/sh +. "$(dirname "$0")/_/husky.sh" + +yarn lint-staged \ No newline at end of file diff --git a/.nvmrc b/.nvmrc deleted file mode 100644 index c9dc0490835..00000000000 --- a/.nvmrc +++ /dev/null @@ -1 +0,0 @@ -8.4 diff --git a/.prettierignore b/.prettierignore new file mode 100644 index 00000000000..96f1f96d2b3 --- /dev/null +++ b/.prettierignore @@ -0,0 +1 @@ +src/content/**/*.md diff --git a/.prettierrc b/.prettierrc index eb91e6abb75..19b54ad0599 100644 --- a/.prettierrc +++ b/.prettierrc @@ -1,8 +1,21 @@ { "bracketSpacing": false, - "jsxBracketSameLine": true, - "parser": "flow", - "printWidth": 80, "singleQuote": true, - "trailingComma": "all" -} \ No newline at end of file + "bracketSameLine": true, + "trailingComma": "es5", + "printWidth": 80, + "overrides": [ + { + "files": "*.css", + "options": { + "parser": "css" + } + }, + { + "files": "*.md", + "options": { + "parser": "mdx" + } + } + ] +} diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 00000000000..3a081e6d517 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,52 @@ +# CLAUDE.md + +This file provides guidance to Claude Code when working with this repository. + +## Project Overview + +This is the React documentation website (react.dev), built with Next.js 15.1.11 and React 19. Documentation is written in MDX format. + +## Development Commands + +```bash +yarn build # Production build +yarn lint # Run ESLint +yarn lint:fix # Auto-fix lint issues +yarn tsc # TypeScript type checking +yarn check-all # Run prettier, lint:fix, tsc, and rss together +``` + +## Project Structure + +``` +src/ +├── content/ # Documentation content (MDX files) +│ ├── learn/ # Tutorial/learning content +│ ├── reference/ # API reference docs +│ ├── blog/ # Blog posts +│ └── community/ # Community pages +├── components/ # React components +├── pages/ # Next.js pages +├── hooks/ # Custom React hooks +├── utils/ # Utility functions +└── styles/ # CSS/Tailwind styles +``` + +## Code Conventions + +### TypeScript/React +- Functional components only +- Tailwind CSS for styling + +### Documentation Style + +When editing files in `src/content/`, the appropriate skill will be auto-suggested: +- `src/content/learn/` - Learn page structure and tone +- `src/content/reference/` - Reference page structure and tone + +For MDX components (DeepDive, Pitfall, Note, etc.), invoke `/docs-components`. +For Sandpack code examples, invoke `/docs-sandpack`. + +See `.claude/docs/react-docs-patterns.md` for comprehensive style guidelines. + +Prettier is used for formatting (config in `.prettierrc`). diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 00000000000..f049d4c5317 --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,76 @@ +# Code of Conduct + +## Our Pledge + +In the interest of fostering an open and welcoming environment, we as +contributors and maintainers pledge to make participation in our project and +our community a harassment-free experience for everyone, regardless of age, body +size, disability, ethnicity, sex characteristics, gender identity and expression, +level of experience, education, socio-economic status, nationality, personal +appearance, race, religion, or sexual identity and orientation. + +## Our Standards + +Examples of behavior that contributes to creating a positive environment +include: + +* Using welcoming and inclusive language +* Being respectful of differing viewpoints and experiences +* Gracefully accepting constructive criticism +* Focusing on what is best for the community +* Showing empathy towards other community members + +Examples of unacceptable behavior by participants include: + +* The use of sexualized language or imagery and unwelcome sexual attention or + advances +* Trolling, insulting/derogatory comments, and personal or political attacks +* Public or private harassment +* Publishing others' private information, such as a physical or electronic + address, without explicit permission +* Other conduct which could reasonably be considered inappropriate in a + professional setting + +## Our Responsibilities + +Project maintainers are responsible for clarifying the standards of acceptable +behavior and are expected to take appropriate and fair corrective action in +response to any instances of unacceptable behavior. + +Project maintainers have the right and responsibility to remove, edit, or +reject comments, commits, code, wiki edits, issues, and other contributions +that are not aligned to this Code of Conduct, or to ban temporarily or +permanently any contributor for other behaviors that they deem inappropriate, +threatening, offensive, or harmful. + +## Scope + +This Code of Conduct applies within all project spaces, and it also applies when +an individual is representing the project or its community in public spaces. +Examples of representing a project or community include using an official +project e-mail address, posting via an official social media account, or acting +as an appointed representative at an online or offline event. Representation of +a project may be further defined and clarified by project maintainers. + +## Enforcement + +Instances of abusive, harassing, or otherwise unacceptable behavior may be +reported by contacting the project team at . All +complaints will be reviewed and investigated and will result in a response that +is deemed necessary and appropriate to the circumstances. The project team is +obligated to maintain confidentiality with regard to the reporter of an incident. +Further details of specific enforcement policies may be posted separately. + +Project maintainers who do not follow or enforce the Code of Conduct in good +faith may face temporary or permanent repercussions as determined by other +members of the project's leadership. + +## Attribution + +This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, +available at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html + +[homepage]: https://www.contributor-covenant.org + +For answers to common questions about this code of conduct, see +https://www.contributor-covenant.org/faq diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000000..4c7e5ec74c2 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,136 @@ +# Contributing + +Thank you for your interest in contributing to the React Docs! + +## Code of Conduct + +Facebook has adopted a Code of Conduct that we expect project +participants to adhere to. Please [read the full text](https://code.facebook.com/codeofconduct) +so that you can understand what actions will and will not be tolerated. + +## Technical Writing Tips + +This is a [good summary](https://medium.com/@kvosswinkel/coding-like-a-journalist-ee52360a16bc) for things to keep in mind when writing technical docs. + +## Guidelines for Text + +**Different sections intentionally have different styles.** + +The documentation is divided into sections to cater to different learning styles and use cases. When editing an article, try to match the surrounding text in tone and style. When creating a new article, try to match the tone of the other articles in the same section. Learn about the motivation behind each section below. + +**[Learn React](https://react.dev/learn)** is designed to introduce fundamental concepts in a step-by-step way. Each individual article in Learn React builds on the knowledge from the previous ones, so make sure not to add any "cyclical dependencies" between them. It is important that the reader can start with the first article and work their way to the last Learn React article without ever having to "look ahead" for a definition. This explains some ordering choices (e.g. that state is explained before events, or that "thinking in React" doesn't use refs). Learn React also serves as a reference manual for React concepts, so it is important to be very strict about their definitions and relationships between them. + +**[API Reference](https://react.dev/reference/react)** is organized by APIs rather than concepts. It is intended to be exhaustive. Any corner cases or recommendations that were skipped for brevity in Learn React should be mentioned in the reference documentation for the corresponding APIs. + +**Try to follow your own instructions.** + +When writing step-by-step instructions (e.g. how to install something), try to forget everything you know about the topic, and actually follow the instructions you wrote, a single step at time. Often you will discover that there is implicit knowledge that you forgot to mention, or that there are missing or out-of-order steps in the instructions. Bonus points for getting *somebody else* to follow the steps and watching what they struggle with. Often it would be something very simple that you have not anticipated. + +## Guidelines for Code Examples + +### Syntax + +#### Prefer JSX to `createElement`. + +Ignore this if you're specifically describing `createElement`. + +#### Use `const` where possible, otherwise `let`. Don't use `var`. + +Ignore this if you're specifically writing about ES5. + +#### Don't use ES6 features when equivalent ES5 features have no downsides. + +Remember that ES6 is still new to a lot of people. While we use it in many places (`const` / `let`, classes, arrow functions), if the equivalent ES5 code is just as straightforward and readable, consider using it. + +In particular, you should prefer named `function` declarations over `const myFunction = () => ...` arrows for top-level functions. However, you *should* use arrow functions where they provide a tangible improvement (such as preserving `this` context inside a component). Consider both sides of the tradeoff when deciding whether to use a new feature. + +#### Don't use features that aren't standardized yet. + +For example, **don't** write this: + +```js +class MyComponent extends React.Component { + state = {value: ''}; + handleChange = (e) => { + this.setState({value: e.target.value}); + }; +} +``` + +Instead, **do** write this: + +```js +class MyComponent extends React.Component { + constructor(props) { + super(props); + this.handleChange = this.handleChange.bind(this); + this.state = {value: ''}; + } + handleChange(e) { + this.setState({value: e.target.value}); + } +} +``` + +Ignore this rule if you're specifically describing an experimental proposal. Make sure to mention its experimental nature in the code and in the surrounding text. + +### Style + +- Use semicolons. +- No space between function names and parens (`method() {}` not `method () {}`). +- When in doubt, use the default style favored by [Prettier](https://prettier.io/playground/). +- Always capitalize React concepts such as Hooks, Effects, and Transitions. + +### Highlighting + +Use `js` as the highlighting language in Markdown code blocks: + +```` +```js +// code +``` +```` + +Sometimes you'll see blocks with numbers. +They tell the website to highlight specific lines. + +You can highlight a single line: + +```` +```js {2} +function hello() { + // this line will get highlighted +} +``` +```` + +A range of lines: + +```` +```js {2-4} +function hello() { + // these lines + // will get + // highlighted +} +``` +```` + +Or even multiple ranges: + +```` +```js {2-4,6} +function hello() { + // these lines + // will get + // highlighted + console.log('hello'); + // also this one + console.log('there'); +} +``` +```` + +Be mindful that if you move some code in an example with highlighting, you also need to update the highlighting. + +Don't be afraid to often use highlighting! It is very valuable when you need to focus the reader's attention on a particular detail that's easy to miss. diff --git a/README.md b/README.md index d7cdee90bb3..182192cb552 100644 --- a/README.md +++ b/README.md @@ -1,38 +1,42 @@ -# reactjs.org +# react.dev -This repo contains the source code and documentation powering [reactjs.org](https://reactjs.org/). +This repo contains the source code and documentation powering [react.dev](https://react.dev/). ## Getting started ### Prerequisites 1. Git -1. Node: install version 8.4 or greater +1. Node: any version starting with v16.8.0 or greater 1. Yarn: See [Yarn website for installation instructions](https://yarnpkg.com/lang/en/docs/install/) -1. A clone of the [reactjs.org repo](https://github.com/reactjs/reactjs.org) on your local machine 1. A fork of the repo (for any contributions) +1. A clone of the [react.dev repo](https://github.com/reactjs/react.dev) on your local machine ### Installation -1. `cd reactjs.org` to go into the project root -1. `yarn` to install the website's npm dependencies +1. `cd react.dev` to go into the project root +3. `yarn` to install the website's npm dependencies ### Running locally -1. `yarn dev` to start the hot-reloading development server (powered by [Gatsby](https://www.gatsbyjs.org)) -1. `open http://localhost:8000` to open the site in your favorite browser +1. `yarn dev` to start the development server (powered by [Next.js](https://nextjs.org/)) +1. `open http://localhost:3000` to open the site in your favorite browser ## Contributing +### Guidelines + +The documentation is divided into several sections with a different tone and purpose. If you plan to write more than a few sentences, you might find it helpful to get familiar with the [contributing guidelines](https://github.com/reactjs/react.dev/blob/main/CONTRIBUTING.md#guidelines-for-text) for the appropriate sections. + ### Create a branch -1. `git checkout master` from any folder in your local `reactjs.org` repository -1. `git pull origin master` to ensure you have the latest main code +1. `git checkout main` from any folder in your local `react.dev` repository +1. `git pull origin main` to ensure you have the latest main code 1. `git checkout -b the-name-of-my-branch` (replacing `the-name-of-my-branch` with a suitable name) to create a branch ### Make the change -1. Follow the "Running locally" instructions +1. Follow the ["Running locally"](#running-locally) instructions 1. Save the files and check in the browser 1. Changes to React components in `src` will hot-reload 1. Changes to markdown files in `content` will hot-reload @@ -41,16 +45,19 @@ This repo contains the source code and documentation powering [reactjs.org](http ### Test the change 1. If possible, test any visual changes in all latest versions of common browsers, on both desktop and mobile. -1. Run `yarn check-all` from the project root. (This will run Prettier, ESLint, and Flow.) +2. Run `yarn check-all`. (This will run Prettier, ESLint and validate types.) ### Push it -1. `git add -A && git commit -m "My message"` (replacing `My message` with a commit message, such as `Fixed header logo on Android`) to stage and commit your changes +1. `git add -A && git commit -m "My message"` (replacing `My message` with a commit message, such as `Fix header logo on Android`) to stage and commit your changes 1. `git push my-fork-name the-name-of-my-branch` -1. Go to the [reactjs.org repo](https://github.com/reactjs/reactjs.org) and you should see recently pushed branches. +1. Go to the [react.dev repo](https://github.com/reactjs/react.dev) and you should see recently pushed branches. 1. Follow GitHub's instructions. -1. If possible, include screenshots of visual changes. A Netlify build will also be automatically created once you make your PR so other people can see your change. +1. If possible, include screenshots of visual changes. A preview build is triggered after your changes are pushed to GitHub. + +## Translation -## Troubleshooting +If you are interested in translating `react.dev`, please see the current translation efforts [here](https://github.com/reactjs/react.dev/issues/4135). -- `yarn reset` to clear the local cache +## License +Content submitted to [react.dev](https://react.dev/) is CC-BY-4.0 licensed, as found in the [LICENSE-DOCS.md](https://github.com/reactjs/react.dev/blob/main/LICENSE-DOCS.md) file. diff --git a/colors.js b/colors.js new file mode 100644 index 00000000000..2b282c820c6 --- /dev/null +++ b/colors.js @@ -0,0 +1,102 @@ +/** + * Copyright (c) Meta Platforms, Inc. and affiliates. + * + * This source code is licensed under the MIT license found in the + * LICENSE file in the root directory of this source tree. + */ + +/* + * Copyright (c) Facebook, Inc. and its affiliates. + */ + +module.exports = { + // Text colors + primary: '#23272F', // gray-90 + 'primary-dark': '#F6F7F9', // gray-5 + secondary: '#404756', // gray-70 + 'secondary-dark': '#EBECF0', // gray-10 + tertiary: '#5E687E', // gray-50 + 'tertiary-dark': '#99A1B3', // gray-30 + link: '#087EA4', // blue-50 + 'link-dark': '#58C4DC', // blue-40 + syntax: '#EBECF0', // gray-10 + wash: '#FFFFFF', + 'wash-dark': '#23272F', // gray-90 + card: '#F6F7F9', // gray-05 + 'card-dark': '#343A46', // gray-80 + highlight: '#E6F7FF', // blue-10 + 'highlight-dark': 'rgba(88,175,223,.1)', + border: '#EBECF0', // gray-10 + 'border-dark': '#343A46', // gray-80 + 'secondary-button': '#EBECF0', // gray-10 + 'secondary-button-dark': '#404756', // gray-70 + brand: '#087EA4', // blue-40 + 'brand-dark': '#58C4DC', // blue-40 + + // Gray + 'gray-95': '#16181D', + 'gray-90': '#23272F', + 'gray-80': '#343A46', + 'gray-70': '#404756', + 'gray-60': '#4E5769', + 'gray-50': '#5E687E', + 'gray-40': '#78839B', + 'gray-30': '#99A1B3', + 'gray-20': '#BCC1CD', + 'gray-15': '#D0D3DC', + 'gray-10': '#EBECF0', + 'gray-5': '#F6F7F9', + + // Blue + 'blue-80': '#043849', + 'blue-60': '#045975', + 'blue-50': '#087EA4', + 'blue-40': '#149ECA', // Brand Blue + 'blue-30': '#58C4DC', // unused + 'blue-20': '#ABE2ED', + 'blue-10': '#E6F7FF', // todo: doesn't match illustrations + 'blue-5': '#E6F6FA', + + // Yellow + 'yellow-60': '#B65700', + 'yellow-50': '#C76A15', + 'yellow-40': '#DB7D27', // unused + 'yellow-30': '#FABD62', // unused + 'yellow-20': '#FCDEB0', // unused + 'yellow-10': '#FDE7C7', + 'yellow-5': '#FEF5E7', + + // Purple + 'purple-60': '#2B3491', // unused + 'purple-50': '#575FB7', + 'purple-40': '#6B75DB', + 'purple-30': '#8891EC', + 'purple-20': '#C3C8F5', // unused + 'purple-10': '#E7E9FB', + 'purple-5': '#F3F4FD', + + // Green + 'green-60': '#2B6E62', + 'green-50': '#388F7F', + 'green-40': '#44AC99', + 'green-30': '#7FCCBF', + 'green-20': '#ABDED5', + 'green-10': '#E5F5F2', + 'green-5': '#F4FBF9', + + // RED + 'red-60': '#712D28', + 'red-50': '#A6423A', // unused + 'red-40': '#C1554D', + 'red-30': '#D07D77', + 'red-20': '#E5B7B3', // unused + 'red-10': '#F2DBD9', // unused + 'red-5': '#FAF1F0', + + // MISC + 'code-block': '#99a1b30f', // gray-30 @ 6% + 'gradient-blue': '#58C4DC', // Only used for the landing gradient for now. + github: { + highlight: '#fffbdd', + }, +}; diff --git a/content/404.md b/content/404.md deleted file mode 100644 index ab9ba1d60cf..00000000000 --- a/content/404.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -layout: single -title: Page Not Found -permalink: 404.html ---- - -We couldn't find what you were looking for. - -Please contact the owner of the site that linked you to the original URL and let them know their link is broken. diff --git a/content/acknowledgements.yml b/content/acknowledgements.yml deleted file mode 100644 index a8ebfacb320..00000000000 --- a/content/acknowledgements.yml +++ /dev/null @@ -1,1130 +0,0 @@ ---- -- '839' -- Aaron Ackerman -- Aaron Cannon -- Aaron Franks -- Aaron Gelter -- Abhay Nikam -- Abhishek Soni -- Adam -- Adam Bloomston -- Adam Krebs -- Adam Mark -- Adam Solove -- Adam Stankiewicz -- Adam Timberlake -- Adam Zapletal -- Addy Osmani -- Adrian Sieber -- Aesop Wolf -- Ahmad Wali Sidiqi -- Alan Plum -- Alan Souza -- Alan deLevie -- Alastair Hole -- Alex -- Alex Babkov -- Alex Baumgertner -- Alex Boatwright -- Alex Boyd -- Alex Dajani -- Alex Jacobs -- Alex Katopodis -- Alex Lopatin -- Alex Mykyta -- Alex Pien -- Alex Smith -- Alex Zelenskiy -- Alex Zherdev -- Alexander -- Alexander Shtuchkin -- Alexander Solovyov -- Alexander Tseung -- Alexandre Gaudencio -- Alexandre Kirszenberg -- Alexey Raspopov -- Alexey Shamrin -- Ali Taheri Moghaddar -- Ali Ukani -- Alireza Mostafizi -- Almero Steyn -- Amanvir Sangha -- Amjad Masad -- Anastasia A -- Andre Giron -- Andre Z Sanchez -- Andreas Möller -- Andreas Savvides -- Andreas Svensson -- Andres Kalle -- Andres Suarez -- Andrew Clark -- Andrew Cobby -- Andrew Davey -- Andrew Henderson -- Andrew Imm -- Andrew Kulakov -- Andrew Lo -- Andrew Poliakov -- Andrew Rasmussen -- Andrew Rota -- Andrew Sokolov -- Andrew Zich -- Andrey Marchenko -- Andrey Okonetchnikov -- Andrey Popp -- Andrey Safronov -- Andy Edwards -- Ankeet Maini -- Anthony van der Hoorn -- Anto Aravinth -- Antonio Ruberto -- Antti Ahti -- António Nuno Monteiro -- Anuj Tomar -- Anuja Ware -- AoDev -- April Arcus -- Areeb Malik -- Aria Buckles -- Aria Stewart -- Arian Faurtosh -- Arni Fannar -- Arshabh Kumar Agarwal -- Artem Nezvigin -- Arthur Gunn -- Ashish -- Austin Wright -- Avinash Kondeti -- Ayman Osman -- B.Orlov -- BDav24 -- BEAUDRU Manuel -- Baraa Hamodi -- Bartosz Kaszubowski -- Basarat Ali Syed -- Battaile Fauber -- Beau Smith -- Ben Anderson -- Ben Berman -- Ben Brooks -- Ben Foxall -- Ben Halpern -- Ben Jaffe -- Ben Moss -- Ben Newman -- Ben Ripkens -- Benedikt Meurer -- Benjamin Keen -- Benjamin Leiken -- Benjamin Woodruff -- Benjy Cui -- Benoit Girard -- Benton Rochester -- Bernard Lin -- Bill Blanchard -- Bill Fisher -- Billy Shih -- Blaine Hatab -- Blaine Kasten -- Bob Eagan -- Bob Ralian -- Bob Renwick -- Bobby -- Bogdan Chadkin -- Bojan Mihelac -- Boris Yankov -- Brad Vogel -- Bradford -- Bradley Spaulding -- Brandon Bloom -- Brandon Dail -- Brandon Tilley -- Brenard Cubacub -- Brent Vatne -- Brian Cooke -- Brian Emil Hartz -- Brian Holt -- Brian Hsu -- Brian Kim -- Brian Kung -- Brian Reavis -- Brian Rue -- Brian Vaughn -- Bruce Harris -- Bruno Heridet -- Bruno Škvorc -- Bryan Braun -- CT Wu -- Cam Song -- Cam Spiers -- Cameron Chamberlain -- Cameron Matheson -- Carolina Powers -- Carter Chung -- Cassus Adam Banko -- Cat Chen -- Cedric Sohrauer -- Cesar William Alvarenga -- Chad Fawcett -- Changsoon Bok -- Charles Marsh -- Charlie Garcia -- Chase Adams -- Cheng Lou -- Chitharanjan Das -- Chris -- Chris Bolin -- Chris Grovers -- Chris Ha -- Chris Pearce -- Chris Rebert -- Chris Sciolla -- Christian Alfoni -- Christian Oliff -- Christian Roman -- Christoffer Sawicki -- Christoph Pojer -- Christophe Hurpeau -- Christopher Monsanto -- Claudio Brandolino -- Clay Allsopp -- Clay Miller -- Clement Hoang -- CodinCat -- Cody Reichert -- Colin Wren -- Connor McSheffrey -- Conor Hastings -- Constantin Gavrilete -- Cory House -- Cotton Hou -- Craig Akimoto -- Cristovao Verstraeten -- DQNEO -- Dai Nguyen -- Damian Nicholson -- Damien Pellier -- Damien Soulard -- Dan Abramov -- Dan Fox -- Dan Schafer -- DanZeuss -- Daniel Carlsson -- Daniel Cousens -- Daniel Friesen -- Daniel Gasienica -- Daniel Hejl -- Daniel Hejl -- Daniel Liburd -- Daniel Lo Nigro -- Daniel Mané -- Daniel Miladinov -- Daniel Rodgers-Pryor -- Daniel Rosenwasser -- Daniel Rotter -- Daniel Schonfeld -- Daniela Borges -- Danilo Vitoriano -- Danny Ben-David -- Danny Hurlburt -- Darcy -- Daryl Lau -- Darío Javier Cravero -- Dave Galbraith -- Dave Lunny -- Dave Voyles -- David Aurelio -- David Baker -- David Beitey -- David Ed Mellum -- David Goldberg -- David Granado -- David Greenspan -- David Hellsing -- David Hu -- David Khourshid -- David Mininger -- David Neubauer -- David Percy -- Dean Shi -- Denis Laxalde -- Denis Pismenny -- Denis Sokolov -- Deniss Jacenko -- Dennis Johnson -- Desmond Brand -- Devedse -- Devinsuit -- Devon Blandin -- Devon Harvey -- Dheeraj Kumar -- Dhyey Thakore -- Diego Muracciole -- Dima Beznos -- Dimzel Sobolev -- Dmitri Zaitsev -- Dmitrii Abramov -- Dmitriy Kubyshkin -- Dmitriy Rozhkov -- Dmitry Blues -- Dmitry Mazuro -- Dmitry Zhuravlev-Nevsky -- Domenico Matteo -- Dominic Gannaway -- Don Abrams -- Dongsheng Liu -- Duke Pham -- Dustan Kasten -- Dustin Getz -- Dylan Harrington -- Dylan Kirby -- Edgar (Algebr) -- Eduard -- Eduardo Garcia -- Edvin Erikson -- Elaine Fang -- Eli White -- Enguerran -- Eoin Hennessy -- Eric Churchill -- Eric Clemmons -- Eric Douglas -- Eric Eastwood -- Eric Elliott -- Eric Florenzano -- Eric Matthys -- Eric Nakagawa -- Eric O'Connell -- Eric Pitcher -- Eric Sakmar -- Eric Schoffstall -- Erik Harper -- Erik Hellman -- Espen Hovlandsdal -- Esteban -- Eugene -- EugeneGarbuzov -- Evan Coonrod -- Evan Jacobs -- Evan Scott -- Evan Vosberg -- Fabio M. Costa -- Fabrizio Castellarin -- Faheel Ahmad -- Fatih -- Federico Rampazzo -- Felipe Oliveira Carvalho -- Felix Gnass -- Felix Kling -- Fernando Alex Helwanger -- Fernando Correia -- Fernando Montoya -- Filip Hoško -- Filip Spiridonov -- Flarnie Marchan -- Fokke Zandbergen -- Frank Yan -- Frankie Bagnardi -- François Chalifour -- François-Xavier Bois -- Fraser Haer -- Fred Zhao -- Freddy Rangel -- Fyodor Ivanishchev -- G Scott Olson -- G. Kay Lee -- Gabe Levi -- Gabriel Lett Viviani -- Gajus Kuizinas -- Gant Laborde -- Gareth Nicholson -- Garmash Nikolay -- Garren Smith -- Garrett McCullough -- Gavin McQuistin -- Gaëtan Renaudeau -- Geert Pasteels -- Geert-Jan Brits -- George A Sisco III -- Georgii Dolzhykov -- Gert Hengeveld -- Giamir Buoncristiani -- Gil Chen-Zion -- Gilbert -- Giorgio Polvara -- Giuseppe -- Glen Mailer -- Grant Timmerman -- Greg Hurrell -- Greg Palmer -- Greg Perkins -- Greg Roodt -- Gregory -- Grgur Grisogono -- Griffin Michl -- Guangqiang Dong -- Guido Bouman -- Guilherme Oenning -- Guilherme Ruiz -- Guillaume Claret -- Harry Hull -- Harry Marr -- Harry Moreno -- Harshad Sabne -- Hekar Khani -- Hendrik Swanepoel -- Henrik Nyh -- Henry Harris -- Henry Wong -- Henry Zhu -- Hideo Matsumoto -- Hikaru Suido -- Hiroyuki Wada -- Hou Chia -- Huang-Wei Chang -- Hugo Agbonon -- Hugo Jobling -- Hyeock Kwon -- Héctor Ramos -- Héliton Nordt -- Ian Obermiller -- Ian Sutherland -- Ignacio Carbajo -- Igor Scekic -- Ike Peters -- Ilia Pavlenkov -- Ilya Gelman -- Ilya Shuklin -- Ilyá Belsky -- Ingvar Stepanyan -- Irae Carvalho -- Isaac Salier-Hellendag -- Islam Sharabash -- Iurii Kucherov -- Ivan -- Ivan Kozik -- Ivan Krechetov -- Ivan Vergiliev -- Ivan Zotov -- J. Andrew Brassington -- J. Renée Beach -- JD Isaacks -- JJ Weber -- JW -- Jack -- Jack Cross -- Jack Ford -- Jack Zhang -- Jackie Wung -- Jackson Huang -- Jacob Gable -- Jacob Greenleaf -- Jacob Lamont -- Jae Hun Lee -- Jae Hun Ro -- Jaeho Lee -- Jaime Mingo -- Jake Boone -- Jake Worth -- Jakub Malinowski -- James -- James Brantly -- James Burnett -- James Friend -- James Ide -- James Long -- James Pearce -- James Seppi -- James South -- James Wen -- Jamie Wong -- Jamis Charles -- Jamison Dance -- Jan Hancic -- Jan Kassens -- Jan Raasch -- Jan Schär -- Jane Manchun Wong -- Jared Forsyth -- Jared Fox -- Jarrod Mosen -- Jason -- Jason Bonta -- Jason Grlicky -- Jason Ly -- Jason Miller -- Jason Quense -- Jason Trill -- Jason Webster -- Jay Jaeho Lee -- Jay Phelps -- Jayen Ashar -- Jean Lauliac -- Jed Watson -- Jeff Barczewski -- Jeff Carpenter -- Jeff Chan -- Jeff Hicken -- Jeff Kolesky -- Jeff Morrison -- Jeff Welch -- Jeffrey Lin -- Jeffrey Wan -- Jen Wong -- Jeremy Fairbank -- Jess Telford -- Jesse Skinner -- Jignesh Kakadiya -- Jim OBrien -- Jim Sproch -- Jiminikiz -- Jimmy Jea -- Jing Chen -- Jinwoo Oh -- Jinxiu Lee -- Jirat Ki -- Jiyeon Seo -- Jody McIntyre -- Joe Critchley -- Joe Stein -- Joel Auterson -- Joel Denning -- Joel Sequeira -- Johan Tinglöf -- Johannes Baiter -- Johannes Emerich -- Johannes Lumpe -- John Heroy -- John Longanecker -- John Ryan -- John Watson -- John-David Dalton -- Jon Beebe -- Jon Bretman -- Jon Chester -- Jon Hester -- Jon Madison -- Jon Scott Clark -- Jon Tewksbury -- Jonas Enlund -- Jonas Gebhardt -- Jonathan Hsu -- Jonathan Persson -- Jordan Harband -- Jordan Walke -- Jorrit Schippers -- Joseph Nudell -- Joseph Savona -- Josh Bassett -- Josh Duck -- Josh Hunt -- Josh Perez -- Josh Yudaken -- Joshua Evans -- Joshua Go -- Joshua Goldberg -- Joshua Ma -- João Valente -- Juan -- Juan Serrano -- Julen Ruiz Aizpuru -- Julian Viereck -- Julien Bordellier -- Julio Lopez -- Jun Kim -- Jun Wu -- Juraj Dudak -- Justas Brazauskas -- Justin -- Justin Grant -- Justin Jaffray -- Justin Robison -- Justin Woo -- KB -- Kale -- Kamron Batman -- Karl Horky -- Karl Mikkelsen -- Karpich Dmitry -- Karthik Balakrishnan -- Karthik Chintapalli -- Kateryna -- Kaylee Knowles -- KeicaM -- Keito Uchiyama -- Ken Powers -- Kenneth Chau -- Kent C. Dodds -- Kevin Cheng -- Kevin Coughlin -- Kevin Huang -- Kevin Lacker -- Kevin Lau -- Kevin Lin -- Kevin Old -- Kevin Robinson -- Kevin Suttle -- Kewei Jiang -- Keyan Zhang -- Kier Borromeo -- Kiho · Cham -- KimCoding -- Kirk Steven Hansen -- Kit Randel -- Kite -- Kohei TAKATA -- Koo Youngmin -- Krystian Karczewski -- Kunal Mehta -- Kurt Furbush -- Kurt Ruppel -- Kurt Weiberth -- Kyle Kelley -- Kyle Mathews -- Laurence Rowe -- Laurent Etiemble -- Lee Byron -- Lee Jaeyoung -- Lee Sanghyeon -- Lei -- Leland Richardson -- Leon Fedotov -- Leon Yip -- Leonardo YongUk Kim -- Levi Buzolic -- Levi McCallum -- Lewis Blackwood -- Liangzhen Zhu -- Lily -- Linus Unnebäck -- Lipis -- Liz -- Logan Allen -- Lovisa Svallingson -- Lucas -- Ludovico Fischer -- Luigy Leon -- Luke Belliveau -- Luke Horvat -- Lutz Rosema -- MICHAEL JACKSON -- MIKAMI Yoshiyuki -- Maciej Kasprzyk -- Maher Beg -- Maksim Shastsel -- Manas -- Marcelo Alves -- Marcin K. -- Marcin Kwiatkowski -- Marcin Mazurek -- Marcin Szczepanski -- Marcio Puga -- Marcos Ojeda -- Marcy Sutton -- Mariano Desanze -- Mario Souto -- Marius Skaar Ludvigsen -- Marjan -- Mark Anderson -- Mark Funk -- Mark Hintz -- Mark IJbema -- Mark Murphy -- Mark Pedrotti -- Mark Penner -- Mark Richardson -- Mark Rushakoff -- Mark Sun -- Marks Polakovs -- Marlon Landaverde -- Marshall Bowers -- Marshall Roch -- Martin Andert -- Martin Hochel -- Martin Hujer -- Martin Jul -- Martin Konicek -- Martin Mihaylov -- Martin V -- Masaki KOBAYASHI -- Mateusz Burzyński -- Mathieu M-Gosselin -- Mathieu Savy -- Matias Singers -- Matsunoki -- Matt Brookes -- Matt Dunn-Rankin -- Matt Harrison -- Matt Huggins -- Matt Stow -- Matt Zabriskie -- Matthew Dapena-Tretter -- Matthew Herbst -- Matthew Hodgson -- Matthew Johnston -- Matthew King -- Matthew Looi -- Matthew Miner -- Matthew Shotton -- Matthias Le Brun -- Matti Nelimarkka -- Mattijs Kneppers -- Max Donchenko -- Max F. Albrecht -- Max Heiber -- Max Stoiber -- Maxi Ferreira -- Maxim Abramchuk -- Maxwel D'souza -- Merrick Christensen -- Mert Kahyaoğlu -- Michael Chan -- Michael Jackson -- Michael McDermott -- Michael O'Brien -- Michael Randers-Pehrson -- Michael Ridgway -- Michael Sinov -- Michael Terry -- Michael Warner -- Michael Wiencek -- Michael Ziwisky -- Michal Srb -- Michał Ordon -- Michał Pierzchała -- Michele Bertoli -- Michelle Todd -- Michiya -- Mihai Parparita -- Mike D Pilsbury -- Mike Groseclose -- Mike Nordick -- Mikhail Osher -- Mikolaj Dadela -- Miles Johnson -- Miller Medeiros -- Minwe LUO -- Minwei Xu -- Miorel Palii -- Mitchel Humpherys -- Mitermayer Reis -- Moacir Rosa -- Mojtaba Dashtinejad -- Morhaus -- Moshe Kolodny -- Mouad Debbar -- Murad -- Murray M. Moss -- Murtaza Haveliwala -- NE-SmallTown -- Nadeesha Cabral -- Naman Goel -- Nate -- Nate Hunzaker -- Nate Lee -- Nate Norberg -- Nathan Hardy -- Nathan Smith -- Nathan White -- Nee -- Neo -- Neri Marschik -- NestorTejero -- Nguyen Truong Duy -- Nicholas Bergson-Shilcock -- Nicholas Clawson -- Nick Balestra -- Nick Fitzgerald -- Nick Gavalas -- Nick Kasten -- Nick Merwin -- Nick Presta -- Nick Raienko -- Nick Thompson -- Nick Williams -- Nik Nyby -- Nikita Lebedev -- Niklas Boström -- Nikoloz Buligini -- Nima Jahanshahi -- Ning Xia -- Niole Nelson -- Nolan Lawson -- Nuno Campos -- OJ Kwon -- Oiva Eskola -- Oleg -- Oleksii Markhovskyi -- Oliver Zeigermann -- Olivier Tassinari -- Omid Hezaveh -- Oscar Bolmsten -- Oskari Mantere -- Owen Coutts -- Pablo Lacerda de Miranda -- Paolo Moretti -- Pascal Hartig -- Patrick -- Patrick Finnigan -- Patrick Laughlin -- Patrick Stapleton -- Paul Benigeri -- Paul Harper -- Paul Kehrer -- Paul Manta -- Paul O’Shannessy -- Paul Seiffert -- Paul Shen -- Pedro Nauck -- Pete Hunt -- Peter Blazejewicz -- Peter Cottle -- Peter Jaros -- Peter Newnham -- Peter Ruibal -- Petri Lehtinen -- Petri Lievonen -- Phil Quinn -- Phil Rajchgot -- Philip Jackson -- Philipp Spieß -- Pieter De Baets -- Pieter Vanderwerff -- Piotr Czajkowski -- Piper Chester -- Pontus Abrahamsson -- Pouja Nikray -- Prathamesh Sonpatki -- Prayag Verma -- Preston Parry -- Qin Junwen -- RSG -- Rachel D. Cartwright -- Rafael -- Rafael Angeline -- Rafal Dittwald -- Ragnar Þór Valgeirsson -- Rahul Gupta -- Rainer Oviir -- Raito Bezarius -- Rajat Sehgal -- Rajiv Tirumalareddy -- Ram Kaniyur -- Randall Randall -- Ray -- Ray Dai -- Raymond Ha -- Reed Loden -- Remko Tronçon -- Ricardo -- Rich Harris -- Richard -- Richard D. Worth -- Richard Feldman -- Richard Kho -- Richard Littauer -- Richard Livesey -- Richard Maisano -- Richard Roncancio -- Richard Wood -- Richie Thomas -- Rick Beerendonk -- Rick Ford -- Riley Tomasek -- Rob Arnold -- Robert Binna -- Robert Chang -- Robert Haritonov -- Robert Kielty -- Robert Knight -- Robert Martin -- Robert Sedovsek -- Robin Berjon -- Robin Frischmann -- Robin Ricard -- Roderick Hsiao -- Rodrigo Pombo -- Rohan Nair -- Roman Liutikov -- Roman Matusevich -- Roman Pominov -- Roman Vanesyan -- Rui Araújo -- Russ -- Ryan Lahfa -- Ryan Seddon -- Ryo Shibayama -- Sahat Yalkabov -- Saif Hakim -- Saiichi Hashimoto -- Sakina Crocker -- Sam Balana -- Sam Beveridge -- Sam Saccone -- Sam Selikoff -- Samer Buna -- Samuel -- Samuel Hapák -- Samuel Reed -- Samuel Scheiderich -- Samy Al Zahrani -- Sander Spies -- Sasha Aickin -- Sassan Haradji -- Satoshi Nakajima -- Scott -- Scott Burch -- Scott Feeney -- Sean Gransee -- Sean Kinsey -- Sean Smith -- Seba -- Sebastian Markbåge -- Sebastian McKenzie -- Senin Roman -- Seoh Char -- Sercan Eraslan -- Serg -- Sergey Generalov -- Sergey Rubanov -- Seyi Adebajo -- Shane O'Sullivan -- Shaun Trennery -- ShihChi Huang -- Shim Won -- Shinnosuke Watanabe -- Shogun Sea -- Shota Kubota -- Shripad K -- Shubheksha Jalan -- Shuhei Kagawa -- Sibi -- Simen Bekkhus -- Simon Højberg -- Simon Welsh -- Simone Vittori -- Skasi -- Snowmanzzz(Zhengzhong Zhao) -- Soichiro Kawamura -- Soo Jae Hwang -- Sophia -- Sophia Westwood -- Sophie Alpert -- Sota Ohara -- Spen Taylor -- Spencer Ahrens -- Spencer Handley -- Sriram Thiagarajan -- Stefan Dombrowski -- Stephen John Sorensen -- Stephen Murphy -- Stephie -- Sterling Cobb -- Steve Baker -- Steve Mao -- Steven Luscher -- Steven Syrek -- Steven Vachon -- Stolenkid -- Stoyan Stefanov -- Stuart Harris -- SunHuawei -- Sundeep Malladi -- Sung Won Cho -- Sunny Juneja -- Sunny Ripert -- Superlaziness -- Sven Helmberger -- Sverre Johansen -- Swaroop SM -- Sébastien Lorber -- Sławomir Laskowski -- Taegon Kim -- Taeho Kim -- Taehwan, No -- Tanase Hagi -- Tanner -- Tay Yang Shun -- Ted Kim -- TedPowers -- Tengfei Guo -- Teodor Szente -- Tetsuharu OHZEKI -- Tetsuya Hasegawa -- Thibaut Rizzi -- Thomas Aylott -- Thomas Boyt -- Thomas Broadley -- Thomas Reggi -- Thomas Röggla -- Thomas Shaddox -- Thomas Shafer -- ThomasCrvsr -- Tiago Fernandez -- Tienchai Wirojsaksaree -- Tim Routowicz -- Tim Schaub -- Timothy Yung -- Timur Carpeev -- Tobias Reiss -- Tom Duncalf -- Tom Gasson -- Tom Haggie -- Tom Hauburger -- Tom MacWright -- Tom Occhino -- Tomasz Kołodziejski -- Tomoya Suzuki -- Tomáš Hromada -- Tony Rossi -- Tony Spiro -- Toru Kobayashi -- Trevor Smith -- Trinh Hoang Nhu -- Troy DeMonbreun -- Tsung Hung -- Tyler Brock -- Tyler Buchea -- Tyler Deitz -- Ujjwal Ojha -- Uladzimir Havenchyk -- Usman -- Ustin Zarubin -- Vadim Chernysh -- Valentin Shergin -- Van der Auwermeulen Grégoire -- Varayut Lerdkanlayanawat -- Varun Bhuvanendran -- Varun Rau -- Vasiliy Loginevskiy -- Vedat Mahir YILMAZ -- Veljko Tornjanski -- Vesa Laakso -- Victor Alvarez -- Victor Homyakov -- Victor Koenders -- Victoria Quirante -- Vikash Agrawal -- Ville Immonen -- Vincent Riemer -- Vincent Siao -- Vincent Taing -- Vipul A M -- Vitaliy Potapov -- Vitaly Kramskikh -- Vitor Balocco -- Vjeux -- Vladimir Kovpak -- Vladimir Tikunov -- Volkan Unsal -- Wander Wang -- Wayne Larsen -- Weizenlol -- Whien -- WickyNilliams -- Will Myers -- William Hoffmann -- Wincent Colaiuta -- Wout Mertens -- Xavier Morel -- XuefengWu -- Yakov Dalinchuk -- Yan Li -- Yasar icli -- Yaxian -- YouBao Nong -- Yuichi Hagio -- Yura Chuchola -- Yuriy Dybskiy -- Yusong Liu -- Yutaka Nakajima -- Yuval Dekel -- Zac Braddy -- Zac Smith -- Zach Bruggeman -- Zach Ramaekers -- Zacharias -- Zeke Sikelianos -- Zhangjd -- adraeth -- ankitml -- arush -- bel3atar -- brafdlog -- brillout -- chen -- chocolateboy -- cjshawMIT -- clariroid -- claudiopro -- cloudy1 -- comerc -- cutbko -- davidxi -- dfrownfelter -- djskinner -- dongmeng.ldm -- everdimension -- gillchristian -- gitanupam -- guoyong yi -- hanumanthan -- hao.huang -- hjmoss -- hkal -- iamchenxin -- iamdoron -- iawia002 -- imagentleman -- imjanghyuk -- inkinworld -- jaaberg -- jddxf -- jinmmd -- koh-taka -- kohashi85 -- ksvitkovsky -- laiso -- lamo2k123 -- leeyoungalias -- li.li -- lucas -- maxprafferty -- mdogadailo -- mfijas -- mguidotto -- mondaychen -- najisawas -- neeldeep -- newvlad -- nhducit -- ogom -- pingan1927 -- rgarifullin -- saiyagg -- scloudyy -- segmentationfaulter -- shifengchen -- songawee -- starkch -- sugarshin -- tokikuch -- ventuno -- wacii -- wali-s -- walrusfruitcake -- yiminghe -- youmoo -- yuntao.qyt -- z.ky -- zhangjg -- zhangs -- zombieJ -- zwhitchcox -- "Árni Hermann Reynisson" -- "元彦" -- "凌恒" -- "张敏" -- "王晓勇" -- "龙海燕" \ No newline at end of file diff --git a/content/authors.yml b/content/authors.yml deleted file mode 100644 index e9105367c47..00000000000 --- a/content/authors.yml +++ /dev/null @@ -1,78 +0,0 @@ -# Map of short name to more information. `name` will be used but if you don't -# want to use your real name, just use whatever. If url is included, your name -# will be a link to the provided url. -acdlite: - name: Andrew Clark - url: https://twitter.com/acdlite -benigeri: - name: Paul Benigeri - url: https://github.com/benigeri -chenglou: - name: Cheng Lou - url: https://twitter.com/_chenglou -Daniel15: - name: Daniel Lo Nigro - url: http://dan.cx/ -fisherwebdev: - name: Bill Fisher - url: https://twitter.com/fisherwebdev -flarnie: - name: Flarnie Marchan - url: https://twitter.com/ProbablyFlarnie -gaearon: - name: Dan Abramov - url: https://twitter.com/dan_abramov -jaredly: - name: Jared Forsyth - url: https://twitter.com/jaredforsyth -jgebhardt: - name: Jonas Gebhardt - url: https://twitter.com/jonasgebhardt -jimfb: - name: Jim Sproch - url: http://www.jimsproch.com -jingc: - name: Jing Chen - url: https://twitter.com/jingc -josephsavona: - name: Joseph Savona - url: https://twitter.com/en_JS -keyanzhang: - name: Keyan Zhang - url: https://twitter.com/keyanzhang -kmeht: - name: Kunal Mehta - url: https://github.com/kmeht -LoukaN: - name: Lou Husson - url: https://twitter.com/loukan42 -matthewjohnston4: - name: Matthew Johnston - url: https://github.com/matthewathome -nhunzaker: - name: Nathan Hunzaker - url: https://github.com/nhunzaker -petehunt: - name: Pete Hunt - url: https://twitter.com/floydophone -schrockn: - name: Nick Schrock - url: https://twitter.com/schrockn -sebmarkbage: - name: Sebastian Markbåge - url: https://twitter.com/sebmarkbage -sophiebits: - name: Sophie Alpert - url: https://sophiealpert.com -steveluscher: - name: Steven Luscher - url: https://twitter.com/steveluscher -vjeux: - name: Vjeux - url: https://twitter.com/vjeux -wincent: - name: Greg Hurrell - url: https://twitter.com/wincent -zpao: - name: Paul O’Shannessy - url: https://twitter.com/zpao diff --git a/content/blog/2013-06-02-jsfiddle-integration.md b/content/blog/2013-06-02-jsfiddle-integration.md deleted file mode 100644 index 43922bcc7fc..00000000000 --- a/content/blog/2013-06-02-jsfiddle-integration.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -title: JSFiddle Integration -author: [vjeux] ---- - -[JSFiddle](https://jsfiddle.net) just announced support for React. This is an exciting news as it makes collaboration on snippets of code a lot easier. You can play around this **[base React JSFiddle](http://jsfiddle.net/vjeux/kb3gN/)**, fork it and share it! A [fiddle without JSX](http://jsfiddle.net/vjeux/VkebS/) is also available. - - - diff --git a/content/blog/2013-06-05-why-react.md b/content/blog/2013-06-05-why-react.md deleted file mode 100644 index 79e5af0baaf..00000000000 --- a/content/blog/2013-06-05-why-react.md +++ /dev/null @@ -1,88 +0,0 @@ ---- -title: Why did we build React? -author: [petehunt] ---- - -There are a lot of JavaScript MVC frameworks out there. Why did we build React -and why would you want to use it? - -## React isn't an MVC framework. - -React is a library for building composable user interfaces. It encourages -the creation of reusable UI components which present data that changes over -time. - -## React doesn't use templates. - -Traditionally, web application UIs are built using templates or HTML directives. -These templates dictate the full set of abstractions that you are allowed to use -to build your UI. - -React approaches building user interfaces differently by breaking them into -**components**. This means React uses a real, full featured programming language -to render views, which we see as an advantage over templates for a few reasons: - -- **JavaScript is a flexible, powerful programming language** with the ability - to build abstractions. This is incredibly important in large applications. -- By unifying your markup with its corresponding view logic, React can actually - make views **easier to extend and maintain**. -- By baking an understanding of markup and content into JavaScript, there's - **no manual string concatenation** and therefore less surface area for XSS - vulnerabilities. - -We've also created [JSX](/docs/jsx-in-depth.html), an optional syntax -extension, in case you prefer the readability of HTML to raw JavaScript. - -## Reactive updates are dead simple. - -React really shines when your data changes over time. - -In a traditional JavaScript application, you need to look at what data changed -and imperatively make changes to the DOM to keep it up-to-date. Even AngularJS, -which provides a declarative interface via directives and data binding [requires -a linking function to manually update DOM nodes](https://code.angularjs.org/1.0.8/docs/guide/directive#reasonsbehindthecompilelinkseparation). - -React takes a different approach. - -When your component is first initialized, the `render` method is called, -generating a lightweight representation of your view. From that representation, -a string of markup is produced, and injected into the document. When your data -changes, the `render` method is called again. In order to perform updates as -efficiently as possible, we diff the return value from the previous call to -`render` with the new one, and generate a minimal set of changes to be applied -to the DOM. - -> The data returned from `render` is neither a string nor a DOM node -- it's a -> lightweight description of what the DOM should look like. - -We call this process **reconciliation**. Check out -[this jsFiddle](http://jsfiddle.net/2h6th4ju/) to see an example of -reconciliation in action. - -Because this re-render is so fast (around 1ms for TodoMVC), the developer -doesn't need to explicitly specify data bindings. We've found this approach -makes it easier to build apps. - -## HTML is just the beginning. - -Because React has its own lightweight representation of the document, we can do -some pretty cool things with it: - -- Facebook has dynamic charts that render to `` instead of HTML. -- Instagram is a "single page" web app built entirely with React and - `Backbone.Router`. Designers regularly contribute React code with JSX. -- We've built internal prototypes that run React apps in a web worker and use - React to drive **native iOS views** via an Objective-C bridge. -- You can run React - [on the server](https://github.com/petehunt/react-server-rendering-example) - for SEO, performance, code sharing and overall flexibility. -- Events behave in a consistent, standards-compliant way in all browsers - (including IE8) and automatically use - [event delegation](http://davidwalsh.name/event-delegate). - -Head on over to https://reactjs.org to check out what we have -built. Our documentation is geared towards building apps with the framework, -but if you are interested in the nuts and bolts -[get in touch](/support.html) with us! - -Thanks for reading! diff --git a/content/blog/2013-06-12-community-roundup.md b/content/blog/2013-06-12-community-roundup.md deleted file mode 100644 index c8d4af256f0..00000000000 --- a/content/blog/2013-06-12-community-roundup.md +++ /dev/null @@ -1,47 +0,0 @@ ---- -title: "Community Round-up #1" -author: [vjeux] ---- - -React was open sourced two weeks ago and it's time for a little round-up of what has been going on. - -## Khan Academy Question Editor - -It looks like [Sophie Alpert](http://sophiebits.com/) is the first person outside of Facebook and Instagram to push React code to production. We are very grateful for her contributions in form of pull requests, bug reports and presence on IRC ([#reactjs on Freenode](irc://chat.freenode.net/reactjs)). Sophie wrote about her experience using React: - -> I just rewrote a 2000-line project in React and have now made a handful of pull requests to React. Everything about React I've seen so far seems really well thought-out and I'm proud to be the first non-FB/IG production user of React. -> -> The project that I rewrote in React (and am continuing to improve) is the Khan Academy question editor which content creators can use to enter questions and hints that will be presented to students: ->
    -> -> [Read the full post...](http://sophiebits.com/2013/06/09/using-react-to-speed-up-khan-academy.html) - -## Pimp my Backbone.View (by replacing it with React) - -[Paul Seiffert](https://blog.mayflower.de/) wrote a blog post that explains how to integrate React into Backbone applications. - -> React has some interesting concepts for JavaScript view objects that can be used to eliminate this one big problem I have with Backbone.js. -> -> As in most MVC implementations (although React is probably just a VC implementation), a view is one portion of the screen that is managed by a controlling object. This object is responsible for deciding when to re-render the view and how to react to user input. With React, these view-controllers objects are called components. A component knows how to render its view and how to handle to the user's interaction with it. -> -> The interesting thing is that React is figuring out by itself when to re-render a view and how to do this in the most efficient way. -> -> [Read the full post...](https://blog.mayflower.de/3937-Backbone-React.html) - -## Using facebook's React with require.js - -[Mario Mueller](http://blog.xenji.com/) wrote a menu component in React and was able to easily integrate it with require.js, EventEmitter2 and bower. - -> I recently stumbled upon facebook's React library, which is a JavaScript library for building reusable frontend components. Even if this lib is only at version 0.3.x it behaves very stable, it is fast and is fun to code. I'm a big fan of require.js, so I tried to use React within the require.js eco system. It was not as hard as expected and here are some examples and some thoughts about it. -> -> [Read the full post...](http://blog.xenji.com/2013/06/facebooks-react-require-js.html) - -## Origins of React - -[Pete Hunt](http://www.petehunt.net/blog/) explained what differentiates React from other JavaScript libraries in [a previous blog post](/blog/2013/06/05/why-react.html). [Lee Byron](http://leebyron.com/) gives another perspective on Quora: - -> React isn't quite like any other popular JavaScript libraries, and it solves a very specific problem: complex UI rendering. It's also intended to be used along side many other popular libraries. For example, React works well with Backbone.js, amongst many others. -> -> React was born out of frustrations with the common pattern of writing two-way data bindings in complex MVC apps. React is an implementation of one-way data bindings. -> -> [Read the full post...](https://www.quora.com/React-JS-Library/How-is-Facebooks-React-JavaScript-library/answer/Lee-Byron?srid=3DcX) diff --git a/content/blog/2013-06-19-community-roundup-2.md b/content/blog/2013-06-19-community-roundup-2.md deleted file mode 100644 index 3350d68216a..00000000000 --- a/content/blog/2013-06-19-community-roundup-2.md +++ /dev/null @@ -1,70 +0,0 @@ ---- -title: "Community Round-up #2" -author: [vjeux] ---- - -Since the launch we have received a lot of feedback and are actively working on React 0.4. In the meantime, here are the highlights of this week. - -## Some quick thoughts on React - -[Andrew Greig](http://www.andrewgreig.com/) made a blog post that gives a high level description of what React is. - -> I have been using Facebooks recently released JavaScript framework called React.js for the last few days and have managed to obtain a rather high level understanding of how it works and formed a good perspective on how it fits in to the entire javascript framework ecosystem. -> -> Basically, React is not an MVC framework. It is not a replacement for Backbone or Knockout or Angular, instead it is designed to work with existing frameworks and help extend their functionality. -> -> It is designed for building big UIs. The type where you have lots of reusable components that are handling events and presenting and changing some backend data. In a traditional MVC app, React fulfils the role of the View. So you would still need to handle the Model and Controller on your own. -> -> I found the best way to utilise React was to pair it with Backbone, with React replacing the Backbone View, or to write your own Model/Data object and have React communicate with that. -> -> [Read the full post...](http://www.andrewgreig.com/637/) - -## React and Socket.IO Chat Application - -[Danial Khosravi](https://danialk.github.io/) made a real-time chat application that interacts with the back-end using Socket.IO. - -> A week ago I was playing with AngularJS and [this little chat application](https://github.com/btford/angular-socket-io-im) which uses socket.io and nodejs for realtime communication. Yesterday I saw a post about ReactJS in [EchoJS](http://www.echojs.com/) and started playing with this UI library. After playing a bit with React, I decided to write and chat application using React and I used Bran Ford's Backend for server side of this little app. ->
    -> -> [Read the full post...](https://danialk.github.io/blog/2013/06/16/reactjs-and-socket-dot-io-chat-application/) - -## React and Other Frameworks - -[Pete Hunt](http://www.petehunt.net/blog/) wrote an answer on Quora comparing React and Angular directives. At the end, he explains how you can make an Angular directive that is in fact being rendered with React. - -> To set the record straight: React components are far more powerful than Angular templates; they should be compared with Angular's directives instead. So I took the first Google hit for "AngularJS directive tutorial" (AngularJS Directives Tutorial - Fundoo Solutions), rewrote it in React and compared them. [...] -> -> We've designed React from the beginning to work well with other libraries. Angular is no exception. Let's take the original Angular example and use React to implement the fundoo-rating directive. -> -> [Read the full post...](https://www.quora.com/Pete-Hunt/Posts/Facebooks-React-vs-AngularJS-A-Closer-Look) - -In the same vein, [Markov Twain](https://twitter.com/markov_twain/status/345702941845499906) re-implemented the examples on the front-page [with Ember](http://jsbin.com/azihiw/2/edit) and [Vlad Yazhbin](https://twitter.com/vla) re-implemented the tutorial [with Angular](http://jsfiddle.net/vla/Cdrse/). - -## Web Components: React & x-tags - -Mozilla and Google are actively working on Web Components. [Vjeux](http://blog.vjeux.com/) wrote a proof of concept that shows how to implement them using React. - -> Using [x-tags](http://www.x-tags.org/) from Mozilla, we can write custom tags within the DOM. This is a great opportunity to be able to write reusable components without being tied to a particular library. I wrote [x-react](https://github.com/vjeux/react-xtags/) to have them being rendered in React. ->
    -> -> [Read the full post...](http://blog.vjeux.com/2013/javascript/custom-components-react-x-tags.html) - -## React TodoMVC Example - -[TodoMVC.com](http://todomvc.com/) is a website that collects various implementations of the same basic Todo app. [Pete Hunt](http://www.petehunt.net/blog/) wrote an idiomatic React version. - -> Developers these days are spoiled with choice when it comes to selecting an MV* framework for structuring and organizing their JavaScript web apps. -> -> To help solve this problem, we created TodoMVC - a project which offers the same Todo application implemented using MV* concepts in most of the popular JavaScript MV* frameworks of today. ->
    -> -> [Read the source code...](https://github.com/tastejs/todomvc/tree/gh-pages/labs/architecture-examples/react) - -## JSX is not HTML - -Many of you pointed out differences between JSX and HTML. In order to clear up some confusion, we have added some documentation that covers the four main differences: - - - [Whitespace removal](/docs/jsx-is-not-html.html) - - [HTML Entities](/docs/jsx-is-not-html.html) - - [Comments](/docs/jsx-is-not-html.html) - - [Custom HTML Attributes](/docs/jsx-is-not-html.html) diff --git a/content/blog/2013-06-21-react-v0-3-3.md b/content/blog/2013-06-21-react-v0-3-3.md deleted file mode 100644 index f09bf8a6f10..00000000000 --- a/content/blog/2013-06-21-react-v0-3-3.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -title: "React v0.3.3" -author: [zpao] ---- - -We have a ton of great stuff coming in v0.4, but in the meantime we're releasing v0.3.3. This release addresses some small issues people were having and simplifies our tools to make them easier to use. - - -## react-tools - -* Upgrade Commoner so `require` statements are no longer relativized when passing through the transformer. This was a feature needed when building React, but doesn't translate well for other consumers of `bin/jsx`. -* Upgraded our dependencies on Commoner and Recast so they use a different directory for their cache. -* Freeze our esprima dependency. - - -## React - -* Allow reusing the same DOM node to render different components. e.g. `React.renderComponent(
    , domNode); React.renderComponent(, domNode);` will work now. - - -## JSXTransformer - -* Improved the in-browser transformer so that transformed scripts will execute in the expected scope. The allows components to be defined and used from separate files. diff --git a/content/blog/2013-06-27-community-roundup-3.md b/content/blog/2013-06-27-community-roundup-3.md deleted file mode 100644 index 69041ea09c9..00000000000 --- a/content/blog/2013-06-27-community-roundup-3.md +++ /dev/null @@ -1,90 +0,0 @@ ---- -title: "Community Round-up #3" -author: [vjeux] ---- - -The highlight of this week is that an interaction-heavy app has been ported to React. React components are solving issues they had with nested views. - -## Moving From Backbone To React - -[Clay Allsopp](https://twitter.com/clayallsopp) successfully ported [Propeller](http://usepropeller.com/blog/posts/from-backbone-to-react/), a fairly big, interaction-heavy JavaScript app, to React. - -> [](http://usepropeller.com/blog/posts/from-backbone-to-react/)Subviews involve a lot of easy-to-forget boilerplate that Backbone (by design) doesn't automate. Libraries like Backbone.Marionette offer more abstractions to make view nesting easier, but they're all limited by the fact that Backbone delegates how and went view-document attachment occurs to the application code. -> -> React, on the other hand, manages the DOM and only exposes real nodes at select points in its API. The "elements" you code in React are actually objects which wrap DOM nodes, not the actual objects which get inserted into the DOM. Internally, React converts those abstractions into actual DOMElements and fills out the document accordingly. [...] -> -> We moved about 20 different Backbone view classes to React over the past few weeks, including the live-preview pane that you see in our little iOS demo. Most importantly, it's allowed us to put energy into making each component work great on its own, instead of spending extra cycles to ensure they function in unison. For that reason, we think React is a more scalable way to build view-intensive apps than Backbone alone, and it doesn't require you to drop-everything-and-refactor like a move to Ember or Angular would demand. -> -> [Read the full post...](http://usepropeller.com/blog/posts/from-backbone-to-react/) - -## Grunt Task for JSX - -[Eric Clemmons](https://ericclemmons.github.io/) wrote a task for [Grunt](http://gruntjs.com/) that applies the JSX transformation to your JavaScript files. It also works with [Browserify](http://browserify.org/) if you want all your files to be concatenated and minified together. - -> Grunt task for compiling Facebook React's .jsx templates into .js -> -> ```javascript -> grunt.initConfig({ -> react: { -> app: { -> options: { extension: 'js' }, -> files: { 'path/to/output/dir': 'path/to/jsx/templates/dir' } -> ``` -> -> It also works great with `grunt-browserify`! -> -> ```javascript -> browserify: { -> options: { -> transform: [ require('grunt-react').browserify ] -> }, -> app: { -> src: 'path/to/source/main.js', -> dest: 'path/to/target/output.js' -> ``` -> -> [Check out the project ...](https://github.com/ericclemmons/grunt-react) - -## Backbone/Handlebars Nested Views - -[Joel Burget](http://joelburget.com/) wrote a blog post talking about the way we would write React-like components in Backbone and Handlebars. - -> The problem here is that we're trying to maniplate a tree, but there's a textual layer we have to go through. Our views are represented as a tree - the subviews are children of CommentCollectionView - and they end up as part of a tree in the DOM. But there's a Handlebars layer in the middle (which deals in flat strings), so the hierarchy must be destructed and rebuilt when we render. -> -> What does it take to render a collection view? In the Backbone/Handlebars view of the world you have to render the template (with stubs), render each subview which replaces a stub, and keep a reference to each subview (or anything within the view that could change in the future). -> -> So while our view is conceptually hierarchical, due to the fact that it has to go through a flat textual representation, we need to do a lot of extra work to reassemble that structure after rendering. -> -> [Read the full post...](http://joelburget.com/react/) - -## JSRomandie Meetup - -[Renault John Lecoultre](https://twitter.com/renajohn/) from [BugBuster](http://www.bugbuster.com) did a React introduction talk at a JS meetup called [JS Romandie](https://twitter.com/jsromandie) last week. - - - -## CoffeeScript integration - -[Vjeux](http://blog.vjeux.com/) used the fact that JSX is just a syntactic sugar on-top of regular JS to rewrite the React front-page examples in CoffeeScript. - -> Multiple people asked what's the story about JSX and CoffeeScript. There is no JSX pre-processor for CoffeeScript and I'm not aware of anyone working on it. Fortunately, CoffeeScript is pretty expressive and we can play around the syntax to come up with something that is usable. -> -> ```javascript -> {div, h3, textarea} = React.DOM -> (div {className: 'MarkdownEditor'}, [ -> (h3 {}, 'Input'), -> (textarea {onKeyUp: @handleKeyUp, ref: 'textarea'}, -> @state.value -> ) -> ]) -> ``` -> -> [Read the full post...](http://blog.vjeux.com/2013/javascript/react-coffeescript.html) - -## Tutorial in Plain JavaScript - -We've seen a lot of people comparing React with various frameworks. [Ricardo Tomasi](http://ricardo.cc/) decided to re-implement the tutorial without any framework, just plain JavaScript. - -> Facebook & Instagram launched the React framework and an accompanying tutorial. Developer Vlad Yazhbin decided to rewrite that using AngularJS. The end result is pretty neat, but if you're like me you will not actually appreciate the HTML speaking for itself and doing all the hard work. So let's see what that looks like in plain javascript. -> -> [Read the full post...](http://ricardo.cc/2013/06/07/react-tutorial-rewritten-in-plain-javascript.html) diff --git a/content/blog/2013-07-02-react-v0-4-autobind-by-default.md b/content/blog/2013-07-02-react-v0-4-autobind-by-default.md deleted file mode 100644 index c8e5155ff96..00000000000 --- a/content/blog/2013-07-02-react-v0-4-autobind-by-default.md +++ /dev/null @@ -1,51 +0,0 @@ ---- -title: "New in React v0.4: Autobind by Default" -author: [zpao] ---- - -React v0.4 is very close to completion. As we finish it off, we'd like to share with you some of the major changes we've made since v0.3. This is the first of several posts we'll be making over the next week. - - -## What is React.autoBind? - -If you take a look at most of our current examples, you'll see us using `React.autoBind` for event handlers. This is used in place of `Function.prototype.bind`. Remember that in JS, [function calls are late-bound](https://bonsaiden.github.io/JavaScript-Garden/#function.this). That means that if you simply pass a function around, the `this` used inside won't necessarily be the `this` you expect. `Function.prototype.bind` creates a new, properly bound, function so that when called, `this` is exactly what you expect it to be. - -Before we launched React, we would write this: - -```js{4} -React.createClass({ - onClick: function(event) {/* do something with this */}, - render: function() { - return + + + +

    That's right!

    + + +``` + + + +Manipulating the UI imperatively works well enough for isolated examples, but it gets exponentially more difficult to manage in more complex systems. Imagine updating a page full of different forms like this one. Adding a new UI element or a new interaction would require carefully checking all existing code to make sure you haven't introduced a bug (for example, forgetting to show or hide something). + +React was built to solve this problem. + +In React, you don't directly manipulate the UI--meaning you don't enable, disable, show, or hide components directly. Instead, you **declare what you want to show,** and React figures out how to update the UI. Think of getting into a taxi and telling the driver where you want to go instead of telling them exactly where to turn. It's the driver's job to get you there, and they might even know some shortcuts you haven't considered! + + + +## Thinking about UI declaratively {/*thinking-about-ui-declaratively*/} + +You've seen how to implement a form imperatively above. To better understand how to think in React, you'll walk through reimplementing this UI in React below: + +1. **Identify** your component's different visual states +2. **Determine** what triggers those state changes +3. **Represent** the state in memory using `useState` +4. **Remove** any non-essential state variables +5. **Connect** the event handlers to set the state + +### Step 1: Identify your component's different visual states {/*step-1-identify-your-components-different-visual-states*/} + +In computer science, you may hear about a ["state machine"](https://en.wikipedia.org/wiki/Finite-state_machine) being in one of several “states”. If you work with a designer, you may have seen mockups for different "visual states". React stands at the intersection of design and computer science, so both of these ideas are sources of inspiration. + +First, you need to visualize all the different "states" of the UI the user might see: + +* **Empty**: Form has a disabled "Submit" button. +* **Typing**: Form has an enabled "Submit" button. +* **Submitting**: Form is completely disabled. Spinner is shown. +* **Success**: "Thank you" message is shown instead of a form. +* **Error**: Same as Typing state, but with an extra error message. + +Just like a designer, you'll want to "mock up" or create "mocks" for the different states before you add logic. For example, here is a mock for just the visual part of the form. This mock is controlled by a prop called `status` with a default value of `'empty'`: + + + +```js +export default function Form({ + status = 'empty' +}) { + if (status === 'success') { + return

    That's right!

    + } + return ( + <> +

    City quiz

    +

    + In which city is there a billboard that turns air into drinkable water? +

    +
    + ` is not allowed. [Use `defaultValue` for initial content.](#providing-an-initial-value-for-a-text-area) +- If a text area receives a string `value` prop, it will be [treated as controlled.](#controlling-a-text-area-with-a-state-variable) +- A text area can't be both controlled and uncontrolled at the same time. +- A text area cannot switch between being controlled or uncontrolled over its lifetime. +- Every controlled text area needs an `onChange` event handler that synchronously updates its backing value. + +--- + +## Usage {/*usage*/} + +### Displaying a text area {/*displaying-a-text-area*/} + +Render `` is not supported. + + + +--- + +### Reading the text area value when submitting a form {/*reading-the-text-area-value-when-submitting-a-form*/} + +Add a [``](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/form) around your textarea with a [`