| 1 | # React Compiler Development Guide |
| 2 | |
| 3 | Note: for general notes about contributing, see the [CONTRIBUTING.md](../../CONTRIBUTING.md). |
| 4 | |
| 5 | ## Compiler Development |
| 6 | |
| 7 | For general compiler development we recommend the following workflow: |
| 8 | |
| 9 | ```sh |
| 10 | # Install dependencies |
| 11 | yarn |
| 12 | |
| 13 | # build the custom test runner |
| 14 | yarn snap:build |
| 15 | |
| 16 | # Run the primary tests in watch mode |
| 17 | yarn snap --watch |
| 18 | ``` |
| 19 | |
| 20 | `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. |
| 21 | |
| 22 | ### Compiling Arbitrary Files |
| 23 | |
| 24 | You can compile any file (not just fixtures) using: |
| 25 | |
| 26 | ```sh |
| 27 | # Compile a file and see the output |
| 28 | yarn snap compile <path> |
| 29 | |
| 30 | # Compile with debug output to see the state after each compiler pass |
| 31 | # This is an alternative to `yarn snap -d -p <pattern>` when you don't have a fixture file yet |
| 32 | yarn snap compile --debug <path> |
| 33 | ``` |
| 34 | |
| 35 | ### Minimizing Test Cases |
| 36 | |
| 37 | To reduce a failing test case to its minimal reproduction: |
| 38 | |
| 39 | ```sh |
| 40 | # Minimize a file that causes a compiler error |
| 41 | yarn snap minimize <path> |
| 42 | |
| 43 | # Minimize and update the file in-place |
| 44 | yarn snap minimize --update <path> |
| 45 | ``` |
| 46 | |
| 47 | When contributing changes, we prefer to: |
| 48 | * Add one or more fixtures that demonstrate the current compiled output for a particular combination of input and configuration. Send this as a first PR. |
| 49 | * Then, make changes to the compiler that achieve the desired output for those examples. Commit both the output changes and the corresponding compiler changes in a second PR. |
| 50 |