# react-native-streamdown
> This project is not affiliated with, endorsed by, or sponsored by Vercel.
A streaming-ready markdown component for React Native built on top of [`react-native-enriched-markdown`](https://github.com/software-mansion-labs/react-native-enriched-markdown) and [`remend`](https://www.npmjs.com/package/remend).
It processes raw, incomplete markdown (as it streams token-by-token from an LLM) in the background using [`react-native-worklets`](https://docs.swmansion.com/react-native-worklets/docs/) powerful concurrency feature - the Bundle Mode - keeping the JS thread free at all times.
## Features
- Renders incomplete streaming markdown correctly — no visual glitches mid-stream
- Background thread processing via `react-native-worklets` Bundle Mode
- LaTeX support with streaming completion — applied automatically, no configuration needed
- CommonMark and GitHub Flavored Markdown rendering powered by `react-native-enriched-markdown` with built-in `streamingAnimation`
- Customizable via `remendConfig`
---
## Installation
```sh
yarn add react-native-streamdown
```
### Peer dependencies
```sh
yarn add react-native-enriched-markdown react-native-worklets remend
```
| Package | Version |
| -------------------------------- | ------- |
| `react-native-enriched-markdown` | `>=1.0.0` |
| `react-native-worklets` | `>=0.10.0` |
| `remend` | `1.3.0` |
---
## Required setup — Bundle Mode
`react-native-streamdown` runs markdown processing on a worklet thread using **Bundle Mode** from `react-native-worklets`. This requires extra configuration steps from the [official Bundle Mode setup guide](https://docs.swmansion.com/react-native-worklets/docs/bundleMode/setup/). Make sure to complete these steps before continuing. For a real-world reference of an app configured with Bundle Mode, check out the [Bundle Mode Showcase App](https://github.com/software-mansion-labs/Bundle-Mode-showcase-app).
### 1. `babel.config.js` — configure Worklets Babel plugin
`react-native-streamdown` requires special options to be added to the Worklets Babel plugin config in `babel.config.js`, namely `bundleMode: true` and `importForwarding.moduleNames: ['remend']`. Your final config could look like this:
#### Expo
```js
module.exports = function (api) {
api.cache(true);
return {
presets: ['babel-preset-expo'],
plugins: [
[
'react-native-worklets/plugin',
{
bundleMode: true,
// other options...
importForwarding: {
moduleNames: ['remend'], // add this line
},
},
],
],
};
};
```
#### React Native CLI
```js
const workletsPluginOptions = {
bundleMode: true,
// other options...
importForwarding: {
moduleNames: ['remend'], // add this line
},
};
```
`importForwarding.moduleNames: ['remend']` tells the Babel plugin to forward the `remend` import into the generated worklet so it can be called off the JS thread. See the [import forwarding docs](https://docs.swmansion.com/react-native-worklets/docs/bundleMode/importForwarding/) for details.
### 2. `metro.config.js` — configure Metro for monorepos
`react-native-worklets` Bundle Mode generates files on the fly that might not be tracked by Metro in some monorepo setups. It might also shadow your resolving function. If you're running into issues with module resolution, use `getBundleModeMetroConfig` (which preserves your existing `resolveRequest`) and watch the `.worklets/` output directory in your `metro.config.js`:
#### Expo
```js
const { getDefaultConfig } = require('expo/metro-config');
const {
getBundleModeMetroConfig,
} = require('react-native-worklets/bundleMode');
const config = getDefaultConfig(__dirname);
// Watch the .worklets/ output directory
config.watchFolders.push(
require('path').resolve(
__dirname,
'node_modules/react-native-worklets/.worklets'
)
);
module.exports = getBundleModeMetroConfig(config);
```
#### React Native CLI
```js
const { getDefaultConfig } = require('@react-native/metro-config');
const {
getBundleModeMetroConfig,
} = require('react-native-worklets/bundleMode');
const config = getDefaultConfig(__dirname);
// Watch the .worklets/ output directory
config.watchFolders.push(
require('path').resolve(
__dirname,
'node_modules/react-native-worklets/.worklets'
)
);
module.exports = getBundleModeMetroConfig(config);
```
### 3. Patch Metro for synchronous worklet indexing (recommended)
Bundle Mode isolates worklets into separate modules **on the fly**. Metro builds its file map when it starts, so it can fail to index these freshly generated modules in time — you'll see `Failed to get the SHA-1 for .../.worklets/.js` and need to reload the app a few times before the bundle succeeds.
To avoid this, patch Metro to allow synchronous indexing of the new modules, as described in the [Worklets Bundle Mode setup guide](https://docs.swmansion.com/react-native-worklets/docs/bundleMode/setup). This repository's `example/` app applies such a patch via `resolutions` — use it as a reference.
> Without the patch the app still works, but expect a few extra reloads on first launch while Metro catches up. The one-shot `react-native bundle` command (offline release bundling) requires the patch.
---
## Usage
```tsx
import { StreamdownText } from 'react-native-streamdown';
// markdown can be updated token-by-token as the LLM streams
;
```
### Props
`StreamdownText` accepts all props from `EnrichedMarkdownText` plus one additional prop:
| Prop | Type | Description |
| -------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `remendConfig` | `RemendOptions` | Optional. Override the default remend processing config. See [remend docs](https://www.npmjs.com/package/remend) for all available options. |
Pass `flavor="github"` to render GitHub Flavored Markdown.
---
## Example app
The `example/` directory in this repository contains a fully working demo app that shows:
- **Streaming Markdown Simulator** — streams a sample markdown document token-by-token to demonstrate rendering quality and the `streamingAnimation` effect
- **LLM Streaming Demo** — connects to the OpenAI Chat Completions API via SSE and renders the response live using `StreamdownText`
It is a practical reference for the full Bundle Mode setup (Babel, Metro, `package.json` flags) and for how to wire `StreamdownText` into a real streaming UI.
---
Built by [Software Mansion](https://swmansion.com/).
[
](https://swmansion.com/)
---
## License
MIT