cloudinary · dawid-ai · Jul 20, 2026
diff --git a/.cursor/rules/cloudinary.mdc b/.cursor/rules/cloudinary.mdc
@@ -0,0 +1,8 @@
+---
+description: Cloudinary cloudinary-react-native — agent guide
+alwaysApply: true
+---
+
+Read and follow `AGENTS.md` in the repository root. It is the single
+authoritative guide for this package: build/test commands, conventions,
+gotchas, and when to use this SDK versus a sibling Cloudinary package.
diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
@@ -0,0 +1,5 @@
+# Cloudinary cloudinary-react-native — instructions for AI coding agents
+
+Read `AGENTS.md` in the repository root and follow it. It is the single
+authoritative guide for this package: build/test commands, conventions,
+gotchas, and when to use this SDK versus a sibling Cloudinary package.
diff --git a/AGENTS.md b/AGENTS.md
@@ -0,0 +1,72 @@
+# AGENTS.md — cloudinary-react-native
+
+## What this package is (one line)
+Official Cloudinary React Native / Expo SDK: upload media from a device and render Cloudinary images and video in-app, built on `@cloudinary/url-gen`.
+
+## When to use this / when NOT to use this
+- **Use this when:** you are in a **React Native or Expo app** and need to upload assets from the device (unsigned via upload preset, or signed via a server-generated signature) or render media through the `AdvancedImage` / `AdvancedVideo` components.
+- **Do NOT use this when:** you only need to build delivery URLs with no native components — use `@cloudinary/url-gen` directly.
+- **Sibling packages:**
+  - Fully native iOS (Swift/Obj-C, no RN) → [`cloudinary_ios`](https://github.com/cloudinary/cloudinary_ios)
+  - Fully native Android (Kotlin/Java, no RN) → [`cloudinary_android`](https://github.com/cloudinary/cloudinary_android)
+  - Plain web React (not RN) → [`@cloudinary/react`](https://github.com/cloudinary/frontend-frameworks)
+  - URL building only → [`@cloudinary/url-gen`](https://github.com/cloudinary/js-url-gen)
+  - Rule of thumb: React Native / Expo app → this package; native iOS/Android or web React → the matching SDK above.
+
+## Setup
+```bash
+npm install cloudinary-react-native
+# Video playback (pick one for your Expo SDK): expo-av (through SDK 54) or expo-video (recommended, SDK 52+)
+# CLDVideoLayer controls also need: @expo/vector-icons expo-font
+```
+No env vars are required to build URLs — only a `cloudName`. Uploads need an upload preset (unsigned) or a server-generated signature (signed). **Never embed `api_secret` in the app.**
+
+## Minimal runnable example
+```tsx
+import { AdvancedImage } from 'cloudinary-react-native';
+import { Cloudinary } from '@cloudinary/url-gen';
+import { View } from 'react-native';
+
+const cld = new Cloudinary({ cloud: { cloudName: 'demo' } });
+const img = cld.image('sample');
+
+export default function App() {
+  return (
+    <View>
+      <AdvancedImage cldImg={img} style={{ width: 300, height: 200 }} />
+    </View>
+  );
+}
+```
+
+## Build / test commands (run these after editing)
+```bash
+npm install        # CI uses npm (`npm ci`). package.json carries a (malformed) "packageManager": "^yarn@1.22.15" field, but CI runs npm — use npm.
+npm test           # jest — run after any change to src/
+npm run typecheck  # tsc --noEmit  (not in CI; run it anyway)
+npm run lint       # eslint "**/*.{js,ts,tsx}"  (not in CI; run it anyway)
+npm run prepack    # bob build — produces lib/ (commonjs, module, typescript); CI runs this
+```
+CI (`.github/workflows/ci.yml`) runs exactly: `npm ci` → `npm run prepack` → `npm test` on Node 18. `lint` and `typecheck` are real scripts but are **not** gated in CI — run them locally before opening a PR.
+
+## Conventions & gotchas
+- **Built on `@cloudinary/url-gen`.** URL/transformation building comes from there (`new Cloudinary(...)`, `cld.image()`, `cld.video()`); this package adds native components and device upload. Import URL-building symbols from `@cloudinary/url-gen`, components from `cloudinary-react-native`.
+- **Source vs build output.** Edit `src/`; `lib/` is generated by `react-native-builder-bob` (`npm run prepack`) and is git/lint/jest-ignored. Never hand-edit `lib/`.
+- **Formatter is Prettier via ESLint** (config inline in `package.json`): single quotes, 2-space, `trailingComma: es5`, no tabs. `npm run lint` enforces it.
+- **Tests** are jest with the `react-native` preset; Expo modules (`expo-av`, `expo-video`, `expo-constants`, `expo-crypto`) are mocked under `mocks/`. Add mocks there if you depend on a new Expo native module.
+- **Peer ranges (v1.3.0):** React `^18 || ^19`, React Native `>=0.79.0`, Expo `^50 || ^51 || ^52 || ^53`; `expo-constants` and `expo-modules-core` are required peers. `@expo/vector-icons`, `expo-av`, and `expo-video` are **optional** peers — only `CLDVideoLayer` and video playback need them. (`expo-font` appears only under `peerDependenciesMeta`, not in `peerDependencies` — it is not a declared peer.) The SDK auto-detects `expo-av` vs `expo-video`. `expo-video` is the recommended player from SDK 52; the `expo-av` package is deprecated in SDK 53 and removed in SDK 55 (last shipped in SDK 54) → prefer `expo-video`.
+- **Mobile security:** uploads use unsigned presets or server-side signatures only; full account credentials must never ship in the bundle.
+
+## Canonical docs (leave the repo for depth)
+- Product docs: https://cloudinary.com/documentation/
+- Transformations: https://cloudinary.com/documentation/image_transformations
+- Upload presets / signed uploads: https://cloudinary.com/documentation/upload_presets
+- API & SDK references: https://cloudinary.com/documentation/cloudinary_references
+- MCP servers (agent/no-code path): https://github.com/cloudinary/mcp-servers
+
+## Agent / MCP note
+If the same capability is exposed via the Cloudinary MCP servers, prefer the MCP tool for autonomous task execution and use this SDK for code generation. See cloudinary/mcp-servers.
+
+## Commit / PR conventions
+- **Conventional Commits** — releases run via `release-it` with the angular conventional-changelog preset (commit format `chore: release ${version}`, tag `v${version}`). Use `feat:` / `fix:` / `chore:` etc.
+- Before opening a PR: `npm test`, `npm run typecheck`, `npm run lint`, and confirm `npm run prepack` builds clean.
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -0,0 +1,30 @@
+@AGENTS.md
+
+# CLAUDE.md — cloudinary-react-native
+
+## What this repo is
+
+`cloudinary-react-native` is the official Cloudinary SDK for React Native and Expo apps: device uploads (`upload`, `unsignedUpload`, `uploadBase64`) and in-app media rendering via `AdvancedImage`, `AdvancedVideo`, and `CLDVideoLayer`. It bundles `@cloudinary/url-gen` as a direct dependency — URL-building imports come from there; components and upload functions come from this package.
+
+## Key constraints and gotchas
+
+- **Edit `src/` only.** `lib/` is generated by `react-native-builder-bob` (`npm run prepack`) and is git/lint/jest-ignored — never hand-edit it.
+- **Use npm, not yarn.** CI runs `npm ci` → `npm run prepack` → `npm test` on Node 18. The `packageManager` field in `package.json` names yarn, but CI is npm.
+- **Video peers are optional and version-sensitive.** `expo-av` (Expo SDK 50–51) and `expo-video` (SDK 52+) are auto-detected; install the one matching your Expo SDK. `expo-av` is deprecated in SDK 53 and removed in SDK 55 — prefer `expo-video`.
+- **`CLDVideoLayer` needs extra setup.** Install `@expo/vector-icons` and `expo-font` explicitly (`expo-font` is not a declared `peerDependency`, so no manager warning appears). Preload with `useFonts({ ...Ionicons.font })` before mounting the component.
+- **Mobile security.** Never embed `api_secret` in the bundle. Use unsigned uploads with an upload preset, or signed uploads where the signature is generated server-side.
+- **Formatter.** Prettier via ESLint (single quotes, 2-space indent, `trailingComma: es5`, no tabs). `npm run lint` enforces it.
+- **New Expo native modules** require jest mocks added to `mocks/` — the preset (`react-native`) does not auto-mock Expo modules.
+- **Conventional Commits.** Releases run via `release-it` with the angular changelog preset. Use `feat:` / `fix:` / `chore:` prefixes.
+
+## Verified build/test commands
+
+```bash
+npm install        # install deps (CI uses npm ci)
+npm test           # jest with react-native preset — run after any src/ change
+npm run typecheck  # tsc --noEmit — not CI-gated; run before opening a PR
+npm run lint       # eslint "**/*.{js,ts,tsx}" — not CI-gated; run before opening a PR
+npm run prepack    # react-native-builder-bob build → lib/ — CI runs this
+```
+
+CI gate (`.github/workflows/ci.yml`, Node 18): `npm ci` → `npm run prepack` → `npm test`. `lint` and `typecheck` are real scripts but are not CI-gated — run them locally before a PR.