You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
`genType` is tightly integrated in the ReScript Compiler. It only requires minimal setup.
10
-
11
9
## Setup
12
10
13
-
14
-
Install the binaries via `npm` (or `yarn`):
11
+
Since compiler v10.1, there's no need to install anything. For compiler 10.0 or older, install the binaries via `npm` (or `yarn`):
15
12
16
13
```
17
14
npm install gentype --save-dev
@@ -20,8 +17,6 @@ npm install gentype --save-dev
20
17
npx gentype --help
21
18
```
22
19
23
-
**Note:** Version requirements / compatibility list can be found [here](https://github.com/rescript-association/genType#requirements).
24
-
25
20
Add a `gentypeconfig` section to your `bsconfig.json` (See [Configuration](#configuration) for details):
26
21
27
22
```
@@ -37,10 +32,6 @@ Add a `gentypeconfig` section to your `bsconfig.json` (See [Configuration](#conf
37
32
}
38
33
```
39
34
40
-
For running `genType` with ReScript via `npm` workflow, no special setup is required in `package.json`.
41
-
42
-
> **Note:**`rescript` will automatically detect your installed `genType` version.
43
-
44
35
## Configuration
45
36
46
37
Every `genType` powered project requires a configuration item `"gentypeconfig"`
@@ -50,7 +41,7 @@ structure:
50
41
```js
51
42
//...
52
43
"gentypeconfig": {
53
-
"language":"typescript"|"flow"|"untyped",
44
+
"language":"typescript",
54
45
"generatedFileExtension":".gen.tsx",
55
46
"module":"es6"|"commonjs",
56
47
"shims": {
@@ -63,9 +54,7 @@ structure:
63
54
- File extension used for genType generated files (defaults to `.gen.tsx`)
64
55
65
56
-**language**
66
-
-`"typescript"` : Generate `*.gen.tsx` files written in TypeScript.
67
-
-`"flow"`: Generate `*.gen.js` files with Flow type annotations.
68
-
-`"untyped"`: Generate `*.gen.js` files in vanilla JavaScript.
57
+
-`"typescript"` : the `language` setting is not required from compiler v10.1
69
58
70
59
-**module**
71
60
- Module format used for the generated `*.gen.tsx` files (supports `"es6"` and `"commonjs"`)
@@ -74,17 +63,17 @@ structure:
74
63
- Required only if one needs to export certain basic ReScript data types to JS when one cannot modify the sources to add annotations (e.g. exporting ReScript lists), and if the types are not first-classed in genType.
75
64
- Example: `Array<string>` with format: `"RescriptModule=JavaScriptModule"`
76
65
77
-
## Adding Shims (TS & Flow)
66
+
## Adding Shims
78
67
79
-
A shim is a TS / Flow file that provides user-provided definitions for library types.
68
+
A shim is a TS file that provides user-provided definitions for library types.
80
69
81
-
Configure your shim files within `"gentypeconfig"` in your [`bsconfig.json`](https://github.com/reason-association/genType/blob/master/examples/typescript-react-example/bsconfig.json), and add relevant `.shims.js` files in a directory which is visible by ReScript e.g. [`src/shims/`](https://github.com/reason-association/genType/blob/master/examples/typescript-react-example/src/shims). An example shim to export ReactEvent can be found [here](https://github.com/reason-association/genType/blob/master/examples/typescript-react-example/src/shims/ReactEvent.shim.ts).
70
+
Configure your shim files within `"gentypeconfig"` in your [`bsconfig.json`](https://github.com/rescript-lang/rescript-compiler/blob/master/jscomp/gentype_tests/typescript-react-example/bsconfig.json), and add relevant `.shims.ts` files in a directory which is visible by ReScript e.g. [`src/shims/`](https://github.com/rescript-lang/rescript-compiler/tree/master/jscomp/gentype_tests/typescript-react-example/src/shims). An example shim to export ReactEvent can be found [here](https://github.com/rescript-lang/rescript-compiler/blob/master/jscomp/gentype_tests/typescript-react-example/src/shims/ReactEvent.shim.ts).
82
71
83
72
## Testing the Whole Setup
84
73
85
74
Open any relevant `*.res` file and add `@genType` annotations to any bindings / values / functions to be used from JavaScript. If an annotated value uses a type, the type must be annotated too. See e.g. [Hooks.res](https://github.com/reason-association/genType/blob/master/examples/typescript-react-example/src/Hooks.res).
86
75
87
-
Save the file and rebuild the project via `npm run bs:build` or similar. You should now see a `*.gen.tsx`(for TypeScript, or `*.gen.js` for Flow) file with the same name (e.g. `MyComponent.res` -> `MyComponent.gen.tsx`).
76
+
Save the file and rebuild the project via `npm run bs:build` or similar. You should now see a `*.gen.tsx` file with the same name (e.g. `MyComponent.res` -> `MyComponent.gen.tsx`).
88
77
89
78
Any values exported from `MyComponent.res` can then be imported from JS. For example:
90
79
@@ -96,11 +85,7 @@ import MyComponent from "./components/MyComponent.gen";
96
85
97
86
We prepared some examples to give you an idea on how to integrate `genType` in your own project. Check out the READMEs of the listed projects.
98
87
99
-
**Please make sure to build genType before trying to build the examples.**
@@ -115,7 +100,3 @@ These features are for experimentation only. They could be changed/removed any t
115
100
-**in-source = true**. Currently only supports ReScript projects with [in-source generation](/docs/manual/latest/build-configuration#package-specs) and `.bs.js` file suffix.
116
101
117
102
-**Limited namespace support**. Currently there's limited [namespace](/docs/manual/latest/build-configuration#name-namespace) support, and only `namespace:true` is possible, not e.g. `namespace:"custom"`.
118
-
119
-
## Changelog
120
-
121
-
See [Changes.md](https://github.com/reason-association/genType/blob/master/Changes.md) for a complete list of features, fixes, and changes for each release.
`genType` is a code generation tool that lets you export ReScript values and types to use in JavaScript, and import JavaScript values and types into ReScript.
9
+
`genType` is a code generation tool that lets you export ReScript values and types to use in TypeScript (TS), and import TS values and types into ReScript.
10
10
11
-
Converter functions between the two representations are generated based on the type of the value. The converters can be generated in vanilla JavaScript, or in [TypeScript](https://www.typescriptlang.org/) / [Flow](https://flow.org/en/) for a type-safe idiomatic interface.
11
+
Converter functions between the two runtime representations are generated when required based on the type of the values.
12
12
In particular, conversion of [rescript-react](/docs/react/latest/introduction) components both ways is supported, with automatic generation of the wrappers.
13
13
14
14
Here's an article describing how to use `genType` as part of a migration strategy where a tree of components is gradually converted to ReScript bottom-up (old article containing Reason / BuckleScript): [Adopting Reason: strategies, dual sources of truth, and why genType is a big deal](https://medium.com/p/c514265b466d).
15
15
16
-
The implementation of genType performs a type-directed transformation of ReScript programs after ReScript source code compilation. The transformed programs operate on data types idiomatic to JS.
16
+
The implementation of genType performs a type-directed transformation of ReScript programs after compilation. The transformed programs operate on data types idiomatic to JS.
17
17
18
-
For example, a ReScript function operating on a ReScript variant `type t = | A(int) | B(string)` (which is represented as custom blocks at runtime) is exported to a JS function operating on the corresponding JS object of type `{tag: "A"; value: number}
18
+
For example, a ReScript function operating on a ReScript variant `type t = | A(int) | B(string)` (which is represented as custom objects with tags at runtime) is exported to a JS function operating on the corresponding JS object of type `{tag: "A"; value: number}
19
19
| {tag: "B"; value: string}`.
20
20
21
-
The output of genType can be configured by using one of 3 back-ends: `untyped` to generate wrappers in vanilla JS, `typescript` to generate [TypeScript](https://www.typescriptlang.org/), and `flow` to generate JS with [Flow](https://flow.org/en/) type annotations.
22
-
23
21
## A Quick Example
24
22
25
-
Let's assume we are working on a TypeScript (TS) codebase and we want to integrate a single rescript-react component.
23
+
Let's assume we are working on a TypeScript codebase and we want to integrate a single rescript-react component.
26
24
27
25
We want to be able to import the rescript-react component like any other React component in our existing TS code, but we also want to preserve all the ReScript types in the TS type system (and convert incompatible values if necessary).
28
26
@@ -51,7 +49,7 @@ let make = (~name: string, ~color: color) => {
51
49
};
52
50
```
53
51
54
-
On a successful compile, `genType` will convert `src/MyComp.res` to a TS file called `src/MyComp.gen.ts` which will look something like this:
52
+
On a successful compile, `genType` will convert `src/MyComp.res` to a TS file called `src/MyComp.gen.tsx` which will look something like this:
55
53
56
54
```ts
57
55
// src/MyComp.gen.tsx
@@ -104,4 +102,4 @@ For detailed information, head to the [Getting Started](getting-started) or [Usa
104
102
105
103
## Development
106
104
107
-
For contributions, issues or questions, please refer to the [GitHub repository](https://github.com/reason-association/genType) or our [ReScript forum](https://forum.rescript-lang.org).
105
+
Since ReScript v10.1, genType is part of the compiler's [GitHub repository](https://github.com/rescript-lang/rescript-compiler).
0 commit comments