Getting Started

genType is tightly integrated in the ReScript Compiler. It only requires minimal setup.

Setup

Install the binaries via npm (or yarn):

npm install --save-dev gentype

# Verify installed gentype binary
npx gentype --help

Note: Version requirements / compatibility list can be found here.

Add a gentypeconfig section to your bsconfig.json (See Configuration for details):

"gentypeconfig": {
    "language": "typescript",
    "shims": {},
    "generatedFileExtension": ".gen.tsx",
    "debug": {
      "all": false,
      "basic": false
    }
}

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" at top level in the project's bsconfig.json. The configuration has following structure:

JS
  //...
  "gentypeconfig": {
    "language": "typescript" | "flow" | "untyped",
    "generatedFileExtension": ".gen.tsx",
    "shims": {
      "ReasonReact": "ReactShim"
    }
  }

• generatedFileExtension

  • File extension used for genType generated files (defaults to .gen.tsx)

• 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.

• shims

  • 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)

A shim is a TS / Flow file that provides user-provided definitions for library types.

Configure your shim files within "gentypeconfig" in your bsconfig.json, and add relevant .shims.js files in a directory which is visible by ReScript e.g. src/shims/. An example shim to export ReactEvent can be found here.

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.

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).

Any values exported from MyComponent.res can then be imported from JS. For example:

JS
import MyComponent from "./components/MyComponent.gen";

Examples

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

• flow-react-example

• untyped-react-example

Experimental features

These features are for experimentation only. They could be changed/removed any time, and not be considered breaking changes.

• Export object and record types as interfaces. To activate, add "exportInterfaces": true to the configuration. The types are also renamed from name to Iname.

• Emit prop types for the untyped back-end. To activate, add "propTypes": true and "language": "untyped" to the configuration.

Limitations

• in-source = true. Currently only supports ReScript projects with in-source generation and .bs.js file suffix.

• Limited namespace support. Currently there's limited namespace support, and only namespace:true is possible, not e.g. namespace:"custom".

Changelog

See Changes.md for a complete list of features, fixes, and changes for each release.