From 3fe7cebdbe43bf0c99e2755d48e3fe692a3161f5 Mon Sep 17 00:00:00 2001
From: Martin Donadieu <martindonadieu@gmail.com>
Date: Sun, 10 May 2026 20:22:31 +0200
Subject: [PATCH] Document React JSX setup for transitions

---
 .../plugins/transitions/getting-started.mdx   | 27 +++++++++++++++++++
 .../en/capacitor-transitions.md               | 15 +++++++++++
 .../plugins/transitions/getting-started.mdx   | 27 +++++++++++++++++++
 3 files changed, 69 insertions(+)

diff --git a/apps/docs/src/content/docs/docs/plugins/transitions/getting-started.mdx b/apps/docs/src/content/docs/docs/plugins/transitions/getting-started.mdx
index 61701dd50..86f51dea0 100644
--- a/apps/docs/src/content/docs/docs/plugins/transitions/getting-started.mdx
+++ b/apps/docs/src/content/docs/docs/plugins/transitions/getting-started.mdx
@@ -119,6 +119,33 @@ export function InboxPage() {
 }
 ```
 
+### React JSX TypeScript
+
+Importing from `@capgo/capacitor-transitions/react` includes JSX typings for `cap-router-outlet`, `cap-page`, `cap-header`, `cap-content`, and `cap-footer`. In most React projects, that import makes the custom elements valid in TSX automatically.
+
+If TypeScript still reports `Property 'cap-router-outlet' does not exist on type 'JSX.IntrinsicElements'`, add a project declaration file:
+
+```ts
+// src/capgo-transitions.d.ts
+import '@capgo/capacitor-transitions/react';
+```
+
+For Vite, Create React App, and most webpack React apps, placing that file inside `src/` is enough. For Next.js, put it in `src/` or the project root and make sure `tsconfig.json` includes it:
+
+```json
+{
+  "include": ["src", "src/capgo-transitions.d.ts"]
+}
+```
+
+For custom TypeScript or webpack setups that use a separate `types/` folder, include that folder instead:
+
+```json
+{
+  "include": ["src", "types"]
+}
+```
+
 ## Swipe Back
 
 Enable or disable the iOS edge gesture from markup:
diff --git a/apps/web/src/content/plugins-tutorials/en/capacitor-transitions.md b/apps/web/src/content/plugins-tutorials/en/capacitor-transitions.md
index 35f835aad..363159bca 100644
--- a/apps/web/src/content/plugins-tutorials/en/capacitor-transitions.md
+++ b/apps/web/src/content/plugins-tutorials/en/capacitor-transitions.md
@@ -104,6 +104,21 @@ export function InboxPage() {
 }
 ```
 
+The React subpath includes JSX typings for the custom elements. If TypeScript still reports that `cap-router-outlet` does not exist on `JSX.IntrinsicElements`, add this file:
+
+```ts
+// src/capgo-transitions.d.ts
+import '@capgo/capacitor-transitions/react';
+```
+
+For Vite, Create React App, and most webpack React apps, keeping that file under `src/` is enough. For Next.js or custom TypeScript setups, make sure it is included by `tsconfig.json`:
+
+```json
+{
+  "include": ["src", "src/capgo-transitions.d.ts"]
+}
+```
+
 ## Enable swipe back
 
 Use `swipe-gesture="auto"` to enable the gesture only when Capacitor reports a native iOS runtime:
diff --git a/src/content/docs/docs/plugins/transitions/getting-started.mdx b/src/content/docs/docs/plugins/transitions/getting-started.mdx
index 61701dd50..86f51dea0 100644
--- a/src/content/docs/docs/plugins/transitions/getting-started.mdx
+++ b/src/content/docs/docs/plugins/transitions/getting-started.mdx
@@ -119,6 +119,33 @@ export function InboxPage() {
 }
 ```
 
+### React JSX TypeScript
+
+Importing from `@capgo/capacitor-transitions/react` includes JSX typings for `cap-router-outlet`, `cap-page`, `cap-header`, `cap-content`, and `cap-footer`. In most React projects, that import makes the custom elements valid in TSX automatically.
+
+If TypeScript still reports `Property 'cap-router-outlet' does not exist on type 'JSX.IntrinsicElements'`, add a project declaration file:
+
+```ts
+// src/capgo-transitions.d.ts
+import '@capgo/capacitor-transitions/react';
+```
+
+For Vite, Create React App, and most webpack React apps, placing that file inside `src/` is enough. For Next.js, put it in `src/` or the project root and make sure `tsconfig.json` includes it:
+
+```json
+{
+  "include": ["src", "src/capgo-transitions.d.ts"]
+}
+```
+
+For custom TypeScript or webpack setups that use a separate `types/` folder, include that folder instead:
+
+```json
+{
+  "include": ["src", "types"]
+}
+```
+
 ## Swipe Back
 
 Enable or disable the iOS edge gesture from markup: