Quickstart

Prerequisites

• Node.js 20+
• pnpm
• A Slack app with signing secret + bot token
• Redis URL
• A Vercel account

Setup

Create a new app

npx @sentry/junior init my-bot
cd my-bot
pnpm install

Install Junior with a plugin package

pnpm add @sentry/junior @sentry/junior-github

This keeps the model extension-first from the start: runtime + at least one integration package.

Wire routes

app/api/[...path]/route.ts

export { GET, POST } from "@sentry/junior/handler";
export const runtime = "nodejs";

app/api/queue/callback/route.ts

export { POST } from "@sentry/junior/handlers/queue-callback";
export const runtime = "nodejs";

Enable Next.js runtime config

next.config.mjs

import { withJunior } from "@sentry/junior/config";

export default withJunior({
  pluginPackages: ["@sentry/junior-github"]
});

instrumentation.ts

export { register, onRequestError } from "@sentry/junior/instrumentation";

If your app has no root layout yet:

export { default } from "@sentry/junior/app/layout";

Set required env vars

SLACK_SIGNING_SECRET=...
SLACK_BOT_TOKEN=...
REDIS_URL=...

Run locally

pnpm dev

Verify locally

• GET http://localhost:3000/api/health returns JSON with status: "ok".
• A Slack mention triggers a threaded response.

Deploy to Vercel

Link the project

pnpm dlx vercel@latest login
pnpm dlx vercel@latest link

Add queue trigger

vercel.json

{
  "functions": {
    "app/api/queue/callback/route.ts": {
      "experimentalTriggers": [
        {
          "type": "queue/v2beta",
          "topic": "junior-thread-message"
        }
      ]
    }
  }
}

If your project uses JavaScript route files (for example from junior init), use app/api/queue/callback/route.js instead.

Configure build command

Set the Vercel build command to run snapshot warmup after app build.

package.json

{
  "scripts": {
    "build": "next build && junior snapshot create"
  }
}

If you prefer postbuild, ensure Vercel runs pnpm build as the build command.

Configure production environment

Required:

• SLACK_SIGNING_SECRET
• SLACK_BOT_TOKEN (or SLACK_BOT_USER_TOKEN)
• REDIS_URL

Also required for build-time snapshot warmup:

• Vercel OIDC enabled so VERCEL_OIDC_TOKEN is available during build

Recommended:

• JUNIOR_BOT_NAME
• AI_MODEL
• AI_FAST_MODEL

Optional:

• JUNIOR_BASE_URL
• AI_GATEWAY_API_KEY

Configure Slack request URL

Set Event Subscriptions and Interactivity URLs to:

https://<your-domain>/api/webhooks/slack

Verify in production

• GET https://<your-domain>/api/health succeeds.
• A Slack mention produces a thread reply.
• Queue callback logs show successful processing.

Common failures

• 401 or signature failures: verify SLACK_SIGNING_SECRET.
• No thread processing: confirm both catch-all and queue callback routes exist.
• No bot post: verify bot token scopes and Slack app installation.
• Slack timeouts in production: check vercel.json queue trigger and callback route path.
• OAuth callback issues for plugins: set JUNIOR_BASE_URL to production URL.
• Snapshot warmup build failures: verify REDIS_URL is available to builds and OIDC is enabled for VERCEL_OIDC_TOKEN.

Next step

Now that runtime wiring is done, focus on extension:

• Plugins Overview
• Custom Plugins