docs(en): merge reactjs.org/main into zh-hans.reactjs.org/main @ 2534424 (#1856)

Author: loveloki

.github/ISSUE_TEMPLATE/3-framework.yml

@@ -0,0 +1,116 @@
+name: "📄 Suggest new framework"
+description: "I am a framework author applying to be included as a recommended framework."
+title: "[Framework]: "
+labels: ["type: framework"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        ## Apply to be included as a recommended React framework
+
+        _This form is for framework authors to apply to be included as a recommended [React framework](https://react.dev/learn/creating-a-react-app). If you are not a framework author, please contact the authors before submitting._
+        
+        Our goal when recommending a framework is to start developers with a React project that solves common problems like code splitting, data fetching, routing, and HTML generation without any extra work later. We believe this will allow users to get started quickly with React, and scale their app to production.
+        
+        While we understand that many frameworks may want to be featured, this page is not a place to advertise every possible React framework or all frameworks that you can add React to. There are many great frameworks that offer support for React that are not listed in our guides. The frameworks we recommend have invested significantly in the React ecosystem, and collaborated with the React team to be compatible with our [full-stack React architecture vision](https://react.dev/learn/creating-a-react-app#which-features-make-up-the-react-teams-full-stack-architecture-vision).
+        
+        To be included, frameworks must meet the following criteria:
+        
+        - **Free & open-source**: must be open source and free to use.
+        - **Well maintained**. must be actively maintained, providing bug fixes and improvements.
+        - **Active community**: must have a sufficiently large and active community to support users.
+        - **Clear onboarding**: must have clear install steps to install the React version of the framework.
+        - **Ecosystem compatibility**: must support using the full range of libraries and tools in the React ecosystem.
+        - **Self-hosting option**: must support an option to self-host applications without losing access to features.
+        - **Developer experience**. must allow developers to be productive by supporting features like Fast Refresh.
+        - **User experience**. must provide built-in support for common problems like routing and data-fetching.
+        - **Compatible with our future vision for React**. React evolves over time, and frameworks that do not align with React’s direction risk isolating their users from the main React ecosystem over time. To be included on this page we must feel confident that the framework is setting its users up for success with React over time.
+        
+        Please note, we have reviewed most of the popular frameworks available today, so it is unlikely we have not considered your framework already. But if you think we missed something, please complete the application below.
+  - type: input
+    attributes:
+      label: Name
+      description: |
+        What is the name of your framework?
+    validations:
+      required: true
+  - type: input
+    attributes:
+      label: Homepage
+      description: |
+        What is the URL of your homepage?
+    validations:
+      required: true
+  - type: input
+    attributes:
+      label: Install instructions
+      description: |
+        What is the URL of your getting started guide?
+    validations:
+      required: true
+  - type: dropdown
+    attributes:
+      label: Is your framework open source?
+      description: |
+        We only recommend free and open source frameworks.
+      options:
+        - 'No'
+        - 'Yes'
+    validations:
+      required: true
+  - type: textarea
+    attributes:
+      label: Well maintained
+      description: |
+        Please describe how your framework is actively maintained. Include recent releases, bug fixes, and improvements as examples.
+    validations:
+      required: true
+  - type: textarea
+    attributes:
+      label: Active community
+      description: |
+        Please describe your community. Include the size of your community, and links to community resources.
+    validations:
+      required: true
+  - type: textarea
+    attributes:
+      label: Clear onboarding
+      description: |
+        Please describe how a user can install your framework with React. Include links to any relevant documentation.
+    validations:
+      required: true
+  - type: textarea
+    attributes:
+      label: Ecosystem compatibility
+      description: |
+        Please describe any limitations your framework has with the React ecosystem. Include any libraries or tools that are not compatible with your framework.
+    validations:
+      required: true
+  - type: textarea
+    attributes:
+      label: Self-hosting option
+      description: |
+        Please describe how your framework supports self-hosting. Include any limitations to features when self-hosting. Also include whether you require a server to deploy your framework.
+    validations:
+      required: true
+  - type: textarea
+    attributes:
+      label: Developer Experience
+      description: |
+        Please describe how your framework provides a great developer experience. Include any limitations to React features like React DevTools, Chrome DevTools, and Fast Refresh.
+    validations:
+      required: true
+  - type: textarea
+    attributes:
+      label: User Experience
+      description: |
+        Please describe how your framework helps developers create high quality user experiences by solving common use-cases. Include specifics for how your framework offers built-in support for code-splitting, routing, HTML generation, and data-fetching in a way that avoids client/server waterfalls by default. Include details on how you offer features such as SSG and SSR.
+    validations:
+      required: true
+  - type: textarea
+    attributes:
+      label: Compatible with our future vision for React
+      description: |
+        Please describe how your framework aligns with our future vision for React. Include how your framework will evolve with React over time, and your plans to support future React features like React Server Components.
+    validations:
+      required: true

plugins/remark-smartypants.js

@@ -14,12 +14,24 @@ const visit = require('unist-util-visit');
 const retext = require('retext');
 const smartypants = require('retext-smartypants');
 
-function check(parent) {
+function check(node, parent) {
+  if (node.data?.skipSmartyPants) return false;
   if (parent.tagName === 'script') return false;
   if (parent.tagName === 'style') return false;
   return true;
 }
 
+function markSkip(node) {
+  if (!node) return;
+  node.data ??= {};
+  node.data.skipSmartyPants = true;
+  if (Array.isArray(node.children)) {
+    for (const child of node.children) {
+      markSkip(child);
+    }
+  }
+}
+
 module.exports = function (options) {
   const processor = retext().use(smartypants, {
     ...options,
@@ -43,8 +55,14 @@ module.exports = function (options) {
     let startIndex = 0;
     const textOrInlineCodeNodes = [];
 
+    visit(tree, 'mdxJsxFlowElement', (node) => {
+      if (['TerminalBlock'].includes(node.name)) {
+        markSkip(node); // Mark all children to skip smarty pants
+      }
+    });
+
     visit(tree, ['text', 'inlineCode'], (node, _, parent) => {
-      if (check(parent)) {
+      if (check(node, parent)) {
         if (node.type === 'text') allText += node.value;
         // for the case when inlineCode contains just one part of quote: `foo'bar`
         else allText += 'A'.repeat(node.value.length);

src/components/Layout/HomeContent.js

@@ -265,7 +265,7 @@ export function HomeContent() {
               <CTA
                 color="gray"
                 icon="framework"
-                href="/learn/start-a-new-react-project">
+                href="/learn/creating-a-react-app">
                 使用框架开始一个新项目
               </CTA>
             </div>

src/components/MDX/TerminalBlock.tsx

@@ -79,13 +79,15 @@ function TerminalBlock({level = 'info', children}: TerminalBlockProps) {
           </div>
         </div>
       </div>
-      <div
+      <pre
         className="px-8 pt-4 pb-6 text-primary-dark dark:text-primary-dark font-mono text-code whitespace-pre overflow-x-auto"
         translate="no"
         dir="ltr">
-        <LevelText type={level} />
-        {message}
-      </div>
+        <code>
+          <LevelText type={level} />
+          {message}
+        </code>
+      </pre>
     </div>
   );
 }

src/content/blog/2023/03/22/react-labs-what-we-have-been-working-on-march-2023.md

@@ -31,7 +31,7 @@ RSC 将面向服务器的多页面应用程序的简单“请求/响应”思维
 
 现在我们已经相当好地解决了数据提取的问题，我们正在探索另一个方向：从客户端向服务器发送数据，以便可以执行数据库变更和实现表单。我们通过在服务器/客户端边界传递 Server Action 函数来实现这一点。客户端可以调用该函数，提供无缝 RPC。而在 JavaScript 加载之前，Server Action 还可以提供逐步增强的表单。
 
-RSC 已经在 [Next.js App Router](/learn/start-a-new-react-project#nextjs-app-router) 中发布，展示了一个真正深度集成的路由器，它使用了 RSC 并将其作为 primitive。但这不是构建 RSC 兼容的路由器和框架的唯一方法。RSC 规范和实现提供了特定功能的明确分离，旨在成为适用于兼容 React 框架的组件规范。
+RSC 已经在 [Next.js App Router](/learn/creating-a-react-app#nextjs-app-router) 中发布，展示了一个真正深度集成的路由器，它使用了 RSC 并将其作为 primitive。但这不是构建 RSC 兼容的路由器和框架的唯一方法。RSC 规范和实现提供了特定功能的明确分离，旨在成为适用于兼容 React 框架的组件规范。
 
 我们通常建议使用现有的框架，但你仍然可以构建自定义框架。由于需要深度集成 bundler，构建自定义 RSC 兼容的框架并不像想象中那么容易。当前的若代 bundler 非常适合在客户端使用，但它们并没有专门为将单个模块图分割为服务器和客户端提供一流的支持而设计。因此我们选择直接与 bundler 开发人员合作，以将内置 RSC 作为 primitive。
 
@@ -92,7 +92,7 @@ React 的核心思想是开发人员将其 UI 定义为当前状态的函数。
 
 ## 追踪 Transition {/*transition-tracing*/}
 
-追踪 Transition 的 API 可以检测 [React Transition](/reference/react/useTransition) 变慢的原因，并调查为什么会变慢。在上次更新后，我们完成了 API 的初始设计，并发布了一个 [RFC](https://github.com/reactjs/rfcs/pull/238)，基本功能也已经实现。该项目目前处于暂停状态。我们欢迎对 RFC 进行反馈，并期待恢复其开发，为 React 提供更好的性能测量工具。这将特别对基于 React Transition 构建的路由非常有用，例如 [Next.js App Router](/learn/start-a-new-react-project#nextjs-app-router)。
+追踪 Transition 的 API 可以检测 [React Transition](/reference/react/useTransition) 变慢的原因，并调查为什么会变慢。在上次更新后，我们完成了 API 的初始设计，并发布了一个 [RFC](https://github.com/reactjs/rfcs/pull/238)，基本功能也已经实现。该项目目前处于暂停状态。我们欢迎对 RFC 进行反馈，并期待恢复其开发，为 React 提供更好的性能测量工具。这将特别对基于 React Transition 构建的路由非常有用，例如 [Next.js App Router](/learn/creating-a-react-app#nextjs-app-router)。
 
 * * *
 除了这个更新，我们的团队最近还在社区播客和直播中客串，更多地讲述我们的工作并回答问题。

src/content/blog/2024/12/05/react-19.md

@@ -355,7 +355,7 @@ For more information, see [React DOM Static APIs](/reference/react-dom/static).
 
 服务器组件是一种新的选项，允许在打包前提前渲染组件，在与你的客户端应用程序或 SSR 服务器不同的环境中。这个独立的环境就是 React 服务器组件中的 "服务器"。服务器组件可以在你的 CI 服务器上在构建时运行一次，或者可以在每次请求时使用 web 服务器运行。
 
-React 19 包含了所有从 Canary 渠道引入的 React 服务器组件功能。这意味着，现在可以将 React 19 作为 peer 依赖项来发布带有服务器组件的库，使用 `react-server` [导出条件](https://github.com/reactjs/rfcs/blob/main/text/0227-server-module-conventions.md#react-server-conditional-exports) 用于支持 [全栈 React 架构](/learn/start-a-new-react-project#which-features-make-up-the-react-teams-full-stack-architecture-vision) 的框架。
+React 19 包含了所有从 Canary 渠道引入的 React 服务器组件功能。这意味着，现在可以将 React 19 作为 peer 依赖项来发布带有服务器组件的库，使用 `react-server` [导出条件](https://github.com/reactjs/rfcs/blob/main/text/0227-server-module-conventions.md#react-server-conditional-exports) 用于支持 [全栈 React 架构](/learn/creating-a-react-app#which-features-make-up-the-react-teams-full-stack-architecture-vision) 的框架。
 
 
 <Note>

src/content/blog/2025/10/07/react-compiler-1.md

@@ -69,17 +69,17 @@ To install the compiler:
 
 npm
 <TerminalBlock>
-{`npm install --save-dev --save-exact babel-plugin-react-compiler@latest`}
+npm install --save-dev --save-exact babel-plugin-react-compiler@latest
 </TerminalBlock>
 
 pnpm
 <TerminalBlock>
-{`pnpm add --save-dev --save-exact babel-plugin-react-compiler@latest`}
+pnpm add --save-dev --save-exact babel-plugin-react-compiler@latest
 </TerminalBlock>
 
 yarn
 <TerminalBlock>
-{`yarn add --dev --exact babel-plugin-react-compiler@latest`}
+yarn add --dev --exact babel-plugin-react-compiler@latest
 </TerminalBlock>
 
 As part of the stable release, we've been making React Compiler easier to add to your projects and added optimizations to how the compiler generates memoization. React Compiler now supports optional chains and array indices as dependencies. These improvements ultimately result in fewer re-renders and more responsive UIs, while letting you keep writing idiomatic declarative code.
@@ -101,17 +101,17 @@ To install:
 
 npm
 <TerminalBlock>
-{`npm install --save-dev eslint-plugin-react-hooks@latest`}
+npm install --save-dev eslint-plugin-react-hooks@latest
 </TerminalBlock>
 
 pnpm
 <TerminalBlock>
-{`pnpm add --save-dev eslint-plugin-react-hooks@latest`}
+pnpm add --save-dev eslint-plugin-react-hooks@latest
 </TerminalBlock>
 
 yarn
 <TerminalBlock>
-{`yarn add --dev eslint-plugin-react-hooks@latest`}
+yarn add --dev eslint-plugin-react-hooks@latest
 </TerminalBlock>
 
 ```js {6}
@@ -153,19 +153,19 @@ We have partnered with the Expo, Vite, and Next.js teams to add the compiler to
 [Expo SDK 54](https://docs.expo.dev/guides/react-compiler/) and up has the compiler enabled by default, so new apps will automatically be able to take advantage of the compiler from the start.
 
 <TerminalBlock>
-{`npx create-expo-app@latest`}
+npx create-expo-app@latest
 </TerminalBlock>
 
 [Vite](https://vite.dev/guide/) and [Next.js](https://nextjs.org/docs/app/api-reference/cli/create-next-app) users can choose the compiler enabled templates in `create-vite` and `create-next-app`.
 
 <TerminalBlock>
-{`npm create vite@latest`}
+npm create vite@latest
 </TerminalBlock>
 
 <br />
 
 <TerminalBlock>
-{`npx create-next-app@latest`}
+npx create-next-app@latest
 </TerminalBlock>
 
 ## Adopt React Compiler incrementally {/*adopt-react-compiler-incrementally*/}

src/content/learn/add-react-to-an-existing-project.md

@@ -20,7 +20,7 @@ title: 将 React 添加到现有项目中
 
 以下是推荐的配置方式：
 
-1. 使用一个 [基于 React 的框架](/learn/start-a-new-react-project) 构建 **应用的 React 部分**。
+1. 使用一个 [基于 React 的框架](/learn/creating-a-react-app) 构建 **应用的 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 应用处理。
 
@@ -149,7 +149,7 @@ root.render(<NavigationBar />);
 
 请注意 `index.html` 中的原始 HTML 内容是如何保留的，但现在你自己的 `NavigationBar` React 组件出现在 HTML 的 `<nav id="navigation">` 中。阅读 [`createRoot` 用法文档](/reference/react-dom/client/createRoot#rendering-a-page-partially-built-with-react) 以了解如何在现有 HTML 页面中渲染 React 组件。
 
-当在现有项目中采用 React 时，通常会从小型交互式组件（例如按钮）开始，然后逐渐“向上移动”，直到最终整个页面都由 React 构建。到那个时候，我们建议立即迁移到 [一个 React 框架](/learn/start-a-new-react-project)，以充分利用 React 的优势。
+当在现有项目中采用 React 时，通常会从小型交互式组件（例如按钮）开始，然后逐渐“向上移动”，直到最终整个页面都由 React 构建。到那个时候，我们建议立即迁移到 [一个 React 框架](/learn/creating-a-react-app)，以充分利用 React 的优势。
 
 ## 在现有的原生移动应用中使用 React Native {/*using-react-native-in-an-existing-native-mobile-app*/}
 

src/content/learn/build-a-react-app-from-scratch.md

@@ -34,7 +34,7 @@ title: 从零开始构建 React 应用
 [Vite](https://vite.dev/) 是一个构建工具，旨在为现代网络项目提供更快更简洁的开发体验。
 
 <TerminalBlock>
-{`npm create vite@latest my-app -- --template react-ts`}
+npm create vite@latest my-app -- --template react-ts
 </TerminalBlock>
 
 Vite 采用约定式设计，开箱即提供合理的默认配置。它拥有丰富的插件生态系统，能够支持快速热更新、JSX、Babel/SWC 等常见功能。你可以查看 Vite 的 [React 插件](https://vite.dev/plugins/#vitejs-plugin-react) 或 [React SWC 插件](https://vite.dev/plugins/#vitejs-plugin-react-swc) 和 [React 服务器端渲染示例项目](https://vite.dev/guide/ssr.html#example-projects) 来开始使用。
@@ -46,7 +46,7 @@ Vite 已经作为构建工具在我们 [推荐的框架](/learn/creating-a-react
 [Parcel](https://parceljs.org/) 结合了出色的开箱即用开发体验和可扩展的架构，可以将你的项目从刚开始的阶段推向大规模的生产应用。
 
 <TerminalBlock>
-{`npm install --save-dev parcel`}
+npm install --save-dev parcel
 </TerminalBlock>
 
 Parcel 支持快速刷新、JSX、TypeScript、Flow 和开箱即用的样式。请查看 [Parcel 的 React 教程](https://parceljs.org/recipes/react/#getting-started) 以开始。
@@ -56,7 +56,7 @@ Parcel 支持快速刷新、JSX、TypeScript、Flow 和开箱即用的样式。
 [Rsbuild](https://rsbuild.dev/) 是一个基于 Rspack 的构建工具，旨在为 React 应用程序提供无缝的开发体验。它配备了精心调优的默认设置和现成的性能优化。
 
 <TerminalBlock>
-{`npx create-rsbuild --template react`}
+npx create-rsbuild --template react
 </TerminalBlock>
 
 Rsbuild 内置了对 React 特性的支持，如快速刷新、JSX、TypeScript 和样式。请查看 [Rsbuild 的 React 指南](https://rsbuild.dev/zh/guide/framework/react) 以开始使用。

src/content/learn/react-compiler/installation.md

@@ -114,7 +114,7 @@ export default defineConfig({
 安装 `vite-plugin-babel`，并将其编译器的 Babel 插件添加到其中：
 
 <TerminalBlock>
-{`npm install vite-plugin-babel`}
+npm install vite-plugin-babel
 </TerminalBlock>
 
 ```js {3-4,16}