diff --git a/compiler/CLAUDE.md b/compiler/CLAUDE.md index 94a7d4b5d6d9..166769ab0272 100644 --- a/compiler/CLAUDE.md +++ b/compiler/CLAUDE.md @@ -62,7 +62,7 @@ yarn snap minimize --update ## Version Control -This repository uses Sapling (`sl`) for version control. Sapling is similar to Mercurial: there is not staging area, but new/deleted files must be explicitlyu added/removed. +This repository uses Sapling (`sl`) for version control. Sapling is similar to Mercurial: there is no staging area, but new/deleted files must be explicitly added/removed. ```bash # Check status diff --git a/compiler/README.md b/compiler/README.md index 53c0c22a0dc3..b0ad59011ef4 100644 --- a/compiler/README.md +++ b/compiler/README.md @@ -2,6 +2,6 @@ React Compiler is a compiler that optimizes React applications, ensuring that only the minimal parts of components and hooks will re-render when state changes. The compiler also validates that components and hooks follow the Rules of React. -More information about the design and architecture of the compiler are covered in the [Design Goals](./docs/DESIGN_GOALS.md). +More information about the design and architecture of the compiler is covered in the [Design Goals](./docs/DESIGN_GOALS.md). More information about developing the compiler itself is covered in the [Development Guide](./docs/DEVELOPMENT_GUIDE.md). \ No newline at end of file diff --git a/compiler/docs/DESIGN_GOALS.md b/compiler/docs/DESIGN_GOALS.md index 76d19e25c084..e23ce42dce91 100644 --- a/compiler/docs/DESIGN_GOALS.md +++ b/compiler/docs/DESIGN_GOALS.md @@ -8,7 +8,7 @@ The idea of React Compiler is to allow developers to use React's familiar declar * Bound the amount of re-rendering that happens on updates to ensure that apps have predictably fast performance by default. * Keep startup time neutral with pre-React Compiler performance. Notably, this means holding code size increases and memoization overhead low enough to not impact startup. -* Retain React's familiar declarative, component-oriented programming model. Ie, the solution should not fundamentally change how developers think about writing React, and should generally _remove_ concepts (the need to use React.memo(), useMemo(), and useCallback()) rather than introduce new concepts. +* Retain React's familiar declarative, component-oriented programming model. I.e., the solution should not fundamentally change how developers think about writing React, and should generally _remove_ concepts (the need to use React.memo(), useMemo(), and useCallback()) rather than introduce new concepts. * "Just work" on idiomatic React code that follows React's rules (pure render functions, the rules of hooks, etc). * Support typical debugging and profiling tools and workflows. * Be predictable and understandable enough by React developers — i.e. developers should be able to quickly develop a rough intuition of how React Compiler works. @@ -19,12 +19,12 @@ The idea of React Compiler is to allow developers to use React's familiar declar The following are explicitly *not* goals for React Compiler: * Provide perfectly optimal re-rendering with zero unnecessary recomputation. This is a non-goal for several reasons: - * The runtime overhead of the extra tracking involved can outweight the cost of recomputation in many cases. + * The runtime overhead of the extra tracking involved can outweigh the cost of recomputation in many cases. * In cases with conditional dependencies it may not be possible to avoid recomputing some/all instructions. * The amount of code may regress startup times, which would conflict with our goal of neutral startup performance. * Support code that violates React's rules. React's rules exist to help developers build robust, scalable applications and form a contract that allows us to continue improving React without breaking applications. React Compiler depends on these rules to safely transform code, and violations of rules will therefore break React Compiler's optimizations. * Support legacy React features. Notably we will not support class components due to their inherent mutable state being shared across multiple methods with complex lifetimes and data flow. -* Support 100% of the JavaScript language. In particular, we will not support rarely used features and/or features which are known to be unsafe or which cannot be modeled soundly. For example, nested classes that capture values from their closure are difficult to model accurately because of mutability, and `eval()` is unsafe. We aim to support the vast majority of JavaScript code (and the TypeScript and Flow dialects) +* Support 100% of the JavaScript language. In particular, we will not support rarely used features and/or features which are known to be unsafe or which cannot be modeled soundly. For example, nested classes that capture values from their closure are difficult to model accurately because of mutability, and `eval()` is unsafe. We aim to support the vast majority of JavaScript code (and the TypeScript and Flow dialects). ## Design Principles @@ -43,7 +43,7 @@ The core of the compiler is largely decoupled from Babel, using its own intermed - **Babel Plugin**: Determines which functions in a file should be compiled, based on the plugin options and any local opt-in/opt-out directives. For each component or hook to be compiled, the plugin calls the compiler, passing in the original function and getting back a new AST node which will replace the original. - **Lowering** (BuildHIR): The first step of the compiler is to convert the Babel AST into React Compiler's primary intermediate representation, HIR (High-level Intermediate Representation). This phase is primarily based on the AST itself, but currently leans on Babel to resolve identifiers. The HIR preserves the precise order-of-evaluation semantics of JavaScript, resolves break/continue to their jump points, etc. The resulting HIR forms a control-flow graph of basic blocks, each of which contains zero or more consecutive instructions followed by a terminal. The basic blocks are stored in reverse postorder, such that forward iteration of the blocks allows predecessors to be visited before successors _unless_ there is a "back edge" (ie a loop). -- **SSA Conversion** (EnterSSA): The HIR is converted to HIR form, such that all Identifiers in the HIR are updated to an SSA-based identifier. +- **SSA Conversion** (EnterSSA): The HIR is converted to SSA form, such that all Identifiers in the HIR are updated to an SSA-based identifier. - Validation: We run various validation passes to check that the input is valid React, ie that it does not break the rules. This includes looking for conditional hook calls, unconditional setState calls, etc. - **Optimization**: Various passes such as dead code elimination and constant propagation can generally improve performance and reduce the amount of instructions to be optimized later. - **Type Inference** (InferTypes): We run a conservative type inference pass to identify certain key types of data that may appear in the program that are relevant for further analysis, such as which values are hooks, primitives, etc. diff --git a/compiler/docs/DEVELOPMENT_GUIDE.md b/compiler/docs/DEVELOPMENT_GUIDE.md index a38d8436e68e..4364013a9e8c 100644 --- a/compiler/docs/DEVELOPMENT_GUIDE.md +++ b/compiler/docs/DEVELOPMENT_GUIDE.md @@ -17,7 +17,7 @@ yarn snap:build yarn snap --watch ``` -`snap` is our custom test runner, which creates "golden" test files that have the expected output for each input fixture, as well as the results of executing a specific input (or sequence of inputs) in both the uncompiled and compiler versions of the input. +`snap` is our custom test runner, which creates "golden" test files that have the expected output for each input fixture, as well as the results of executing a specific input (or sequence of inputs) in both the uncompiled and compiled versions of the input. ### Compiling Arbitrary Files diff --git a/compiler/packages/babel-plugin-react-compiler/README.md b/compiler/packages/babel-plugin-react-compiler/README.md index 37282975f2a5..dfd57feb2599 100644 --- a/compiler/packages/babel-plugin-react-compiler/README.md +++ b/compiler/packages/babel-plugin-react-compiler/README.md @@ -2,4 +2,4 @@ React Compiler is a compiler that optimizes React applications, ensuring that only the minimal parts of components and hooks will re-render when state changes. The compiler also validates that components and hooks follow the Rules of React. -This package contains the React Compiler Babel plugin use in projects that make use of Babel. You can find instructions for using this plugin here: https://react.dev/learn/react-compiler +This package contains the React Compiler Babel plugin used in projects that make use of Babel. You can find instructions for using this plugin here: https://react.dev/learn/react-compiler diff --git a/compiler/packages/babel-plugin-react-compiler/src/Inference/MUTABILITY_ALIASING_MODEL.md b/compiler/packages/babel-plugin-react-compiler/src/Inference/MUTABILITY_ALIASING_MODEL.md index ab327c255b10..ab16d8182ac7 100644 --- a/compiler/packages/babel-plugin-react-compiler/src/Inference/MUTABILITY_ALIASING_MODEL.md +++ b/compiler/packages/babel-plugin-react-compiler/src/Inference/MUTABILITY_ALIASING_MODEL.md @@ -22,17 +22,17 @@ function Component() { The goal of mutability and aliasing inference is to understand the set of instructions that create/modify a, b, and c. -In code, the mutability and aliasing model is compromised of the following phases: +In code, the mutability and aliasing model is comprised of the following phases: -* `InferMutationAliasingEffects`. Infers a set of mutation and aliasing effects for each instruction. The approach is to generate a set of candidate effects based purely on the semantics of each instruction and the types of the operands, then use abstract interpretation to determine the actual effects (or errros) that would apply. For example, an instruction that by default has a Capture effect might downgrade to an ImmutableCapture effect if the value is known to be frozen. -* `InferMutationAliasingRanges`. Infers a mutable range (start:end instruction ids) for each value in the program, and annotates each Place with its effect type for usage in later passes. This builds a graph of data flow through the program over time in order to understand which mutations effect which values. +* `InferMutationAliasingEffects`. Infers a set of mutation and aliasing effects for each instruction. The approach is to generate a set of candidate effects based purely on the semantics of each instruction and the types of the operands, then use abstract interpretation to determine the actual effects (or errors) that would apply. For example, an instruction that by default has a Capture effect might downgrade to an ImmutableCapture effect if the value is known to be frozen. +* `InferMutationAliasingRanges`. Infers a mutable range (start:end instruction ids) for each value in the program, and annotates each Place with its effect type for usage in later passes. This builds a graph of data flow through the program over time in order to understand which mutations affect which values. * `InferReactiveScopeVariables`. Given the per-Place effects, determines disjoint sets of values that mutate together and assigns all identifiers in each set to a unique scope, and updates the range to include the ranges of all constituent values. Finally, `AnalyzeFunctions` needs to understand the mutation and aliasing semantics of nested FunctionExpression and ObjectMethod values. `AnalyzeFunctions` calls `InferFunctionExpressionAliasingEffectsSignature` to determine the publicly observable set of mutation/aliasing effects for nested functions. ## Mutation and Aliasing Effects -The inference model is based on a set of "effects" that describe subtle aspects of mutation, aliasing, and other changes to the state of values over time +The inference model is based on a set of "effects" that describe subtle aspects of mutation, aliasing, and other changes to the state of values over time. ### Creation Effects @@ -69,7 +69,7 @@ Describes the creation of new function value, capturing the given set of mutable kind: 'Apply'; receiver: Place; function: Place; // same as receiver for function calls - mutatesFunction: boolean; // indicates if this is a type that we consdier to mutate the function itself by default + mutatesFunction: boolean; // indicates if this is a type that we consider to mutate the function itself by default args: Array; into: Place; // where result is stored signature: FunctionSignature | null; @@ -314,7 +314,7 @@ Mutate b Mutate a ``` -A derived value changes when it's source value is mutated. +A derived value changes when its source value is mutated. Example: @@ -526,7 +526,7 @@ Capture c <- a Intuition: these effects are inverses of each other (capturing into an object, extracting from an object). The result is based on the order of operations: -Capture then CreatFrom is equivalent to Alias: we have to assume that the result _is_ the original value and that a local mutation of the result could mutate the original. +Capture then CreateFrom is equivalent to Alias: we have to assume that the result _is_ the original value and that a local mutation of the result could mutate the original. ```js const b = [a]; // capture diff --git a/compiler/packages/react-mcp-server/README.md b/compiler/packages/react-mcp-server/README.md index ec4f398942dd..53d3a1e0e6b9 100644 --- a/compiler/packages/react-mcp-server/README.md +++ b/compiler/packages/react-mcp-server/README.md @@ -19,4 +19,4 @@ First, add this file if you're using Claude Desktop: `code ~/Library/Application } ``` -Next, run `yarn workspace react-mcp-server watch` from the `react/compiler` directory and make changes as needed. You will need to restart Claude everytime you want to try your changes. +Next, run `yarn workspace react-mcp-server watch` from the `react/compiler` directory and make changes as needed. You will need to restart Claude every time you want to try your changes. diff --git a/compiler/packages/react-mcp-server/todo.md b/compiler/packages/react-mcp-server/todo.md index a7f0af9adbee..10a93a4ae13e 100644 --- a/compiler/packages/react-mcp-server/todo.md +++ b/compiler/packages/react-mcp-server/todo.md @@ -1,5 +1,5 @@ TODO -- [ ] If code doesnt compile, read diagnostics and try again +- [ ] If code doesn't compile, read diagnostics and try again - [ ] Provide detailed examples in assistant prompt (use another LLM to generate good prompts, iterate from there) - [ ] Provide more tools for working with HIR/AST (eg so we can prompt it to try and optimize code via HIR, which it can then translate back into user code changes) diff --git a/packages/dom-event-testing-library/README.md b/packages/dom-event-testing-library/README.md index d6ad0f183c0b..705cf0ace5e8 100644 --- a/packages/dom-event-testing-library/README.md +++ b/packages/dom-event-testing-library/README.md @@ -3,7 +3,7 @@ A library for unit testing events via high-level interactions, e.g., `pointerdown`, that produce realistic and complete DOM event sequences. -There are number of challenges involved in unit testing modules that work with +There are a number of challenges involved in unit testing modules that work with DOM events. 1. Gesture recognizers may need to support environments with and without support for diff --git a/packages/eslint-plugin-react-hooks/src/code-path-analysis/README.md b/packages/eslint-plugin-react-hooks/src/code-path-analysis/README.md index 1109cb2f387e..7301995490cf 100644 --- a/packages/eslint-plugin-react-hooks/src/code-path-analysis/README.md +++ b/packages/eslint-plugin-react-hooks/src/code-path-analysis/README.md @@ -1,6 +1,6 @@ # Code Path Analyzer -This code is a forked version of ESLints Code Path Analyzer which includes +This code is a forked version of ESLint's Code Path Analyzer which includes support for Component Syntax. Forked from: https://github.com/eslint/eslint/tree/main/lib/linter/code-path-analysis diff --git a/packages/react-devtools/CONTRIBUTING.md b/packages/react-devtools/CONTRIBUTING.md index ac0799127a8b..6a93658b2139 100644 --- a/packages/react-devtools/CONTRIBUTING.md +++ b/packages/react-devtools/CONTRIBUTING.md @@ -53,7 +53,7 @@ yarn start Now any changes you make to DevTools will automatically reload in the test app at http://localhost:8080 ### Option 2: Using the extension -Some changes requiring testing in the browser extension (e.g. like "named hooks"). To do this, run the following script: +Some changes require testing in the browser extension (e.g. like "named hooks"). To do this, run the following script: ```sh cd cd packages/react-devtools-extensions diff --git a/packages/react-devtools/OVERVIEW.md b/packages/react-devtools/OVERVIEW.md index 7f705e4c3f34..06249e47c534 100644 --- a/packages/react-devtools/OVERVIEW.md +++ b/packages/react-devtools/OVERVIEW.md @@ -49,7 +49,7 @@ Later operations will reference strings by a one-based index. For example, `1` w #### Adding a root node -Adding a root to the tree requires sending 5 numbers: +Adding a root to the tree requires sending 7 numbers: 1. add operation constant (`1`) 1. fiber id @@ -234,7 +234,7 @@ for (let i = 0; i < this._roots.length; i++) { } ``` -We skip the root itself because don't display them in the tree: +We skip the root itself because we don't display them in the tree: ```js const firstChildID = root.children[0]; ``` diff --git a/packages/react-devtools/README.md b/packages/react-devtools/README.md index 8c436c1fb2b4..189b2fbd33fb 100644 --- a/packages/react-devtools/README.md +++ b/packages/react-devtools/README.md @@ -112,7 +112,7 @@ Or you could develop with a local HTTP server like [`serve`](https://www.npmjs.c ### The React tab shows no components #### The Issue with Chrome v101 and earlier -As we migrate to a Chrome Extension Manifest V3, we start to use a new method to hook the DevTools with the inspected page. This new method is more secure, but relies on a new API that's only supported in Chrome v102+. For Chrome v101 or earlier, we use a fallback method, which can cause malfunctions (e.g. failure to load React Elements in the Components tab) if the JS resources on your page is loaded from cache. Please upgrade to Chrome v102+ to avoid this issue. +As we migrate to a Chrome Extension Manifest V3, we start to use a new method to hook the DevTools with the inspected page. This new method is more secure, but relies on a new API that's only supported in Chrome v102+. For Chrome v101 or earlier, we use a fallback method, which can cause malfunctions (e.g. failure to load React Elements in the Components tab) if the JS resources on your page are loaded from cache. Please upgrade to Chrome v102+ to avoid this issue. #### Service Worker malfunction Go to chrome://extensions. If you see "service worker (inactive)" in the React Developer Tools extension, try disabling and re-enabling the extension. This will restart the service worker. Then go to the page you want to inspect, close the DevTools, and reload the page. Open the DevTools again and the React components tab should be working. diff --git a/packages/react-server/README.md b/packages/react-server/README.md index e88807a267f4..474ee67a5426 100644 --- a/packages/react-server/README.md +++ b/packages/react-server/README.md @@ -8,7 +8,7 @@ This is an experimental package for creating custom React streaming server rende ## Usage -`react-server` is a package implementing various Server Rendering capabilities. The two implementation are codenamed `Fizz` and `Flight`. +`react-server` is a package implementing various Server Rendering capabilities. The two implementations are codenamed `Fizz` and `Flight`. `Fizz` is a renderer for Server Side Rendering React. The same code that runs in the client (browser or native) is run on the server to produce an initial view to send to the client before it has to download and run React and all the user code to produce that view on the client. @@ -86,7 +86,7 @@ createResponse({ messages: ['hello', 'react'] }, ...) createResponse({ m: Map(['k', 'v'])}, ...) ``` -Additionally React built ins can be rendered including Function Components +Additionally, React built-ins can be rendered, including Function Components Function Component are called and the return value can be any renderable type. Since `react-server` supports Promises, Function Components can be async functions. @@ -100,10 +100,10 @@ async function App({ children }) { createResponse(, ...) ``` -Finally, There are two types of references in `react-server` that can be rendered +Finally, there are two types of references in `react-server` that can be rendered #### Client References -When a React Server Component framework bundles an application and encounters a `"use client"` directive it must resister exported members with `"registerClientReference"` which will encode the necessary information for `Flight` to interpret the export as a reference to be loaded on the client rather than a direct dependency on the Server module graph. +When a React Server Component framework bundles an application and encounters a `"use client"` directive it must register exported members with `"registerClientReference"` which will encode the necessary information for `Flight` to interpret the export as a reference to be loaded on the client rather than a direct dependency on the Server module graph. When rendering a client reference `Flight` will encode necessary information in the serialized output to describe how to load the code which represents the client module. @@ -146,7 +146,7 @@ createResponse( ``` #### Server References -Similarly When a React Server Component framework bundles an application and encounters a `"use server"` directive in a file or in a function body, including closures, it must implement that function as as a server entrypoint that can be called from the client. To make `Flight` aware that a function is a Server Reference the function should be registered with `registerServerReference()`. +Similarly When a React Server Component framework bundles an application and encounters a `"use server"` directive in a file or in a function body, including closures, it must implement that function as a server entrypoint that can be called from the client. To make `Flight` aware that a function is a Server Reference the function should be registered with `registerServerReference()`. ```js @@ -172,9 +172,9 @@ createResponse( When rendering with `react-server` there are two broad contexts when this might happen. Realtime when responding to a user request and ahead of time when prerendering a page that can later be used more than once. -While the core rendering implementation is the same in both cases there are subtle differences we can adopt that take advantage of the context. For instance while rendering in response to a real user request we want to stream eagerly if the consumer is requesting information. This allows us to stream content to the consumer as it becomes available but might have implications for the stability of the serialized format. When prerendering we assume there is not urgency to producing a partial result as quickly as possible so we can alter the internal implementation take advantage of this. To implement a prerender API use `createPrerenderRequest` in place of `createRequest`. +While the core rendering implementation is the same in both cases there are subtle differences we can adopt that take advantage of the context. For instance while rendering in response to a real user request we want to stream eagerly if the consumer is requesting information. This allows us to stream content to the consumer as it becomes available but might have implications for the stability of the serialized format. When prerendering we assume there is not urgency to producing a partial result as quickly as possible so we can alter the internal implementation to take advantage of this. To implement a prerender API use `createPrerenderRequest` in place of `createRequest`. -One key semantic change prerendering has with rendering is how errors are handled. When rendering an error is embedded into the output and must be handled by the consumer such as an SSR render or on the client. However with prerendering there is an expectation that if the prerender errors then the entire prerender will be discarded or it will be used but the consumer will attempt to recover that error by asking for a dynamic render. This is analogous to how errors during SSR aren't immediately handled they are actually encoded as requests for client recovery. The error only is observed if the retry on the client actually fails. To account for this prerenders simply omit parts of the model that errored. you can use the `onError` argument in `createPrerenderRequest` to observe if an error occurred and users of your `prerender` implementation can choose whether to abandon the prerender or implement dynamic recovery when an error occurs. +One key semantic change prerendering has with rendering is how errors are handled. When rendering an error is embedded into the output and must be handled by the consumer such as an SSR render or on the client. However with prerendering there is an expectation that if the prerender errors then the entire prerender will be discarded or it will be used but the consumer will attempt to recover that error by asking for a dynamic render. This is analogous to how errors during SSR aren't immediately handled they are actually encoded as requests for client recovery. The error only is observed if the retry on the client actually fails. To account for this prerenders simply omit parts of the model that errored. You can use the `onError` argument in `createPrerenderRequest` to observe if an error occurred and users of your `prerender` implementation can choose whether to abandon the prerender or implement dynamic recovery when an error occurs. Existing implementations only return the stream containing the output of the prerender once it has completed. In the future we may introduce a `resume` API similar to the one that exists for `Fizz`. In anticipation of such an API it is expected that implementations of `prerender` return the type `Promise<{ prelude: }>` diff --git a/scripts/error-codes/README.md b/scripts/error-codes/README.md index 38918bd42a52..e3a7a840546a 100644 --- a/scripts/error-codes/README.md +++ b/scripts/error-codes/README.md @@ -8,7 +8,7 @@ provide a better debugging support in production. Check out the blog post our documentation. This file is append-only, which means an existing code in the file will never be changed/removed. - [`extract-errors.js`](https://github.com/facebook/react/blob/main/scripts/error-codes/extract-errors.js) - is an node script that traverses our codebase and updates `codes.json`. You + is a node script that traverses our codebase and updates `codes.json`. You can test it by running `yarn extract-errors`. It works by crawling the build artifacts directory, so you need to have either run the build script or downloaded pre-built artifacts (e.g. with `yarn download build`). It works diff --git a/scripts/release/README.md b/scripts/release/README.md index 77042a5dac8b..130f5ed25f7c 100644 --- a/scripts/release/README.md +++ b/scripts/release/README.md @@ -45,7 +45,7 @@ If your code lands in the main branch, it will be automatically published to the This will grab the specified revision on the main branch and publish it to the Next and Experimental channels. ## Publishing Without Tags -The sections below include meaningful `--tags` in the instructions. However, keep in mind that **the `--tags` arguments is optional**, and you can omit it if you don't want to tag the release on npm at all. This can be useful when preparing breaking changes. +The sections below include meaningful `--tags` in the instructions. However, keep in mind that **the `--tags` argument is optional**, and you can omit it if you don't want to tag the release on npm at all. This can be useful when preparing breaking changes. ## Publishing Next