diff --git a/package.json b/package.json
index 918d42fa20..c1cd16741a 100644
--- a/package.json
+++ b/package.json
@@ -15,12 +15,13 @@
     "prettier:diff": "yarn nit:source",
     "lint-heading-ids": "node scripts/headingIdLinter.js",
     "fix-headings": "node scripts/headingIdLinter.js --fix",
-    "ci-check": "npm-run-all prettier:diff --parallel lint tsc lint-heading-ids rss",
+    "ci-check": "npm-run-all prettier:diff --parallel lint tsc lint-heading-ids rss deadlinks",
     "tsc": "tsc --noEmit",
     "start": "next start",
     "postinstall": "is-ci || husky install .husky",
     "check-all": "npm-run-all prettier lint:fix tsc rss",
-    "rss": "node scripts/generateRss.js"
+    "rss": "node scripts/generateRss.js",
+    "deadlinks": "node scripts/deadLinkChecker.js"
   },
   "dependencies": {
     "@codesandbox/sandpack-react": "2.13.5",
@@ -61,6 +62,7 @@
     "autoprefixer": "^10.4.2",
     "babel-eslint": "10.x",
     "babel-plugin-react-compiler": "19.0.0-beta-e552027-20250112",
+    "chalk": "4.1.2",
     "eslint": "7.x",
     "eslint-config-next": "12.0.3",
     "eslint-config-react-app": "^5.2.1",
diff --git a/scripts/deadLinkChecker.js b/scripts/deadLinkChecker.js
new file mode 100644
index 0000000000..90593b878a
--- /dev/null
+++ b/scripts/deadLinkChecker.js
@@ -0,0 +1,385 @@
+#!/usr/bin/env node
+
+const fs = require('fs');
+const path = require('path');
+const globby = require('globby');
+const chalk = require('chalk');
+
+const CONTENT_DIR = path.join(__dirname, '../src/content');
+const PUBLIC_DIR = path.join(__dirname, '../public');
+const fileCache = new Map();
+const anchorMap = new Map(); // Map<filepath, Set<anchorId>>
+const contributorMap = new Map(); // Map<anchorId, URL>
+const redirectMap = new Map(); // Map<source, destination>
+let errorCodes = new Set();
+
+async function readFileWithCache(filePath) {
+  if (!fileCache.has(filePath)) {
+    try {
+      const content = await fs.promises.readFile(filePath, 'utf8');
+      fileCache.set(filePath, content);
+    } catch (error) {
+      throw new Error(`Failed to read file ${filePath}: ${error.message}`);
+    }
+  }
+  return fileCache.get(filePath);
+}
+
+async function fileExists(filePath) {
+  try {
+    await fs.promises.access(filePath, fs.constants.R_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function getMarkdownFiles() {
+  // Convert Windows paths to POSIX for globby compatibility
+  const baseDir = CONTENT_DIR.replace(/\\/g, '/');
+  const patterns = [
+    path.posix.join(baseDir, '**/*.md'),
+    path.posix.join(baseDir, '**/*.mdx'),
+  ];
+  return globby.sync(patterns);
+}
+
+function extractAnchorsFromContent(content) {
+  const anchors = new Set();
+
+  // MDX-style heading IDs: {/*anchor-id*/}
+  const mdxPattern = /\{\/\*([a-zA-Z0-9-_]+)\*\/\}/g;
+  let match;
+  while ((match = mdxPattern.exec(content)) !== null) {
+    anchors.add(match[1].toLowerCase());
+  }
+
+  // HTML id attributes
+  const htmlIdPattern = /\sid=["']([a-zA-Z0-9-_]+)["']/g;
+  while ((match = htmlIdPattern.exec(content)) !== null) {
+    anchors.add(match[1].toLowerCase());
+  }
+
+  // Markdown heading with explicit ID: ## Heading {#anchor-id}
+  const markdownHeadingPattern = /^#+\s+.*\{#([a-zA-Z0-9-_]+)\}/gm;
+  while ((match = markdownHeadingPattern.exec(content)) !== null) {
+    anchors.add(match[1].toLowerCase());
+  }
+
+  return anchors;
+}
+
+async function buildAnchorMap(files) {
+  for (const filePath of files) {
+    const content = await readFileWithCache(filePath);
+    const anchors = extractAnchorsFromContent(content);
+    if (anchors.size > 0) {
+      anchorMap.set(filePath, anchors);
+    }
+  }
+}
+
+function extractLinksFromContent(content) {
+  const linkPattern = /\[([^\]]*)\]\(([^)]+)\)/g;
+  const links = [];
+  let match;
+
+  while ((match = linkPattern.exec(content)) !== null) {
+    const [, linkText, linkUrl] = match;
+    if (linkUrl.startsWith('/') && !linkUrl.startsWith('//')) {
+      const lines = content.substring(0, match.index).split('\n');
+      const line = lines.length;
+      const lastLineStart =
+        lines.length > 1 ? content.lastIndexOf('\n', match.index - 1) + 1 : 0;
+      const column = match.index - lastLineStart + 1;
+
+      links.push({
+        text: linkText,
+        url: linkUrl,
+        line,
+        column,
+      });
+    }
+  }
+
+  return links;
+}
+
+async function findTargetFile(urlPath) {
+  // Check if it's an image or static asset that might be in the public directory
+  const imageExtensions = [
+    '.png',
+    '.jpg',
+    '.jpeg',
+    '.gif',
+    '.svg',
+    '.ico',
+    '.webp',
+  ];
+  const hasImageExtension = imageExtensions.some((ext) =>
+    urlPath.toLowerCase().endsWith(ext)
+  );
+
+  if (hasImageExtension || urlPath.includes('.')) {
+    // Check in public directory (with and without leading slash)
+    const publicPaths = [
+      path.join(PUBLIC_DIR, urlPath),
+      path.join(PUBLIC_DIR, urlPath.substring(1)),
+    ];
+
+    for (const p of publicPaths) {
+      if (await fileExists(p)) {
+        return p;
+      }
+    }
+  }
+
+  const possiblePaths = [
+    path.join(CONTENT_DIR, urlPath + '.md'),
+    path.join(CONTENT_DIR, urlPath + '.mdx'),
+    path.join(CONTENT_DIR, urlPath, 'index.md'),
+    path.join(CONTENT_DIR, urlPath, 'index.mdx'),
+    // Without leading slash
+    path.join(CONTENT_DIR, urlPath.substring(1) + '.md'),
+    path.join(CONTENT_DIR, urlPath.substring(1) + '.mdx'),
+    path.join(CONTENT_DIR, urlPath.substring(1), 'index.md'),
+    path.join(CONTENT_DIR, urlPath.substring(1), 'index.mdx'),
+  ];
+
+  for (const p of possiblePaths) {
+    if (await fileExists(p)) {
+      return p;
+    }
+  }
+  return null;
+}
+
+async function validateLink(link) {
+  const urlAnchorPattern = /#([a-zA-Z0-9-_]+)$/;
+  const anchorMatch = link.url.match(urlAnchorPattern);
+  const urlWithoutAnchor = link.url.replace(urlAnchorPattern, '');
+
+  if (urlWithoutAnchor === '/') {
+    return {valid: true};
+  }
+
+  // Check for redirects
+  if (redirectMap.has(urlWithoutAnchor)) {
+    const redirectDestination = redirectMap.get(urlWithoutAnchor);
+    if (
+      redirectDestination.startsWith('http://') ||
+      redirectDestination.startsWith('https://')
+    ) {
+      return {valid: true};
+    }
+    const redirectedLink = {
+      ...link,
+      url: redirectDestination + (anchorMatch ? anchorMatch[0] : ''),
+    };
+    return validateLink(redirectedLink);
+  }
+
+  // Check if it's an error code link
+  const errorCodeMatch = urlWithoutAnchor.match(/^\/errors\/(\d+)$/);
+  if (errorCodeMatch) {
+    const code = errorCodeMatch[1];
+    if (!errorCodes.has(code)) {
+      return {
+        valid: false,
+        reason: `Error code ${code} not found in React error codes`,
+      };
+    }
+    return {valid: true};
+  }
+
+  // Check if it's a contributor link on the team or acknowledgements page
+  if (
+    anchorMatch &&
+    (urlWithoutAnchor === '/community/team' ||
+      urlWithoutAnchor === '/community/acknowledgements')
+  ) {
+    const anchorId = anchorMatch[1].toLowerCase();
+    if (contributorMap.has(anchorId)) {
+      const correctUrl = contributorMap.get(anchorId);
+      if (correctUrl !== link.url) {
+        return {
+          valid: false,
+          reason: `Contributor link should be updated to: ${correctUrl}`,
+        };
+      }
+      return {valid: true};
+    } else {
+      return {
+        valid: false,
+        reason: `Contributor link not found`,
+      };
+    }
+  }
+
+  const targetFile = await findTargetFile(urlWithoutAnchor);
+
+  if (!targetFile) {
+    return {
+      valid: false,
+      reason: `Target file not found for: ${urlWithoutAnchor}`,
+    };
+  }
+
+  // Only check anchors for content files, not static assets
+  if (anchorMatch && targetFile.startsWith(CONTENT_DIR)) {
+    const anchorId = anchorMatch[1].toLowerCase();
+
+    // TODO handle more special cases. These are usually from custom MDX components that include
+    // a Heading from src/components/MDX/Heading.tsx which automatically injects an anchor tag.
+    switch (anchorId) {
+      case 'challenges':
+      case 'recap': {
+        return {valid: true};
+      }
+    }
+
+    const fileAnchors = anchorMap.get(targetFile);
+
+    if (!fileAnchors || !fileAnchors.has(anchorId)) {
+      return {
+        valid: false,
+        reason: `Anchor #${anchorMatch[1]} not found in ${path.relative(
+          CONTENT_DIR,
+          targetFile
+        )}`,
+      };
+    }
+  }
+
+  return {valid: true};
+}
+
+async function processFile(filePath) {
+  const content = await readFileWithCache(filePath);
+  const links = extractLinksFromContent(content);
+  const deadLinks = [];
+
+  for (const link of links) {
+    const result = await validateLink(link);
+    if (!result.valid) {
+      deadLinks.push({
+        file: path.relative(process.cwd(), filePath),
+        line: link.line,
+        column: link.column,
+        text: link.text,
+        url: link.url,
+        reason: result.reason,
+      });
+    }
+  }
+
+  return {deadLinks, totalLinks: links.length};
+}
+
+async function buildContributorMap() {
+  const teamFile = path.join(CONTENT_DIR, 'community/team.md');
+  const teamContent = await readFileWithCache(teamFile);
+
+  const teamMemberPattern = /<TeamMember[^>]*permalink=["']([^"']+)["']/g;
+  let match;
+
+  while ((match = teamMemberPattern.exec(teamContent)) !== null) {
+    const permalink = match[1];
+    contributorMap.set(permalink, `/community/team#${permalink}`);
+  }
+
+  const ackFile = path.join(CONTENT_DIR, 'community/acknowledgements.md');
+  const ackContent = await readFileWithCache(ackFile);
+  const contributorPattern = /\*\s*\[([^\]]+)\]\(([^)]+)\)/g;
+
+  while ((match = contributorPattern.exec(ackContent)) !== null) {
+    const name = match[1];
+    const url = match[2];
+    const hyphenatedName = name.toLowerCase().replace(/\s+/g, '-');
+    if (!contributorMap.has(hyphenatedName)) {
+      contributorMap.set(hyphenatedName, url);
+    }
+  }
+}
+
+async function fetchErrorCodes() {
+  try {
+    const response = await fetch(
+      'https://raw.githubusercontent.com/facebook/react/main/scripts/error-codes/codes.json'
+    );
+    if (!response.ok) {
+      throw new Error(`Failed to fetch error codes: ${response.status}`);
+    }
+    const codes = await response.json();
+    errorCodes = new Set(Object.keys(codes));
+    console.log(chalk.gray(`Fetched ${errorCodes.size} React error codes`));
+  } catch (error) {
+    throw new Error(`Failed to fetch error codes: ${error.message}`);
+  }
+}
+
+async function buildRedirectsMap() {
+  try {
+    const vercelConfigPath = path.join(__dirname, '../vercel.json');
+    const vercelConfig = JSON.parse(
+      await fs.promises.readFile(vercelConfigPath, 'utf8')
+    );
+
+    if (vercelConfig.redirects) {
+      for (const redirect of vercelConfig.redirects) {
+        redirectMap.set(redirect.source, redirect.destination);
+      }
+      console.log(
+        chalk.gray(`Loaded ${redirectMap.size} redirects from vercel.json`)
+      );
+    }
+  } catch (error) {
+    console.log(
+      chalk.yellow(
+        `Warning: Could not load redirects from vercel.json: ${error.message}\n`
+      )
+    );
+  }
+}
+
+async function main() {
+  const files = getMarkdownFiles();
+  console.log(chalk.gray(`Checking ${files.length} markdown files...`));
+
+  await fetchErrorCodes();
+  await buildRedirectsMap();
+  await buildContributorMap();
+  await buildAnchorMap(files);
+
+  const filePromises = files.map((filePath) => processFile(filePath));
+  const results = await Promise.all(filePromises);
+  const deadLinks = results.flatMap((r) => r.deadLinks);
+  const totalLinks = results.reduce((sum, r) => sum + r.totalLinks, 0);
+
+  if (deadLinks.length > 0) {
+    console.log('\n');
+    for (const link of deadLinks) {
+      console.log(chalk.yellow(`${link.file}:${link.line}:${link.column}`));
+      console.log(chalk.reset(`  Link text: ${link.text}`));
+      console.log(chalk.reset(`  URL: ${link.url}`));
+      console.log(`  ${chalk.red('✗')} ${chalk.red(link.reason)}\n`);
+    }
+
+    console.log(
+      chalk.red(
+        `\nFound ${deadLinks.length} dead link${
+          deadLinks.length > 1 ? 's' : ''
+        } out of ${totalLinks} total links\n`
+      )
+    );
+    process.exit(1);
+  }
+
+  console.log(chalk.green(`\n✓ All ${totalLinks} links are valid!\n`));
+  process.exit(0);
+}
+
+main().catch((error) => {
+  console.log(chalk.red(`Error: ${error.message}`));
+  process.exit(1);
+});
diff --git a/src/content/blog/2024/02/15/react-labs-what-we-have-been-working-on-february-2024.md b/src/content/blog/2024/02/15/react-labs-what-we-have-been-working-on-february-2024.md
index 6b75e59f63..864160a616 100644
--- a/src/content/blog/2024/02/15/react-labs-what-we-have-been-working-on-february-2024.md
+++ b/src/content/blog/2024/02/15/react-labs-what-we-have-been-working-on-february-2024.md
@@ -107,7 +107,7 @@ Activity 仍处于研究阶段，我们剩下的工作是最终确定向库开
 
 除了此更新之外，我们的团队还在会议上发表了演讲并在播客中露面，更多地讲述我们的工作并回答问题。
 
-- [Sathya Gunasekaran](/community/team#sathya-gunasekaran) 在 [React India](https://www.youtube.com/watch?v=kjOacmVsLSE) 大会上介绍了 React 编译器。
+- [Sathya Gunasekaran](https://github.com/gsathya) 在 [React India](https://www.youtube.com/watch?v=kjOacmVsLSE) 大会上介绍了 React 编译器。
 
 - [Dan Abramov](/community/team#dan-abramov) 在 [RemixConf](https://www.youtube.com/watch?v=zMf_xeGPn6s) 上发表了名为“React from Another Dimension”的演讲，探讨了 React 服务器组件与 Action 可能是如何创建的另一种历史。
 
diff --git a/src/content/blog/2024/10/21/react-compiler-beta-release.md b/src/content/blog/2024/10/21/react-compiler-beta-release.md
index 04f77ab3ae..6ef13a3399 100644
--- a/src/content/blog/2024/10/21/react-compiler-beta-release.md
+++ b/src/content/blog/2024/10/21/react-compiler-beta-release.md
@@ -72,11 +72,11 @@ npm install -D eslint-plugin-react-compiler@beta
 yarn add -D eslint-plugin-react-compiler@beta
 </TerminalBlock>
 
-安装后你可以通过[将其添加到 ESLint 配置](/learn/react-compiler#installing-eslint-plugin-react-compiler) 来启用 linter。使用 linter 有助于发现破坏 React 规则的地方，从而在编译器完全发布后更容易采用它。
+安装后你可以通过[将其添加到 ESLint 配置](/learn/react-compiler/installation#eslint-integration) 来启用 linter。使用 linter 有助于发现破坏 React 规则的地方，从而在编译器完全发布后更容易采用它。
 
 ## 向后兼容性 {/*backwards-compatibility*/}
 
-React Compiler 生成的代码依赖于 React 19 中添加的运行时 API，但我们后来添加了对 React 17 和 18 的支持。如果你还没有使用 React 19，在 Beta 版本中可以通过在 compiler 配置中设置 `target` 来使用 React Compiler，并添加 `react-compiler-runtime` 作为依赖项。[你可以在这里找到相关文档](/learn/react-compiler#using-react-compiler-with-react-17-or-18)。
+React Compiler 生成的代码依赖于 React 19 中添加的运行时 API，但我们后来添加了对 React 17 和 18 的支持。如果你还没有使用 React 19，在 Beta 版本中可以通过在 compiler 配置中设置 `target` 来使用 React Compiler，并添加 `react-compiler-runtime` 作为依赖项。[你可以在这里找到相关文档](/reference/react-compiler/configuration#react-17-18)。
 
 ## 在库中使用 React Compiler {/*using-react-compiler-in-libraries*/}
 
@@ -86,7 +86,7 @@ React Compiler 还可以用来编译库。由于 React Compiler 需要在代码
 
 由于库的代码是预编译的，因此用户无需启用 Compiler 即可从编译器的自动记忆化中受益。如果库的 target 不是 React 19，请指定一个最小的 [`target` 并且将 `react-compiler-runtime` 添加为直接依赖](#using-react-compiler-with-react-17-or-18)。这个运行时包将根据应用程序的版本使用正确的 API 实现，并在必要时填充缺失的 API。
 
-[你可以在此处找到更多相关文档。](/learn/react-compiler#using-the-compiler-on-libraries)
+[你可以在此处找到更多相关文档。](/reference/react-compiler/compiling-libraries)
 
 ## 向所有人开放 React Compiler 工作组 {/*opening-up-react-compiler-working-group-to-everyone*/}
 
diff --git a/src/content/blog/2025/04/23/react-labs-view-transitions-activity-and-more.md b/src/content/blog/2025/04/23/react-labs-view-transitions-activity-and-more.md
index 80fb35a1c3..9f5a00318e 100644
--- a/src/content/blog/2025/04/23/react-labs-view-transitions-activity-and-more.md
+++ b/src/content/blog/2025/04/23/react-labs-view-transitions-activity-and-more.md
@@ -2495,7 +2495,7 @@ root.render(
 </ViewTransition>
 ```
 
-并使用[视图过渡类](/reference/react/ViewTransition#view-transition-classes)在 CSS 中定义 `slow-fade`：
+并使用[视图过渡类](/reference/react/ViewTransition#view-transition-class)在 CSS 中定义 `slow-fade`：
 
 ```css
 ::view-transition-old(.slow-fade) {
diff --git a/src/content/learn/add-react-to-an-existing-project.md b/src/content/learn/add-react-to-an-existing-project.md
index 6708659ebb..3cbac49084 100644
--- a/src/content/learn/add-react-to-an-existing-project.md
+++ b/src/content/learn/add-react-to-an-existing-project.md
@@ -24,7 +24,7 @@ title: 将 React 添加到现有项目中
 2. **在框架配置中将 `/some-app` 指定为基本路径**（这里有 [Next.js](https://nextjs.org/docs/app/api-reference/config/next-config-js/basePath) 与 [Gatsby](https://www.gatsbyjs.com/docs/how-to/previews-deploys-hosting/path-prefix/) 的配置样例）。
 3. **配置服务器或代理**，以便所有位于 `/some-app/` 下的请求都由 React 应用处理。
 
-这可以确保应用的 React 部分可以受益于这些框架中内置的 [最佳实践](/learn/start-a-new-react-project#can-i-use-react-without-a-framework)。
+这可以确保应用的 React 部分可以受益于这些框架中内置的 [最佳实践](/learn/build-a-react-app-from-scratch#consider-using-a-framework)。
 
 许多基于 React 的框架都是全栈的，从而可以让你的 React 应用充分利用服务器。但是，即使无法或不想在服务器上运行 JavaScript，也可以使用相同的方法。在这种情况下，将 HTML/CSS/JS 导出（Next.js 的 [`next export` output](https://nextjs.org/docs/advanced-features/static-html-export)，Gatsby 的 default）替换为 `/some-app/`。
 
diff --git a/src/content/learn/react-compiler/debugging.md b/src/content/learn/react-compiler/debugging.md
new file mode 100644
index 0000000000..1883125a6a
--- /dev/null
+++ b/src/content/learn/react-compiler/debugging.md
@@ -0,0 +1,93 @@
+---
+title: Debugging and Troubleshooting
+---
+
+<Intro>
+This guide helps you identify and fix issues when using React Compiler. Learn how to debug compilation problems and resolve common issues.
+</Intro>
+
+<YouWillLearn>
+
+* The difference between compiler errors and runtime issues
+* Common patterns that break compilation
+* Step-by-step debugging workflow
+
+</YouWillLearn>
+
+## Understanding Compiler Behavior {/*understanding-compiler-behavior*/}
+
+React Compiler is designed to handle code that follows the [Rules of React](/reference/rules). When it encounters code that might break these rules, it safely skips optimization rather than risk changing your app's behavior.
+
+### Compiler Errors vs Runtime Issues {/*compiler-errors-vs-runtime-issues*/}
+
+**Compiler errors** occur at build time and prevent your code from compiling. These are rare because the compiler is designed to skip problematic code rather than fail.
+
+**Runtime issues** occur when compiled code behaves differently than expected. Most of the time, if you encounter an issue with React Compiler, it's a runtime issue. This typically happens when your code violates the Rules of React in subtle ways that the compiler couldn't detect, and the compiler mistakenly compiled a component it should have skipped.
+
+When debugging runtime issues, focus your efforts on finding Rules of React violations in the affected components that were not detected by the ESLint rule. The compiler relies on your code following these rules, and when they're broken in ways it can't detect, that's when runtime problems occur.
+
+
+## Common Breaking Patterns {/*common-breaking-patterns*/}
+
+One of the main ways React Compiler can break your app is if your code was written to rely on memoization for correctness. This means your app depends on specific values being memoized to work properly. Since the compiler may memoize differently than your manual approach, this can lead to unexpected behavior like effects over-firing, infinite loops, or missing updates.
+
+Common scenarios where this occurs:
+
+- **Effects that rely on referential equality** - When effects depend on objects or arrays maintaining the same reference across renders
+- **Dependency arrays that need stable references** - When unstable dependencies cause effects to fire too often or create infinite loops
+- **Conditional logic based on reference checks** - When code uses referential equality checks for caching or optimization
+
+## Debugging Workflow {/*debugging-workflow*/}
+
+Follow these steps when you encounter issues:
+
+### Compiler Build Errors {/*compiler-build-errors*/}
+
+If you encounter a compiler error that unexpectedly breaks your build, this is likely a bug in the compiler. Report it to the [facebook/react](https://github.com/facebook/react/issues) repository with:
+- The error message
+- The code that caused the error
+- Your React and compiler versions
+
+### Runtime Issues {/*runtime-issues*/}
+
+For runtime behavior issues:
+
+### 1. Temporarily Disable Compilation {/*temporarily-disable-compilation*/}
+
+Use `"use no memo"` to isolate whether an issue is compiler-related:
+
+```js
+function ProblematicComponent() {
+  "use no memo"; // Skip compilation for this component
+  // ... rest of component
+}
+```
+
+If the issue disappears, it's likely related to a Rules of React violation.
+
+You can also try removing manual memoization (useMemo, useCallback, memo) from the problematic component to verify that your app works correctly without any memoization. If the bug still occurs when all memoization is removed, you have a Rules of React violation that needs to be fixed.
+
+### 2. Fix Issues Step by Step {/*fix-issues-step-by-step*/}
+
+1. Identify the root cause (often memoization-for-correctness)
+2. Test after each fix
+3. Remove `"use no memo"` once fixed
+4. Verify the component shows the ✨ badge in React DevTools
+
+## Reporting Compiler Bugs {/*reporting-compiler-bugs*/}
+
+If you believe you've found a compiler bug:
+
+1. **Verify it's not a Rules of React violation** - Check with ESLint
+2. **Create a minimal reproduction** - Isolate the issue in a small example
+3. **Test without the compiler** - Confirm the issue only occurs with compilation
+4. **File an [issue](https://github.com/facebook/react/issues/new?template=compiler_bug_report.yml)**:
+   - React and compiler versions
+   - Minimal reproduction code
+   - Expected vs actual behavior
+   - Any error messages
+
+## Next Steps {/*next-steps*/}
+
+- Review the [Rules of React](/reference/rules) to prevent issues
+- Check the [incremental adoption guide](/learn/react-compiler/incremental-adoption) for gradual rollout strategies
\ No newline at end of file
diff --git a/src/content/learn/react-compiler/incremental-adoption.md b/src/content/learn/react-compiler/incremental-adoption.md
new file mode 100644
index 0000000000..56d9320346
--- /dev/null
+++ b/src/content/learn/react-compiler/incremental-adoption.md
@@ -0,0 +1,225 @@
+---
+title: Incremental Adoption
+---
+
+<Intro>
+React Compiler can be adopted incrementally, allowing you to try it on specific parts of your codebase first. This guide shows you how to gradually roll out the compiler in existing projects.
+</Intro>
+
+<YouWillLearn>
+
+* Why incremental adoption is recommended
+* Using Babel overrides for directory-based adoption
+* Using the "use memo" directive for opt-in compilation
+* Using the "use no memo" directive to exclude components
+* Runtime feature flags with gating
+* Monitoring your adoption progress
+
+</YouWillLearn>
+
+## Why Incremental Adoption? {/*why-incremental-adoption*/}
+
+React Compiler is designed to optimize your entire codebase automatically, but you don't have to adopt it all at once. Incremental adoption gives you control over the rollout process, letting you test the compiler on small parts of your app before expanding to the rest.
+
+Starting small helps you build confidence in the compiler's optimizations. You can verify that your app behaves correctly with compiled code, measure performance improvements, and identify any edge cases specific to your codebase. This approach is especially valuable for production applications where stability is critical.
+
+Incremental adoption also makes it easier to address any Rules of React violations the compiler might find. Instead of fixing violations across your entire codebase at once, you can tackle them systematically as you expand compiler coverage. This keeps the migration manageable and reduces the risk of introducing bugs.
+
+By controlling which parts of your code get compiled, you can also run A/B tests to measure the real-world impact of the compiler's optimizations. This data helps you make informed decisions about full adoption and demonstrates the value to your team.
+
+## Approaches to Incremental Adoption {/*approaches-to-incremental-adoption*/}
+
+There are three main approaches to adopt React Compiler incrementally:
+
+1. **Babel overrides** - Apply the compiler to specific directories
+2. **Opt-in with "use memo"** - Only compile components that explicitly opt in
+3. **Runtime gating** - Control compilation with feature flags
+
+All approaches allow you to test the compiler on specific parts of your application before full rollout.
+
+## Directory-Based Adoption with Babel Overrides {/*directory-based-adoption*/}
+
+Babel's `overrides` option lets you apply different plugins to different parts of your codebase. This is ideal for gradually adopting React Compiler directory by directory.
+
+### Basic Configuration {/*basic-configuration*/}
+
+Start by applying the compiler to a specific directory:
+
+```js
+// babel.config.js
+module.exports = {
+  plugins: [
+    // Global plugins that apply to all files
+  ],
+  overrides: [
+    {
+      test: './src/modern/**/*.{js,jsx,ts,tsx}',
+      plugins: [
+        'babel-plugin-react-compiler'
+      ]
+    }
+  ]
+};
+```
+
+### Expanding Coverage {/*expanding-coverage*/}
+
+As you gain confidence, add more directories:
+
+```js
+// babel.config.js
+module.exports = {
+  plugins: [
+    // Global plugins
+  ],
+  overrides: [
+    {
+      test: ['./src/modern/**/*.{js,jsx,ts,tsx}', './src/features/**/*.{js,jsx,ts,tsx}'],
+      plugins: [
+        'babel-plugin-react-compiler'
+      ]
+    },
+    {
+      test: './src/legacy/**/*.{js,jsx,ts,tsx}',
+      plugins: [
+        // Different plugins for legacy code
+      ]
+    }
+  ]
+};
+```
+
+### With Compiler Options {/*with-compiler-options*/}
+
+You can also configure compiler options per override:
+
+```js
+// babel.config.js
+module.exports = {
+  plugins: [],
+  overrides: [
+    {
+      test: './src/experimental/**/*.{js,jsx,ts,tsx}',
+      plugins: [
+        ['babel-plugin-react-compiler', {
+          // options ...
+        }]
+      ]
+    },
+    {
+      test: './src/production/**/*.{js,jsx,ts,tsx}',
+      plugins: [
+        ['babel-plugin-react-compiler', {
+          // options ...
+        }]
+      ]
+    }
+  ]
+};
+```
+
+
+## Opt-in Mode with "use memo" {/*opt-in-mode-with-use-memo*/}
+
+For maximum control, you can use `compilationMode: 'annotation'` to only compile components and hooks that explicitly opt in with the `"use memo"` directive.
+
+<Note>
+This approach gives you fine-grained control over individual components and hooks. It's useful when you want to test the compiler on specific components without affecting entire directories.
+</Note>
+
+### Annotation Mode Configuration {/*annotation-mode-configuration*/}
+
+```js
+// babel.config.js
+module.exports = {
+  plugins: [
+    ['babel-plugin-react-compiler', {
+      compilationMode: 'annotation',
+    }],
+  ],
+};
+```
+
+### Using the Directive {/*using-the-directive*/}
+
+Add `"use memo"` at the beginning of functions you want to compile:
+
+```js
+function TodoList({ todos }) {
+  "use memo"; // Opt this component into compilation
+
+  const sortedTodos = todos.slice().sort();
+
+  return (
+    <ul>
+      {sortedTodos.map(todo => (
+        <TodoItem key={todo.id} todo={todo} />
+      ))}
+    </ul>
+  );
+}
+
+function useSortedData(data) {
+  "use memo"; // Opt this hook into compilation
+
+  return data.slice().sort();
+}
+```
+
+With `compilationMode: 'annotation'`, you must:
+- Add `"use memo"` to every component you want optimized
+- Add `"use memo"` to every custom hook
+- Remember to add it to new components
+
+This gives you precise control over which components are compiled while you evaluate the compiler's impact.
+
+## Runtime Feature Flags with Gating {/*runtime-feature-flags-with-gating*/}
+
+The `gating` option enables you to control compilation at runtime using feature flags. This is useful for running A/B tests or gradually rolling out the compiler based on user segments.
+
+### How Gating Works {/*how-gating-works*/}
+
+The compiler wraps optimized code in a runtime check. If the gate returns `true`, the optimized version runs. Otherwise, the original code runs.
+
+### Gating Configuration {/*gating-configuration*/}
+
+```js
+// babel.config.js
+module.exports = {
+  plugins: [
+    ['babel-plugin-react-compiler', {
+      gating: {
+        source: 'ReactCompilerFeatureFlags',
+        importSpecifierName: 'isCompilerEnabled',
+      },
+    }],
+  ],
+};
+```
+
+### Implementing the Feature Flag {/*implementing-the-feature-flag*/}
+
+Create a module that exports your gating function:
+
+```js
+// ReactCompilerFeatureFlags.js
+export function isCompilerEnabled() {
+  // Use your feature flag system
+  return getFeatureFlag('react-compiler-enabled');
+}
+```
+
+## Troubleshooting Adoption {/*troubleshooting-adoption*/}
+
+If you encounter issues during adoption:
+
+1. Use `"use no memo"` to temporarily exclude problematic components
+2. Check the [debugging guide](/learn/react-compiler/debugging) for common issues
+3. Fix Rules of React violations identified by the ESLint plugin
+4. Consider using `compilationMode: 'annotation'` for more gradual adoption
+
+## Next Steps {/*next-steps*/}
+
+- Read the [configuration guide](/reference/react-compiler/configuration) for more options
+- Learn about [debugging techniques](/learn/react-compiler/debugging)
+- Check the [API reference](/reference/react-compiler/configuration) for all compiler options
\ No newline at end of file
diff --git a/src/content/learn/react-compiler/index.md b/src/content/learn/react-compiler/index.md
new file mode 100644
index 0000000000..480187ed5e
--- /dev/null
+++ b/src/content/learn/react-compiler/index.md
@@ -0,0 +1,33 @@
+---
+title: React Compiler
+---
+
+## Introduction {/*introduction*/}
+
+Learn [what React Compiler does](/learn/react-compiler/introduction) and how it automatically optimizes your React application by handling memoization for you, eliminating the need for manual `useMemo`, `useCallback`, and `React.memo`.
+
+## Installation {/*installation*/}
+
+Get started with [installing React Compiler](/learn/react-compiler/installation) and learn how to configure it with your build tools.
+
+
+## Incremental Adoption {/*incremental-adoption*/}
+
+Learn [strategies for gradually adopting React Compiler](/learn/react-compiler/incremental-adoption) in your existing codebase if you're not ready to enable it everywhere yet.
+
+## Debugging and Troubleshooting {/*debugging-and-troubleshooting*/}
+
+When things don't work as expected, use our [debugging guide](/learn/react-compiler/debugging) to understand the difference between compiler errors and runtime issues, identify common breaking patterns, and follow a systematic debugging workflow.
+
+## Configuration and Reference {/*configuration-and-reference*/}
+
+For detailed configuration options and API reference:
+
+- [Configuration Options](/reference/react-compiler/configuration) - All compiler configuration options including React version compatibility
+- [Directives](/reference/react-compiler/directives) - Function-level compilation control
+- [Compiling Libraries](/reference/react-compiler/compiling-libraries) - Shipping pre-compiled libraries
+
+## Additional resources {/*additional-resources*/}
+
+In addition to these docs, we recommend checking the [React Compiler Working Group](https://github.com/reactwg/react-compiler) for additional information and discussion about the compiler.
+
diff --git a/src/content/learn/react-compiler/installation.md b/src/content/learn/react-compiler/installation.md
new file mode 100644
index 0000000000..3606c9c6dd
--- /dev/null
+++ b/src/content/learn/react-compiler/installation.md
@@ -0,0 +1,258 @@
+---
+title: Installation
+---
+
+<Intro>
+This guide will help you install and configure React Compiler in your React application.
+</Intro>
+
+<YouWillLearn>
+
+* How to install React Compiler
+* Basic configuration for different build tools
+* How to verify your setup is working
+
+</YouWillLearn>
+
+## Prerequisites {/*prerequisites*/}
+
+React Compiler is designed to work best with React 19, but it also supports React 17 and 18. Learn more about [React version compatibility](/reference/react-compiler/target).
+
+<Note>
+React Compiler is currently in RC. Install it using the `@rc` tag to get the latest release candidate version.
+</Note>
+
+## Installation {/*installation*/}
+
+Install React Compiler as a `devDependency`:
+
+<TerminalBlock>
+npm install -D babel-plugin-react-compiler@rc
+</TerminalBlock>
+
+Or with Yarn:
+
+<TerminalBlock>
+yarn add -D babel-plugin-react-compiler@rc
+</TerminalBlock>
+
+Or with pnpm:
+
+<TerminalBlock>
+pnpm install -D babel-plugin-react-compiler@rc
+</TerminalBlock>
+
+## Basic Setup {/*basic-setup*/}
+
+React Compiler is designed to work by default without any configuration. However, if you need to configure it in special circumstances (for example, to target React versions below 19), refer to the [compiler options reference](/reference/react-compiler/configuration).
+
+The setup process depends on your build tool. React Compiler includes a Babel plugin that integrates with your build pipeline.
+
+<Pitfall>
+React Compiler must run **first** in your Babel plugin pipeline. The compiler needs the original source information for proper analysis, so it must process your code before other transformations.
+</Pitfall>
+
+### Babel {/*babel*/}
+
+Create or update your `babel.config.js`:
+
+```js {3}
+module.exports = {
+  plugins: [
+    'babel-plugin-react-compiler', // must run first!
+    // ... other plugins
+  ],
+  // ... other config
+};
+```
+
+### Vite {/*vite*/}
+
+If you use Vite, you can add the plugin to vite-plugin-react:
+
+```js {3,9}
+// vite.config.js
+import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react';
+
+export default defineConfig({
+  plugins: [
+    react({
+      babel: {
+        plugins: ['babel-plugin-react-compiler'],
+      },
+    }),
+  ],
+});
+```
+
+Alternatively, if you prefer a separate Babel plugin for Vite:
+
+<TerminalBlock>
+npm install -D vite-plugin-babel
+</TerminalBlock>
+
+```js {2,11}
+// vite.config.js
+import babel from 'vite-plugin-babel';
+import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react';
+
+export default defineConfig({
+  plugins: [
+    react(),
+    babel({
+      babelConfig: {
+        plugins: ['babel-plugin-react-compiler'],
+      },
+    }),
+  ],
+});
+```
+
+### Next.js {/*usage-with-nextjs*/}
+
+Please refer to the [Next.js docs](https://nextjs.org/docs/app/api-reference/next-config-js/reactCompiler) for more information.
+
+### React Router {/*usage-with-react-router*/}
+Install `vite-plugin-babel`, and add the compiler's Babel plugin to it:
+
+<TerminalBlock>
+{`npm install vite-plugin-babel`}
+</TerminalBlock>
+
+```js {3-4,16}
+// vite.config.js
+import { defineConfig } from "vite";
+import babel from "vite-plugin-babel";
+import { reactRouter } from "@react-router/dev/vite";
+
+const ReactCompilerConfig = { /* ... */ };
+
+export default defineConfig({
+  plugins: [
+    reactRouter(),
+    babel({
+      filter: /\.[jt]sx?$/,
+      babelConfig: {
+        presets: ["@babel/preset-typescript"], // if you use TypeScript
+        plugins: [
+          ["babel-plugin-react-compiler", ReactCompilerConfig],
+        ],
+      },
+    }),
+  ],
+});
+```
+
+### Webpack {/*usage-with-webpack*/}
+
+A community webpack loader is [now available here](https://github.com/SukkaW/react-compiler-webpack).
+
+### Expo {/*usage-with-expo*/}
+
+Please refer to [Expo's docs](https://docs.expo.dev/guides/react-compiler/) to enable and use the React Compiler in Expo apps.
+
+### Metro (React Native) {/*usage-with-react-native-metro*/}
+
+React Native uses Babel via Metro, so refer to the [Usage with Babel](#babel) section for installation instructions.
+
+### Rspack {/*usage-with-rspack*/}
+
+Please refer to [Rspack's docs](https://rspack.dev/guide/tech/react#react-compiler) to enable and use the React Compiler in Rspack apps.
+
+### Rsbuild {/*usage-with-rsbuild*/}
+
+Please refer to [Rsbuild's docs](https://rsbuild.dev/guide/framework/react#react-compiler) to enable and use the React Compiler in Rsbuild apps.
+
+
+## ESLint Integration {/*eslint-integration*/}
+
+React Compiler includes an ESLint rule that helps identify code that can't be optimized. When the ESLint rule reports an error, it means the compiler will skip optimizing that specific component or hook. This is safe: the compiler will continue optimizing other parts of your codebase. You don't need to fix all violations immediately. Address them at your own pace to gradually increase the number of optimized components.
+
+Install the ESLint plugin:
+
+<TerminalBlock>
+npm install -D eslint-plugin-react-hooks@rc
+</TerminalBlock>
+
+Then enable the compiler rule in your ESLint configuration:
+
+```js {3}
+// .eslintrc.js
+module.exports = {
+  rules: {
+    'react-hooks/react-compiler': 'error',
+  },
+};
+```
+
+The ESLint rule will:
+- Identify violations of the [Rules of React](/reference/rules)
+- Show which components can't be optimized
+- Provide helpful error messages for fixing issues
+
+## Verify Your Setup {/*verify-your-setup*/}
+
+After installation, verify that React Compiler is working correctly.
+
+### Check React DevTools {/*check-react-devtools*/}
+
+Components optimized by React Compiler will show a "Memo ✨" badge in React DevTools:
+
+1. Install the [React Developer Tools](/learn/react-developer-tools) browser extension
+2. Open your app in development mode
+3. Open React DevTools
+4. Look for the ✨ emoji next to component names
+
+If the compiler is working:
+- Components will show a "Memo ✨" badge in React DevTools
+- Expensive calculations will be automatically memoized
+- No manual `useMemo` is required
+
+### Check Build Output {/*check-build-output*/}
+
+You can also verify the compiler is running by checking your build output. The compiled code will include automatic memoization logic that the compiler adds automatically.
+
+```js
+import { c as _c } from "react/compiler-runtime";
+export default function MyApp() {
+  const $ = _c(1);
+  let t0;
+  if ($[0] === Symbol.for("react.memo_cache_sentinel")) {
+    t0 = <div>Hello World</div>;
+    $[0] = t0;
+  } else {
+    t0 = $[0];
+  }
+  return t0;
+}
+
+```
+
+## Troubleshooting {/*troubleshooting*/}
+
+### Opting out specific components {/*opting-out-specific-components*/}
+
+If a component is causing issues after compilation, you can temporarily opt it out using the `"use no memo"` directive:
+
+```js
+function ProblematicComponent() {
+  "use no memo";
+  // Component code here
+}
+```
+
+This tells the compiler to skip optimization for this specific component. You should fix the underlying issue and remove the directive once resolved.
+
+For more troubleshooting help, see the [debugging guide](/learn/react-compiler/debugging).
+
+## Next Steps {/*next-steps*/}
+
+Now that you have React Compiler installed, learn more about:
+
+- [React version compatibility](/reference/react-compiler/target) for React 17 and 18
+- [Configuration options](/reference/react-compiler/configuration) to customize the compiler
+- [Incremental adoption strategies](/learn/react-compiler/incremental-adoption) for existing codebases
+- [Debugging techniques](/learn/react-compiler/debugging) for troubleshooting issues
+- [Compiling Libraries guide](/reference/react-compiler/compiling-libraries) for compiling your React library
\ No newline at end of file
diff --git a/src/content/learn/react-compiler/introduction.md b/src/content/learn/react-compiler/introduction.md
new file mode 100644
index 0000000000..440c66ab61
--- /dev/null
+++ b/src/content/learn/react-compiler/introduction.md
@@ -0,0 +1,176 @@
+---
+title: Introduction
+---
+
+<Intro>
+React Compiler is a new build-time tool that automatically optimizes your React app. It works with plain JavaScript, and understands the [Rules of React](/reference/rules), so you don't need to rewrite any code to use it.
+</Intro>
+
+<YouWillLearn>
+
+* What React Compiler does
+* Getting started with the compiler
+* Incremental adoption strategies
+* Debugging and troubleshooting when things go wrong
+* Using the compiler on your React library
+
+</YouWillLearn>
+
+<Note>
+React Compiler is currently in Release Candidate (RC). We now recommend everyone to try the compiler and provide feedback. The latest RC release can be found with the `@rc` tag.
+</Note>
+
+## What does React Compiler do? {/*what-does-react-compiler-do*/}
+
+React Compiler automatically optimizes your React application at build time. React is often fast enough without optimization, but sometimes you need to manually memoize components and values to keep your app responsive. This manual memoization is tedious, easy to get wrong, and adds extra code to maintain. React Compiler does this optimization automatically for you, freeing you from this mental burden so you can focus on building features.
+
+### Before React Compiler {/*before-react-compiler*/}
+
+Without the compiler, you need to manually memoize components and values to optimize re-renders:
+
+```js
+import { useMemo, useCallback, memo } from 'react';
+
+const ExpensiveComponent = memo(function ExpensiveComponent({ data, onClick }) {
+  const processedData = useMemo(() => {
+    return expensiveProcessing(data);
+  }, [data]);
+
+  const handleClick = useCallback((item) => {
+    onClick(item.id);
+  }, [onClick]);
+
+  return (
+    <div>
+      {processedData.map(item => (
+        <Item key={item.id} onClick={() => handleClick(item)} />
+      ))}
+    </div>
+  );
+});
+```
+
+### After React Compiler {/*after-react-compiler*/}
+
+With React Compiler, you write the same code without manual memoization:
+
+```js
+function ExpensiveComponent({ data, onClick }) {
+  const processedData = expensiveProcessing(data);
+
+  const handleClick = (item) => {
+    onClick(item.id);
+  };
+
+  return (
+    <div>
+      {processedData.map(item => (
+        <Item key={item.id} onClick={() => handleClick(item)} />
+      ))}
+    </div>
+  );
+}
+```
+
+_[See this example in the React Compiler Playground](https://playground.react.dev/#N4Igzg9grgTgxgUxALhAMygOzgFwJYSYAEAogB4AOCmYeAbggMIQC2Fh1OAFMEQCYBDHAIA0RQowA2eOAGsiAXwCURYAB1iROITA4iFGBERgwCPgBEhAogF4iCStVoMACoeO1MAcy6DhSgG4NDSItHT0ACwFMPkkmaTlbIi48HAQWFRsAPlUQ0PFMKRlZFLSWADo8PkC8hSDMPJgEHFhiLjzQgB4+eiyO-OADIwQTM0thcpYBClL02xz2zXz8zoBJMqJZBABPG2BU9Mq+BQKiuT2uTJyomLizkoOMk4B6PqX8pSUFfs7nnro3qEapgFCAFEA)_
+
+React Compiler automatically applies the equivalent optimizations, ensuring your app only re-renders when necessary.
+
+<DeepDive>
+#### What kind of memoization does React Compiler add? {/*what-kind-of-memoization-does-react-compiler-add*/}
+
+React Compiler's automatic memoization is primarily focused on **improving update performance** (re-rendering existing components), so it focuses on these two use cases:
+
+1. **Skipping cascading re-rendering of components**
+    * Re-rendering `<Parent />` causes many components in its component tree to re-render, even though only `<Parent />` has changed
+1. **Skipping expensive calculations from outside of React**
+    * For example, calling `expensivelyProcessAReallyLargeArrayOfObjects()` inside of your component or hook that needs that data
+
+#### Optimizing Re-renders {/*optimizing-re-renders*/}
+
+React lets you express your UI as a function of their current state (more concretely: their props, state, and context). In its current implementation, when a component's state changes, React will re-render that component _and all of its children_ — unless you have applied some form of manual memoization with `useMemo()`, `useCallback()`, or `React.memo()`. For example, in the following example, `<MessageButton>` will re-render whenever `<FriendList>`'s state changes:
+
+```javascript
+function FriendList({ friends }) {
+  const onlineCount = useFriendOnlineCount();
+  if (friends.length === 0) {
+    return <NoFriends />;
+  }
+  return (
+    <div>
+      <span>{onlineCount} online</span>
+      {friends.map((friend) => (
+        <FriendListCard key={friend.id} friend={friend} />
+      ))}
+      <MessageButton />
+    </div>
+  );
+}
+```
+[_See this example in the React Compiler Playground_](https://playground.react.dev/#N4Igzg9grgTgxgUxALhAMygOzgFwJYSYAEAYjHgpgCYAyeYOAFMEWuZVWEQL4CURwADrEicQgyKEANnkwIAwtEw4iAXiJQwCMhWoB5TDLmKsTXgG5hRInjRFGbXZwB0UygHMcACzWr1ABn4hEWsYBBxYYgAeADkIHQ4uAHoAPksRbisiMIiYYkYs6yiqPAA3FMLrIiiwAAcAQ0wU4GlZBSUcbklDNqikusaKkKrgR0TnAFt62sYHdmp+VRT7SqrqhOo6Bnl6mCoiAGsEAE9VUfmqZzwqLrHqM7ubolTVol5eTOGigFkEMDB6u4EAAhKA4HCEZ5DNZ9ErlLIWYTcEDcIA)
+
+React Compiler automatically applies the equivalent of manual memoization, ensuring that only the relevant parts of an app re-render as state changes, which is sometimes referred to as "fine-grained reactivity". In the above example, React Compiler determines that the return value of `<FriendListCard />` can be reused even as `friends` changes, and can avoid recreating this JSX _and_ avoid re-rendering `<MessageButton>` as the count changes.
+
+#### Expensive calculations also get memoized {/*expensive-calculations-also-get-memoized*/}
+
+React Compiler can also automatically memoize expensive calculations used during rendering:
+
+```js
+// **Not** memoized by React Compiler, since this is not a component or hook
+function expensivelyProcessAReallyLargeArrayOfObjects() { /* ... */ }
+
+// Memoized by React Compiler since this is a component
+function TableContainer({ items }) {
+  // This function call would be memoized:
+  const data = expensivelyProcessAReallyLargeArrayOfObjects(items);
+  // ...
+}
+```
+[_See this example in the React Compiler Playground_](https://playground.react.dev/#N4Igzg9grgTgxgUxALhAejQAgFTYHIQAuumAtgqRAJYBeCAJpgEYCemASggIZyGYDCEUgAcqAGwQwANJjBUAdokyEAFlTCZ1meUUxdMcIcIjyE8vhBiYVECAGsAOvIBmURYSonMCAB7CzcgBuCGIsAAowEIhgYACCnFxioQAyXDAA5gixMDBcLADyzvlMAFYIvGAAFACUmMCYaNiYAHStOFgAvk5OGJgAshTUdIysHNy8AkbikrIKSqpaWvqGIiZmhE6u7p7ymAAqXEwSguZcCpKV9VSEFBodtcBOmAYmYHz0XIT6ALzefgFUYKhCJRBAxeLcJIsVIZLI5PKFYplCqVa63aoAbm6u0wMAQhFguwAPPRAQA+YAfL4dIloUmBMlODogDpAA)
+
+However, if `expensivelyProcessAReallyLargeArrayOfObjects` is truly an expensive function, you may want to consider implementing its own memoization outside of React, because:
+
+- React Compiler only memoizes React components and hooks, not every function
+- React Compiler's memoization is not shared across multiple components or hooks
+
+So if `expensivelyProcessAReallyLargeArrayOfObjects` was used in many different components, even if the same exact items were passed down, that expensive calculation would be run repeatedly. We recommend [profiling](reference/react/useMemo#how-to-tell-if-a-calculation-is-expensive) first to see if it really is that expensive before making code more complicated.
+</DeepDive>
+
+## Should I try out the compiler? {/*should-i-try-out-the-compiler*/}
+
+We encourage everyone to start using React Compiler. While the compiler is still an optional addition to React today, in the future some features may require the compiler in order to fully work.
+
+### Is it safe to use? {/*is-it-safe-to-use*/}
+
+React Compiler is now in RC and has been tested extensively in production. While it has been used in production at companies like Meta, rolling out the compiler to production for your app will depend on the health of your codebase and how well you've followed the [Rules of React](/reference/rules).
+
+## What build tools are supported? {/*what-build-tools-are-supported*/}
+
+React Compiler can be installed across [several build tools](/learn/react-compiler/installation) such as Babel, Vite, Metro, and Rsbuild.
+
+React Compiler is primarily a light Babel plugin wrapper around the core compiler, which was designed to be decoupled from Babel itself. While the initial stable version of the compiler will remain primarily a Babel plugin, we are working with the swc and [oxc](https://github.com/oxc-project/oxc/issues/10048) teams to build first class support for React Compiler so you won't have to add Babel back to your build pipelines in the future.
+
+Next.js users can enable the swc-invoked React Compiler by using [v15.3.1](https://github.com/vercel/next.js/releases/tag/v15.3.1) and up.
+
+## What should I do about useMemo, useCallback, and React.memo? {/*what-should-i-do-about-usememo-usecallback-and-reactmemo*/}
+
+If you are using React Compiler, [`useMemo`](/reference/react/useMemo), [`useCallback`](/reference/react/useCallback), and [`React.memo`](/reference/react/memo) can be removed. React Compiler adds automatic memoization more precisely and granularly than is possible with these hooks. If you choose to keep manual memoization, React Compiler will analyze them and determine if your manual memoization matches its automatically inferred memoization. If there isn't a match, the compiler will choose to bail out of optimizing that component.
+
+This is done out of caution as a common anti-pattern with manual memoization is using it for correctness.  This means your app depends on specific values being memoized to work properly. For example, in order to prevent an infinite loop, you may have memoized some values to stop a `useEffect` call from firing. This breaks the Rules of React, but since it can potentially be dangerous for the compiler to automatically remove manual memoization, the compiler will just bail out instead. You should manually remove your handwritten memoization and verify that your app still works as expected.
+
+## Try React Compiler {/*try-react-compiler*/}
+
+This section will help you get started with React Compiler and understand how to use it effectively in your projects.
+
+* **[Installation](/learn/react-compiler/installation)** - Install React Compiler and configure it for your build tools
+* **[React Version Compatibility](/reference/react-compiler/target)** - Support for React 17, 18, and 19
+* **[Configuration](/reference/react-compiler/configuration)** - Customize the compiler for your specific needs
+* **[Incremental Adoption](/learn/react-compiler/incremental-adoption)** - Strategies for gradually rolling out the compiler in existing codebases
+* **[Debugging and Troubleshooting](/learn/react-compiler/debugging)** - Identify and fix issues when using the compiler
+* **[Compiling Libraries](/reference/react-compiler/compiling-libraries)** - Best practices for shipping compiled code
+* **[API Reference](/reference/react-compiler/configuration)** - Detailed documentation of all configuration options
+
+## Additional resources {/*additional-resources*/}
+
+In addition to these docs, we recommend checking the [React Compiler Working Group](https://github.com/reactwg/react-compiler) for additional information and discussion about the compiler.
+
diff --git a/src/content/learn/synchronizing-with-effects.md b/src/content/learn/synchronizing-with-effects.md
index 5b1c09bd6e..85c2f3b4e2 100644
--- a/src/content/learn/synchronizing-with-effects.md
+++ b/src/content/learn/synchronizing-with-effects.md
@@ -732,7 +732,7 @@ function TodoList() {
 
 这些弊端并不仅限于 React。任何库在组件挂载时进行数据获取都会遇到这些问题。与路由处理一样，要做好数据获取并非易事，因此我们推荐以下方法：
 
-- **如果你正在使用 [框架](/learn/start-a-new-react-project#production-grade-react-frameworks) ，请使用其内置的数据获取机制**。现代 React 框架集成了高效的数据获取机制，不会出现上述问题。
+- **如果你正在使用 [框架](/learn/start-a-new-react-project#full-stack-frameworks) ，请使用其内置的数据获取机制**。现代 React 框架集成了高效的数据获取机制，不会出现上述问题。
 - **否则，请考虑使用或构建客户端缓存**。流行的开源解决方案包括 [React Query](https://tanstack.com/query/latest)、[useSWR](https://swr.vercel.app/) 和 [React Router v6.4+](https://beta.reactrouter.com/en/main/start/overview)。你也可以自己构建解决方案：在底层使用 Effect，但添加对请求的去重、缓存响应以及避免网络瀑布（通过预加载数据或将数据请求提升到路由层次）的逻辑。
 
 如果这些方法都不适合你，你可以继续直接在 Effect 中获取数据。
diff --git a/src/content/learn/typescript.md b/src/content/learn/typescript.md
index e9b7bfe340..b24f0963e7 100644
--- a/src/content/learn/typescript.md
+++ b/src/content/learn/typescript.md
@@ -13,14 +13,14 @@ TypeScript 是一种向 JavaScript 代码添加类型定义的常用方法。Typ
 
 * [在 React 组件中使用 TypeScript](/learn/typescript#typescript-with-react-components)
 * [带有 Hook 的类型示例](/learn/typescript#example-hooks)
-* [来自 `@types/react` 的常见类型](/learn/typescript/#useful-types)
-* [更多学习资源](/learn/typescript/#further-learning)
+* [来自 `@types/react` 的常见类型](/learn/typescript#useful-types)
+* [更多学习资源](/learn/typescript#further-learning)
 
 </YouWillLearn>
 
 ## 安装 {/*installation*/}
 
-所有的 [生产级 React 框架](/learn/start-a-new-react-project#production-grade-react-framework) 都支持使用 TypeScript。请按照框架特定的指南进行安装：
+所有的 [生产级 React 框架](/learn/start-a-new-react-project#full-stack-frameworks) 都支持使用 TypeScript。请按照框架特定的指南进行安装：
 
 - [Next.js](https://nextjs.org/docs/app/building-your-application/configuring/typescript)
 - [Remix](https://remix.run/docs/en/1.19.2/guides/typescript)
@@ -174,7 +174,7 @@ const [requestState, setRequestState] = useState<RequestState>({ status: 'idle'
 import {useReducer} from 'react';
 
 interface State {
-   count: number 
+   count: number
 };
 
 type CounterAction =
@@ -284,7 +284,7 @@ export default App = AppTSX;
 
 </Sandpack>
 
-当你没有一个合理的默认值时，这种技术是有效的，而在这些情况下，`null` 作为默认值可能感觉是合理的。但是，为了让类型系统理解你的代码，你需要在 `createContext` 上显式设置 `ContextShape | null`。
+当你有一个合理的默认值情况下，这种技术是有效的。但是当你没有合理的默认值的时候，`null` 作为默认值可能感觉是合理的。但是为了让类型系统理解你的代码，你需要在 `createContext` 上显式设置 `ContextShape | null`。
 
 这会导致一个问题，你需要在 context consumer 中消除 `| null` 的类型。我们建议让 Hook 在运行时检查它的存在，并在不存在时抛出一个错误：
 
@@ -329,6 +329,12 @@ function MyComponent() {
 
 ### `useMemo` {/*typing-usememo*/}
 
+<Note>
+
+[React Compiler](/learn/react-compiler) 会自动对值和函数进行记忆化处理，从而减少手动调用 `useMemo` 的需求。你可以使用编译器自动处理记忆化。
+
+</Note>
+
 [`useMemo`](/reference/react/useMemo) 会从函数调用中创建/重新访问记忆化值，只有在第二个参数中传入的依赖项发生变化时，才会重新运行该函数。函数的类型是根据第一个参数中函数的返回值进行推断的，如果希望明确指定，可以为该 Hook 提供一个类型参数以指定函数类型。
 
 ```ts
@@ -339,6 +345,12 @@ const visibleTodos = useMemo(() => filterTodos(todos, tab), [todos, tab]);
 
 ### `useCallback` {/*typing-usecallback*/}
 
+<Note>
+
+[React Compiler](/learn/react-compiler) 会自动对值和函数进行记忆化处理，从而减少手动调用 `useCallback` 的需求。你可以使用编译器自动处理记忆化。
+
+</Note>
+
 [`useCallback`](/reference/react/useCallback) 会在第二个参数中传入的依赖项保持不变的情况下，为函数提供相同的引用。与 `useMemo` 类似，函数的类型是根据第一个参数中函数的返回值进行推断的，如果希望明确指定，可以为这个 Hook 提供一个类型参数以指定函数类型。
 
 
@@ -361,7 +373,7 @@ export default function Form() {
   const handleChange = useCallback<React.ChangeEventHandler<HTMLInputElement>>((event) => {
     setValue(event.currentTarget.value);
   }, [setValue])
-  
+
   return (
     <>
       <input value={value} onChange={handleChange} />
diff --git a/src/content/learn/you-might-not-need-an-effect.md b/src/content/learn/you-might-not-need-an-effect.md
index f27f42513a..7b970e7040 100644
--- a/src/content/learn/you-might-not-need-an-effect.md
+++ b/src/content/learn/you-might-not-need-an-effect.md
@@ -26,7 +26,7 @@ Effect 是 React 范式中的一种脱围机制。它们让你可以 “逃出
 * **你不必使用 Effect 来转换渲染所需的数据**。例如，你想在展示一个列表前先做筛选。你的直觉可能是写一个当列表变化时更新 state 变量的 Effect。然而，这是低效的。当你更新这个 state 时，React 首先会调用你的组件函数来计算应该显示在屏幕上的内容。然后 React 会把这些变化“[提交](/learn/render-and-commit)”到 DOM 中来更新屏幕。然后 React 会执行你的 Effect。如果你的 Effect 也立即更新了这个 state，就会重新执行整个流程。为了避免不必要的渲染流程，应在你的组件顶层转换数据。这些代码会在你的 props 或 state 变化时自动重新执行。
 * **你不必使用 Effect 来处理用户事件**。例如，你想在用户购买一个产品时发送一个 `/api/buy` 的 POST 请求并展示一个提示。在这个购买按钮的点击事件处理函数中，你确切地知道会发生什么。但是当一个 Effect 运行时，你却不知道用户做了什么（例如，点击了哪个按钮）。这就是为什么你通常应该在相应的事件处理函数中处理用户事件。
 
-你 **的确** 可以使用 Effect 来和外部系统 [同步](/learn/synchronizing-with-effects#what-are-effects-and-how-are-they-different-from-events) 。例如，你可以写一个 Effect 来保持一个 jQuery 的组件和 React state 之间的同步。你也可以使用 Effect 来获取数据：例如，你可以同步当前的查询搜索和查询结果。请记住，比起直接在你的组件中写 Effect，现代 [框架](/learn/start-a-new-react-project#production-grade-react-frameworks) 提供了更加高效的，内置的数据获取机制。
+你 **的确** 可以使用 Effect 来和外部系统 [同步](/learn/synchronizing-with-effects#what-are-effects-and-how-are-they-different-from-events) 。例如，你可以写一个 Effect 来保持一个 jQuery 的组件和 React state 之间的同步。你也可以使用 Effect 来获取数据：例如，你可以同步当前的查询搜索和查询结果。请记住，比起直接在你的组件中写 Effect，现代 [框架](/learn/start-a-new-react-project#full-stack-frameworks) 提供了更加高效的，内置的数据获取机制。
 
 为了帮助你获得正确的直觉，让我们来看一些常见的实例吧！
 
@@ -95,6 +95,12 @@ function TodoList({ todos, filter }) {
 
 你可以使用 [`useMemo`](/reference/react/useMemo) Hook 缓存（或者说 [记忆（memoize）](https://en.wikipedia.org/wiki/Memoization)）一个昂贵的计算。
 
+<Note>
+
+[React Compiler](/learn/react-compiler) 可以自动记忆化昂贵计算，从而减少很多手动调用 `useMemo` 的场景。
+
+</Note>
+
 ```js {5-8}
 import { useMemo, useState } from 'react';
 
@@ -751,7 +757,7 @@ function SearchResults({ query }) {
 
 处理竞态条件并不是实现数据获取的唯一难点。你可能还需要考虑缓存响应结果（使用户点击后退按钮时可以立即看到先前的屏幕内容），如何在服务端获取数据（使服务端初始渲染的 HTML 中包含获取到的内容而不是加载动画），以及如何避免网络瀑布（使子组件不必等待每个父组件的数据获取完毕后才开始获取数据）。
 
-**这些问题适用于任何 UI 库，而不仅仅是 React。解决这些问题并不容易，这也是现代 [框架](/learn/start-a-new-react-project#production-grade-react-frameworks) 提供了比在 Effect 中获取数据更有效的内置数据获取机制的原因。**
+**这些问题适用于任何 UI 库，而不仅仅是 React。解决这些问题并不容易，这也是现代 [框架](/learn/start-a-new-react-project#full-stack-frameworks) 提供了比在 Effect 中获取数据更有效的内置数据获取机制的原因。**
 
 如果你不使用框架（也不想开发自己的框架），但希望使从 Effect 中获取数据更符合人类直觉，请考虑像这个例子一样，将获取逻辑提取到一个自定义 Hook 中：
 
diff --git a/src/content/reference/react-compiler/compilationMode.md b/src/content/reference/react-compiler/compilationMode.md
new file mode 100644
index 0000000000..5513d1c6a6
--- /dev/null
+++ b/src/content/reference/react-compiler/compilationMode.md
@@ -0,0 +1,201 @@
+---
+title: compilationMode
+---
+
+<Intro>
+
+The `compilationMode` option controls how the React Compiler selects which functions to compile.
+
+</Intro>
+
+```js
+{
+  compilationMode: 'infer' // or 'annotation', 'syntax', 'all'
+}
+```
+
+<InlineToc />
+
+---
+
+## Reference {/*reference*/}
+
+### `compilationMode` {/*compilationmode*/}
+
+Controls the strategy for determining which functions the React Compiler will optimize.
+
+#### Type {/*type*/}
+
+```
+'infer' | 'syntax' | 'annotation' | 'all'
+```
+
+#### Default value {/*default-value*/}
+
+`'infer'`
+
+#### Options {/*options*/}
+
+- **`'infer'`** (default): The compiler uses intelligent heuristics to identify React components and hooks:
+  - Functions explicitly annotated with `"use memo"` directive
+  - Functions that are named like components (PascalCase) or hooks (`use` prefix) AND create JSX and/or call other hooks
+
+- **`'annotation'`**: Only compile functions explicitly marked with the `"use memo"` directive. Ideal for incremental adoption.
+
+- **`'syntax'`**: Only compile components and hooks that use Flow's [component](https://flow.org/en/docs/react/component-syntax/) and [hook](https://flow.org/en/docs/react/hook-syntax/) syntax.
+
+- **`'all'`**: Compile all top-level functions. Not recommended as it may compile non-React functions.
+
+#### Caveats {/*caveats*/}
+
+- The `'infer'` mode requires functions to follow React naming conventions to be detected
+- Using `'all'` mode may negatively impact performance by compiling utility functions
+- The `'syntax'` mode requires Flow and won't work with TypeScript
+- Regardless of mode, functions with `"use no memo"` directive are always skipped
+
+---
+
+## Usage {/*usage*/}
+
+### Default inference mode {/*default-inference-mode*/}
+
+The default `'infer'` mode works well for most codebases that follow React conventions:
+
+```js
+{
+  compilationMode: 'infer'
+}
+```
+
+With this mode, these functions will be compiled:
+
+```js
+// ✅ Compiled: Named like a component + returns JSX
+function Button(props) {
+  return <button>{props.label}</button>;
+}
+
+// ✅ Compiled: Named like a hook + calls hooks
+function useCounter() {
+  const [count, setCount] = useState(0);
+  return [count, setCount];
+}
+
+// ✅ Compiled: Explicit directive
+function expensiveCalculation(data) {
+  "use memo";
+  return data.reduce(/* ... */);
+}
+
+// ❌ Not compiled: Not a component/hook pattern
+function calculateTotal(items) {
+  return items.reduce((a, b) => a + b, 0);
+}
+```
+
+### Incremental adoption with annotation mode {/*incremental-adoption*/}
+
+For gradual migration, use `'annotation'` mode to only compile marked functions:
+
+```js
+{
+  compilationMode: 'annotation'
+}
+```
+
+Then explicitly mark functions to compile:
+
+```js
+// Only this function will be compiled
+function ExpensiveList(props) {
+  "use memo";
+  return (
+    <ul>
+      {props.items.map(item => (
+        <li key={item.id}>{item.name}</li>
+      ))}
+    </ul>
+  );
+}
+
+// This won't be compiled without the directive
+function NormalComponent(props) {
+  return <div>{props.content}</div>;
+}
+```
+
+### Using Flow syntax mode {/*flow-syntax-mode*/}
+
+If your codebase uses Flow instead of TypeScript:
+
+```js
+{
+  compilationMode: 'syntax'
+}
+```
+
+Then use Flow's component syntax:
+
+```js
+// Compiled: Flow component syntax
+component Button(label: string) {
+  return <button>{label}</button>;
+}
+
+// Compiled: Flow hook syntax
+hook useCounter(initial: number) {
+  const [count, setCount] = useState(initial);
+  return [count, setCount];
+}
+
+// Not compiled: Regular function syntax
+function helper(data) {
+  return process(data);
+}
+```
+
+### Opting out specific functions {/*opting-out*/}
+
+Regardless of compilation mode, use `"use no memo"` to skip compilation:
+
+```js
+function ComponentWithSideEffects() {
+  "use no memo"; // Prevent compilation
+
+  // This component has side effects that shouldn't be memoized
+  logToAnalytics('component_rendered');
+
+  return <div>Content</div>;
+}
+```
+
+---
+
+## Troubleshooting {/*troubleshooting*/}
+
+### Component not being compiled in infer mode {/*component-not-compiled-infer*/}
+
+In `'infer'` mode, ensure your component follows React conventions:
+
+```js
+// ❌ Won't be compiled: lowercase name
+function button(props) {
+  return <button>{props.label}</button>;
+}
+
+// ✅ Will be compiled: PascalCase name
+function Button(props) {
+  return <button>{props.label}</button>;
+}
+
+// ❌ Won't be compiled: doesn't create JSX or call hooks
+function useData() {
+  return window.localStorage.getItem('data');
+}
+
+// ✅ Will be compiled: calls a hook
+function useData() {
+  const [data] = useState(() => window.localStorage.getItem('data'));
+  return data;
+}
+```
diff --git a/src/content/reference/react-compiler/compiling-libraries.md b/src/content/reference/react-compiler/compiling-libraries.md
new file mode 100644
index 0000000000..f09ffcb725
--- /dev/null
+++ b/src/content/reference/react-compiler/compiling-libraries.md
@@ -0,0 +1,106 @@
+---
+title: Compiling Libraries
+---
+
+<Intro>
+This guide helps library authors understand how to use React Compiler to ship optimized library code to their users.
+</Intro>
+
+<InlineToc />
+
+## Why Ship Compiled Code? {/*why-ship-compiled-code*/}
+
+As a library author, you can compile your library code before publishing to npm. This provides several benefits:
+
+- **Performance improvements for all users** - Your library users get optimized code even if they aren't using React Compiler yet
+- **No configuration required by users** - The optimizations work out of the box
+- **Consistent behavior** - All users get the same optimized version regardless of their build setup
+
+## Setting Up Compilation {/*setting-up-compilation*/}
+
+Add React Compiler to your library's build process:
+
+<TerminalBlock>
+npm install -D babel-plugin-react-compiler@rc
+</TerminalBlock>
+
+Configure your build tool to compile your library. For example, with Babel:
+
+```js
+// babel.config.js
+module.exports = {
+  plugins: [
+    'babel-plugin-react-compiler',
+  ],
+  // ... other config
+};
+```
+
+## Backwards Compatibility {/*backwards-compatibility*/}
+
+If your library supports React versions below 19, you'll need additional configuration:
+
+### 1. Install the runtime package {/*install-runtime-package*/}
+
+We recommend installing react-compiler-runtime as a direct dependency:
+
+<TerminalBlock>
+npm install react-compiler-runtime@rc
+</TerminalBlock>
+
+```json
+{
+  "dependencies": {
+    "react-compiler-runtime": "^19.1.0-rc.2"
+  },
+  "peerDependencies": {
+    "react": "^17.0.0 || ^18.0.0 || ^19.0.0"
+  }
+}
+```
+
+### 2. Configure the target version {/*configure-target-version*/}
+
+Set the minimum React version your library supports:
+
+```js
+{
+  target: '17', // Minimum supported React version
+}
+```
+
+## Testing Strategy {/*testing-strategy*/}
+
+Test your library both with and without compilation to ensure compatibility. Run your existing test suite against the compiled code, and also create a separate test configuration that bypasses the compiler. This helps catch any issues that might arise from the compilation process and ensures your library works correctly in all scenarios.
+
+## Troubleshooting {/*troubleshooting*/}
+
+### Library doesn't work with older React versions {/*library-doesnt-work-with-older-react-versions*/}
+
+If your compiled library throws errors in React 17 or 18:
+
+1. Verify you've installed `react-compiler-runtime` as a dependency
+2. Check that your `target` configuration matches your minimum supported React version
+3. Ensure the runtime package is included in your published bundle
+
+### Compilation conflicts with other Babel plugins {/*compilation-conflicts-with-other-babel-plugins*/}
+
+Some Babel plugins may conflict with React Compiler:
+
+1. Place `babel-plugin-react-compiler` early in your plugin list
+2. Disable conflicting optimizations in other plugins
+3. Test your build output thoroughly
+
+### Runtime module not found {/*runtime-module-not-found*/}
+
+If users see "Cannot find module 'react-compiler-runtime'":
+
+1. Ensure the runtime is listed in `dependencies`, not `devDependencies`
+2. Check that your bundler includes the runtime in the output
+3. Verify the package is published to npm with your library
+
+## Next Steps {/*next-steps*/}
+
+- Learn about [debugging techniques](/learn/react-compiler/debugging) for compiled code
+- Check the [configuration options](/reference/react-compiler/configuration) for all compiler options
+- Explore [compilation modes](/reference/react-compiler/compilationMode) for selective optimization
\ No newline at end of file
diff --git a/src/content/reference/react-compiler/configuration.md b/src/content/reference/react-compiler/configuration.md
new file mode 100644
index 0000000000..f38f1afc0a
--- /dev/null
+++ b/src/content/reference/react-compiler/configuration.md
@@ -0,0 +1,151 @@
+---
+title: Configuration
+---
+
+<Intro>
+
+This page lists all configuration options available in React Compiler.
+
+</Intro>
+
+<Note>
+
+For most apps, the default options should work out of the box. If you have a special need, you can use these advanced options.
+
+</Note>
+
+```js
+// babel.config.js
+module.exports = {
+  plugins: [
+    [
+      'babel-plugin-react-compiler', {
+        // compiler options
+      }
+    ]
+  ]
+};
+```
+
+---
+
+## Compilation Control {/*compilation-control*/}
+
+These options control *what* the compiler optimizes and *how* it selects components and hooks to compile.
+
+* [`compilationMode`](/reference/react-compiler/compilationMode) controls the strategy for selecting functions to compile (e.g., all functions, only annotated ones, or intelligent detection).
+
+```js
+{
+  compilationMode: 'annotation' // Only compile "use memo" functions
+}
+```
+
+---
+
+## Version Compatibility {/*version-compatibility*/}
+
+React version configuration ensures the compiler generates code compatible with your React version.
+
+[`target`](/reference/react-compiler/target) specifies which React version you're using (17, 18, or 19).
+
+```js
+// For React 18 projects
+{
+  target: '18' // Also requires react-compiler-runtime package
+}
+```
+
+---
+
+## Error Handling {/*error-handling*/}
+
+These options control how the compiler responds to code that doesn't follow the [Rules of React](/reference/rules).
+
+[`panicThreshold`](/reference/react-compiler/panicThreshold) determines whether to fail the build or skip problematic components.
+
+```js
+// Recommended for production
+{
+  panicThreshold: 'none' // Skip components with errors instead of failing the build
+}
+```
+
+---
+
+## Debugging {/*debugging*/}
+
+Logging and analysis options help you understand what the compiler is doing.
+
+[`logger`](/reference/react-compiler/logger) provides custom logging for compilation events.
+
+```js
+{
+  logger: {
+    logEvent(filename, event) {
+      if (event.kind === 'CompileSuccess') {
+        console.log('Compiled:', filename);
+      }
+    }
+  }
+}
+```
+
+---
+
+## Feature Flags {/*feature-flags*/}
+
+Conditional compilation lets you control when optimized code is used.
+
+[`gating`](/reference/react-compiler/gating) enables runtime feature flags for A/B testing or gradual rollouts.
+
+```js
+{
+  gating: {
+    source: 'my-feature-flags',
+    importSpecifierName: 'isCompilerEnabled'
+  }
+}
+```
+
+---
+
+## Common Configuration Patterns {/*common-patterns*/}
+
+### Default configuration {/*default-configuration*/}
+
+For most React 19 applications, the compiler works without configuration:
+
+```js
+// babel.config.js
+module.exports = {
+  plugins: [
+    'babel-plugin-react-compiler'
+  ]
+};
+```
+
+### React 17/18 projects {/*react-17-18*/}
+
+Older React versions need the runtime package and target configuration:
+
+```bash
+npm install react-compiler-runtime@rc
+```
+
+```js
+{
+  target: '18' // or '17'
+}
+```
+
+### Incremental adoption {/*incremental-adoption*/}
+
+Start with specific directories and expand gradually:
+
+```js
+{
+  compilationMode: 'annotation' // Only compile "use memo" functions
+}
+```
+
diff --git a/src/content/reference/react-compiler/directives.md b/src/content/reference/react-compiler/directives.md
new file mode 100644
index 0000000000..705d0f6209
--- /dev/null
+++ b/src/content/reference/react-compiler/directives.md
@@ -0,0 +1,198 @@
+---
+title: Directives
+---
+
+<Intro>
+React Compiler directives are special string literals that control whether specific functions are compiled.
+</Intro>
+
+```js
+function MyComponent() {
+  "use memo"; // Opt this component into compilation
+  return <div>{/* ... */}</div>;
+}
+```
+
+<InlineToc />
+
+---
+
+## Overview {/*overview*/}
+
+React Compiler directives provide fine-grained control over which functions are optimized by the compiler. They are string literals placed at the beginning of a function body or at the top of a module.
+
+### Available directives {/*available-directives*/}
+
+* **[`"use memo"`](/reference/react-compiler/directives/use-memo)** - Opts a function into compilation
+* **[`"use no memo"`](/reference/react-compiler/directives/use-no-memo)** - Opts a function out of compilation
+
+### Quick comparison {/*quick-comparison*/}
+
+| Directive | Purpose | When to use |
+|-----------|---------|-------------|
+| [`"use memo"`](/reference/react-compiler/directives/use-memo) | Force compilation | When using `annotation` mode or to override `infer` mode heuristics |
+| [`"use no memo"`](/reference/react-compiler/directives/use-no-memo) | Prevent compilation | Debugging issues or working with incompatible code |
+
+---
+
+## Usage {/*usage*/}
+
+### Function-level directives {/*function-level*/}
+
+Place directives at the beginning of a function to control its compilation:
+
+```js
+// Opt into compilation
+function OptimizedComponent() {
+  "use memo";
+  return <div>This will be optimized</div>;
+}
+
+// Opt out of compilation
+function UnoptimizedComponent() {
+  "use no memo";
+  return <div>This won't be optimized</div>;
+}
+```
+
+### Module-level directives {/*module-level*/}
+
+Place directives at the top of a file to affect all functions in that module:
+
+```js
+// At the very top of the file
+"use memo";
+
+// All functions in this file will be compiled
+function Component1() {
+  return <div>Compiled</div>;
+}
+
+function Component2() {
+  return <div>Also compiled</div>;
+}
+
+// Can be overridden at function level
+function Component3() {
+  "use no memo"; // This overrides the module directive
+  return <div>Not compiled</div>;
+}
+```
+
+### Compilation modes interaction {/*compilation-modes*/}
+
+Directives behave differently depending on your [`compilationMode`](/reference/react-compiler/compilationMode):
+
+* **`annotation` mode**: Only functions with `"use memo"` are compiled
+* **`infer` mode**: Compiler decides what to compile, directives override decisions
+* **`all` mode**: Everything is compiled, `"use no memo"` can exclude specific functions
+
+---
+
+## Best practices {/*best-practices*/}
+
+### Use directives sparingly {/*use-sparingly*/}
+
+Directives are escape hatches. Prefer configuring the compiler at the project level:
+
+```js
+// ✅ Good - project-wide configuration
+{
+  plugins: [
+    ['babel-plugin-react-compiler', {
+      compilationMode: 'infer'
+    }]
+  ]
+}
+
+// ⚠️ Use directives only when needed
+function SpecialCase() {
+  "use no memo"; // Document why this is needed
+  // ...
+}
+```
+
+### Document directive usage {/*document-usage*/}
+
+Always explain why a directive is used:
+
+```js
+// ✅ Good - clear explanation
+function DataGrid() {
+  "use no memo"; // TODO: Remove after fixing issue with dynamic row heights (JIRA-123)
+  // Complex grid implementation
+}
+
+// ❌ Bad - no explanation
+function Mystery() {
+  "use no memo";
+  // ...
+}
+```
+
+### Plan for removal {/*plan-removal*/}
+
+Opt-out directives should be temporary:
+
+1. Add the directive with a TODO comment
+2. Create a tracking issue
+3. Fix the underlying problem
+4. Remove the directive
+
+```js
+function TemporaryWorkaround() {
+  "use no memo"; // TODO: Remove after upgrading ThirdPartyLib to v2.0
+  return <ThirdPartyComponent />;
+}
+```
+
+---
+
+## Common patterns {/*common-patterns*/}
+
+### Gradual adoption {/*gradual-adoption*/}
+
+When adopting the React Compiler in a large codebase:
+
+```js
+// Start with annotation mode
+{
+  compilationMode: 'annotation'
+}
+
+// Opt in stable components
+function StableComponent() {
+  "use memo";
+  // Well-tested component
+}
+
+// Later, switch to infer mode and opt out problematic ones
+function ProblematicComponent() {
+  "use no memo"; // Fix issues before removing
+  // ...
+}
+```
+
+
+---
+
+## Troubleshooting {/*troubleshooting*/}
+
+For specific issues with directives, see the troubleshooting sections in:
+
+* [`"use memo"` troubleshooting](/reference/react-compiler/directives/use-memo#troubleshooting)
+* [`"use no memo"` troubleshooting](/reference/react-compiler/directives/use-no-memo#troubleshooting)
+
+### Common issues {/*common-issues*/}
+
+1. **Directive ignored**: Check placement (must be first) and spelling
+2. **Compilation still happens**: Check `ignoreUseNoForget` setting
+3. **Module directive not working**: Ensure it's before all imports
+
+---
+
+## See also {/*see-also*/}
+
+* [`compilationMode`](/reference/react-compiler/compilationMode) - Configure how the compiler chooses what to optimize
+* [`Configuration`](/reference/react-compiler/configuration) - Full compiler configuration options
+* [React Compiler documentation](https://react.dev/learn/react-compiler) - Getting started guide
\ No newline at end of file
diff --git a/src/content/reference/react-compiler/directives/use-memo.md b/src/content/reference/react-compiler/directives/use-memo.md
new file mode 100644
index 0000000000..431862682f
--- /dev/null
+++ b/src/content/reference/react-compiler/directives/use-memo.md
@@ -0,0 +1,157 @@
+---
+title: "use memo"
+titleForTitleTag: "'use memo' directive"
+---
+
+<Intro>
+
+`"use memo"` marks a function for React Compiler optimization.
+
+</Intro>
+
+<Note>
+
+In most cases, you don't need `"use memo"`. It's primarily needed in `annotation` mode where you must explicitly mark functions for optimization. In `infer` mode, the compiler automatically detects components and hooks by their naming patterns (PascalCase for components, `use` prefix for hooks). If a component or hook isn't being compiled in `infer` mode, you should fix its naming convention rather than forcing compilation with `"use memo"`.
+
+</Note>
+
+<InlineToc />
+
+---
+
+## Reference {/*reference*/}
+
+### `"use memo"` {/*use-memo*/}
+
+Add `"use memo"` at the beginning of a function to mark it for React Compiler optimization.
+
+```js {1}
+function MyComponent() {
+  "use memo";
+  // ...
+}
+```
+
+When a function contains `"use memo"`, the React Compiler will analyze and optimize it during build time. The compiler will automatically memoize values and components to prevent unnecessary re-computations and re-renders.
+
+#### Caveats {/*caveats*/}
+
+* `"use memo"` must be at the very beginning of a function body, before any imports or other code (comments are OK).
+* The directive must be written with double or single quotes, not backticks.
+* The directive must exactly match `"use memo"`.
+* Only the first directive in a function is processed; additional directives are ignored.
+* The effect of the directive depends on your [`compilationMode`](/reference/react-compiler/compilationMode) setting.
+
+### How `"use memo"` marks functions for optimization {/*how-use-memo-marks*/}
+
+In a React app that uses the React Compiler, functions are analyzed at build time to determine if they can be optimized. By default, the compiler automatically infers which components to memoize, but this can depend on your [`compilationMode`](/reference/react-compiler/compilationMode) setting if you've set it.
+
+`"use memo"` explicitly marks a function for optimization, overriding the default behavior:
+
+* In `annotation` mode: Only functions with `"use memo"` are optimized
+* In `infer` mode: The compiler uses heuristics, but `"use memo"` forces optimization
+* In `all` mode: Everything is optimized by default, making `"use memo"` redundant
+
+The directive creates a clear boundary in your codebase between optimized and non-optimized code, giving you fine-grained control over the compilation process.
+
+### When to use `"use memo"` {/*when-to-use*/}
+
+You should consider using `"use memo"` when:
+
+#### You're using annotation mode {/*annotation-mode-use*/}
+In `compilationMode: 'annotation'`, the directive is required for any function you want optimized:
+
+```js
+// ✅ This component will be optimized
+function OptimizedList() {
+  "use memo";
+  // ...
+}
+
+// ❌ This component won't be optimized
+function SimpleWrapper() {
+  // ...
+}
+```
+
+#### You're gradually adopting React Compiler {/*gradual-adoption*/}
+Start with `annotation` mode and selectively optimize stable components:
+
+```js
+// Start by optimizing leaf components
+function Button({ onClick, children }) {
+  "use memo";
+  // ...
+}
+
+// Gradually move up the tree as you verify behavior
+function ButtonGroup({ buttons }) {
+  "use memo";
+  // ...
+}
+```
+
+---
+
+## Usage {/*usage*/}
+
+### Working with different compilation modes {/*compilation-modes*/}
+
+The behavior of `"use memo"` changes based on your compiler configuration:
+
+```js
+// babel.config.js
+module.exports = {
+  plugins: [
+    ['babel-plugin-react-compiler', {
+      compilationMode: 'annotation' // or 'infer' or 'all'
+    }]
+  ]
+};
+```
+
+#### Annotation mode {/*annotation-mode-example*/}
+```js
+// ✅ Optimized with "use memo"
+function ProductCard({ product }) {
+  "use memo";
+  // ...
+}
+
+// ❌ Not optimized (no directive)
+function ProductList({ products }) {
+  // ...
+}
+```
+
+#### Infer mode (default) {/*infer-mode-example*/}
+```js
+// Automatically memoized because this is named like a Component
+function ComplexDashboard({ data }) {
+  // ...
+}
+
+// Skipped: Is not named like a Component
+function simpleDisplay({ text }) {
+  // ...
+}
+```
+
+In `infer` mode, the compiler automatically detects components and hooks by their naming patterns (PascalCase for components, `use` prefix for hooks). If a component or hook isn't being compiled in `infer` mode, you should fix its naming convention rather than forcing compilation with `"use memo"`.
+
+---
+
+## Troubleshooting {/*troubleshooting*/}
+
+### Verifying optimization {/*verifying-optimization*/}
+
+To confirm your component is being optimized:
+
+1. Check the compiled output in your build
+2. Use React DevTools to check for Memo ✨ badge
+
+### See also {/*see-also*/}
+
+* [`"use no memo"`](/reference/react-compiler/directives/use-no-memo) - Opt out of compilation
+* [`compilationMode`](/reference/react-compiler/compilationMode) - Configure compilation behavior
+* [React Compiler](/learn/react-compiler) - Getting started guide
\ No newline at end of file
diff --git a/src/content/reference/react-compiler/directives/use-no-memo.md b/src/content/reference/react-compiler/directives/use-no-memo.md
new file mode 100644
index 0000000000..e6c419bc66
--- /dev/null
+++ b/src/content/reference/react-compiler/directives/use-no-memo.md
@@ -0,0 +1,147 @@
+---
+title: "use no memo"
+titleForTitleTag: "'use no memo' directive"
+---
+
+<Intro>
+
+`"use no memo"` prevents a function from being optimized by React Compiler.
+
+</Intro>
+
+<InlineToc />
+
+---
+
+## Reference {/*reference*/}
+
+### `"use no memo"` {/*use-no-memo*/}
+
+Add `"use no memo"` at the beginning of a function to prevent React Compiler optimization.
+
+```js {1}
+function MyComponent() {
+  "use no memo";
+  // ...
+}
+```
+
+When a function contains `"use no memo"`, the React Compiler will skip it entirely during optimization. This is useful as a temporary escape hatch when debugging or when dealing with code that doesn't work correctly with the compiler.
+
+#### Caveats {/*caveats*/}
+
+* `"use no memo"` must be at the very beginning of a function body, before any imports or other code (comments are OK).
+* The directive must be written with double or single quotes, not backticks.
+* The directive must exactly match `"use no memo"` or its alias `"use no forget"`.
+* This directive takes precedence over all compilation modes and other directives.
+* It's intended as a temporary debugging tool, not a permanent solution.
+
+### How `"use no memo"` opts-out of optimization {/*how-use-no-memo-opts-out*/}
+
+React Compiler analyzes your code at build time to apply optimizations. `"use no memo"` creates an explicit boundary that tells the compiler to skip a function entirely.
+
+This directive takes precedence over all other settings:
+* In `all` mode: The function is skipped despite the global setting
+* In `infer` mode: The function is skipped even if heuristics would optimize it
+
+The compiler treats these functions as if the React Compiler wasn't enabled, leaving them exactly as written.
+
+### When to use `"use no memo"` {/*when-to-use*/}
+
+`"use no memo"` should be used sparingly and temporarily. Common scenarios include:
+
+#### Debugging compiler issues {/*debugging-compiler*/}
+When you suspect the compiler is causing issues, temporarily disable optimization to isolate the problem:
+
+```js
+function ProblematicComponent({ data }) {
+  "use no memo"; // TODO: Remove after fixing issue #123
+
+  // Rules of React violations that weren't statically detected
+  // ...
+}
+```
+
+#### Third-party library integration {/*third-party*/}
+When integrating with libraries that might not be compatible with the compiler:
+
+```js
+function ThirdPartyWrapper() {
+  "use no memo";
+
+  useThirdPartyHook(); // Has side effects that compiler might optimize incorrectly
+  // ...
+}
+```
+
+---
+
+## Usage {/*usage*/}
+
+The `"use no memo"` directive is placed at the beginning of a function body to prevent React Compiler from optimizing that function:
+
+```js
+function MyComponent() {
+  "use no memo";
+  // Function body
+}
+```
+
+The directive can also be placed at the top of a file to affect all functions in that module:
+
+```js
+"use no memo";
+
+// All functions in this file will be skipped by the compiler
+```
+
+`"use no memo"` at the function level overrides the module level directive.
+
+---
+
+## Troubleshooting {/*troubleshooting*/}
+
+### Directive not preventing compilation {/*not-preventing*/}
+
+If `"use no memo"` isn't working:
+
+```js
+// ❌ Wrong - directive after code
+function Component() {
+  const data = getData();
+  "use no memo"; // Too late!
+}
+
+// ✅ Correct - directive first
+function Component() {
+  "use no memo";
+  const data = getData();
+}
+```
+
+Also check:
+* Spelling - must be exactly `"use no memo"`
+* Quotes - must use single or double quotes, not backticks
+
+### Best practices {/*best-practices*/}
+
+**Always document why** you're disabling optimization:
+
+```js
+// ✅ Good - clear explanation and tracking
+function DataProcessor() {
+  "use no memo"; // TODO: Remove after fixing rule of react violation
+  // ...
+}
+
+// ❌ Bad - no explanation
+function Mystery() {
+  "use no memo";
+  // ...
+}
+```
+
+### See also {/*see-also*/}
+
+* [`"use memo"`](/reference/react-compiler/directives/use-memo) - Opt into compilation
+* [React Compiler](/learn/react-compiler) - Getting started guide
\ No newline at end of file
diff --git a/src/content/reference/react-compiler/gating.md b/src/content/reference/react-compiler/gating.md
new file mode 100644
index 0000000000..479506af32
--- /dev/null
+++ b/src/content/reference/react-compiler/gating.md
@@ -0,0 +1,141 @@
+---
+title: gating
+---
+
+<Intro>
+
+The `gating` option enables conditional compilation, allowing you to control when optimized code is used at runtime.
+
+</Intro>
+
+```js
+{
+  gating: {
+    source: 'my-feature-flags',
+    importSpecifierName: 'shouldUseCompiler'
+  }
+}
+```
+
+<InlineToc />
+
+---
+
+## Reference {/*reference*/}
+
+### `gating` {/*gating*/}
+
+Configures runtime feature flag gating for compiled functions.
+
+#### Type {/*type*/}
+
+```
+{
+  source: string;
+  importSpecifierName: string;
+} | null
+```
+
+#### Default value {/*default-value*/}
+
+`null`
+
+#### Properties {/*properties*/}
+
+- **`source`**: Module path to import the feature flag from
+- **`importSpecifierName`**: Name of the exported function to import
+
+#### Caveats {/*caveats*/}
+
+- The gating function must return a boolean
+- Both compiled and original versions increase bundle size
+- The import is added to every file with compiled functions
+
+---
+
+## Usage {/*usage*/}
+
+### Basic feature flag setup {/*basic-setup*/}
+
+1. Create a feature flag module:
+
+```js
+// src/utils/feature-flags.js
+export function shouldUseCompiler() {
+  // your logic here
+  return getFeatureFlag('react-compiler-enabled');
+}
+```
+
+2. Configure the compiler:
+
+```js
+{
+  gating: {
+    source: './src/utils/feature-flags',
+    importSpecifierName: 'shouldUseCompiler'
+  }
+}
+```
+
+3. The compiler generates gated code:
+
+```js
+// Input
+function Button(props) {
+  return <button>{props.label}</button>;
+}
+
+// Output (simplified)
+import { shouldUseCompiler } from './src/utils/feature-flags';
+
+const Button = shouldUseCompiler()
+  ? function Button_optimized(props) { /* compiled version */ }
+  : function Button_original(props) { /* original version */ };
+```
+
+Note that the gating function is evaluated once at module time, so once the JS bundle has been parsed and evaluated the choice of component stays static for the rest of the browser session.
+
+---
+
+## Troubleshooting {/*troubleshooting*/}
+
+### Feature flag not working {/*flag-not-working*/}
+
+Verify your flag module exports the correct function:
+
+```js
+// ❌ Wrong: Default export
+export default function shouldUseCompiler() {
+  return true;
+}
+
+// ✅ Correct: Named export matching importSpecifierName
+export function shouldUseCompiler() {
+  return true;
+}
+```
+
+### Import errors {/*import-errors*/}
+
+Ensure the source path is correct:
+
+```js
+// ❌ Wrong: Relative to babel.config.js
+{
+  source: './src/flags',
+  importSpecifierName: 'flag'
+}
+
+// ✅ Correct: Module resolution path
+{
+  source: '@myapp/feature-flags',
+  importSpecifierName: 'flag'
+}
+
+// ✅ Also correct: Absolute path from project root
+{
+  source: './src/utils/flags',
+  importSpecifierName: 'flag'
+}
+```
diff --git a/src/content/reference/react-compiler/logger.md b/src/content/reference/react-compiler/logger.md
new file mode 100644
index 0000000000..41e2a1da06
--- /dev/null
+++ b/src/content/reference/react-compiler/logger.md
@@ -0,0 +1,118 @@
+---
+title: logger
+---
+
+<Intro>
+
+The `logger` option provides custom logging for React Compiler events during compilation.
+
+</Intro>
+
+```js
+{
+  logger: {
+    logEvent(filename, event) {
+      console.log(`[Compiler] ${event.kind}: ${filename}`);
+    }
+  }
+}
+```
+
+<InlineToc />
+
+---
+
+## Reference {/*reference*/}
+
+### `logger` {/*logger*/}
+
+Configures custom logging to track compiler behavior and debug issues.
+
+#### Type {/*type*/}
+
+```
+{
+  logEvent: (filename: string | null, event: LoggerEvent) => void;
+} | null
+```
+
+#### Default value {/*default-value*/}
+
+`null`
+
+#### Methods {/*methods*/}
+
+- **`logEvent`**: Called for each compiler event with the filename and event details
+
+#### Event types {/*event-types*/}
+
+- **`CompileSuccess`**: Function successfully compiled
+- **`CompileError`**: Function skipped due to errors
+- **`CompileDiagnostic`**: Non-fatal diagnostic information
+- **`CompileSkip`**: Function skipped for other reasons
+- **`PipelineError`**: Unexpected compilation error
+- **`Timing`**: Performance timing information
+
+#### Caveats {/*caveats*/}
+
+- Event structure may change between versions
+- Large codebases generate many log entries
+
+---
+
+## Usage {/*usage*/}
+
+### Basic logging {/*basic-logging*/}
+
+Track compilation success and failures:
+
+```js
+{
+  logger: {
+    logEvent(filename, event) {
+      switch (event.kind) {
+        case 'CompileSuccess': {
+          console.log(`✅ Compiled: ${filename}`);
+          break;
+        }
+        case 'CompileError': {
+          console.log(`❌ Skipped: ${filename}`);
+          break;
+        }
+        default: {}
+      }
+    }
+  }
+}
+```
+
+### Detailed error logging {/*detailed-error-logging*/}
+
+Get specific information about compilation failures:
+
+```js
+{
+  logger: {
+    logEvent(filename, event) {
+      if (event.kind === 'CompileError') {
+        console.error(`\nCompilation failed: ${filename}`);
+        console.error(`Reason: ${event.detail.reason}`);
+
+        if (event.detail.description) {
+          console.error(`Details: ${event.detail.description}`);
+        }
+
+        if (event.detail.loc) {
+          const { line, column } = event.detail.loc.start;
+          console.error(`Location: Line ${line}, Column ${column}`);
+        }
+
+        if (event.detail.suggestions) {
+          console.error('Suggestions:', event.detail.suggestions);
+        }
+      }
+    }
+  }
+}
+```
+
diff --git a/src/content/reference/react-compiler/panicThreshold.md b/src/content/reference/react-compiler/panicThreshold.md
new file mode 100644
index 0000000000..e20f5c0c50
--- /dev/null
+++ b/src/content/reference/react-compiler/panicThreshold.md
@@ -0,0 +1,87 @@
+---
+title: panicThreshold
+---
+
+<Intro>
+
+The `panicThreshold` option controls how the React Compiler handles errors during compilation.
+
+</Intro>
+
+```js
+{
+  panicThreshold: 'none' // Recommended
+}
+```
+
+<InlineToc />
+
+---
+
+## Reference {/*reference*/}
+
+### `panicThreshold` {/*panicthreshold*/}
+
+Determines whether compilation errors should fail the build or skip optimization.
+
+#### Type {/*type*/}
+
+```
+'none' | 'critical_errors' | 'all_errors'
+```
+
+#### Default value {/*default-value*/}
+
+`'none'`
+
+#### Options {/*options*/}
+
+- **`'none'`** (default, recommended): Skip components that can't be compiled and continue building
+- **`'critical_errors'`**: Fail the build only on critical compiler errors
+- **`'all_errors'`**: Fail the build on any compiler diagnostic
+
+#### Caveats {/*caveats*/}
+
+- Production builds should always use `'none'`
+- Build failures prevent your application from building
+- The compiler automatically detects and skips problematic code with `'none'`
+- Higher thresholds are only useful during development for debugging
+
+---
+
+## Usage {/*usage*/}
+
+### Production configuration (recommended) {/*production-configuration*/}
+
+For production builds, always use `'none'`. This is the default value:
+
+```js
+{
+  panicThreshold: 'none'
+}
+```
+
+This ensures:
+- Your build never fails due to compiler issues
+- Components that can't be optimized run normally
+- Maximum components get optimized
+- Stable production deployments
+
+### Development debugging {/*development-debugging*/}
+
+Temporarily use stricter thresholds to find issues:
+
+```js
+const isDevelopment = process.env.NODE_ENV === 'development';
+
+{
+  panicThreshold: isDevelopment ? 'critical_errors' : 'none',
+  logger: {
+    logEvent(filename, event) {
+      if (isDevelopment && event.kind === 'CompileError') {
+        // ...
+      }
+    }
+  }
+}
+```
\ No newline at end of file
diff --git a/src/content/reference/react-compiler/target.md b/src/content/reference/react-compiler/target.md
new file mode 100644
index 0000000000..381748513d
--- /dev/null
+++ b/src/content/reference/react-compiler/target.md
@@ -0,0 +1,148 @@
+---
+title: target
+---
+
+<Intro>
+
+The `target` option specifies which React version the compiler should generate code for.
+
+</Intro>
+
+```js
+{
+  target: '19' // or '18', '17'
+}
+```
+
+<InlineToc />
+
+---
+
+## Reference {/*reference*/}
+
+### `target` {/*target*/}
+
+Configures the React version compatibility for the compiled output.
+
+#### Type {/*type*/}
+
+```
+'17' | '18' | '19'
+```
+
+#### Default value {/*default-value*/}
+
+`'19'`
+
+#### Valid values {/*valid-values*/}
+
+- **`'19'`**: Target React 19 (default). No additional runtime required.
+- **`'18'`**: Target React 18. Requires `react-compiler-runtime` package.
+- **`'17'`**: Target React 17. Requires `react-compiler-runtime` package.
+
+#### Caveats {/*caveats*/}
+
+- Always use string values, not numbers (e.g., `'17'` not `17`)
+- Don't include patch versions (e.g., use `'18'` not `'18.2.0'`)
+- React 19 includes built-in compiler runtime APIs
+- React 17 and 18 require installing `react-compiler-runtime@rc`
+
+---
+
+## Usage {/*usage*/}
+
+### Targeting React 19 (default) {/*targeting-react-19*/}
+
+For React 19, no special configuration is needed:
+
+```js
+{
+  // defaults to target: '19'
+}
+```
+
+The compiler will use React 19's built-in runtime APIs:
+
+```js
+// Compiled output uses React 19's native APIs
+import { c as _c } from 'react/compiler-runtime';
+```
+
+### Targeting React 17 or 18 {/*targeting-react-17-or-18*/}
+
+For React 17 and React 18 projects, you need two steps:
+
+1. Install the runtime package:
+
+```bash
+npm install react-compiler-runtime@rc
+```
+
+2. Configure the target:
+
+```js
+// For React 18
+{
+  target: '18'
+}
+
+// For React 17
+{
+  target: '17'
+}
+```
+
+The compiler will use the polyfill runtime for both versions:
+
+```js
+// Compiled output uses the polyfill
+import { c as _c } from 'react-compiler-runtime';
+```
+
+---
+
+## Troubleshooting {/*troubleshooting*/}
+
+### Runtime errors about missing compiler runtime {/*missing-runtime*/}
+
+If you see errors like "Cannot find module 'react/compiler-runtime'":
+
+1. Check your React version:
+   ```bash
+   npm why react
+   ```
+
+2. If using React 17 or 18, install the runtime:
+   ```bash
+   npm install react-compiler-runtime@rc
+   ```
+
+3. Ensure your target matches your React version:
+   ```js
+   {
+     target: '18' // Must match your React major version
+   }
+   ```
+
+### Runtime package not working {/*runtime-not-working*/}
+
+Ensure the runtime package is:
+
+1. Installed in your project (not globally)
+2. Listed in your `package.json` dependencies
+3. The correct version (`@rc` tag)
+4. Not in `devDependencies` (it's needed at runtime)
+
+### Checking compiled output {/*checking-output*/}
+
+To verify the correct runtime is being used, note the different import (`react/compiler-runtime` for builtin, `react-compiler-runtime` standalone package for 17/18):
+
+```js
+// For React 19 (built-in runtime)
+import { c } from 'react/compiler-runtime'
+//                      ^
+
+// For React 17/18 (polyfill runtime)
+import { c } from 'react-compiler-runtime'
+//                      ^
+```
\ No newline at end of file
diff --git a/src/content/reference/react-dom/client/createRoot.md b/src/content/reference/react-dom/client/createRoot.md
index 7723a7be96..27fe322fa4 100644
--- a/src/content/reference/react-dom/client/createRoot.md
+++ b/src/content/reference/react-dom/client/createRoot.md
@@ -208,7 +208,7 @@ function Counter() {
 <div id="root"></div>
 ```
 
-这个过程太慢了！要解决这个问题，可以在 [服务端或者应用构建期间](/reference/react-dom/server) 通过组件生成一些初始 HTML。这样一来，在 JavaScript 加载之前，用户就能看到一些文字、图片，也能点击链接。我们推荐 [使用框架](/learn/start-a-new-react-project#production-grade-react-frameworks)，通过框架开箱即用的能力轻易地完成这个优化。根据框架运行的时机，分为 **服务端渲染（SSR）** 和 **静态站点生成（SSG）**。
+这个过程太慢了！要解决这个问题，可以在 [服务端或者应用构建期间](/reference/react-dom/server) 通过组件生成一些初始 HTML。这样一来，在 JavaScript 加载之前，用户就能看到一些文字、图片，也能点击链接。我们推荐 [使用框架](/learn/start-a-new-react-project#full-stack-frameworks)，通过框架开箱即用的能力轻易地完成这个优化。根据框架运行的时机，分为 **服务端渲染（SSR）** 和 **静态站点生成（SSG）**。
 
 </Note>
 
diff --git a/src/content/reference/react-dom/client/index.md b/src/content/reference/react-dom/client/index.md
index 6e6d24751f..238f947ad8 100644
--- a/src/content/reference/react-dom/client/index.md
+++ b/src/content/reference/react-dom/client/index.md
@@ -6,7 +6,7 @@ translators:
 
 <Intro>
 
-`react-dom/client` API 允许你在客户端（浏览器）渲染 React 组件。这些 API 通常在应用程序顶层调用，以初始化 React 树。有的 [框架](/learn/start-a-new-react-project#production-grade-react-frameworks) 可能会为你调用相关 API，大多数组件不需要导入和使用这些 API。
+`react-dom/client` API 允许你在客户端（浏览器）渲染 React 组件。这些 API 通常在应用程序顶层调用，以初始化 React 树。有的 [框架](/learn/start-a-new-react-project#full-stack-frameworks) 可能会为你调用相关 API，大多数组件不需要导入和使用这些 API。
 
 </Intro>
 
diff --git a/src/content/reference/react-dom/components/common.md b/src/content/reference/react-dom/components/common.md
index 8a6ad6a3af..387b31b5bd 100644
--- a/src/content/reference/react-dom/components/common.md
+++ b/src/content/reference/react-dom/components/common.md
@@ -916,7 +916,7 @@ export default function Form() {
 
 </Sandpack>
 
-阅读更多关于 [使用 ref 操纵 DOM](/learn/manipulating-the-dom-with-refs) 的内容并 [查看更多示例](/reference/react/useRef#examples-dom)。
+阅读更多关于 [使用 ref 操纵 DOM](/learn/manipulating-the-dom-with-refs) 的内容并 [查看更多示例](/reference/react/useRef#usage)。
 
 对于更高级的用例，`ref` 属性还可以接受 [回调函数](#ref-callback)。
 
diff --git a/src/content/reference/react-dom/components/form.md b/src/content/reference/react-dom/components/form.md
index 115e6a4cd2..356637bcdc 100644
--- a/src/content/reference/react-dom/components/form.md
+++ b/src/content/reference/react-dom/components/form.md
@@ -36,7 +36,7 @@ To create interactive controls for submitting information, render the [built-in
 
 #### Props {/*props*/}
 
-`<form>` supports all [common element props.](/reference/react-dom/components/common#props)
+`<form>` supports all [common element props.](/reference/react-dom/components/common#common-props)
 
 [`action`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/form#action): a URL or function. When a URL is passed to `action` the form will behave like the HTML form component. When a function is passed to `action` the function will handle the form submission. The function passed to `action` may be async and will be called with a single argument containing the [form data](https://developer.mozilla.org/en-US/docs/Web/API/FormData) of the submitted form. The `action` prop can be overridden by a `formAction` attribute on a `<button>`, `<input type="submit">`, or `<input type="image">` component.
 
@@ -230,7 +230,7 @@ export async function deliverMessage(message) {
 </Sandpack>
 
 [//]: # 'Uncomment the next line, and delete this line after the `useOptimistic` reference documentatino page is published'
-[//]: # 'To learn more about the `useOptimistic` Hook see the [reference documentation](/reference/react/hooks/useOptimistic).'
+[//]: # 'To learn more about the `useOptimistic` Hook see the [reference documentation](/reference/react/useOptimistic).'
 
 ### Handling form submission errors {/*handling-form-submission-errors*/}
 
diff --git a/src/content/reference/react-dom/components/input.md b/src/content/reference/react-dom/components/input.md
index 0e6c850e69..ee1acfa6d0 100644
--- a/src/content/reference/react-dom/components/input.md
+++ b/src/content/reference/react-dom/components/input.md
@@ -30,7 +30,7 @@ title: "<input>"
 
 #### 属性 {/*props*/}
 
-`<input>` 支持所有 [常见的元素属性](/reference/react-dom/components/common#props)。
+`<input>` 支持所有 [常见的元素属性](/reference/react-dom/components/common#common-props)。
 
 [`formAction`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#formaction): 字符串或函数。设置了 `type="submit"` 或 `type="image"` 属性的 `input` 标签，会覆盖父表单对应属性 `<form action>`。当向 `formAction` 传递 URL 时，表单会表现为标准 HTML 表单；当传递函数时，该函数将处理表单提交。详见 [`<form action>`](/reference/react-dom/components/form#props)。
 
diff --git a/src/content/reference/react-dom/components/link.md b/src/content/reference/react-dom/components/link.md
index b4900feedc..17075c4c38 100644
--- a/src/content/reference/react-dom/components/link.md
+++ b/src/content/reference/react-dom/components/link.md
@@ -30,7 +30,7 @@ link: "<link>"
 
 #### 属性 {/*props*/}
 
-`<link>` 支持所有 [常见元素属性](/reference/react-dom/components/common#props)。
+`<link>` 支持所有 [常见元素属性](/reference/react-dom/components/common#common-props)。
 
 * `rel`：字符串，必需字段，用于指定 [与资源的关系](https://developer.mozilla.org/zh-CN/docs/Web/HTML/Attributes/rel)。React [将具有 `rel="stylesheet"` 的链接](#special-rendering-behavior) 与其他链接区别对待。
 
diff --git a/src/content/reference/react-dom/components/meta.md b/src/content/reference/react-dom/components/meta.md
index 381faaf3e8..7a70524afe 100644
--- a/src/content/reference/react-dom/components/meta.md
+++ b/src/content/reference/react-dom/components/meta.md
@@ -30,7 +30,7 @@ meta: "<meta>"
 
 #### 属性 {/*props*/}
 
-`<meta>` 支持所有 [常见元素属性](/reference/react-dom/components/common#props)。
+`<meta>` 支持所有 [常见元素属性](/reference/react-dom/components/common#common-props)。
 
 它应该有恰好一个以下属性之一：`name`、`httpEquiv`、`charset` 或 `itemProp`。根据指定的属性，`<meta>` 组件会执行不同的操作。
 
diff --git a/src/content/reference/react-dom/components/option.md b/src/content/reference/react-dom/components/option.md
index 4fa5a13c65..6b2f64f2b6 100644
--- a/src/content/reference/react-dom/components/option.md
+++ b/src/content/reference/react-dom/components/option.md
@@ -36,7 +36,7 @@ title: "<option>"
 
 #### Props {/*props*/}
 
-`<option>` 支持所有 [常见的元素属性](/reference/react-dom/components/common#props)。
+`<option>` 支持所有 [常见的元素属性](/reference/react-dom/components/common#common-props)。
 
 除此之外，`<option>` 还支持以下属性：
 
diff --git a/src/content/reference/react-dom/components/progress.md b/src/content/reference/react-dom/components/progress.md
index 3e007e6b29..ac2c88af39 100644
--- a/src/content/reference/react-dom/components/progress.md
+++ b/src/content/reference/react-dom/components/progress.md
@@ -30,7 +30,7 @@ title: "<progress>"
 
 #### 参数 {/*props*/}
 
-`<progress>` 支持所有 [常见的元素属性](/reference/react-dom/components/common#props)。
+`<progress>` 支持所有 [常见的元素属性](/reference/react-dom/components/common#common-props)。
 
 除此之外，`<progress>` 还支持以下属性：
 
diff --git a/src/content/reference/react-dom/components/script.md b/src/content/reference/react-dom/components/script.md
index 7f449dccb1..4e3163cc80 100644
--- a/src/content/reference/react-dom/components/script.md
+++ b/src/content/reference/react-dom/components/script.md
@@ -31,7 +31,7 @@ script: "<script>"
 
 #### 属性 {/*props*/}
 
-`<script>` 支持所有 [通用元素属性](/reference/react-dom/components/common#props)。
+`<script>` 支持所有 [通用元素属性](/reference/react-dom/components/common#common-props)。
 
 它应该要么具有 `children` 属性，要么具有 `src` 属性。
 
diff --git a/src/content/reference/react-dom/components/select.md b/src/content/reference/react-dom/components/select.md
index 13c54ee27c..a1c8407919 100644
--- a/src/content/reference/react-dom/components/select.md
+++ b/src/content/reference/react-dom/components/select.md
@@ -36,7 +36,7 @@ title: "<select>"
 
 #### 属性 {/*props*/}
 
-`<select>` 支持所有 [常见的元素属性](/reference/react-dom/components/common#props)。
+`<select>` 支持所有 [常见的元素属性](/reference/react-dom/components/common#common-props)。
 
 你可以通过传递 `value` 属性 [以控制选择框](#controlling-a-select-box-with-a-state-variable):
 
diff --git a/src/content/reference/react-dom/components/style.md b/src/content/reference/react-dom/components/style.md
index f10f1d4c23..685a64980c 100644
--- a/src/content/reference/react-dom/components/style.md
+++ b/src/content/reference/react-dom/components/style.md
@@ -30,7 +30,7 @@ style: "<style>"
 
 #### 属性 {/*props*/}
 
-`<style>` 支持所有 [常见元素属性](/reference/react-dom/components/common#props)。
+`<style>` 支持所有 [常见元素属性](/reference/react-dom/components/common#common-props)。
 
 * `children`：字符串，必需字段，表示样式表的内容。
 * `precedence`：字符串，告诉 React 在文档 `<head>` 中排列 `<style>` DOM 节点的位置，确定哪个样式表可以覆盖另一个。React 会推断其首先发现的 `precedence` 值为“较低”，而后来发现的 `precedence` 值为“较高”。许多样式系统使用单个 `precedence` 值能够很好地工作，因为样式规则是原子的。无论是 `<link>` 还是内联 `<style>` 标签，或者使用 [`preinit`](/reference/react-dom/preinit) 函数加载的样式表，具有相同优先级的将一起处理。
diff --git a/src/content/reference/react-dom/components/textarea.md b/src/content/reference/react-dom/components/textarea.md
index cc4d7aa03a..ddd03a704c 100644
--- a/src/content/reference/react-dom/components/textarea.md
+++ b/src/content/reference/react-dom/components/textarea.md
@@ -30,7 +30,7 @@ title: "<textarea>"
 
 #### 属性 {/*props*/}
 
-`<textarea>` 支持所有 [常见的元素属性](/reference/react-dom/components/common#props)。
+`<textarea>` 支持所有 [常见的元素属性](/reference/react-dom/components/common#common-props)。
 
 你可以通过传递 `value` 属性 [以控制文本框](#controlling-a-text-area-with-a-state-variable)。
 
diff --git a/src/content/reference/react-dom/components/title.md b/src/content/reference/react-dom/components/title.md
index a499ba2af3..06981e1546 100644
--- a/src/content/reference/react-dom/components/title.md
+++ b/src/content/reference/react-dom/components/title.md
@@ -30,7 +30,7 @@ title: "<title>"
 
 #### 属性 {/*props*/}
 
-`<title>` 支持所有 [常见元素属性](/reference/react-dom/components/common#props)。
+`<title>` 支持所有 [常见元素属性](/reference/react-dom/components/common#common-props)。
 
 * `children`：`<title>` 只接受文本作为子元素。该文本将成为文档的标题，也可以传递只渲染文本的自定义组件。
 
diff --git a/src/content/reference/react-dom/createPortal.md b/src/content/reference/react-dom/createPortal.md
index 4fa5b54785..428ca4677c 100644
--- a/src/content/reference/react-dom/createPortal.md
+++ b/src/content/reference/react-dom/createPortal.md
@@ -50,7 +50,7 @@ portal 只改变 DOM 节点的所处位置。在其他方面，渲染至 portal
 
 * `domNode`：某个已经存在的 DOM 节点，例如由 `document.getElementById()` 返回的节点。在更新过程中传递不同的 DOM 节点将导致 portal 内容被重建。
 
-* **可选参数** `key`：用作 portal [key](/learn/rendering-lists/#keeping-list-items-in-order-with-key) 的独特字符串或数字。
+* **可选参数** `key`：用作 portal [key](/learn/rendering-lists#keeping-list-items-in-order-with-key) 的独特字符串或数字。
 
 #### 返回值 {/*returns*/}
 
diff --git a/src/content/reference/react-dom/server/index.md b/src/content/reference/react-dom/server/index.md
index 53510b10a3..49464ae793 100644
--- a/src/content/reference/react-dom/server/index.md
+++ b/src/content/reference/react-dom/server/index.md
@@ -4,7 +4,7 @@ title: Server React DOM API
 
 <Intro>
 
-`react-dom/server` API 允许你通过服务端渲染将 React 组件渲染为 HTML。这些 API 仅在服务器应用程序顶层调用，以生成初始 HTML。有的 [框架](/learn/start-a-new-react-project#production-grade-react-frameworks) 可能会为你调用相关 API。大多数组件不需要导入或使用这些 API。
+`react-dom/server` API 允许你通过服务端渲染将 React 组件渲染为 HTML。这些 API 仅在服务器应用程序顶层调用，以生成初始 HTML。有的 [框架](/learn/start-a-new-react-project#full-stack-frameworks) 可能会为你调用相关 API。大多数组件不需要导入或使用这些 API。
 
 </Intro>
 
diff --git a/src/content/reference/react-dom/static/index.md b/src/content/reference/react-dom/static/index.md
index 82762ae342..97e6949d5d 100644
--- a/src/content/reference/react-dom/static/index.md
+++ b/src/content/reference/react-dom/static/index.md
@@ -4,7 +4,7 @@ title: Static React DOM APIs
 
 <Intro>
 
-`react-dom/static` API 允许你为 React 组件生成静态 HTML。与流式 API 相比，它们的功能有限。[框架](/learn/start-a-new-react-project#production-grade-react-frameworks) 可能会调用它们。你的大多数组件不需要导入或使用它们。
+`react-dom/static` API 允许你为 React 组件生成静态 HTML。与流式 API 相比，它们的功能有限。[框架](/learn/start-a-new-react-project#full-stack-frameworks) 可能会调用它们。你的大多数组件不需要导入或使用它们。
 
 </Intro>
 
diff --git a/src/content/reference/react/ViewTransition.md b/src/content/reference/react/ViewTransition.md
index b0dc7b571b..653a06a635 100644
--- a/src/content/reference/react/ViewTransition.md
+++ b/src/content/reference/react/ViewTransition.md
@@ -143,7 +143,7 @@ In the future, CSS libraries may add built-in animations using View Transition C
 
 #### Caveats {/*caveats*/}
 
-- By default, `setState` updates immediately and does not activate `<ViewTransition>`, only updates wrapped in a [Transition](/reference/react/useTransition). You can also use [`<Suspense>`](/reference/react/Suspense) to opt-in to a Transition to [reveal content](/link-to-suspense-below).
+- By default, `setState` updates immediately and does not activate `<ViewTransition>`, only updates wrapped in a [Transition](/reference/react/useTransition). You can also use [`<Suspense>`](/reference/react/Suspense) to opt-in to a Transition to [reveal content](/reference/react/Suspense#revealing-content-together-at-once).
 - `<ViewTransition>` creates an image that can be moved around, scaled and cross-faded. Unlike Layout Animations you may have seen in React Native or Motion, this means that not every individual Element inside of it animates its position. This can lead to better performance and a more continuous feeling, smooth animation compared to animating every individual piece. However, it can also lose continuity in things that should be moving by themselves. So you might have to add more `<ViewTransition>` boundaries manually as a result.
 - Many users may prefer not having animations on the page. React doesn't automatically disable animations for this case. We recommend that using the `@media (prefers-reduced-motion)` media query to disable animations or tone them down based on user preference. In the future, CSS libraries may have this built-in to their presets.
 - Currently, `<ViewTransition>` only works in the DOM. We're working on adding support for React Native and other platforms.
diff --git a/src/content/reference/react/captureOwnerStack.md b/src/content/reference/react/captureOwnerStack.md
index 6d8cc502d5..7e4fe79fe1 100644
--- a/src/content/reference/react/captureOwnerStack.md
+++ b/src/content/reference/react/captureOwnerStack.md
@@ -57,7 +57,7 @@ If no Owner Stack is available, `null` is returned (see [Troubleshooting: The Ow
 
 #### Owner Stack vs Component Stack {/*owner-stack-vs-component-stack*/}
 
-The Owner Stack is different from the Component Stack available in React error handlers like [`errorInfo.componentStack` in `onUncaughtError`](/reference/react-dom/client/hydrateRoot#show-a-dialog-for-uncaught-errors).
+The Owner Stack is different from the Component Stack available in React error handlers like [`errorInfo.componentStack` in `onUncaughtError`](/reference/react-dom/client/hydrateRoot#error-logging-in-production).
 
 For example, consider the following code:
 
diff --git a/src/content/reference/react/index.md b/src/content/reference/react/index.md
index 774dd40aa2..0ecb3964be 100644
--- a/src/content/reference/react/index.md
+++ b/src/content/reference/react/index.md
@@ -30,6 +30,14 @@ React-dom 仅支持在 web 应用程序中使用（在浏览器 DOM 环境中运
 * [服务端 API](/reference/react-dom/server) —— `react-dom/server` API 允许在服务器端将 React 组件渲染为 HTML。
 
 
+## React Compiler {/*react-compiler*/}
+
+The React Compiler is a build-time optimization tool that automatically memoizes your React components and values:
+
+* [Configuration](/reference/react-compiler/configuration) - Configuration options for React Compiler.
+* [Directives](/reference/react-compiler/directives) - Function-level directives to control compilation.
+* [Compiling Libraries](/reference/react-compiler/compiling-libraries) - Guide for shipping pre-compiled library code.
+
 ## Rules of React {/*rules-of-react*/}
 
 React 有一套表达模式的俗语与规则，它们以一种易于理解并能帮助实现高质量应用程序的方式表达出来：
diff --git a/src/content/reference/react/memo.md b/src/content/reference/react/memo.md
index ca9e00ef42..ad62988ce7 100644
--- a/src/content/reference/react/memo.md
+++ b/src/content/reference/react/memo.md
@@ -12,6 +12,12 @@ const MemoizedComponent = memo(SomeComponent, arePropsEqual?)
 
 </Intro>
 
+<Note>
+
+[React Compiler](/learn/react-compiler) automatically applies the equivalent of `memo` to all components, reducing the need for manual memoization. You can use the compiler to handle component memoization automatically.
+
+</Note>
+
 <InlineToc />
 
 ---
@@ -222,7 +228,7 @@ export default function MyApp() {
   const [theme, setTheme] = useState('dark');
 
   function handleClick() {
-    setTheme(theme === 'dark' ? 'light' : 'dark'); 
+    setTheme(theme === 'dark' ? 'light' : 'dark');
   }
 
   return (
@@ -357,6 +363,87 @@ function arePropsEqual(oldProps, newProps) {
 
 ---
 
+### Do I still need React.memo if I use React Compiler? {/*react-compiler-memo*/}
+
+When you enable [React Compiler](/learn/react-compiler), you typically don't need `React.memo` anymore. The compiler automatically optimizes component re-rendering for you.
+
+Here's how it works:
+
+**Without React Compiler**, you need `React.memo` to prevent unnecessary re-renders:
+
+```js
+// Parent re-renders every second
+function Parent() {
+  const [seconds, setSeconds] = useState(0);
+
+  useEffect(() => {
+    const interval = setInterval(() => {
+      setSeconds(s => s + 1);
+    }, 1000);
+    return () => clearInterval(interval);
+  }, []);
+
+  return (
+    <>
+      <h1>Seconds: {seconds}</h1>
+      <ExpensiveChild name="John" />
+    </>
+  );
+}
+
+// Without memo, this re-renders every second even though props don't change
+const ExpensiveChild = memo(function ExpensiveChild({ name }) {
+  console.log('ExpensiveChild rendered');
+  return <div>Hello, {name}!</div>;
+});
+```
+
+**With React Compiler enabled**, the same optimization happens automatically:
+
+```js
+// No memo needed - compiler prevents re-renders automatically
+function ExpensiveChild({ name }) {
+  console.log('ExpensiveChild rendered');
+  return <div>Hello, {name}!</div>;
+}
+```
+
+Here's the key part of what the React Compiler generates:
+
+```js {6-12}
+function Parent() {
+  const $ = _c(7);
+  const [seconds, setSeconds] = useState(0);
+  // ... other code ...
+
+  let t3;
+  if ($[4] === Symbol.for("react.memo_cache_sentinel")) {
+    t3 = <ExpensiveChild name="John" />;
+    $[4] = t3;
+  } else {
+    t3 = $[4];
+  }
+  // ... return statement ...
+}
+```
+
+Notice the highlighted lines: The compiler wraps `<ExpensiveChild name="John" />` in a cache check. Since the `name` prop is always `"John"`, this JSX is created once and reused on every parent re-render. This is exactly what `React.memo` does - it prevents the child from re-rendering when its props haven't changed.
+
+The React Compiler automatically:
+1. Tracks that the `name` prop passed to `ExpensiveChild` hasn't changed
+2. Reuses the previously created JSX for `<ExpensiveChild name="John" />`
+3. Skips re-rendering `ExpensiveChild` entirely
+
+This means **you can safely remove `React.memo` from your components when using React Compiler**. The compiler provides the same optimization automatically, making your code cleaner and easier to maintain.
+
+<Note>
+
+The compiler's optimization is actually more comprehensive than `React.memo`. It also memoizes intermediate values and expensive computations within your components, similar to combining `React.memo` with `useMemo` throughout your component tree.
+
+</Note>
+
+---
+
 ## 疑难解答 {/*troubleshooting*/}
 ### 当组件的某个 prop 是对象、数组或函数时，我的组件会重新渲染。 {/*my-component-rerenders-when-a-prop-is-an-object-or-array*/}
 
diff --git a/src/content/reference/react/use.md b/src/content/reference/react/use.md
index 7825e9a8e8..e804af6596 100644
--- a/src/content/reference/react/use.md
+++ b/src/content/reference/react/use.md
@@ -312,7 +312,7 @@ export default async function App() {
 }
 ```
 
-但是在 [服务器组件](/reference/react/components#server-components) 中使用 `await` 会在 `await` 执行完成前阻塞渲染。而将 Promise 从服务器组件传递到客户端组件可以防止 Promise 阻塞服务器组件渲染。
+但是在 [服务器组件](/reference/rsc/server-component) 中使用 `await` 会在 `await` 执行完成前阻塞渲染。而将 Promise 从服务器组件传递到客户端组件可以防止 Promise 阻塞服务器组件渲染。
 
 </DeepDive>
 
diff --git a/src/content/reference/react/useCallback.md b/src/content/reference/react/useCallback.md
index e3760ff5dd..ca5cd7df71 100644
--- a/src/content/reference/react/useCallback.md
+++ b/src/content/reference/react/useCallback.md
@@ -12,6 +12,12 @@ const cachedFn = useCallback(fn, dependencies)
 
 </Intro>
 
+<Note>
+
+[React Compiler](/learn/react-compiler) 会自动对值和函数进行记忆化处理，从而减少手动调用 `useCallback` 的需求。你可以使用编译器自动处理记忆化。
+
+</Note>
+
 <InlineToc />
 
 ---
diff --git a/src/content/reference/react/useEffect.md b/src/content/reference/react/useEffect.md
index 2af11bd1c7..42d372799c 100644
--- a/src/content/reference/react/useEffect.md
+++ b/src/content/reference/react/useEffect.md
@@ -896,7 +896,7 @@ button { margin: 5px; }
 
 ### 使用 Effect 请求数据 {/*fetching-data-with-effects*/}
 
-你可以使用 Effect 来为组件请求数据。请注意，[如果你使用框架](/learn/start-a-new-react-project#production-grade-react-frameworks)，使用框架的数据请求方式将比在 Effect 中手动编写要有效得多。
+你可以使用 Effect 来为组件请求数据。请注意，[如果你使用框架](/learn/start-a-new-react-project#full-stack-frameworks)，使用框架的数据请求方式将比在 Effect 中手动编写要有效得多。
 
 如果你想手动从 Effect 中请求数据，你的代码可能是这样的：
 
@@ -1048,7 +1048,7 @@ export async function fetchBio(person) {
 
 这些缺点并不仅仅体现在 React 上，它可能出现在所有挂载时请求数据的地方。与路由一样，要做好数据请求并非易事，因此我们推荐以下方法：
 
-- **如果正在使用 [框架](/learn/start-a-new-react-project#production-grade-react-frameworks)，那么请使用其内置的数据获取机制**。现代 React 框架已经集成了高效的数据获取机制，不会受到上述问题的影响。
+- **如果正在使用 [框架](/learn/start-a-new-react-project#full-stack-frameworks)，那么请使用其内置的数据获取机制**。现代 React 框架已经集成了高效的数据获取机制，不会受到上述问题的影响。
 - **否则，请考虑使用或构建客户端缓存**。流行的开源解决方案包括 [React Query](https://tanstack.com/query/latest/)、[useSWR](https://swr.vercel.app/) 和 [React Router v6.4+](https://beta.reactrouter.com/en/main/start/overview)。你也可以构建自己的解决方案，在这种情况下，你将在底层使用 Effect，但还需添加逻辑以避免重复请求、缓存响应并避免网络瀑布效应（通过预加载数据或将数据需求提升到路由级别）。
 
 如果这两种方法都不适合你，可以继续直接在 Effect 中请求数据。
@@ -1733,7 +1733,7 @@ function Page({ url, shoppingCart }) {
 
 ### 在服务器和客户端上显示不同的内容 {/*displaying-different-content-on-the-server-and-the-client*/}
 
-如果你的应用程序使用服务端（[直接](/reference/react-dom/server) 或通过 [框架](/learn/start-a-new-react-project#production-grade-react-frameworks)）渲染，你的组件将会在两个不同的环境中渲染。在服务器上，它将渲染生成初始 HTML。在客户端，React 将再次运行渲染代码，以便将事件处理附加到该 HTML 上。这就是为什么要让 [hydration](/reference/react-dom/client/hydrateRoot#hydrating-server-rendered-html) 发挥作用，你的初始渲染输出必须在客户端和服务器上完全相同。
+如果你的应用程序使用服务端（[直接](/reference/react-dom/server) 或通过 [框架](/learn/start-a-new-react-project#full-stack-frameworks)）渲染，你的组件将会在两个不同的环境中渲染。在服务器上，它将渲染生成初始 HTML。在客户端，React 将再次运行渲染代码，以便将事件处理附加到该 HTML 上。这就是为什么要让 [hydration](/reference/react-dom/client/hydrateRoot#hydrating-server-rendered-html) 发挥作用，你的初始渲染输出必须在客户端和服务器上完全相同。
 
 在极少数情况下，你可能需要在客户端上显示不同的内容。例如，如果你的应用从 [`localStorage`](https://developer.mozilla.org/zh-CN/docs/Web/API/Window/localStorage) 中读取某些数据，服务器上肯定不可能做到这一点。以下是这如何实现的：
 
diff --git a/src/content/reference/react/useInsertionEffect.md b/src/content/reference/react/useInsertionEffect.md
index ee02cc99a2..b9b7f1a092 100644
--- a/src/content/reference/react/useInsertionEffect.md
+++ b/src/content/reference/react/useInsertionEffect.md
@@ -131,7 +131,7 @@ function useCSS(rule) {
 
 #### 这与在渲染期间或 `useLayoutEffect` 中注入样式相比有何优势？ {/*how-is-this-better-than-injecting-styles-during-rendering-or-uselayouteffect*/}
 
-如果你在渲染期间注入样式并且 React 正在处理 [非阻塞更新](/reference/react/useTransition#marking-a-state-update-as-a-non-blocking-transition)，那么浏览器将在渲染组件树时每一帧都会重新计算样式，这可能会 **非常慢**。
+如果你在渲染期间注入样式并且 React 正在处理 [非阻塞更新](/reference/react/useTransition#perform-non-blocking-updates-with-actions)，那么浏览器将在渲染组件树时每一帧都会重新计算样式，这可能会 **非常慢**。
 
 `useInsertionEffect` 比在 [`useLayoutEffect`](/reference/react/useLayoutEffect) 或 [`useEffect`](/reference/react/useEffect) 期间注入样式更好。因为它会确保 `<style>` 标签在其它 Effect 运行前被注入。否则，正常的 Effect 中的布局计算将由于过时的样式而出错。
 
diff --git a/src/content/reference/react/useMemo.md b/src/content/reference/react/useMemo.md
index 723bb023af..1c7047616a 100644
--- a/src/content/reference/react/useMemo.md
+++ b/src/content/reference/react/useMemo.md
@@ -12,6 +12,12 @@ const cachedValue = useMemo(calculateValue, dependencies)
 
 </Intro>
 
+<Note>
+
+[React Compiler](/learn/react-compiler) 会自动对值和函数进行记忆化处理，从而减少手动调用 `useMemo` 的需求。你可以使用编译器自动处理记忆化。
+
+</Note>
+
 <InlineToc />
 
 ---
diff --git a/src/content/reference/rsc/use-server.md b/src/content/reference/rsc/use-server.md
index 4cd1ae14f9..04c447bc67 100644
--- a/src/content/reference/rsc/use-server.md
+++ b/src/content/reference/rsc/use-server.md
@@ -95,7 +95,7 @@ async function addToCart(data) {
 * 来自事件处理程序的事件
 
 
-支持的可序列化返回值与边界客户端组件的 [可序列化 props](/reference/rsc/use-client#passing-props-from-server-to-client-components) 相同。
+支持的可序列化返回值与边界客户端组件的 [可序列化 props](/reference/rsc/use-client#serializable-types) 相同。
 
 
 ## 用法 {/*usage*/}
diff --git a/src/sidebarHome.json b/src/sidebarHome.json
index 240c88a933..8ec32a3151 100644
--- a/src/sidebarHome.json
+++ b/src/sidebarHome.json
@@ -14,6 +14,10 @@
       "title": "安装",
       "path": "/learn/installation"
     },
+    {
+      "title": "React Compiler",
+      "path": "/learn/react-compiler"
+    },
     {
       "hasSectionHeader": true,
       "sectionHeader": "学习 React"
@@ -74,6 +78,22 @@
       "title": "服务端 API",
       "path": "/reference/react-dom/server"
     },
+    {
+      "hasSectionHeader": true,
+      "sectionHeader": "REACT COMPILER API"
+    },
+    {
+      "title": "Configuration",
+      "path": "/reference/react-compiler/configuration"
+    },
+    {
+      "title": "Directives",
+      "path": "/reference/react-compiler/directives"
+    },
+    {
+      "title": "Compiling Libraries",
+      "path": "/reference/react-compiler/compiling-libraries"
+    },
     {
       "hasSectionHeader": true,
       "sectionHeader": "参与贡献"
diff --git a/src/sidebarLearn.json b/src/sidebarLearn.json
index d1a41443e6..d5e6fa3a47 100644
--- a/src/sidebarLearn.json
+++ b/src/sidebarLearn.json
@@ -53,11 +53,29 @@
         {
           "title": "React 开发者工具",
           "path": "/learn/react-developer-tools"
+        }
+      ]
+    },
+    {
+      "title": "React Compiler",
+      "path": "/learn/react-compiler",
+      "canary": true,
+      "routes": [
+        {
+          "title": "介绍",
+          "path": "/learn/react-compiler/introduction"
+        },
+        {
+          "title": "安装",
+          "path": "/learn/react-compiler/installation"
+        },
+        {
+          "title": "逐步使用",
+          "path": "/learn/react-compiler/incremental-adoption"
         },
         {
-          "title": "React Compiler",
-          "path": "/learn/react-compiler",
-          "canary": true
+          "title": "调试和故障排除",
+          "path": "/learn/react-compiler/debugging"
         }
       ]
     },
diff --git a/src/sidebarReference.json b/src/sidebarReference.json
index f1e439dd89..94fb5a12f1 100644
--- a/src/sidebarReference.json
+++ b/src/sidebarReference.json
@@ -127,7 +127,8 @@
         {
           "title": "cache",
           "path": "/reference/react/cache"
-        },        {
+        },
+        {
           "title": "captureOwnerStack",
           "path": "/reference/react/captureOwnerStack"
         },
@@ -324,6 +325,54 @@
         }
       ]
     },
+    {
+      "hasSectionHeader": true,
+      "sectionHeader": "React Compiler"
+    },
+    {
+      "title": "配置",
+      "path": "/reference/react-compiler/configuration",
+      "routes": [
+        {
+          "title": "compilationMode",
+          "path": "/reference/react-compiler/compilationMode"
+        },
+        {
+          "title": "gating",
+          "path": "/reference/react-compiler/gating"
+        },
+        {
+          "title": "logger",
+          "path": "/reference/react-compiler/logger"
+        },
+        {
+          "title": "panicThreshold",
+          "path": "/reference/react-compiler/panicThreshold"
+        },
+        {
+          "title": "target",
+          "path": "/reference/react-compiler/target"
+        }
+      ]
+    },
+    {
+      "title": "指令",
+      "path": "/reference/react-compiler/directives",
+      "routes": [
+        {
+          "title": "\"use memo\"",
+          "path": "/reference/react-compiler/directives/use-memo"
+        },
+        {
+          "title": "\"use no memo\"",
+          "path": "/reference/react-compiler/directives/use-no-memo"
+        }
+      ]
+    },
+    {
+      "title": "Compiling Libraries",
+      "path": "/reference/react-compiler/compiling-libraries"
+    },
     {
       "hasSectionHeader": true,
       "sectionHeader": "React 规则"
diff --git a/yarn.lock b/yarn.lock
index e866a206bb..e5eecaac22 100644
--- a/yarn.lock
+++ b/yarn.lock
@@ -2443,6 +2443,14 @@ ccount@^2.0.0:
   resolved "https://registry.npmjs.org/ccount/-/ccount-2.0.1.tgz"
   integrity sha512-eyrF0jiFpY+3drT6383f1qhkbGsLSifNAjA61IUjZjmLCWjItY6LB9ft9YhoDgwfmclB2zhu51Lc7+95b8NRAg==
 
+chalk@4.1.2, chalk@^4.0.0, chalk@^4.1.0:
+  version "4.1.2"
+  resolved "https://registry.yarnpkg.com/chalk/-/chalk-4.1.2.tgz#aac4e2b7734a740867aeb16bf02aad556a1e7a01"
+  integrity sha512-oKnbhFyRIXpUuez8iBMmyEa4nbj4IOQyuhc/wy9kY7/WVPcwIO9VA668Pu8RkO7+0G76SLROeyw9CpQ061i4mA==
+  dependencies:
+    ansi-styles "^4.1.0"
+    supports-color "^7.1.0"
+
 chalk@^2.0.0, chalk@^2.4.1:
   version "2.4.2"
   resolved "https://registry.npmjs.org/chalk/-/chalk-2.4.2.tgz"
@@ -2452,14 +2460,6 @@ chalk@^2.0.0, chalk@^2.4.1:
     escape-string-regexp "^1.0.5"
     supports-color "^5.3.0"
 
-chalk@^4.0.0, chalk@^4.1.0:
-  version "4.1.2"
-  resolved "https://registry.yarnpkg.com/chalk/-/chalk-4.1.2.tgz#aac4e2b7734a740867aeb16bf02aad556a1e7a01"
-  integrity sha512-oKnbhFyRIXpUuez8iBMmyEa4nbj4IOQyuhc/wy9kY7/WVPcwIO9VA668Pu8RkO7+0G76SLROeyw9CpQ061i4mA==
-  dependencies:
-    ansi-styles "^4.1.0"
-    supports-color "^7.1.0"
-
 character-entities-html4@^1.0.0:
   version "1.1.4"
   resolved "https://registry.npmjs.org/character-entities-html4/-/character-entities-html4-1.1.4.tgz"