TypeScript schemas require the new React Native runtime,
@rive-app/react-native 0.5.0 or later. See the migration guide to upgrade..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.
Quick start
1
Install @rive-app/canvas
.riv files. It’s a dev dependency only and is not bundled into your app.2
Generate schemas
3
Import the Rive file
Importing a
.riv file needs riv in Metro’s assetExts. See loading Rive files.What gets typed
A generated schema looks like this:rewards.riv.d.ts
RiveView are checked, and the state machine must belong to the chosen artboard:
EnumValues:
Referenced assets
Out-of-band assets are listed inreferencedAssets, 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.
Typing your own components
To pass a typed Rive file or view model instance to another component, useTypedRiveFile and TypedViewModelOf:
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:
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:
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
Names aren't checked
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.An import reports 'This .riv.d.ts is out of date'
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.