> ## Documentation Index
> Fetch the complete documentation index at: https://rive.app/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# TypeScript Schemas

> Generate TypeScript types from your .riv files so artboard, state machine, view model, and property names are checked at compile time.

> [!NOTE]
>
> TypeScript schemas require the new React Native runtime, `@rive-app/react-native` 0.5.0 or later. See the [migration guide](https://rive.app/docs/runtimes/react-native/migration-guide.md) to upgrade.

You can generate a TypeScript schema for each `.riv` file. With it, artboard, state machine, view model, property, and enum names are checked at compile time, and your editor autocompletes them. A typo becomes a compile error instead of a runtime failure.

A schema is a `.riv.d.ts` file next to the `.riv` file. It lists the file's artboards, state machines, view models, and enums. It contains only types, so nothing changes in your bundle.

Types only apply when you load the Rive file with `import`. TypeScript finds the `.riv.d.ts` file automatically, with no tsconfig change. `require(...)` returns `any`, so it stays untyped even if a schema exists. This lets you adopt schemas one file at a time.

```tsx theme={null}
import rewardsRiv from './assets/rive/rewards.riv'; // typed by rewards.riv.d.ts
const untypedRiv = require('./assets/rive/rewards.riv'); // untyped
```

## Quick start

**1. Install @rive-app/canvas**

```bash theme={null}
npm install --save-dev @rive-app/canvas
```

The generator uses it to read `.riv` files. It's a dev dependency only and is not bundled into your app.

**2. Generate schemas**

```bash theme={null}
npx rive-gen-types assets/rive/rewards.riv   # writes rewards.riv.d.ts
npx rive-gen-types --all assets/rive         # every .riv in the directory
```

Commit the generated files. The output is stable, so regenerating an unchanged file gives no diff.

**3. Import the Rive file**

Importing a `.riv` file needs `riv` in Metro's `assetExts`. See [loading Rive files](https://rive.app/docs/runtimes/react-native/loading-rive-files.md).

```tsx theme={null}
import { useRiveFile } from '@rive-app/react-native';
import rewardsRiv from './assets/rive/rewards.riv';

const { riveFile } = useRiveFile(rewardsRiv);
```

## What gets typed

A generated schema looks like this:

```ts rewards.riv.d.ts theme={null}
// Generated by rive-gen-types — do not edit manually. @generated
/* eslint-disable */
// Source: rewards.riv
import type { RiveFileSource } from '@rive-app/react-native';
declare const asset: RiveFileSource<{
  schemaVersion: 1;
  artboards: 'Main' | 'Chest' | 'Button' | 'Item';
  defaultArtboard: 'Main';
  stateMachines: {
    'Main': 'State Machine 1';
    // ...one entry per artboard
  };
  enums: {
    Item_Selection: 'Coin' | 'Gem';
  };
  viewModels: {
    Rewards: {
      Price_Value: 'number';
      Coin: 'viewModel:Item_Icon_Value';
    };
    Item: {
      Item_Selection: 'enum:Item_Selection';
    };
    // ...
  };
  referencedAssets: {};
}>;
export default asset;
```

The types flow from the import, so you don't need to annotate anything. Artboard and state machine names on `RiveView` are checked, and the state machine must belong to the chosen artboard:

```tsx theme={null}
<RiveView
  file={riveFile}
  artboardName="Main"                 // "Mian" is an error
  stateMachineName="State Machine 1"
/>
```

View model names, property paths, and enum values are checked too. Each hook only accepts paths to properties of its type, including nested property paths:

```tsx theme={null}
const { instance } = useViewModelInstance(riveFile, {
  viewModelName: 'Rewards',           // 'Rewrads' is an error
  async: true,
});

useRiveNumber('Price_Value', instance);       // ✓
useRiveNumber('Coin/Item_Value', instance);   // ✓ nested
useRiveTrigger('Price_Value', instance);      // ✗ not a trigger

const { setValue } = useRiveEnum('Item_Selection/Item_Selection', instance);
setValue('Gem');       // ✓
setValue('Diamond');   // ✗ not a value of Item_Selection
```

Enum values are checked against the value names defined in the Rive file. To reuse an enum's values in your own types, use `EnumValues`:

```ts theme={null}
import { type EnumValues } from '@rive-app/react-native';

type ItemKind = EnumValues<typeof rewardsRiv, 'Item_Selection'>; // 'Coin' | 'Gem'
```

### Referenced assets

Out-of-band assets are listed in `referencedAssets`, keyed by the asset name and unique identifier as exported from the Rive editor. The `referencedAssets` option of `useRiveFile` is checked against that list: an unknown key or a wrong `type` is a compile error.

```tsx theme={null}
// Schema contains: referencedAssets: { 'Inter-594377': 'font' }
const { riveFile } = useRiveFile(outOfBandRiv, {
  referencedAssets: {
    'Inter-594377': { source: require('./assets/Inter.ttf'), type: 'font' },
  },
});
```

See [loading assets](https://rive.app/docs/runtimes/react-native/loading-assets.md) for the ways to load out-of-band assets.

## Typing your own components

To pass a typed Rive file or view model instance to another component, use `TypedRiveFile` and `TypedViewModelOf`:

```tsx theme={null}
import {
  type TypedRiveFile,
  type TypedViewModelOf,
} from '@rive-app/react-native';
import rewardsRiv from './assets/rive/rewards.riv';

function RewardsScreen({ file }: { file: TypedRiveFile<typeof rewardsRiv> }) {
  // ...
}

function PricePanel({
  instance,
}: {
  instance: TypedViewModelOf<typeof rewardsRiv, 'Rewards'>;
}) {
  const { value } = useRiveNumber('Price_Value', instance);
  // ...
}
```

## Files loaded from a URL

A `.riv.d.ts` file only types a local import. For a URL, generate a schema type with `--out` and pass it as a generic:

```bash theme={null}
npx rive-gen-types https://example.com/rewards.riv --out src/rive/rewards-schema.ts
```

```tsx theme={null}
import { RiveFileFactory, useRiveFile } from '@rive-app/react-native';
import type { RewardsSchema } from './rive/rewards-schema';

const url = 'https://example.com/rewards.riv';

const { riveFile } = useRiveFile<RewardsSchema>({ uri: url });

// Or, outside a component:
const file = await RiveFileFactory.fromURL<RewardsSchema>(url, undefined);
```

The type is named after the file (`rewards.riv` → `RewardsSchema`). Use `--name` to pick another name.

## Keeping schemas up to date

Regenerate after you edit a `.riv` file, then fix what TypeScript flags. Renamed artboards, removed properties, and changed enum values show up as errors where they're used.

To catch stale schemas in CI, regenerate and fail if anything changed:

```yaml theme={null}
- name: Check .riv schemas
  run: |
    npx rive-gen-types --all assets/rive
    test -z "$(git status --porcelain -- 'assets/rive/*.riv.d.ts')"
```

## Limits

* Nested property paths are typed up to two levels deep (`'a/b/leaf'`). Deeper paths work at runtime but need a cast.
* Paths must be string literals. To build a path at runtime, use a view model instance without a schema.
* List items are untyped, because the schema can't know which view model each item uses.
* A nested view model is only typed if it has a default instance in the file. Otherwise its paths aren't typed.

## Troubleshooting

> [accordion] Names aren't checked
>
> Load the Rive file with `import`, not `require(...)`. Check that a `.riv.d.ts` file with the same name sits next to the `.riv` file.

> [accordion] An import reports 'This .riv.d.ts is out of date'
>
> The schema was generated for a different version of `@rive-app/react-native`. Run `npx rive-gen-types` again.
