Use with AI agents

Point Lovable, Cursor, Replit, and other AI coding tools at the SDK so they generate correct, secure code.

Built for AI agents

Point your agent at the machine-readable docs: llms.txt is the page index, and llms-full.txt is the full-text dump. Load those first, then use the starter prompt below.

Prime your agent

Drop this into your agent's context before you ask it to build a native feature.

You're building with @bdk/native (docs: https://docs.thebdk.com).

Install:  npm install @bdk/native
Browser:  import { createBdkNative } from "@bdk/native/browser"
          const bdk = createBdkNative();

Rules:
- Use the typed namespaced helpers: bdk.media.*, bdk.ui.*, bdk.navigation.*,
  bdk.iap.*, bdk.auth.*, bdk.location.*, bdk.device.*, bdk.share.*, bdk.permissions.*.
- Results arrive on an event — subscribe with bdk.on(event, cb) BEFORE you call.
- To detect the native app: const info = await bdk.ready(3000). Never branch on
  bdk.isNative() at page load — it reads false until device info arrives.
- bdk.environment() is safe synchronously: "native" is reliable immediately on
  current app builds; on "unknown" fall back to await bdk.ready(3000).
- Outside the app a call resolves with triggered: false; branch on
  !result.triggered to fall back to the web.
- Server features: import from @bdk/native/server/* in backend code only, and
  read credentials from env — never hardcode keys.

Full machine-readable reference: https://docs.thebdk.com/llms-full.txt

The patterns to follow

A handful of rules keep generated code correct.

Subscribe before you call. Interactive features (camera, pickers, biometrics, purchases) deliver their result on an event, not the returned promise.
await bdk.ready(...) before branching on bdk.isNative(). Device info arrives shortly after load, so a page-load isNative() check takes the web path even inside the app.
bdk.environment() for an instant answer. "native" is trustworthy at first tick on current app builds; treat "unknown" as "wait" and use ready(). UX only — never auth.
Branch on !result.triggered. Outside the native app a call doesn't run — handle that path so your web build keeps working.
Keep server code on the server. @bdk/native/server/* runs on your backend with your credentials; never import it into a browser bundle.

import { createBdkNative } from "@bdk/native/browser";

const bdk = createBdkNative();

// Subscribe first…
bdk.on("photoCaptured", (photo) => console.log(photo.fileUrl));

// …then call. Outside the app, fall back to the web.
const result = await bdk.media.capturePhoto();
if (!result.triggered) openWebFilePicker();

Keys stay in the environment

Agents copy your examples closely, so every example here reads credentials from the environment. Follow the same rule: pass keys from env (or a secrets manager), never in client code or source.

Server helpers read their credentials from arguments or environment variables. Don't hardcode API keys, and never ship a server import to the browser.

import { sendPushNotification } from "@bdk/native/server/onesignal";

await sendPushNotification({
  message: "Your order shipped",
  playerIds: [playerId],
  oneSignalAppId: process.env.ONESIGNAL_APP_ID,
  oneSignalApiKey: process.env.ONESIGNAL_API_KEY
});