Crossdeck Docs
Dashboard

Errors USP · AI-assisted

Setting up source maps with an AI assistant

If you use Cursor, Claude Code, Codex, GitHub Copilot, or any AI coding assistant, you can set up Crossdeck source-map uploads in one paste. The prompt is personalised for your project's framework + deploy target, so the assistant has everything it needs to do the setup in one pass.

The prompt is generated server-side at click-time from your project's recent events (detected framework, deploy target, key prefix). Two different projects get two different prompts.

How it works

  1. Open your project in your AI assistant.
  2. Click Copy AI prompt above.
  3. Paste it into your AI assistant.
  4. The assistant installs @cross-deck/cli, configures your bundler, adds the CI step, wires the release identifier into your SDK init, and tells you what it changed.
  5. Review the diff, commit, deploy. Trigger a test error — the dashboard shows readable file paths within seconds.
Heads-up — you handle the secret key. The prompt includes your project's publishable key prefix so the assistant knows which Crossdeck project it's setting up. The secret key (cd_sk_live_…) is on you to add to your CI secrets — the assistant will tell you the exact secret name to use (CROSSDECK_AUTH_TOKEN) and point you at your CI provider's secrets UI, but it won't (and can't) write the key into your CI for you. Grab the secret key from Developers → API keys.

Preview the prompt

For the skeptical senior dev — yes, you can read the prompt before pasting it. The exact text is generated server-side at click-time and personalised to your project (framework, deploy target, key prefix), but the structure below is what every prompt looks like.

Show an anonymized example 
I'm setting up source-map uploading for Crossdeck on my web app so production
stack traces show real file:line:function references instead of minified output.

Project: Acme App (publishable key starts with cd_pub_live_3f2a…)
My framework appears to be: vite
My deploy target appears to be: Vercel

Please complete ALL of the following in one pass — don't ask me clarifying
questions I can't answer; make sensible choices and tell me what you chose.

1. Install the Crossdeck CLI as a dev dependency:
     npm install --save-dev @cross-deck/cli
   (or pnpm/yarn equivalent based on the lockfile present)

2. Configure my bundler to emit external source maps with sourcesContent inlined:
   - Vite/Rollup: `build: { sourcemap: true }` in vite.config.ts
   - Webpack: `devtool: 'source-map'` in webpack.config.js
   - Next.js: `productionBrowserSourceMaps: true` in next.config.js
   - ESBuild: `sourcemap: true, sourcesContent: true`

3. Configure my Crossdeck SDK init code to stamp the git SHA as the release identifier.

4. Add a CI step that runs the source-map upload after each production build:
     npx @cross-deck/cli upload-sourcemaps \
       --release "$GIT_SHA" \
       --url-prefix "<my-bundle-runtime-url-prefix>" \
       ./dist

5. The CLI needs a Crossdeck SECRET key (cd_sk_live_…) for upload. Tell me the
   exact secret name to add (CROSSDECK_AUTH_TOKEN) and where to add it in my
   CI provider (GitHub Actions / Vercel / Netlify / GitLab CI).

6. Make sure source maps are NOT deployed to production — strip .map files
   from the deploy artifact after upload.

7. Verify by triggering a test error after deploy and checking the dashboard.

Success criteria: an error captured after deploy resolves on the Crossdeck
dashboard to a readable file path + line + function name
(e.g. "src/checkout/Pay.tsx:114 — handleSubmit"), not a minified bundle hash.

Your actual prompt will swap the framework / deploy target lines for whatever's detected on your project, and lengthen the CI section with provider-specific hints when we know your deploy target.

What success looks like

A normal first run takes ~3–5 minutes. The assistant should:

  • Touch 3–6 files typically: package.json (CLI dependency), the bundler config (vite.config.ts / next.config.js / etc.), your SDK init file (to add appVersion), your CI workflow (.github/workflows/deploy.yml or equivalent), optionally a .gitignore entry for *.map files.
  • Tell you the exact CI secret name to add (CROSSDECK_AUTH_TOKEN) and where to add it in your CI provider's UI.
  • Print a summary of changes at the end — which files it touched and why.

After you commit and deploy, trigger a test error (throw new Error("crossdeck sourcemap test")) and check /dashboard/errors/. A successful setup resolves the top stack frame to something like src/checkout/Pay.tsx:114 — handleSubmit, not a minified bundle hash like main.a7f3.js:1.

Always review the diff before committing. AI assistants occasionally misread project shape and edit the wrong config file — especially in monorepos or projects with multiple bundlers. If the diff looks wrong (touches files unrelated to source-maps, modifies app code beyond the SDK init, or changes the build output dir in ways you don't recognise), discard the changes and use the manual setup guide instead. The manual guide produces the same outcome with framework-specific recipes.

What the prompt covers

The assistant will:

  • Install @cross-deck/cli as a dev dependency using your project's package manager.
  • Configure your bundler to emit external source maps with sourcesContent inlined (Vite, Webpack, Next.js, Rollup, ESBuild — whichever you use).
  • Add the source-map upload step to your CI pipeline (GitHub Actions, GitLab CI, Vercel, Netlify, etc.).
  • Stamp the git SHA as the appVersion in your Crossdeck.init() call so uploads pair with events.
  • Strip .map files from the deploy artefact so they don't get served publicly.
  • Tell you exactly which CI secret to add and where (CROSSDECK_AUTH_TOKEN).

Which AI assistants does this work with?

Any of them. The prompt is plain text and self-contained — no tool-use, no provider-specific syntax:

  • Cursor — paste into chat, the diff appears in your editor.
  • Claude Code — paste into the terminal interface.
  • GitHub Copilot Chat — paste into the chat side panel.
  • Codex — paste into the terminal interface or the cloud agent.
  • Aider / Continue / any open-source assistant — same paste, same outcome.
  • Or any chat AI (ChatGPT, Claude.ai, Gemini) for guidance you apply manually.

Prefer to do this by hand?

The manual setup guide covers everything in framework-by-framework recipes — Vite, Webpack, Next.js, Rollup, ESBuild — with CI examples for GitHub Actions, GitLab CI, Vercel, and Netlify. Same outcome, more typing.

CLI source is public at github.com/Crossdeckhq/crossdeck-cli. File an issue there, or email [email protected].