From 5070a366f47bc6f191fe2796e9a7d47795cbd3b9 Mon Sep 17 00:00:00 2001 From: Cristiano Calcagno Date: Wed, 9 Nov 2022 09:14:24 +0100 Subject: [PATCH 1/2] Update genType docs after the move inside the compiler. --- pages/docs/gentype/latest/getting-started.mdx | 33 ++++--------------- pages/docs/gentype/latest/introduction.mdx | 16 ++++----- 2 files changed, 14 insertions(+), 35 deletions(-) diff --git a/pages/docs/gentype/latest/getting-started.mdx b/pages/docs/gentype/latest/getting-started.mdx index fa4d20c1e..b97d30238 100644 --- a/pages/docs/gentype/latest/getting-started.mdx +++ b/pages/docs/gentype/latest/getting-started.mdx @@ -6,12 +6,9 @@ canonical: "/docs/gentype/latest/getting-started" # Getting Started -`genType` is tightly integrated in the ReScript Compiler. It only requires minimal setup. - ## Setup - -Install the binaries via `npm` (or `yarn`): +Since compiler v10.1, there's no need to install anything. For compiler 10.0 or older, install the binaries via `npm` (or `yarn`): ``` npm install gentype --save-dev @@ -20,8 +17,6 @@ npm install gentype --save-dev npx gentype --help ``` -**Note:** Version requirements / compatibility list can be found [here](https://github.com/rescript-association/genType#requirements). - Add a `gentypeconfig` section to your `bsconfig.json` (See [Configuration](#configuration) for details): ``` @@ -37,10 +32,6 @@ Add a `gentypeconfig` section to your `bsconfig.json` (See [Configuration](#conf } ``` -For running `genType` with ReScript via `npm` workflow, no special setup is required in `package.json`. - -> **Note:** `rescript` will automatically detect your installed `genType` version. - ## Configuration Every `genType` powered project requires a configuration item `"gentypeconfig"` @@ -50,7 +41,7 @@ structure: ```js //... "gentypeconfig": { - "language": "typescript" | "flow" | "untyped", + "language": "typescript", "generatedFileExtension": ".gen.tsx", "module": "es6" | "commonjs", "shims": { @@ -64,8 +55,6 @@ structure: - **language** - `"typescript"` : Generate `*.gen.tsx` files written in TypeScript. - - `"flow"`: Generate `*.gen.js` files with Flow type annotations. - - `"untyped"`: Generate `*.gen.js` files in vanilla JavaScript. - **module** - Module format used for the generated `*.gen.tsx` files (supports `"es6"` and `"commonjs"`) @@ -74,17 +63,17 @@ structure: - 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. - Example: `Array` with format: `"RescriptModule=JavaScriptModule"` -## Adding Shims (TS & Flow) +## Adding Shims -A shim is a TS / Flow file that provides user-provided definitions for library types. +A shim is a TS file that provides user-provided definitions for library types. -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). +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). ## Testing the Whole Setup 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). -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`). +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`). Any values exported from `MyComponent.res` can then be imported from JS. For example: @@ -96,11 +85,7 @@ import MyComponent from "./components/MyComponent.gen"; 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. -**Please make sure to build genType before trying to build the examples.** - -- [typescript-react-example](https://github.com/reason-association/genType/tree/master/examples/typescript-react-example) -- [flow-react-example](https://github.com/reason-association/genType/tree/master/examples/flow-react-example) -- [untyped-react-example](https://github.com/reason-association/genType/tree/master/examples/untyped-react-example) +- [typescript-react-example](https://github.com/rescript-lang/rescript-compiler/tree/master/jscomp/gentype_tests/typescript-react-example) ## Experimental features @@ -115,7 +100,3 @@ These features are for experimentation only. They could be changed/removed any t - **in-source = true**. Currently only supports ReScript projects with [in-source generation](/docs/manual/latest/build-configuration#package-specs) and `.bs.js` file suffix. - **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"`. - -## Changelog - -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. diff --git a/pages/docs/gentype/latest/introduction.mdx b/pages/docs/gentype/latest/introduction.mdx index 01a7654ef..eed273bda 100644 --- a/pages/docs/gentype/latest/introduction.mdx +++ b/pages/docs/gentype/latest/introduction.mdx @@ -6,23 +6,21 @@ canonical: "/docs/gentype/latest/introduction" # GenType -`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. +`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. -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. +Converter functions between the two runtime representations are generated when required based on the type of the values. In particular, conversion of [rescript-react](/docs/react/latest/introduction) components both ways is supported, with automatic generation of the wrappers. 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). -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. +The implementation of genType performs a type-directed transformation of ReScript programs after compilation. The transformed programs operate on data types idiomatic to JS. -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 } +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 } | { tag: "B"; value: string }`. -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. - ## A Quick Example -Let's assume we are working on a TypeScript (TS) codebase and we want to integrate a single rescript-react component. +Let's assume we are working on a TypeScript codebase and we want to integrate a single rescript-react component. 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). @@ -51,7 +49,7 @@ let make = (~name: string, ~color: color) => { }; ``` -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: +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: ```ts // src/MyComp.gen.tsx @@ -104,4 +102,4 @@ For detailed information, head to the [Getting Started](getting-started) or [Usa ## Development -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). +Since ReScript v10.1, genType is part of the compiler's [GitHub repository](https://github.com/rescript-lang/rescript-compiler). From 4c2804166dfc10c374db762042955116d92a2c7b Mon Sep 17 00:00:00 2001 From: Cristiano Calcagno Date: Wed, 9 Nov 2022 09:36:37 +0100 Subject: [PATCH 2/2] Update getting-started.mdx --- pages/docs/gentype/latest/getting-started.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pages/docs/gentype/latest/getting-started.mdx b/pages/docs/gentype/latest/getting-started.mdx index b97d30238..11c33f3e7 100644 --- a/pages/docs/gentype/latest/getting-started.mdx +++ b/pages/docs/gentype/latest/getting-started.mdx @@ -54,7 +54,7 @@ structure: - File extension used for genType generated files (defaults to `.gen.tsx`) - **language** - - `"typescript"` : Generate `*.gen.tsx` files written in TypeScript. + - `"typescript"` : the `language` setting is not required from compiler v10.1 - **module** - Module format used for the generated `*.gen.tsx` files (supports `"es6"` and `"commonjs"`)