Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Update genType docs after the move inside the compiler. #597

Merged
merged 2 commits into from
Nov 9, 2022
Merged

Update genType docs after the move inside the compiler. #597

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
5070a36
Update genType docs after the move inside the compiler.
cristianoc Nov 9, 2022
4c28041
Update getting-started.mdx
cristianoc Nov 9, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
33 changes: 7 additions & 26 deletions pages/docs/gentype/latest/getting-started.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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):

```
Expand All @@ -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"`
Expand All @@ -50,7 +41,7 @@ structure:
```js
//...
"gentypeconfig": {
"language": "typescript" | "flow" | "untyped",
"language": "typescript",
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not for now, but should we remove this configuration option all together now that it just supports one? Or am I misunderstanding?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If you're using compiler 10.0 or earlier, this is still required. I'll say that explicitly.

"generatedFileExtension": ".gen.tsx",
"module": "es6" | "commonjs",
"shims": {
Expand All @@ -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"`)
Expand All @@ -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<string>` 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:

Expand All @@ -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

Expand All @@ -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.
16 changes: 7 additions & 9 deletions pages/docs/gentype/latest/introduction.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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).

Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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).