Docs / GenType / GettingStarted

Getting Started

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

Setup

Requirements:

bs-platform 7.0.2 or higher: use genType 3.8.0 or higher.

bs-platform 7.0.0 or higher: use genType 3.2.0 or higher.

bs-platform 6.2.0 or higher: use genType 3.0.0 or higher.

bs-platform 5.2.0 or higher: use genType 2.40.0 or higher.

bs-platform 5.0.x and 5.1.x: use genType 2.17.0 or higher.

For earlier versions, see the older README.

Install the binaries via npm (or yarn):

npm install --save-dev gentype # Verify installed gentype binary npx gentype --help

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

"gentypeconfig": { "language": "untyped", "shims": {}, "debug": { "all": false, "basic": false } }

For running gentype with BuckleScript via npm workflow, add following script in your package.json:

scripts: { "bs:build": "bsb -make-world", "bs:clean": "bsb -clean-world" }

Note: bsb will automatically detect your installed genType version.

With genType < 2.17.0 or bucklescript < 5.0.0, one has to set the environment variable BS_CMT_POST_PROCESS_CMD. See the older README.

Configuration

Every genType powered project requires a configuration item "gentypeconfig" at top level in the project's bsconfig.json. (The use of a separate file gentypeconfig.json is being deprecated). The configuration has following structure:

JS
//... "gentypeconfig": { "language": "typescript" | "flow" | "untyped", "shims": { "ReasonReact": "ReactShim" } }
  • 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

    • e.g. Array<string> with format: "ReasonModule=JavaScriptModule"

    • Required to export certain basic Reason data types to JS when one cannot modify the sources to add annotations (e.g. exporting Reason lists)

Adding Shims (TS & Flow)

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

Testing the Whole Setup

Open any relevant *.re 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.re.

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.re -> MyComponent.gen.tsx).

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

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

Limitations

  • BuckleScript in-source = true. Currently only supports bucklescript 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".

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.

Changelog

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