Docs / GenType / Getting Started
Edit

Getting Started

Setup

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

# Verify installed gentype binary
npx gentype --help

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

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

Configuration

Every genType powered project requires a configuration item "gentypeconfig" at top level in the project's rescript.json. The configuration has following structure:

JS
  //...
  "gentypeconfig": {
    "language": "typescript",
    "generatedFileExtension": ".gen.tsx",
    "module": "es6" | "commonjs",
    "shims": {
      "ReasonReact": "ReactShim"
    }
  }

  • generatedFileExtension

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

  • language

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

  • 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

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

Configure your shim files within "gentypeconfig" in your rescript.json, and add relevant .shims.ts 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 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.

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

IntroductionUsage