migrate-to-strict-api — Claude Code skill
migrate-to-strict-api automates migration of a React Native project to the Strict TypeScript API, the default in version 0.87 and available as opt-in preview since 0.80.
MIT 275 installs ★ 28 updated 2026-08-05
npx skills add react-native-community/skills --skill migrate-to-strict-api -a claude-codeWhat migrate-to-strict-api does
The Strict TypeScript API exports auto-generated types from the react-native root. Unlike the old approach, types stay synchronized with the actual API and deep imports from react-native/Libraries/Alert/Alert disappear. This is TypeScript-only — your code and bundle are unchanged.
The skill walks through the project step by step. It checks React Native version (0.80+ required) and confirms tsconfig.json exists. Then it enables the Strict API: on 0.87+ it removes the legacy react-native-legacy-deep-imports flag, on 0.80–0.86 it adds "customConditions": ["react-native", "react-native-strict-api"] to compilerOptions. Next it scans all source files for imports from react-native/Libraries/... or react-native/src/... and rewrites them to root imports, consulting node_modules/react-native/types_generated/index.d.ts. Special cases: codegen imports move under the CodegenTypes namespace, and InitializeCore becomes react-native/setup-env.
If dependencies ship raw TypeScript that breaks under the Strict API, the skill suggests updating the package or adding a path alias with a type stub in tsconfig.json. Jest mock strings like jest.mock('react-native/Libraries/...') are left alone — module resolution for them is independent of TypeScript config.
What it helps with
- Update tsconfig.json to enable Strict API
- Rewrite all deep imports to root imports using the types_generated reference
- Upgrade dependencies incompatible with Strict API
- Move codegen imports into the CodegenTypes namespace
- Replace InitializeCore with setup-env
Example prompts for the agent
- /migrate-to-strict-api
- Run /migrate-to-strict-api to automatically migrate the project to Strict TypeScript API
- Call /migrate-to-strict-api and follow prompts to update dependencies
How to install migrate-to-strict-api
1Skills CLI (Vercel)
npx skills add react-native-community/skills --skill migrate-to-strict-api -a claude-code2Manually: put the files in place
~/.claude/skills/migrate-to-strict-api/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/migrate-to-strict-api/
1Skills CLI (Vercel)
npx skills add react-native-community/skills --skill migrate-to-strict-api -a codex2Manually: put the files in place
.agents/skills/migrate-to-strict-api/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add react-native-community/skills --skill migrate-to-strict-api -a cursor2Manually: put the files in place
.cursor/skills/migrate-to-strict-api/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install react-native-community/skills migrate-to-strict-api2Manually: put the files in place
.github/skills/migrate-to-strict-api/SKILL.md1Skills CLI (Vercel)
npx skills add react-native-community/skills --skill migrate-to-strict-api -a gemini-cli2Platform CLI
gemini skills install https://github.com/react-native-community/skills --path migrate-to-strict-apiManually: put the files in place
.devin/skills/migrate-to-strict-api/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add react-native-community/skills --skill migrate-to-strict-api -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about migrate-to-strict-api
How do I install migrate-to-strict-api in Claude Code?
Run npx skills add react-native-community/skills --skill migrate-to-strict-api -a claude-code in the terminal, then open ~/.claude/skills/migrate-to-strict-api/SKILL.md. The skill will be available as /migrate-to-strict-api.
What does migrate-to-strict-api do?
It moves a React Native project (version 0.80+) to the Strict TypeScript API: enables it in tsconfig.json, converts imports from react-native/Libraries/... to root imports, and upgrades incompatible dependencies.
Will this change my bundle or runtime behavior?
No. The Strict API is a TypeScript-only change. Your code logic and output are unchanged, so you can migrate incrementally without shipping risk.
Source text
SKILL.md · MIT
---
name: migrate-to-strict-api
description: >
Use when migrating a React Native project to the Strict TypeScript API —
the default JavaScript API from React Native 0.87, available as an opt-in
preview since 0.80. Handles tsconfig.json setup, dependency updates,
rewriting deep imports to root imports, and resolving breaking type
changes. Invoke with `/migrate-to-strict-api`.
license: MIT
metadata:
author: react-native-community
version: 0.1.0
---
# Migrate to Strict TypeScript API
Migrate a React Native project to the [Strict TypeScript API](https://reactnative.dev/docs/strict-typescript-api) — auto-generated TypeScript types, scoped to `react-native`'s root exports. The Strict API is the **default from React Native 0.87**, and an opt-in preview on 0.80–0.86.
This migration affects TypeScript analysis only. Nothing changes in the bundle or at runtime, so it is safe to apply incrementally and there is no shipping risk.
## Invocation
```
/migrate-to-strict-api
```
## Step-by-step procedure
Follow every step below **in order**. Do not skip steps.
### 1. Verify prerequisites
- Read `package.json` and confirm the `react-native` version is **>= 0.80**. If not, stop and tell the user to upgrade first. Record whether the version is **>= 0.87** — this decides steps 3 and 5.
- Confirm `tsconfig.json` exists.
- Confirm `node_modules/react-native/types_generated/index.d.ts` exists. If not, tell the user to run their package manager install first.
### 2. Update dependencies
Some libraries ship raw TypeScript source that is type-checked as part of the user's project — most commonly Jest mock entry points imported from a setup file. Under the Strict API these produce errors located under `node_modules`, typically `TS2307: Cannot find module 'react-native/Libraries/...'`, which the user cannot fix in their own code.
- Confirm `skipLibCheck` is enabled (`@react-native/typescript-config` sets it). Do not disable it.
- Whenever type errors are located under `node_modules/<package>` — at any point in this migration — update that package first, checking its releases for a Strict API compatibility fix. Known fixed versions are listed in [references/library-compatibility.md](references/library-compatibility.md).
- If no fixed release exists, apply a local fix by redirecting the imported subpath to an untyped stub, and tell the user to report the incompatibility to the library:
```json
{
"compilerOptions": {
"paths": {
"some-library/jest/mock": ["./untyped-module.d.ts"]
}
}
}
```
```ts
// untyped-module.d.ts
declare const anyExport: unknown;
export default anyExport;
```
An inline `@ts-ignore` does not work for this case — the errors are reported inside the library's files, not at the import site.
### 3. Enable the Strict API in `tsconfig.json`
**React Native >= 0.87** — the Strict API is the default:
- If `compilerOptions.customConditions` contains `"react-native-legacy-deep-imports"`, remove that entry (it is the temporary opt-out, due for removal in a future release), keeping `"react-native"` in place.
- Otherwise, no config change is needed.
**React Native 0.80–0.86** — opt in:
- Add `"customConditions": ["react-native", "react-native-strict-api"]` to `compilerOptions`. **Both entries are required**: `customConditions` replaces (not merges with) the value from an extended config, so omitting `"react-native"` drops the standard condition set by `@react-native/typescript-config` and breaks module resolution for packages that key on it. The project must use `"moduleResolution": "bundler"` (or `"node16"` / `"nodenext"`) for custom conditions to take effect.
### 4. Fix deep imports
#### 4a. Run the ESLint autofix first
`@react-native/eslint-plugin` ships a `no-deep-imports` rule with a code autofixer that rewrites known deep imports (default and type imports) to root imports. If the plugin is installed — it is bundled with `@react-native/eslint-config` — enable the rule in the project's ESLint config:
```json
{"@react-native/no-deep-imports": "error"}
```
Then run ESLint with `--fix` across the project source. Recommend keeping the rule enabled afterwards to prevent regressions.
#### 4b. Manual pass for the remainder
Read `node_modules/react-native/types_generated/index.d.ts`. This file is the source of truth for every export available under the Strict API. Each line maps an internal source path to an exported name:
```ts
export { default as Alert } from "./Libraries/Alert/Alert";
export type { AlertButton } from "./Libraries/Alert/Alert";
```
Parse this file to build two mappings:
- **Value exports**: internal path + original name → exported name (e.g. `./Libraries/Alert/Alert` default → `Alert`)
- **Type exports**: internal path → list of exported type names (e.g. `./Libraries/Alert/Alert` → `AlertType`, `AlertButton`, ...)
Search all source files (`.ts`, `.tsx`, `.js`, `.jsx`) for remaining imports from `react-native/Libraries/...` or `react-native/src/...` subpaths, and rewrite each using the mapping:
| Deep import pattern | Replacement |
| --- | --- |
| `import Foo from 'react-native/Libraries/.../Foo'` | `import {Foo} from 'react-native'` |
| `import type {FooProps} from 'react-native/Libraries/.../Foo'` | `import type {FooProps} from 'react-native'` |
| `import {named} from 'react-native/Libraries/.../Foo'` | `import {named} from 'react-native'` |
When a file already has a `react-native` root import, merge into it rather than adding a duplicate.
**Codegen imports** move to the `CodegenTypes` namespace:
```ts
// Before
import codegenNativeComponent from 'react-native/Libraries/Utilities/codegenNativeComponent';
import codegenNativeCommands from 'react-native/Libraries/Utilities/codegenNativeCommands';
import type {Int32, WithDefault} from 'react-native/Libraries/Types/CodegenTypes';
// After
import {codegenNativeComponent, codegenNativeCommands} from 'react-native';
import type {CodegenTypes} from 'react-native';
// Usage changes: Int32 → CodegenTypes.Int32, WithDefault<...> → CodegenTypes.WithDefault<...>
```
**`InitializeCore`** is a side-effect entry point with no root export — replace it with the dedicated subpath (usually found in Jest setup files and custom entry points):
```diff
- import 'react-native/Libraries/Core/InitializeCore';
+ import 'react-native/setup-env';
```
If a deep import path does not appear in the mapping, it is intentionally private. Look for a root-API alternative; if none covers the use case, flag it to the user and point them to the [feedback thread](https://github.com/react-native-community/discussions-and-proposals/discussions/1015). Note that `react-native/src/private/*` imports are also removed at runtime in 0.87 — those usages must be removed, not just retyped.
#### 4c. Leave Jest string mocks alone
Do not rewrite `jest.mock('react-native/Libraries/...')` or `jest.requireActual(...)` path strings. Module resolution in Jest and Metro is unchanged — these keep working, and TypeScript does not check them. Only when a test file imports a deep path as a module does TypeScript error; where no root export covers the use case, keep the import and suppress the error explicitly:
```ts
// @ts-expect-error - React Native internal, untyped under the Strict API
import NativeAppState from 'react-native/Libraries/AppState/NativeAppState';
```
### 5. Run typecheck and fix remaining type errors
Run `npx tsc --noEmit`. Fix errors iteratively using these known patterns:
#### Component ref and instance types
Core components are now typed as function components, so a component name no longer works as an instance type (`useRef<TextInput>` refers to the component function, and methods like `.focus()` appear missing). This is the most common blocker.
- **On 0.87+**, use the dedicated `*Instance` types — every ref-supporting core component exports one (`ViewInstance`, `TextInputInstance`, `ScrollViewInstance`, `FlatListInstance`, ...). Components without ref support have no instance type: `InputAccessoryView`, `TouchableWithoutFeedback`, `experimental_LayoutConformance`.
- **On 0.80–0.86**, use `React.ComponentRef<typeof Component>` — it resolves the same instance type and works under both the Strict API and the legacy types.
```ts
// Before
const inputRef = useRef<TextInput>(null);
// After (0.87+) — preferred
const inputRef = useRef<TextInputInstance>(null);
// After (any version) — equivalent
const inputRef = useRef<React.ComponentRef<typeof TextInput>>(null);
```
Apply this everywhere a component name is used as an instance type: `useRef` / `createRef` type arguments, `ref` props on wrapper components (`ref?: React.Ref<ViewInstance>`), `React.forwardRef<View, Props>` type arguments, and variables holding instances.
Related replacements:
- `Animated.LegacyRef<View>` is removed — use the plain `*Instance` type; `*Instance` types work transparently with `Animated.*` component variants.
- `NativeMethods` / `NativeMethodsMixin` are removed — use `HostInstance`, or the specific `*Instance` type.
#### `*Static` types removed
The API name itself is now exported as both the value and its type:
```ts
// Before
import {Linking, LinkingStatic} from 'react-native';
function foo(linking: LinkingStatic) {}
// After
import {Linking} from 'react-native';
function foo(linking: Linking) {}
```
Where no same-name type existed previously (`InteractionManagerStatic`, `PixelRatioStatic`, `DevMenuStatic`, `KeyboardStatic`, `DevSettingsStatic`, `NativeModulesStatic`), use `typeof` the value instead (e.g. `typeof PixelRatio`).
Full list: `AlertStatic`, `ActionSheetIOSStatic`, `ToastAndroidStatic`, `InteractionManagerStatic`, `UIManagerStatic`, `PlatformStatic`, `SectionListStatic`, `PixelRatioStatic`, `AppStateStatic`, `AccessibilityInfoStatic`, `ImageResizeModeStatic`, `BackHandlerStatic`, `DevMenuStatic`, `ClipboardStatic`, `PermissionsAndroidStatic`, `ShareStatic`, `DeviceEventEmitterStatic`, `LayoutAnimationStatic`, `KeyboardStatic`, `DevSettingsStatic`, `I18nManagerStatic`, `EasingStatic`, `PanResponderStatic`, `NativeModulesStatic`, `LogBoxStatic`, `PushNotificationIOSStatic`, `SettingsStatic`, `VibrationStatic`
#### Animated type changes
Animated nodes are no longer generic — they are non-generic types with a generic `interpolate` method. Remove type parameters from `Animated.Value`, `Animated.ValueXY`, etc.
#### Deprecated `*Properties` aliases
The legacy `*Properties` aliases are removed. Rename to the matching `*Props` type: `ViewProperties` → `ViewProps`, `TextProperties` → `TextProps`, `ImageProperties` → `ImageProps`, etc. — plus `ImagePropertiesSourceOptions`, which becomes `ImageSourcePropType`.
#### `StyleSheet.absoluteFillObject`
Not part of the Strict API. Replace with `StyleSheet.absoluteFill`, which is equivalent and works under both API modes:
```tsx
// Before
style={{...StyleSheet.absoluteFillObject, borderRadius: 12}}
// After
style={{...StyleSheet.absoluteFill, borderRadius: 12}}
```
#### `useColorScheme()` and `'unspecified'`
The return type no longer includes `'unspecified'` — this value was inaccurately typed in the old manual types and never occurred at runtime. Check for `'dark'` and default to `'light'`:
```ts
// Before — handles a case that cannot occur
const theme = scheme === 'unspecified' ? 'light' : scheme;
// After
const theme = scheme === 'dark' ? 'dark' : 'light';
```
#### Optional props are `type | undefined`
Every optional prop is now typed as `type | undefined`. Wrapper types that re-declare React Native props may need widening to match.
#### Internal helper types
`RecursiveArray`, `RegisteredStyle`, `Falsy`, `WithAnimatedArray`, `WithAnimatedObject`, and other internal-only helpers are no longer accessible from `react-native`. Inline the type definition or find an alternative.
#### Leftover component props removed
Props that existed only in the old type definitions were removed — for example `lineBreakMode` on `Text`, `scrollWithoutAnimationTo` on `ScrollView`, and transform styles declared outside the `transform` array. Remove or replace these usages.
### 6. Verify
- Run `npx tsc --noEmit` again. Confirm zero type errors remain.
- If the project has a Jest suite, run it. Mocks are unaffected by this migration; investigate any new failure before proceeding.
Present a summary of all changes:
- Files modified (count)
- Deep imports rewritten (count)
- Type errors fixed (by category)
- Anything flagged for the user (private APIs with no root equivalent, library incompatibilities)
## Bailing out
If the migration cannot be completed — an unresolvable library incompatibility, a larger error count than the user wants to absorb now, or the user asks to defer — the project can temporarily revert to the legacy types:
- **React Native >= 0.87**: set `"customConditions": ["react-native", "react-native-legacy-deep-imports"]` in `compilerOptions` (both entries required, as in step 3). This opt-out is temporary and due for removal in a future release.
- **React Native 0.80–0.86**: remove `"react-native-strict-api"` from `customConditions`, restoring its previous value.
Do not revert completed work that is valid under both API modes — it remains forward progress for a later attempt:
- Deep imports rewritten to root imports
- `CodegenTypes` namespace usage (also exported when the Strict API is not enabled)
- `react-native/setup-env`
- Ref types written as `React.ComponentRef<typeof Component>`
The exception is `*Instance` ref types, which only exist under the Strict API — when bailing out after step 5, convert these to the equivalent `React.ComponentRef<typeof Component>` form. If a bail-out seems likely from the start, prefer that form throughout.
When bailing out on 0.87+, encourage the user to share what blocked them in the [opt-out discussion thread](https://github.com/react-native-community/discussions-and-proposals/discussions/1015).
© react-native-community · MIT · react-native-community/skills