apply

$27

Allowed without asking for extra permission (beyond normal repo-edit consent): Installing only the LaunchDarkly SDK package(s) named in the recipe(s) for this integration (e.g. one server SDK, or the exact server + client pair listed in a dual-SDK plan -- both packages count as in-scope LD installs). Use the minimum install each recipe specifies (exact package names).

Requires explicit user approval before you run any command or edit manifests: Any change beyond that scope, including but not limited to:

• Upgrading, downgrading, pinning, or adding non-LaunchDarkly packages (peer-dependency "fixes," npm install X@latest, yarn upgrade, pnpm update, bumping React/Node types, transitive lockfile churn, etc.)

• Running **npm audit fix, bulk updates, or replacing** the project's package manager resolution strategy to satisfy the SDK

• Changing engine / packageManager fields, resolutions / overrides, or workspaces entries for reasons other than adding the LD artifact line

If the package manager reports peer conflicts or install failures:

D8 -- BLOCKING: Call your structured question tool now.

• question: "The install reported [specific error]. To fix this, I would need to [specific changes to non-LD packages]. Should I proceed with those additional changes?"

• options:

• "Yes, make those changes"

• "No, keep only the LaunchDarkly package -- I'll resolve conflicts myself"

• "Show me the exact commands first"

• STOP. Do not write the question as text. Do not upgrade an older repo "to match the newest SDK's dependencies" silently. Do not continue until the user selects an option.

If the user declines broader changes: keep only the LD package addition if possible, document the conflict, and proceed with placeholders or manual steps.

Step 2: Add the SDK key to environment configuration

Never hardcode SDK keys, client-side IDs, or mobile keys in application source files (only reference them via environment variables).

Permission before secrets

D7 -- BLOCKING (MANDATORY -- DO NOT SKIP): Call your structured question tool now. This decision point exists for security compliance -- the user must explicitly choose how secrets are handled. Skipping this and proceeding to write keys without consent is a critical failure.

• question: "The SDK needs an SDK key (or client-side ID / mobile key) for your environment. How would you like to set up the secret?"

• options:

• "I'll tell you where to put it"

• "I'll set up the secret myself -- just tell me what variable name to use"

• "Write it to a .env file for me"

• "I don't have an account yet -- help me sign up" -> point to https://app.launchdarkly.com/signup?source=agent, write placeholders and continue (real keys deferred until account is ready)

• STOP. Do not write the question as text. Do not fetch keys from LaunchDarkly or write real values into the repo without the user selecting an option first. Do not infer the answer from context or prior conversation -- always present this choice.

If the user chooses option 1 ("Tell me where to put it"):

• Ask where they want the secret written (file path, secrets manager, etc.)

• Ask how they want to provide the key: paste it, or have the agent fetch it via MCP/API

• Write the key only to the location the user specified

• Do not create a .env or modify any other file

If the user chooses option 2 ("I'll set it up myself"):

• Tell them the variable name(s) they need to set (see the table below)

• Link them to the right dashboard page. When the project key and environment key are known: **https://app.launchdarkly.com/projects/{projectKey}/settings/environments/{envKey}/keys. When only the project key is known: https://app.launchdarkly.com/projects/{projectKey}/settings/environments and tell them to select the environment. When neither is known: https://app.launchdarkly.com/projects and tell them to navigate to Settings > Environments** to find the key.

• Wait for the user to confirm the secret is in place before proceeding to Step 3

• Do not fetch, write, or handle the key value at all

**If the user chooses option 3 ("Write it to a .env file for me"):**

• Ask how they want to provide the key: paste it, or have the agent fetch it via MCP/API

• Follow the [Write to .env](#write-to-env-when-the-user-consents) section below

• Ensure .env is in .gitignore before writing any real values

If the user chooses option 4 ("I don't have an account yet"):

• Point them to https://app.launchdarkly.com/signup?source=agent

• Explain that SDK key setup requires an account -- they can complete setup after signing up

• Ensure .env is in .gitignore before writing (same check as option 3 / [Write to .env](#write-to-env-when-the-user-consents))

• Write placeholder variable names to .env (no real values) so the code compiles

• Continue with Step 3 (init code) using the placeholder env var references. The app will fail to connect to LaunchDarkly until real keys are set, which is expected.

• Note in the onboarding log that key setup is pending account creation

Fetching keys via MCP

When the user asks the agent to fetch the key (via option 1 or 3 above), use the **get-environments MCP tool (if configured). Call it with the project key — the response includes each environment's SDK key, client-side ID, and mobile key. Do not** make separate API requests for individual keys when get-environments already returns them.

get-environments({ request: { projectKey: "PROJECT_KEY" } })

Security: Treat MCP responses containing keys as sensitive. Write keys only to the location the user chose without echoing full key values in chat responses. Keys in agent conversation history or logs may persist beyond the session.

Pick the correct key type from the matching environment in the response (see table below). If MCP is not configured, fall back to ldcli or the REST API (GET /api/v2/projects/{PROJECT_KEY}/environments).

Variable names and where values come from

SDK Type

Variable name (typical)

Source in LaunchDarkly

Server-side

LAUNCHDARKLY_SDK_KEY

get-environments response → environment → SDK key

Client-side

Logical / bundler-prefixed name (see below)

get-environments response → environment → Client-side ID

Mobile

LAUNCHDARKLY_MOBILE_KEY

get-environments response → environment → Mobile key

Client-side (browser) projects: The LaunchDarkly value is still the Client-side ID. In .env, use a name the bundler exposes to client code:

Stack

.env key

Read in code

Create React App

REACT_APP_LAUNCHDARKLY_CLIENT_SIDE_ID

process.env.REACT_APP_LAUNCHDARKLY_CLIENT_SIDE_ID

Vite

VITE_LAUNCHDARKLY_CLIENT_SIDE_ID

import.meta.env.VITE_LAUNCHDARKLY_CLIENT_SIDE_ID

Next.js

NEXT_PUBLIC_LAUNCHDARKLY_CLIENT_SIDE_ID

process.env.NEXT_PUBLIC_LAUNCHDARKLY_CLIENT_SIDE_ID

Other stacks may use different prefixes or plain LAUNCHDARKLY_CLIENT_SIDE_ID -- match what the project already uses for public env vars.

Write to .env (when the user consents)

Use the integration root for the file path (repo root or the target package in a monorepo -- see Detect repository stack).

• **Create or update .env:** If .env does not exist, create it. If it exists, append or update only the LaunchDarkly lines -- do not remove unrelated variables.

• Add what the integration needs:

• Server-only: LAUNCHDARKLY_SDK_KEY=...

• Client/browser: the client-side ID under the correct bundler-prefixed key (e.g. VITE_LAUNCHDARKLY_CLIENT_SIDE_ID=...).

• Full-stack or hybrid (e.g. Next.js, SSR + client): add both the server SDK key and the client-side ID lines when both SDKs are in use.

• Mobile: LAUNCHDARKLY_MOBILE_KEY=... when applicable.

• **.gitignore:** Ensure .env is listed in .gitignore at the same root where you created .env (or the nearest relevant ignore file in a monorepo). If the entry is missing, add it -- only after the user has agreed to repo changes (same permission scope as writing .env). Do not commit files that contain real secrets.

• **.env.example / .env.sample: If the project uses one, add placeholder** entries only (no real keys), so teammates know which variables to set.

If the project does not use dotenv and relies on a config module or hosted secrets, follow existing patterns there instead -- the same D7 consent above still applies before writing real values into any file.

Step 3: Add SDK initialization code

Initialization shape depends on which SDK was chosen during detection and planning. This skill does not include copy-paste samples per SDK -- using the wrong snippet (e.g. React Web when the recipe is Node server) will mislead you.

Source of truth (use in order, repeat per track when dual-SDK):

• SDK recipes -- the row for this track's SDK: install is Step 1 above; for init, follow the SDK detail / doc links listed there.

• SDK detail files under snippets/ (when linked from the recipe) -- curated links and, for many SDKs, a full onboarding sample aligned with that SDK.

• LaunchDarkly's official docs for that SDK (URLs from the recipe or detail file) -- use their entrypoint and async patterns (e.g. React Web: React Web SDK).

Wire credentials using Step 2: server SDKs use LAUNCHDARKLY_SDK_KEY; client/browser SDKs use the client-side ID with the bundler-prefixed env names from Step 2 where applicable.

Add imports and init to the application entrypoint for that track (or the target package's entrypoint in a monorepo -- see Detect repository stack). Dual SDK: server init goes in the server entrypoint from the plan; client/provider init goes in the client entrypoint -- never a single shared block that pretends to cover both unless the official docs for that stack explicitly prescribe one pattern for both.

Key principles

• Import at the top of the file with other imports

• Initialize early in the application lifecycle for that runtime (Node server vs browser)

• Wait for initialization before evaluating flags when the SDK supports it

• Handle errors -- log failures but don't crash the application

• Match existing code style -- same patterns (async/await, callbacks, modules CommonJS vs ESM) as the rest of the codebase

• Use the right pattern per surface -- server-side init from the server recipe in server code; client/provider init from the client recipe in client code. Do not reuse one snippet for both tracks or skip the second track's init when the plan is dual-SDK.

Step 4: Verify the code compiles

After making changes:

• Run the project's build or compile step

• Run the linter if one is configured

• Fix any import errors or type issues without upgrading unrelated dependencies unless the user approved that scope ([Permission before changing other dependencies](#permission-before-changing-other-dependencies))

Do not proceed to the next step if the code doesn't compile.

Upon completion: Start the application