@spaced-out/ui-design-system/dts-generator/README.md

Sense UI components library

# DTS Generator

This folder contains a standalone utility to generate TypeScript declaration (`.d.ts`) files from existing `.js.flow` files using [`flow-to-ts`](https://github.com/MarcoPolo/flowToTs). These typings are essential for supporting downstream TypeScript consumers of the Genesis component library.

---

## Why this exists

Although Genesis is written in Flow, the JavaScript ecosystem (including editors like VSCode, tsserver, and downstream NPM consumers) expects `.d.ts` files for rich type support. This tool bridges that gap by converting `.js.flow` files into `.d.ts` files that TypeScript understands — without requiring a full migration to TypeScript.

This is **not a Flow-to-TypeScript migration**. It's a compatibility layer that allows us to continue using Flow internally while supporting TS externally.

---

## What it does

- Scans `lib/` for `.js.flow` files
- Uses `flow-to-ts` to convert each file into a `.d.ts` equivalent
- Writes the `.d.ts` files alongside the original files
- Formats the output with Prettier

This process runs automatically as part of the `yarn build` step (via Gulp), ensuring typings are up-to-date with every release.

---

## Usage

Install dependencies:

```bash
yarn --cwd dts-generator install
```

Run the generator:

```bash
yarn --cwd dts-generator generate
```

This will generate and format all `.d.ts` files for the project based on the current contents of `lib/`.

---

## Included in Release

The `.d.ts` files generated here are published as part of our NPM release and are used by any project consuming Genesis with TypeScript.

---

## Tech Stack

- [`flow-to-ts`](https://github.com/khan/flow-to-ts)
- [`jscodeshift`](https://github.com/facebook/jscodeshift)
- [`glob`](https://www.npmjs.com/package/glob)
- [`prettier`](https://prettier.io)

---

## Related Context

This setup is a foundational step toward the long-term vision of migrating all frontend codebases (`ui_server`, `ui_design_system`, `ui_chatbot`) to TypeScript at Sense.

---