diff --git a/pages/docs/react/latest/beyond-jsx.mdx b/pages/docs/react/latest/beyond-jsx.mdx index 6fe7611f9..9cbc3ed1c 100644 --- a/pages/docs/react/latest/beyond-jsx.mdx +++ b/pages/docs/react/latest/beyond-jsx.mdx @@ -14,7 +14,7 @@ JSX is a syntax sugar that allows us to use React components in an HTML like man **Note:** This section requires knowledge about the low level apis for [creating elements](./elements-and-jsx#creating-elements-from-component-functions), such as `React.createElement` or `ReactDOM.createDOMElementVariadic`. -> **Note:** This page assumes your `rescript.json` to be set to `"jsx": { "version": 4 }` to apply the right JSX transformations. +> **Note:** The output shown for the examples on this page assumes your `rescript.json` to be set to `"jsx": { "version": 4, "mode": "classic" }`. We will update it for automatic mode soon. ## Component Types diff --git a/pages/docs/react/latest/elements-and-jsx.mdx b/pages/docs/react/latest/elements-and-jsx.mdx index 4c8be2ed5..aca2954ff 100644 --- a/pages/docs/react/latest/elements-and-jsx.mdx +++ b/pages/docs/react/latest/elements-and-jsx.mdx @@ -12,7 +12,7 @@ Elements are the smallest building blocks of React apps. This page will explain -> **Note:** This page assumes your `rescript.json` to be set to `"jsx": { "version": 4 }`, otherwise your JSX will not be transformed to its React specific form. +> **Note:** The output shown for the examples on this page assumes your `rescript.json` to be set to `"jsx": { "version": 4, "mode": "classic" }`. We will update it for automatic mode soon. ## Element Basics diff --git a/pages/docs/react/latest/extensions-of-props.mdx b/pages/docs/react/latest/extensions-of-props.mdx index 8af1c3b4e..0419fe3f0 100644 --- a/pages/docs/react/latest/extensions-of-props.mdx +++ b/pages/docs/react/latest/extensions-of-props.mdx @@ -6,7 +6,7 @@ canonical: "/docs/react/latest/spread-props" # Extensions of Props -> **Note:** This page assumes your `rescript.json` to be set to `"jsx": { "version": 4 }` to apply the right JSX transformations. +> **Note:** The output shown for the examples on this page assumes your `rescript.json` to be set to `"jsx": { "version": 4, "mode": "classic" }`. We will update it for automatic mode soon. ## Spread props diff --git a/pages/docs/react/latest/installation.mdx b/pages/docs/react/latest/installation.mdx index 517075edd..13558c638 100644 --- a/pages/docs/react/latest/installation.mdx +++ b/pages/docs/react/latest/installation.mdx @@ -8,10 +8,10 @@ canonical: "/docs/react/latest/installation" **Requirements:** -- `rescript@10.1` or later +- `rescript@11.0` or later - `react@18.0.0` or later -Add following dependency to your ReScript project (in case you don't have any project yet, check out the [installation instructions](/docs/manual/latest/installation) in the manual): +Add the following dependency to your ReScript project (in case you don't have any project yet, check out the [installation instructions](/docs/manual/latest/installation)): ``` npm install @rescript/react @@ -21,14 +21,12 @@ Then add the following setting to your existing `rescript.json`: ```json { - "jsx": { "version": 4, "mode": "classic" }, + "jsx": { "version": 4 }, "bs-dependencies": ["@rescript/react"] } ``` -> The [new jsx transform](https://ko.reactjs.org/blog/2020/09/22/introducing-the-new-jsx-transform.html) of ReactJS is available with `mode: "automatic"`. - -**Note** JSX v4 is newly introduced with the idiomatic record-based representation of a component. If your dependencies are not compatible with v4 yet, then you can use v3 in the same project. Check out the details in [Migrate from v3](/docs/react/latest/migrate-react) +**Note:** In case your dependencies are not compatible with version 4 of the ReScript JSX transformation yet, you can use v3 in the same project. Check out the details in [Migrate from v3](/docs/react/latest/migrate-react). To test your setup, create a new `.res` file in your source directory and add the following code: @@ -53,3 +51,21 @@ After a successful installation, `@rescript/react` will make the following modul - `ReactDOMStyle`: Bindings to the inline style API - `RescriptReactRouter`: A simple, yet fully featured router with minimal memory allocations - `RescriptReactErrorBoundary`: A component which handles errors thrown in its child components gracefully + +## Automatic vs. Classic Mode + +By default, JSX v4 uses the new JSX runtime (`react/jsx-runtime`) introduced in React 17. This is called "automatic mode", and can also be specified explicitly like this: + +```json +{ + "jsx": { "version": 4, "mode": "automatic" } +} +``` + +To keep using the legacy `React.createElement` API (like with JSX v3), you can activate classic mode instead: + +```json +{ + "jsx": { "version": 4, "mode": "classic" } +} +``` diff --git a/pages/docs/react/latest/introduction.mdx b/pages/docs/react/latest/introduction.mdx index 5fab2d8e7..8f6be8bd6 100644 --- a/pages/docs/react/latest/introduction.mdx +++ b/pages/docs/react/latest/introduction.mdx @@ -6,7 +6,7 @@ canonical: "/docs/react/latest/introduction" # ReScript & React -ReScript offers first class bindings for [ReactJS](https://reactjs.org) and is designed and built by people using ReScript and React in large mission critical React codebases. The bindings are compatible with modern React versions (>= v18.0). +ReScript offers first class bindings for [ReactJS](https://react.dev) and is designed and built by people using ReScript and React in large mission critical React codebases. The bindings are compatible with modern React versions (>= v18.0). The ReScript philosophy is to compile as closely to idiomatic JS code as possible; in the case of ReactJS, we made no exception, so it's not only easy to transfer all the React knowledge to the ReScript platform, but also straightforward to integrate with existing ReactJS codebases and libraries. @@ -17,12 +17,12 @@ All our documented examples can be compiled in our [ReScript Playground](/try) a - No Babel plugins required (JSX is part of the language!) - Comes with all essential React APIs for building production ready apps (`useState`, `useReducer`, `useEffect`, `useRef`,...) - No component class API (all ReScript & React codebases are built on function components & hooks) -- Strong level of type safetiness and type inference for component props and state values +- Strong level of type safety and type inference for component props and state values - [GenType](/docs/gentype/latest/introduction) support for importing / exporting React components in TypeScript codebases > **This documentation assumes basic knowledge about ReactJS.** > -> Please note that even though we will cover many basic React concepts, it might still be necessary to have a look at the official [ReactJS](https://reactjs.org) resources, especially if you are a complete beginner with React. +> Please note that even though we will cover many basic React concepts, it might still be necessary to have a look at the official [ReactJS](https://react.dev) resources, especially if you are a complete beginner with React. ## Development diff --git a/pages/docs/react/latest/migrate-react.mdx b/pages/docs/react/latest/migrate-react.mdx index 8e6bae8ed..9238174b3 100644 --- a/pages/docs/react/latest/migrate-react.mdx +++ b/pages/docs/react/latest/migrate-react.mdx @@ -6,7 +6,7 @@ canonical: "/docs/react/latest/migrate-react" # Migrate from JSX v3 -JSX v4 introduces a new idiomatic record-based representation of components which is incompatible with v3. Because of this, either the entire project or dependencies need to be compiled in V4 mode, or some compatibility features need to be used to mix V3 and V4 in the same project. This page describes how to migrate from v3 to v4. +JSX v4 introduces a new idiomatic record-based representation of components which is incompatible with v3. Because of this, either the entire project or dependencies need to be compiled in v4 mode, or some compatibility features need to be used to mix v3 and v4 in the same project. This page describes how to migrate from v3 to v4. ## Configuration @@ -26,11 +26,7 @@ Then add the new JSX configuration: } ``` -**Note** JSX v4 requires the rescript compiler 10.1 or higher, and rescript-react version 0.11 or higher. In addition, react version 18.0 is required. - -### Classic and Automatic Mode - -Classic mode is the default and generates calls to `React.createElement` just as with V3. +or, to keep using the legacy `React.createElement` API like with JSX v3: ```json { @@ -38,13 +34,6 @@ Classic mode is the default and generates calls to `React.createElement` just as } ``` -Automatic mode is an experimental mode that generate calls to `_jsx` functions (similar to TypeScript's `react-jsx` mode) - -```json -{ - "jsx": { "version": 4, "mode": "automatic" } -} -``` ### File-level config @@ -84,9 +73,9 @@ JSX v3 is still available with the latest version of compiler and rescript-react } ``` -To build certain dependencies in V3 compatibility mode, whatever the version used in the root project, use `"v3-dependencies"`. The listed dependencies will be built in V3 mode, and in addition `-open ReactV3` is added to the compiler options. +To build certain dependencies in v3 compatibility mode, whatever the version used in the root project, use `"v3-dependencies"`. The listed dependencies will be built in v3 mode, and in addition `-open ReactV3` is added to the compiler options. -## Migration of V3 components +## Migration of v3 components Some components in existing projects are written in a way that is dependent on the v3 internal representation. Here are a few examples of how to convert them to v4. @@ -179,7 +168,7 @@ let make = () => { } ``` -To this: In v3, there is an inconsistency between `ref` as prop and `ref_` as argument. With JSX V4, `ref` is only allowed as an argument. +To this: In v3, there is an inconsistency between `ref` as prop and `ref_` as argument. With JSX v4, `ref` is only allowed as an argument. ```res module FancyInput = { diff --git a/pages/docs/react/v0.10.0/introduction.mdx b/pages/docs/react/v0.10.0/introduction.mdx index cfc6cea39..cdbe5bf20 100644 --- a/pages/docs/react/v0.10.0/introduction.mdx +++ b/pages/docs/react/v0.10.0/introduction.mdx @@ -17,7 +17,7 @@ All our documented examples can be compiled in our [ReScript Playground](/try) a - No Babel plugins required (JSX is part of the language!) - Comes with all essential React APIs for building production ready apps (`useState`, `useReducer`, `useEffect`, `useRef`,...) - No component class API (all ReScript & React codebases are built on functional components & hooks) -- Strong level of type safetiness and type inference for component props and state values +- Strong level of type safety and type inference for component props and state values - [GenType](/docs/gentype/latest/introduction) support for importing / exporting React components in Flow and TypeScript codebases > **This documentation assumes basic knowledge about ReactJS.** diff --git a/pages/docs/react/v0.11.0/introduction.mdx b/pages/docs/react/v0.11.0/introduction.mdx index 5fab2d8e7..018041ad1 100644 --- a/pages/docs/react/v0.11.0/introduction.mdx +++ b/pages/docs/react/v0.11.0/introduction.mdx @@ -17,7 +17,7 @@ All our documented examples can be compiled in our [ReScript Playground](/try) a - No Babel plugins required (JSX is part of the language!) - Comes with all essential React APIs for building production ready apps (`useState`, `useReducer`, `useEffect`, `useRef`,...) - No component class API (all ReScript & React codebases are built on function components & hooks) -- Strong level of type safetiness and type inference for component props and state values +- Strong level of type safety and type inference for component props and state values - [GenType](/docs/gentype/latest/introduction) support for importing / exporting React components in TypeScript codebases > **This documentation assumes basic knowledge about ReactJS.**