# Nitro Cookies > Native cookie management for React Native. Typed synchronous and asynchronous APIs for iOS, Android, and tvOS. These docs cover Nitro Cookies 1.3.0. List APIs, scoped deletion, and normalized errors are available from 1.3.0. Check the installation guide and release history when upgrading from an earlier version. --- Source: [Installation](https://l2hyunwoo.github.io/react-native-nitro-cookies/start/installation.md) # Installation Install Nitro Cookies and its native runtime, then rebuild your React Native app. This guide assumes an existing native project with a working iOS or Android build. ## Choose the documentation version These docs cover Nitro Cookies **1.3.0**. List queries, scoped deletion, normalized errors, and the runtime `CookieErrorCode` export are available from 1.3.0. If you use 1.2.1 or earlier, upgrade to 1.3.0 and rebuild the native app. See the [1.3.0 release notes](https://github.com/l2hyunwoo/react-native-nitro-cookies/releases/tag/v1.3.0) for Apple request-header matching, tvOS support, and Android WebView error handling. ## Install the packages ```sh [npm] npm install react-native-nitro-cookies react-native-nitro-modules ``` ```sh [yarn] yarn add react-native-nitro-cookies react-native-nitro-modules ``` ```sh [pnpm] pnpm add react-native-nitro-cookies react-native-nitro-modules ``` Nitro Cookies 1.3.0 requires `react-native-nitro-modules >=0.35.0 <1.0.0`. Use a React Native version compatible with your installed Nitro runtime. The iOS deployment target follows React Native. The Android library defaults to API 24; your app can require a higher minimum. ## Rebuild the native app For iOS, install the pods from your app's `ios/` directory: ```sh bundle exec pod install ``` If your project does not use Bundler, run `pod install` instead. Build and launch the app again. Metro reload alone cannot install a new native module. Android uses autolinking; rebuild and launch the Android app after installation. ## Expo projects Use a development build that includes both native packages. Follow [Expo development build](https://l2hyunwoo.github.io/react-native-nitro-cookies/start/expo-development-build.md) for installation, local builds, and rebuilds. Expo Go does not include this module. Rebuild the development client when native dependencies change. ## Run the 1.3.0 example from source Use the repository example app to explore the 1.3.0 APIs: ```sh git clone https://github.com/l2hyunwoo/react-native-nitro-cookies.git cd react-native-nitro-cookies git checkout v1.3.0 corepack enable yarn install --immutable yarn nitrogen ``` Follow the example app's native build setup before running it. This is a contributor checkout, not an npm installation command. Continue with [your first cookie](https://l2hyunwoo.github.io/react-native-nitro-cookies/start/first-cookie.md). For configured dependency combinations, see [platform support](https://l2hyunwoo.github.io/react-native-nitro-cookies/reference/platforms.md#repository-configurations). If setup or cookie operations fail, follow [troubleshooting](https://l2hyunwoo.github.io/react-native-nitro-cookies/guides/troubleshooting.md). --- Source: [Expo development build](https://l2hyunwoo.github.io/react-native-nitro-cookies/start/expo-development-build.md) # Expo development build Use a development build that contains Nitro Cookies and `react-native-nitro-modules`. Expo Go does not include these native modules. Installing their JavaScript packages or reloading Metro cannot add native code to Expo Go. This guide uses Expo SDK 56, React Native 0.85.3, and Nitro Modules 0.35.9. It pins the blank TypeScript template rather than following the latest SDK. The installation below uses Nitro Cookies 1.3.0. See [installation](https://l2hyunwoo.github.io/react-native-nitro-cookies/start/installation.md) for API availability. ## Create the app Install Node.js 20.19 or later and the native tools for your platform. iOS local builds require macOS, Xcode 26.4 or later, and CocoaPods. Android local builds require the Android SDK, an emulator or device, and a compatible JDK; the verification below uses JDK 17. See [Expo environment setup](https://docs.expo.dev/get-started/set-up-your-environment/) for the platform tools. ```sh npx create-expo@4.0.4 cookie-check \ --template expo-template-blank-typescript@56.0.37 --yes --no-install cd cookie-check npm install npx expo install expo-dev-client@56.0.27 npm install --save-exact react-native-nitro-cookies@1.3.0 \ react-native-nitro-modules@0.35.9 ``` No Nitro Cookies config plugin or manual native registration is required for this setup. The native packages use autolinking. Keep the generated lockfile to preserve the resolved dependencies. ## Generate and build the native app For a reproducible SDK 56 setup, pin the native template as well: ```sh curl -fsSL https://registry.npmjs.org/expo-template-bare-minimum/-/expo-template-bare-minimum-56.0.37.tgz \ -o expo-template-bare-minimum-56.0.37.tgz npx expo prebuild --template ./expo-template-bare-minimum-56.0.37.tgz ``` Then build the platform you use: ```sh npx expo run:ios # Or: npx expo run:android ``` The commands build, install, and launch your own native app. Prepare an iOS simulator or Android emulator before running them. Use `--device` to select a device. For a physical iPhone, also configure a unique `ios.bundleIdentifier` in `app.json` and follow Expo's signing instructions. Without an explicit prebuild, the run commands generate missing native directories automatically. ## Check native cookie access Call this helper from a button's async handler. Display the returned text on success and the caught error on failure. Use a fresh value on every run so a previously stored cookie cannot produce a false pass. ```ts import NitroCookies from "react-native-nitro-cookies"; async function checkCookies(): Promise { const url = "https://expo-cookie-check.example"; const name = "expo_development_check"; const value = String(Date.now()); await NitroCookies.set(url, { name, value, path: "/", secure: true }); for (let attempt = 0; attempt < 20; attempt++) { const cookies = await NitroCookies.get(url); if (cookies[name]?.value === value) { return "PASS: native cookie set/get"; } await new Promise((resolve) => setTimeout(resolve, 100)); } throw new Error("Cookie was not visible within 2 seconds"); } ``` Android `set()` submits the write without waiting for CookieManager's acknowledgment. An immediate `get()` can be empty after `await set()`. This check retries reads for a bounded period; it does not change that API contract. `flush()` is not a write-acknowledgment barrier. The example uses the default store and performs no HTTP request. A pass checks native module loading and cookie storage, not WebView or HTTP-client cookie sharing. Android still needs a working WebView provider even though this app has no WebView screen. ## Continue development After installing the development build, start Metro with: ```sh npx expo start --dev-client ``` JavaScript-only changes can reload in that client. After changing native dependencies or native app configuration, regenerate and rebuild: ```sh npx expo prebuild --clean --template ./expo-template-bare-minimum-56.0.37.tgz npx expo run:ios # Or: npx expo run:android ``` `--clean` deletes and recreates `ios/` and `android/`, including manual edits there. Preserve native customizations in app config or config plugins before using it. A Metro restart alone does not rebuild a native dependency. ## Test local source changes To test local changes beyond the published 1.3.0 release, install a source tarball. To test the source, prepare and pack the library in a repository checkout, then install that tarball in the Expo app before generating the native projects: ```sh # Repository root: corepack enable yarn install --immutable yarn package prepare yarn package pack --out /tmp/react-native-nitro-cookies-source.tgz # Expo app directory: npm install /tmp/react-native-nitro-cookies-source.tgz ``` `prepare` builds JavaScript, types, and Nitro bindings; `pack` also runs the documentation packaging step. Do not substitute a plain `npm install react-native-nitro-cookies@1.3.0` when you intend to test the source. Use a new tarball filename when repacking changed source, install it again, and rebuild the development client. ## Verified configuration The check ran with Expo `56.0.23`, React Native `0.85.3`, Nitro Modules `0.35.9`, and `expo-dev-client` `56.0.27`. The development build installed and passed `set()`/`get()` on an iPhone 17 Pro simulator running iOS 26.5 and an Android 15 (API 35) emulator. The Android build used JDK 17. The tested package was a source tarball from commit [`827a165`](https://github.com/l2hyunwoo/react-native-nitro-cookies/commit/827a1655ef2f227982f6aefe84f6b08a826e2d62). The npm 1.3.0 artifact was not independently run in that verification. This verification does not cover other SDK combinations, EAS builds, or cookie sharing with WebViews or HTTP clients. ## References - [Expo development builds](https://docs.expo.dev/develop/development-builds/introduction/) - [Expo SDK and React Native versions](https://docs.expo.dev/versions/latest/) - [Native generation and clean behavior](https://docs.expo.dev/workflow/continuous-native-generation/) - [Expo CLI development-client target](https://docs.expo.dev/more/expo-cli/#launch-target) --- Source: [Your first cookie](https://l2hyunwoo.github.io/react-native-nitro-cookies/start/first-cookie.md) # Your first cookie Store a session cookie, read it back, and build an HTTP request header. Complete [installation](https://l2hyunwoo.github.io/react-native-nitro-cookies/start/installation.md) and run your native app before starting. On Android, a working WebView provider is required even when your app does not display a WebView. ## 1. Store a cookie Run this in an async handler, such as a development button press: ```ts import NitroCookies from "react-native-nitro-cookies"; const url = "https://api.example.com"; await NitroCookies.set(url, { name: "demo_session", value: "demo-token", path: "/", secure: true, }); ``` This uses the default store: Apple shared storage or Android CookieManager. The value is a demonstration token. Use the token issued by your server in an actual authentication flow. ## 2. Read the value On Android, `set()` submits the write without waiting for CookieManager to accept it. An immediate read can still be empty. Confirm that the cookie is visible before using it for authentication; awaiting `set()` alone is not an acknowledgment. ```ts const cookies = await NitroCookies.get(url); const matches = cookies.demo_session?.value === "demo-token"; // true once the write is visible ``` `get` returns a dictionary keyed by cookie name. No matching cookies produces `{}`. For cookies that share a name, use the [list APIs](https://l2hyunwoo.github.io/react-native-nitro-cookies/reference/reading.md#getlist). ## 3. Build a request header ```ts const header = await NitroCookies.getCookieHeader(url); // Contains demo_session=demo-token ``` Use the complete destination URL, including its path. See [send request headers](https://l2hyunwoo.github.io/react-native-nitro-cookies/guides/request-headers.md) for a manual `fetch` example. Do not log real authentication cookies. ## 4. Remove the demonstration cookie ```ts await NitroCookies.clearByName(url, "demo_session"); ``` This example uses a unique name and `/` path. When identities overlap, follow [scoped deletion](https://l2hyunwoo.github.io/react-native-nitro-cookies/guides/scoped-deletion.md). If the cookie is missing, confirm the URL, store, native rebuild, and Android provider in [platform support](https://l2hyunwoo.github.io/react-native-nitro-cookies/reference/platforms.md). --- Source: [Stores and scope](https://l2hyunwoo.github.io/react-native-nitro-cookies/concepts/storage.md) # Stores and scope A cookie belongs to a native store and a scope. Its name alone is not a unique identity. Understand both before sharing login state or deleting cookies. ## Choose a store | Platform | Default store | `useWebKit: true` | | -------- | ------------------------------ | --------------------------------------------------- | | iOS | `HTTPCookieStorage.shared` | `WKWebsiteDataStore.default().httpCookieStore` | | tvOS | `HTTPCookieStorage.shared` | Rejects with `WEBKIT_UNAVAILABLE` | | Android | `android.webkit.CookieManager` | Uses the same CookieManager; the flag has no effect | Synchronous methods use the default store. iOS WebKit access requires an asynchronous method. Choosing a store does not synchronize it with another store or configure your networking library. An ephemeral WKWebView uses a different data store and is outside this API's default WebKit-store access. ## Name, domain, and path `session` at `/` and `session` at `/admin` can coexist. A parent-domain cookie can coexist with a host-only cookie. On Apple platforms, a stored leading dot distinguishes a domain cookie from a host-only cookie in list results. Use `getList` to preserve duplicate names. `get` produces a dictionary and keeps only the last native result for each name. Native ordering is not an application-level priority rule. Android returns a request Cookie header rather than full stored objects. URL lists therefore expose name/value pairs with unknown scope fields omitted. Legacy Android dictionary queries expose a derived URL host and `/` path; those fields are not proof of the original scope. ## A query is not a request header Apple `get`, `getList`, and their sync variants use legacy domain selection. They do not apply all request-path, Secure, and expiration rules used by `getCookieHeader`. Android URL queries follow CookieManager's URL selection. Use [request-header APIs](https://l2hyunwoo.github.io/react-native-nitro-cookies/guides/request-headers.md) when sending cookies to a destination. Use lists when inspecting identities or planning [scoped deletion](https://l2hyunwoo.github.io/react-native-nitro-cookies/guides/scoped-deletion.md). ## Security flags `secure` restricts sending cookies to HTTPS. `httpOnly` is a browser script-access flag. Native cookie APIs can still expose HttpOnly values to React Native code. Neither flag encrypts a cookie or makes it a secret vault. Keep authentication values out of logs and diagnostic payloads. --- Source: [Send request headers](https://l2hyunwoo.github.io/react-native-nitro-cookies/guides/request-headers.md) # Send request headers Build a `Cookie` header for the exact URL of a manual request. Use this when your networking layer needs an explicit header. ## Read, then send ```ts import NitroCookies from "react-native-nitro-cookies"; const url = "https://api.example.com/admin/profile"; const cookieHeader = await NitroCookies.getCookieHeader(url); const response = await fetch(url, { headers: cookieHeader ? { Cookie: cookieHeader } : {}, }); ``` Use the full request path. A cookie for `/admin` matches `/admin/profile`, but not `/administrator`. Secure cookies require HTTPS. Matching HttpOnly cookies and duplicate names remain in the header. No match returns `''`, so the example omits the header in that case. For default-store access without a Promise, call `getCookieHeaderSync(url)`. For the iOS WebKit store, call `getCookieHeader(url, true)`. ## Keep the destination consistent The header is a snapshot for the supplied URL. Recompute it when the destination changes. Do not reuse an authentication header for another host or assume it describes a later redirect target. Your networking layer controls redirects and its own cookie behavior; this library does not configure those policies. Do not construct a request header from `get` or `getList`. On Apple platforms, those queries use different selection rules. See [headers and responses](https://l2hyunwoo.github.io/react-native-nitro-cookies/reference/requests.md) for the full signatures. ## Integrate with an HTTP client The example passes the header explicitly to React Native `fetch`. With another client, such as axios, supply the same value through that client's [per-request headers option](https://axios-http.com/docs/req_config) for the same URL. Avoid a global authentication header because requests can target different hosts and paths. Sending a header does not establish automatic cookie sharing or response-cookie import between Nitro Cookies and the client. This package does not configure the client's credentials, redirect handling, or native cookie jar. Verify those behaviors for your installed client and platform versions. For a WebView login, follow [WebView store selection](https://l2hyunwoo.github.io/react-native-nitro-cookies/guides/webviews.md). After login, retain the store and cookie identities needed for [targeted logout](https://l2hyunwoo.github.io/react-native-nitro-cookies/guides/scoped-deletion.md#log-out-without-clearing-unrelated-domains). --- Source: [Use a WebView store](https://l2hyunwoo.github.io/react-native-nitro-cookies/guides/webviews.md) # Use a WebView store On iOS, pass `true` to access the default WebKit cookie store. Await the write before navigating the WebView. ```ts import NitroCookies from "react-native-nitro-cookies"; const url = "https://example.com"; await NitroCookies.set( url, { name: "session", value: "server-issued-token", secure: true, path: "/", }, true, ); const cookies = await NitroCookies.get(url, true); ``` The `useWebKit` argument selects WebKit: it is the third argument to `set` and the second argument to `get`. Leaving it out selects Apple shared storage. Use the same store when reading, writing, and deleting a login cookie. ## Integration boundaries This package manages cookies. It does not create or configure a WebView, copy cookies between stores, or target an ephemeral WKWebsiteDataStore. Configure your WebView library's data-store and cookie options separately. Synchronous methods cannot access the WebKit store. ## Android and TV Android operations always use CookieManager. The `useWebKit` argument does not select another Android store. A missing, disabled, or updating WebView provider can make store operations fail with `WEBVIEW_UNAVAILABLE`. Android TV devices may ship without a provider. Error detection does not supply a replacement cookie backend. tvOS has shared storage but no WebKit implementation in this library. Passing `true` rejects with `WEBKIT_UNAVAILABLE`. Use the default store on tvOS. See [platform support](https://l2hyunwoo.github.io/react-native-nitro-cookies/reference/platforms.md) before sharing code across devices. --- Source: [Delete one cookie scope](https://l2hyunwoo.github.io/react-native-nitro-cookies/guides/scoped-deletion.md) # Delete one cookie scope Use the `clearCookie` APIs when multiple cookies share a name. Supply the original name, domain, and path to avoid selecting a sibling cookie. ## Apple: retain the stored identity ```ts import NitroCookies from "react-native-nitro-cookies"; const url = "https://api.example.com/admin"; const cookies = await NitroCookies.getList(url); const target = cookies.find( (cookie) => cookie.name === "session" && cookie.path === "/admin", ); if (target?.path) { await NitroCookies.clearCookie(url, { name: target.name, domain: target.domain, path: target.path, }); } ``` List results preserve Apple's stored domain, including its leading dot. Pass that representation back unchanged. Pass `true` to both asynchronous calls when working with the iOS WebKit store. Deleting a missing identity succeeds without changing another cookie. ## Android: retain the original write scope Android URL lists cannot recover stored domains or paths. Keep those fields when writing: ```ts const url = "https://api.example.com/admin"; const scope = { name: "session", domain: "api.example.com", path: "/admin" }; await NitroCookies.set(url, { ...scope, value: "server-issued-token", secure: true, }); await NitroCookies.clearCookie(url, scope); ``` An explicit domain emits a Domain attribute, with or without a leading dot. Existing Android `set` also emits a Domain attribute when it defaults a missing domain to the URL host. Retain that domain for deletion; do not infer a host-only scope from an omitted `set` argument. Omit the deletion domain only for a cookie actually stored as host-only, such as a raw Set-Cookie header without Domain. Use HTTPS for Secure cookies. ## Completion and validation On Android, `clearCookieSync` submits an expiration write without acknowledgment. `clearCookie` waits for write acceptance. Neither method can report whether the cookie existed. Apple deletion resolves after the selected store operation. The selector requires a valid cookie name, an absolute path, and a compatible domain. Invalid selectors fail before mutation. See [delete cookies](https://l2hyunwoo.github.io/react-native-nitro-cookies/reference/deletion.md) and [errors](https://l2hyunwoo.github.io/react-native-nitro-cookies/reference/errors.md). ## Log out without clearing unrelated domains Retain every cookie identity used by the login flow, including cookies with the same name at different paths. On Apple, retain the chosen store too. On Android, record the original write scopes because reads cannot reconstruct them. ```ts import NitroCookies, { type CookieIdentifier, } from "react-native-nitro-cookies"; const url = "https://api.example.com/account"; const identities: CookieIdentifier[] = [ { name: "session", domain: "api.example.com", path: "/" }, { name: "session", domain: "api.example.com", path: "/account" }, ]; for (const identity of identities) { await NitroCookies.clearCookie(url, identity); } ``` This example deletes only the supplied identities from the default store. For an iOS WebKit login, pass `true` as the third argument of each `clearCookie` call. Use a compatible URL for each domain; a single URL cannot select unrelated domains. `clearAll` clears the entire selected store, including unrelated domains. Reserve it for a deliberate full-store reset. Local cookie deletion does not revoke a server session or remove credentials held by another store or HTTP client. Complete server logout and any client-specific cleanup according to your app's authentication flow. --- Source: [Migrate an existing app](https://l2hyunwoo.github.io/react-native-nitro-cookies/guides/migration.md) # Migrate an existing app Nitro Cookies follows the familiar asynchronous cookie API from `@react-native-cookies/cookies`. Replace the import, then verify your app's store and platform assumptions. ## Replace the native dependency Install both packages from the [installation guide](https://l2hyunwoo.github.io/react-native-nitro-cookies/start/installation.md), remove the previous native cookie package, and rebuild the app. ```diff - import CookieManager from '@react-native-cookies/cookies'; + import CookieManager from 'react-native-nitro-cookies'; ``` Keeping the local name can reduce changes at call sites. It does not prove every old behavior matches. ## Review your assumptions | Existing assumption | What to verify | | ------------------------------------------ | -------------------------------------------------------------- | | One cookie per name | Use list APIs if duplicate names matter. | | A read result contains the original scope | Android URL results cannot recover it. Retain the write scope. | | Native and WebView cookies share a store | Select the iOS WebKit store explicitly where needed. | | All Android devices have cookie storage | Handle devices without a working WebView provider. | | Name-only removal targets a precise cookie | Use scoped deletion for overlapping identities. | | Every platform supports every method | Check `getAll`, WebKit, persistence, and session behavior. | ## Adopt synchronous methods deliberately Sync methods do not return Promises and cannot access the iOS WebKit store. Keep asynchronous calls where you need WebKit access or platform acknowledgment. Do not replace all async calls solely because sync methods exist. Verify authentication, logout, WebView navigation, and persistence on your target platforms. Use the [error reference](https://l2hyunwoo.github.io/react-native-nitro-cookies/reference/errors.md) for the normalized error contract. --- Source: [Troubleshoot cookies](https://l2hyunwoo.github.io/react-native-nitro-cookies/guides/troubleshooting.md) # Troubleshoot cookies Start with the symptom, then check the native setup, selected store, and cookie scope. Use the [platform table](https://l2hyunwoo.github.io/react-native-nitro-cookies/reference/platforms.md) to confirm which operations are available. ## Import fails before a method runs Nitro Cookies creates its native HybridObject when the module is imported. If the native module is missing, import can fail before the operation-level error wrapper runs. 1. Install both Nitro Cookies and a compatible Nitro runtime. 2. Install Apple pods where applicable, then rebuild and launch the native app. 3. For Expo, use a development build containing both native packages. Expo Go cannot load this module. 4. In Jest, mock the native runtime before importing Nitro Cookies. See the repository's [testing instructions](https://github.com/l2hyunwoo/react-native-nitro-cookies/blob/main/CONTRIBUTING.md). Metro reload alone does not add a native module. See [installation](https://l2hyunwoo.github.io/react-native-nitro-cookies/start/installation.md). ## An example method is missing Compare your installed package version with the [release history](https://github.com/l2hyunwoo/react-native-nitro-cookies/releases). These docs cover 1.3.0. List APIs, scoped deletion, and normalized errors are available from 1.3.0. For an earlier version, follow the [installation guide](https://l2hyunwoo.github.io/react-native-nitro-cookies/start/installation.md) to upgrade and rebuild the native app. ## Android reports WEBVIEW_UNAVAILABLE Android cookie storage depends on a working WebView provider, even if the app displays no WebView. Check that the device has an installed, enabled provider and that its update has finished. Catch `WEBVIEW_UNAVAILABLE` where the app can explain that cookie storage is unavailable. Some Android TV devices have no provider. Installing Nitro Cookies cannot supply a replacement cookie backend. See [errors](https://l2hyunwoo.github.io/react-native-nitro-cookies/reference/errors.md) for the source-branch error contract. ## A write succeeds but the next read is empty On Android, `set` and `setMany` submit writes without waiting for CookieManager's acceptance callback. This applies to both synchronous and asynchronous variants. Awaiting `set` is not an acknowledgment. Confirm that the intended cookie is visible before using it for authentication; do not treat a fixed delay as a completion guarantee. Also check these conditions: - Use an HTTP or HTTPS URL with the intended host and path. Secure cookies require HTTPS. - On iOS, read and write from the same store. `useWebKit` selects the default WebKit store for supported async methods. - `setFromResponse` writes to Apple shared storage. It has no WebKit selector. - A WebView's ephemeral store is outside this package's store selection. - HttpOnly restricts browser `document.cookie`; it does not hide a returned value from React Native JavaScript. See [writes](https://l2hyunwoo.github.io/react-native-nitro-cookies/reference/writing.md) and [stores and scope](https://l2hyunwoo.github.io/react-native-nitro-cookies/concepts/storage.md). ## A dictionary hides a cookie or deletion leaves one behind `get` keys results by name, so duplicate names collapse. Use the list APIs to inspect duplicates. Android URL lists expose name and value but cannot recover the original domain, path, or flags. Retain the scope when writing rather than deriving it from Android read metadata. `clearByName` does not select an exact identity on Android. Its result does not prove every matching scope was removed. Use the `clearCookie` APIs with the original name, domain, and path, and the same Apple store. See [scoped deletion](https://l2hyunwoo.github.io/react-native-nitro-cookies/guides/scoped-deletion.md). ## A manual request sends unexpected cookies Build a request header with `getCookieHeader` for the exact destination URL, including its path. Do not join dictionary or list values to recreate the header. Apple query selection differs from request-header matching. Recompute the header when the destination changes, and inspect your networking layer's redirect and cookie policies separately. See [send request headers](https://l2hyunwoo.github.io/react-native-nitro-cookies/guides/request-headers.md). ## Report a reproducible problem Include the library version or source commit, React Native and Nitro versions, OS/device, full URL shape, store choice, and failing operation. On Android, include the WebView provider status. Use a demonstration cookie and remove authentication tokens from logs. Submit a minimal reproduction through [GitHub Issues](https://github.com/l2hyunwoo/react-native-nitro-cookies/issues). --- Source: [API overview](https://l2hyunwoo.github.io/react-native-nitro-cookies/reference/index.md) # API overview Import the default `NitroCookies` object to access all 23 operations. Signatures in this reference describe methods on that object. ```ts import NitroCookies, { CookieErrorCode, type Cookie, type CookieIdentifier, type Cookies, type CookieError, } from "react-native-nitro-cookies"; ``` ## Find an operation | Task | Methods | Reference | | --------------------------------------- | ------------------------------------------------------------------------------------ | --------------------------------------- | | Read stored cookies | `getSync`, `get`, `getListSync`, `getList`, `getAll`, `getAllList` | [Read cookies](https://l2hyunwoo.github.io/react-native-nitro-cookies/reference/reading.md) | | Write cookies | `setSync`, `set`, `setManySync`, `setMany`, `setFromResponseSync`, `setFromResponse` | [Write cookies](https://l2hyunwoo.github.io/react-native-nitro-cookies/reference/writing.md) | | Build headers or fetch response cookies | `getCookieHeaderSync`, `getCookieHeader`, `getFromResponse`, `getFromResponseList` | [Headers and responses](https://l2hyunwoo.github.io/react-native-nitro-cookies/reference/requests.md) | | Delete cookies | `clearCookieSync`, `clearCookie`, `clearByNameSync`, `clearByName`, `clearAll` | [Delete cookies](https://l2hyunwoo.github.io/react-native-nitro-cookies/reference/deletion.md) | | Persist or remove session cookies | `flush`, `removeSessionCookies` | [Persistence and sessions](https://l2hyunwoo.github.io/react-native-nitro-cookies/reference/lifecycle.md) | ## Shared conventions - Supply a full HTTP(S) URL where a URL is required. - `useWebKit` is an optional boolean argument, not an options object. Its default is `false`. - Sync methods use the default store. Async methods return a Promise, but completion guarantees still depend on the platform and operation. - Dictionary results use cookie names as keys. Lists preserve duplicate names. - Failures in the wrapper expose a string `code`. Read the [error contract](https://l2hyunwoo.github.io/react-native-nitro-cookies/reference/errors.md) before implementing recovery. The list/scoped-deletion APIs and normalized error contract are **available in 1.3.0**. See [installation](https://l2hyunwoo.github.io/react-native-nitro-cookies/start/installation.md) for release availability and upgrade steps. See [types](https://l2hyunwoo.github.io/react-native-nitro-cookies/reference/types.md) for data shapes and [platform support](https://l2hyunwoo.github.io/react-native-nitro-cookies/reference/platforms.md) for availability. ## Documentation for AI tools Use [llms.txt](https://l2hyunwoo.github.io/react-native-nitro-cookies/llms.txt) to find Markdown pages by topic, or [llms-full.txt](https://l2hyunwoo.github.io/react-native-nitro-cookies/llms-full.txt) to read the complete English documentation in one file. Both files are generated from these docs and include the same release guidance and platform limits. --- Source: [Read cookies](https://l2hyunwoo.github.io/react-native-nitro-cookies/reference/reading.md) # Read cookies Read a dictionary for name-based lookup or a list to preserve duplicate names. On Apple platforms, URL queries use domain selection. Use [request headers](https://l2hyunwoo.github.io/react-native-nitro-cookies/reference/requests.md) for cookies eligible for an actual request. `useWebKit` defaults to `false`. It selects the iOS WebKit store when `true`; tvOS rejects that selection and Android ignores the flag. An empty query returns `{}` for dictionaries or `[]` for lists. ## getSync ```ts getSync(url: string): Cookies ``` Read the default store synchronously. Results are keyed by name; duplicate names overwrite earlier entries. ## get ```ts get(url: string, useWebKit?: boolean): Promise ``` Read the selected store asynchronously. Dictionary results retain the existing name-collision behavior. Android metadata is derived from the URL, not the stored cookie scope. ## getListSync ```ts getListSync(url: string): Cookie[] ``` **Added in 1.3.0.** Read the default store without losing duplicate names. Apple results preserve stored domains and paths. Android URL results contain name/value pairs only. ## getList ```ts getList(url: string, useWebKit?: boolean): Promise ``` **Added in 1.3.0.** Read a list from the selected store. Order follows the native result. Do not treat Android list entries as deletion identifiers without the original write scope. ## getAll ```ts getAll(useWebKit?: boolean): Promise ``` Read all cookies from the selected Apple store, regardless of domain. Duplicate names collapse into a dictionary. Android rejects with PLATFORM_UNSUPPORTED. ## getAllList ```ts getAllList(useWebKit?: boolean): Promise ``` **Added in 1.3.0.** Read every cookie from the selected Apple store while preserving duplicate names and stored scope. Android rejects with PLATFORM_UNSUPPORTED. [Types](https://l2hyunwoo.github.io/react-native-nitro-cookies/reference/types.md) · [Errors](https://l2hyunwoo.github.io/react-native-nitro-cookies/reference/errors.md) · [Platform support](https://l2hyunwoo.github.io/react-native-nitro-cookies/reference/platforms.md) --- Source: [Write cookies](https://l2hyunwoo.github.io/react-native-nitro-cookies/reference/writing.md) # Write cookies Write structured cookies or forward a raw Set-Cookie header. Supply an absolute HTTP(S) URL and a cookie domain compatible with its host. For structured writes, missing `path` defaults to `/`; missing `domain` defaults to the URL host. `useWebKit` defaults to `false`. Only iOS asynchronous structured writes can select WebKit. On Android, existing write APIs submit CookieManager writes without an acceptance callback, even when they return a Promise. A `true` result is not a cross-platform persistence guarantee. Use [flush](https://l2hyunwoo.github.io/react-native-nitro-cookies/reference/lifecycle.md#flush) when Android disk persistence is required. ## setSync ```ts setSync(url: string, cookie: Cookie): boolean ``` Submit one cookie to the default store and return true when the native method completes without an exception. ## set ```ts set(url: string, cookie: Cookie, useWebKit?: boolean): Promise ``` Write one cookie to the selected store. On iOS WebKit, resolution follows the store completion callback. Android resolution confirms submission. ## setManySync ```ts setManySync(url: string, cookies: Cookie[]): boolean ``` Submit several cookies to the default store. Domain validation runs before writes. This API does not promise transactional rollback for storage failures. ## setMany ```ts setMany(url: string, cookies: Cookie[], useWebKit?: boolean): Promise ``` Write several cookies to the selected store. Apple WebKit writes run through completion callbacks. The result is true after the operation completes without an exception. ## setFromResponseSync ```ts setFromResponseSync(url: string, value: string): boolean ``` Parse or forward raw Set-Cookie text into the default store. The value argument is a response header, not a request Cookie header. Parsing behavior follows the platform. ## setFromResponse ```ts setFromResponse(url: string, value: string): Promise ``` Asynchronous form of the raw response-header write. It has no useWebKit argument. Do not comma-join separate Set-Cookie headers; Expires values can contain commas. [Types](https://l2hyunwoo.github.io/react-native-nitro-cookies/reference/types.md) · [Errors](https://l2hyunwoo.github.io/react-native-nitro-cookies/reference/errors.md) · [Platform support](https://l2hyunwoo.github.io/react-native-nitro-cookies/reference/platforms.md) --- Source: [Headers and responses](https://l2hyunwoo.github.io/react-native-nitro-cookies/reference/requests.md) # Headers and responses Request-header methods read storage. Response methods make a network GET request and parse its response cookies. They do not parse a Response object passed by your application. Use the exact HTTP(S) destination URL. Empty headers return `''`; empty response results return `{}` or `[]`. ## getCookieHeaderSync ```ts getCookieHeaderSync(url: string): string ``` Return a ready-to-send Cookie header from the default store. Apple selects by host, path, Secure, and expiration; Android delegates URL selection to CookieManager. Matching duplicate names remain in the string. ## getCookieHeader ```ts getCookieHeader(url: string, useWebKit?: boolean): Promise ``` Asynchronous header query. useWebKit defaults to false and can select the iOS WebKit store. tvOS rejects WebKit access. HttpOnly cookies can appear in the returned header. ## getFromResponse ```ts getFromResponse(url: string): Promise ``` Make a native GET request and return parsed cookies keyed by name. The method provides no custom request headers or body parameters. It is not a general HTTP client or a documented cross-platform storage-import operation. ## getFromResponseList ```ts getFromResponseList(url: string): Promise ``` **Added in 1.3.0.** Use the same native response request as getFromResponse, returning a list instead of collapsing names. Results preserve parsed metadata; redirect handling and automatic cookie side effects belong to the native networking stack. [Types](https://l2hyunwoo.github.io/react-native-nitro-cookies/reference/types.md) · [Errors](https://l2hyunwoo.github.io/react-native-nitro-cookies/reference/errors.md) · [Platform support](https://l2hyunwoo.github.io/react-native-nitro-cookies/reference/platforms.md) --- Source: [Delete cookies](https://l2hyunwoo.github.io/react-native-nitro-cookies/reference/deletion.md) # Delete cookies Choose scoped deletion for an exact identity. Legacy name-only deletion keeps its existing platform behavior. `useWebKit` defaults to `false` and selects the iOS WebKit store where accepted. A deletion identifier requires `name` and an absolute `path`. Omit `domain` only for host-only deletion; an explicit domain selects that scope. Invalid selectors fail with `PARSE_ERROR`; incompatible domains fail with `DOMAIN_MISMATCH` before mutation. ## clearCookieSync ```ts clearCookieSync(url: string, identifier: CookieIdentifier): void ``` **Added in 1.3.0.** Delete the exact identity from the default store. Returns void. On Apple, a missing identity is a no-op. Android submits an expiration write without acknowledgment or existence reporting. ## clearCookie ```ts clearCookie(url: string, identifier: CookieIdentifier, useWebKit?: boolean): Promise ``` **Added in 1.3.0.** Delete the exact identity from the selected store. Android awaits write acceptance and rejects rejected writes. It cannot report whether the cookie existed. Use HTTPS for Secure cookies. ## clearByNameSync ```ts clearByNameSync(url: string, name: string): boolean ``` Legacy default-store removal by name. Apple removes its first matching result. Android attempts expiration at / with the URL host Domain attribute. The boolean does not establish exact-scope deletion. ## clearByName ```ts clearByName(url: string, name: string, useWebKit?: boolean): Promise ``` Asynchronous legacy name-only removal. It accepts the iOS WebKit selection flag. For overlapping paths or domains, use clearCookie instead. ## clearAll ```ts clearAll(useWebKit?: boolean): Promise ``` Clear the entire selected store, including unrelated domains. There is no URL argument. Apple returns true after completion; Android returns whether CookieManager removed any cookies. Use only when clearing the whole store is intended. [Types](https://l2hyunwoo.github.io/react-native-nitro-cookies/reference/types.md) · [Errors](https://l2hyunwoo.github.io/react-native-nitro-cookies/reference/errors.md) · [Platform support](https://l2hyunwoo.github.io/react-native-nitro-cookies/reference/platforms.md) --- Source: [Persistence and sessions](https://l2hyunwoo.github.io/react-native-nitro-cookies/reference/lifecycle.md) # Persistence and sessions These operations have Android-specific effects. Apple implementations preserve compatibility through no-op behavior. They do not accept a URL or a WebKit-store selector. ## flush ```ts flush(): Promise ``` On Android, call CookieManager.flush() to persist the current cookies to disk. Resolves with no value. On iOS and tvOS, resolves without work; it does not flush the WebKit store. ## removeSessionCookies ```ts removeSessionCookies(): Promise ``` On Android, remove cookies without a persistent expiration and resolve with the platform removal flag. On iOS and tvOS, perform no removal and resolve false. [Types](https://l2hyunwoo.github.io/react-native-nitro-cookies/reference/types.md) · [Errors](https://l2hyunwoo.github.io/react-native-nitro-cookies/reference/errors.md) · [Platform support](https://l2hyunwoo.github.io/react-native-nitro-cookies/reference/platforms.md) --- Source: [Types](https://l2hyunwoo.github.io/react-native-nitro-cookies/reference/types.md) # Types Import types from the package root. Optional fields may be unavailable in a native query result. ## Cookie ```ts interface Cookie { name: string; value: string; path?: string; domain?: string; version?: string; expires?: string; secure?: boolean; httpOnly?: boolean; } ``` | Field | Meaning | | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | | `name`, `value` | Required for a structured write. | | `path` | Defaults to `/` when writing. Unknown in Android URL lists. | | `domain` | Defaults to the URL host when writing. Apple lists preserve the stored leading dot. Unknown in Android URL lists. | | `version` | Optional legacy field; do not rely on a portable native effect. | | `expires` | ISO 8601 timestamp. Use fractional seconds and a timezone, such as `2030-01-01T00:00:00.000Z`. Omit for a session cookie. Lifetime follows the store. | | `secure` | Restricts request sending to HTTPS. | | `httpOnly` | Browser script-access flag. Native APIs can still read the cookie. | `SameSite` and `Max-Age` are not fields on this interface. Raw Set-Cookie handling follows the platform; structured results do not expose every possible header attribute. ## Cookies ```ts type Cookies = Record; ``` Dictionary keys are names. A later native entry replaces an earlier entry with the same name. Use `Cookie[]` list results when duplicates matter. ## CookieIdentifier **Added in 1.3.0.** Used by `clearCookie` and `clearCookieSync`. ```ts interface CookieIdentifier { name: string; path: string; domain?: string; } ``` `path` is required and must start with `/`. Missing `domain` selects host-only deletion for the URL host. An explicit domain selects that stored scope. Android callers must retain the original scope; URL queries cannot recover it. See [scoped deletion](https://l2hyunwoo.github.io/react-native-nitro-cookies/guides/scoped-deletion.md) for the Android write-default distinction. ## CookieError ```ts interface CookieError extends Error { code: CookieErrorCode | string; cause?: unknown; url?: string; cookieName?: string; } ``` This is a TypeScript interface, not a runtime class for `instanceof` checks. The operation wrapper sets `cause` and preserves the original message and stack where available. See [errors](https://l2hyunwoo.github.io/react-native-nitro-cookies/reference/errors.md) for the runtime enum and fallback behavior. --- Source: [Errors](https://l2hyunwoo.github.io/react-native-nitro-cookies/reference/errors.md) # Errors **Since 1.3.0.** All 23 public operation failures throw or reject with an `Error` carrying a string `code`. Use the exported runtime enum to handle known cases. ```ts import NitroCookies, { CookieErrorCode } from "react-native-nitro-cookies"; try { await NitroCookies.get("https://example.com"); } catch (error) { if (error instanceof Error && "code" in error) { if (error.code === CookieErrorCode.WEBVIEW_UNAVAILABLE) { // Show an unavailable-cookie-store state. } } } ``` ## Codes and recovery | Code | Meaning | Next action | | ---------------------- | ---------------------------------------------------------------- | --------------------------------------------------------------------- | | `INVALID_URL` | Missing protocol or invalid URL. | Supply a complete HTTP(S) URL. | | `DOMAIN_MISMATCH` | Cookie or selector domain is incompatible with the URL. | Check the host and original cookie scope. | | `PLATFORM_UNSUPPORTED` | Operation is unavailable on this platform. | Check the support table; avoid unsupported calls. | | `WEBKIT_UNAVAILABLE` | Requested WebKit store cannot be used, including tvOS. | Select shared storage where appropriate. | | `WEBVIEW_UNAVAILABLE` | Android's WebView-backed store cannot be initialized. | Check provider availability; present a recoverable unavailable state. | | `PARSE_ERROR` | Header parsing or selector validation failed. | Check the input and required fields. | | `NETWORK_ERROR` | Response fetching failed or had an unclassified failure. | Check the destination and connectivity. | | `STORAGE_ERROR` | Storage failed or another operation had an unclassified failure. | Inspect the original cause and store state. | Provider detection does not install WebView or create a fallback store. ## Preserved details The wrapper creates a new Error and preserves the original message, available stack, and thrown value through `cause`. It attaches the supplied `url` and, for single-cookie set and clear operations, `cookieName`. It does not add cookie values to context. Original messages and URLs can still contain application data. Existing nonempty string codes are preserved, including unknown codes. Unclassified `getFromResponse` and `getFromResponseList` failures use `NETWORK_ERROR`; other operations use `STORAGE_ERROR`. Known bridge parsing follows Nitro 0.35.9 message formats and may need updates if the bridge changes. ## Initialization failures Import-time hybrid-object creation occurs outside operation normalization. If the native module cannot be found, check the native installation and rebuild the app before debugging cookie operations. --- Source: [Platform support](https://l2hyunwoo.github.io/react-native-nitro-cookies/reference/platforms.md) # Platform support Nitro Cookies targets native React Native apps on iOS, Android, and tvOS. Android TV uses the Android implementation and still requires a working WebView provider for store operations. Web and Expo Go do not provide this native module. ## Availability | Capability | iOS | tvOS | Android / Android TV | | -------------------------------------------- | -------------------------------- | ---------------------------- | ----------------------------------- | | Default-store read, write, headers, deletion | Shared storage | Shared storage | CookieManager; provider required | | `useWebKit: true` | Default WebKit store, async only | `WEBKIT_UNAVAILABLE` | Flag ignored | | List queries | Stored metadata | Stored metadata | URL lists: name/value only | | `getAll`, `getAllList` | Supported | Supported with default store | `PLATFORM_UNSUPPORTED` | | Scoped deletion | Exact stored identity | Exact stored identity | Expiration at caller-supplied scope | | `getFromResponse`, `getFromResponseList` | Native network request | Native network request | Native network request | | `flush` | No-op | No-op | Persist CookieManager cookies | | `removeSessionCookies` | Resolves `false`, no removal | Resolves `false`, no removal | Platform removal callback | The default Android minimum is API 24. Apple deployment requirements also depend on React Native and Nitro; do not infer app compatibility from WebKit's iOS 11 API availability. The library podspec declares tvOS support, but your React Native tvOS version can require a newer target. ## Repository configurations These are the versions configured in the current example and native fixtures, not a claim that every React Native version is compatible. Check the corresponding CI result when assessing a platform change. | Project | React Native | Nitro Modules | Other configuration | | ----------------------- | ---------------------------- | ------------- | ----------------------------------------------------- | | iOS / Android example | `0.85.3` | `0.35.9` | `react-native-webview 13.16.1`; Android app minSdk 24 | | iOS native fixture | `0.85.3` | `0.35.9` | XCTest through `test-apple.sh ios` | | tvOS native fixture | `react-native-tvos 0.85.3-3` | `0.35.9` | XCTest through `test-tvos.sh` | | Android instrumentation | Example dependencies | `0.35.9` | CI API 35, `google_apis`, x86_64 | The Android CI image is a phone image. Its unavailable-provider tests cover that failure path; they do not establish coverage on an Android TV system image. The peer range is `react-native-nitro-modules >=0.35.0 <1.0.0`. The `react-native: *` peer declaration does not certify every React Native release. Use an Expo development build containing the native packages. See [installation](https://l2hyunwoo.github.io/react-native-nitro-cookies/start/installation.md) and the [CI workflow](https://github.com/l2hyunwoo/react-native-nitro-cookies/blob/main/.github/workflows/ci.yml). ## Diagnose a missing cookie 1. Confirm that the native app was rebuilt after installing both packages. 2. Check the full URL, HTTPS requirement, domain, and request path. 3. Read and write from the same store on iOS. 4. On Android, confirm that a WebView provider is installed and enabled. 5. Use a list for duplicate names and retain the original Android scope. An Android TV device without WebView does not gain a cookie backend from this package. Handle `WEBVIEW_UNAVAILABLE` as a store-availability failure. See [stores and scope](https://l2hyunwoo.github.io/react-native-nitro-cookies/concepts/storage.md) for behavior differences and [errors](https://l2hyunwoo.github.io/react-native-nitro-cookies/reference/errors.md) for recovery codes. For symptom-based checks, follow [troubleshooting](https://l2hyunwoo.github.io/react-native-nitro-cookies/guides/troubleshooting.md).