Skip to content

Commit 475ac87

Browse files
cknittcknitt
committed
Some JSX docs updates
1 parent a721750 commit 475ac87

File tree

6 files changed

+32
-27
lines changed

6 files changed

+32
-27
lines changed

‎pages/docs/react/latest/beyond-jsx.mdx

+1-1
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,7 @@ JSX is a syntax sugar that allows us to use React components in an HTML like man
1414

1515
**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`.
1616

17-
> **Note:** This page assumes your `rescript.json` to be set to `"jsx": { "version": 4 }` to apply the right JSX transformations.
17+
> **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.
1818
1919
## Component Types
2020

‎pages/docs/react/latest/elements-and-jsx.mdx

+1-1
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,7 @@ Elements are the smallest building blocks of React apps. This page will explain
1212

1313
</Intro>
1414

15-
> **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.
15+
> **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.
1616
1717
## Element Basics
1818

‎pages/docs/react/latest/extensions-of-props.mdx

+1-1
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ canonical: "/docs/react/latest/spread-props"
66

77
# Extensions of Props
88

9-
> **Note:** This page assumes your `rescript.json` to be set to `"jsx": { "version": 4 }` to apply the right JSX transformations.
9+
> **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.
1010
1111
## Spread props
1212

‎pages/docs/react/latest/installation.mdx

+22-6
Original file line numberDiff line numberDiff line change
@@ -8,10 +8,10 @@ canonical: "/docs/react/latest/installation"
88

99
**Requirements:**
1010

11-
- `rescript@10.1` or later
11+
- `rescript@11.0` or later
1212
- `[email protected]` or later
1313

14-
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):
14+
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)):
1515

1616
```
1717
npm install @rescript/react
@@ -21,14 +21,12 @@ Then add the following setting to your existing `rescript.json`:
2121

2222
```json
2323
{
24-
"jsx": { "version": 4, "mode": "classic" },
24+
"jsx": { "version": 4 },
2525
"bs-dependencies": ["@rescript/react"]
2626
}
2727
```
2828

29-
> 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"`.
30-
31-
**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)
29+
**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).
3230

3331
To test your setup, create a new `.res` file in your source directory and add the following code:
3432

@@ -53,3 +51,21 @@ After a successful installation, `@rescript/react` will make the following modul
5351
- `ReactDOMStyle`: Bindings to the inline style API
5452
- `RescriptReactRouter`: A simple, yet fully featured router with minimal memory allocations
5553
- `RescriptReactErrorBoundary`: A component which handles errors thrown in its child components gracefully
54+
55+
## Automatic vs. Classic Mode
56+
57+
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:
58+
59+
```json
60+
{
61+
"jsx": { "version": 4, "mode": "automatic" }
62+
}
63+
```
64+
65+
To keep using the legacy `React.createElement` API (like with JSX v3), you can activate classic mode instead:
66+
67+
```json
68+
{
69+
"jsx": { "version": 4, "mode": "classic" }
70+
}
71+
```

‎pages/docs/react/latest/introduction.mdx

+2-2
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ canonical: "/docs/react/latest/introduction"
66

77
# ReScript & React
88

9-
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).
9+
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).
1010

1111
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.
1212

@@ -22,7 +22,7 @@ All our documented examples can be compiled in our [ReScript Playground](/try) a
2222

2323
> **This documentation assumes basic knowledge about ReactJS.**
2424
>
25-
> 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.
25+
> 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.
2626
2727
## Development
2828

‎pages/docs/react/latest/migrate-react.mdx

+5-16
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ canonical: "/docs/react/latest/migrate-react"
66

77
# Migrate from JSX v3
88

9-
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.
9+
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.
1010

1111
## Configuration
1212

@@ -26,25 +26,14 @@ Then add the new JSX configuration:
2626
}
2727
```
2828

29-
**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.
30-
31-
### Classic and Automatic Mode
32-
33-
Classic mode is the default and generates calls to `React.createElement` just as with V3.
29+
or, to keep using the legacy `React.createElement` API like with JSX v3:
3430

3531
```json
3632
{
3733
"jsx": { "version": 4, "mode": "classic" }
3834
}
3935
```
4036

41-
Automatic mode is an experimental mode that generate calls to `_jsx` functions (similar to TypeScript's `react-jsx` mode)
42-
43-
```json
44-
{
45-
"jsx": { "version": 4, "mode": "automatic" }
46-
}
47-
```
4837

4938
### File-level config
5039

@@ -84,9 +73,9 @@ JSX v3 is still available with the latest version of compiler and rescript-react
8473
}
8574
```
8675

87-
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.
76+
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.
8877

89-
## Migration of V3 components
78+
## Migration of v3 components
9079

9180
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.
9281

@@ -179,7 +168,7 @@ let make = () => {
179168
}
180169
```
181170

182-
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.
171+
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.
183172

184173
```res
185174
module FancyInput = {

0 commit comments

Comments
 (0)