Quickstart

Prerequisites

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

Create a new app

Start with the initializer. This is the default path for a new project.

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

junior init already creates the core runtime wiring for you:

server.ts
nitro.config.ts and vite.config.ts
vercel.json
app/SOUL.md, app/WORLD.md, and app/DESCRIPTION.md
app/skills/ and app/plugins/
.env.example

SOUL.md defines Junior’s voice, WORLD.md carries operational context, and DESCRIPTION.md is the app description shown on user-facing surfaces. If you need extra context files, add more app/*.md documents and Junior will make them available as optional reference docs at runtime. Do not recreate the old ABOUT.md; use WORLD.md and DESCRIPTION.md instead.

For a new app, you usually do not need to hand-create routes or runtime wrapper files.

Configure environment

Copy values into your local env file. The scaffold includes .env.example with the core runtime variables.

Required:

SLACK_SIGNING_SECRET
SLACK_BOT_TOKEN
REDIS_URL

Recommended:

JUNIOR_BOT_NAME
AI_MODEL
AI_FAST_MODEL
AI_VISION_MODEL

See Config & Environment for the full reference.

Run locally

pnpm dev

This starts the local app on http://localhost:3000 by default.

Verify locally

Check the health route first, then verify a real Slack thread.

GET http://localhost:3000/health returns JSON with status: "ok".
Set your Slack Event Subscriptions and Interactivity URLs to http://<your-tunnel-or-dev-host>/api/webhooks/slack.
Mention the bot in Slack and confirm it replies in the same thread.

Add plugins

The initializer creates local app/plugins and app/skills directories, so you can start there without extra runtime config.

If you want to use npm-distributed plugins, install them explicitly:

pnpm add @sentry/junior-datadog @sentry/junior-github @sentry/junior-linear @sentry/junior-notion @sentry/junior-sentry

List the plugin packages in juniorNitro so they are bundled and available at runtime:

import { defineConfig } from "nitro";
import { juniorNitro } from "@sentry/junior/nitro";

export default defineConfig({
  preset: "vercel",
  modules: [
    juniorNitro({
      pluginPackages: [
        "@sentry/junior-datadog",
        "@sentry/junior-github",
        "@sentry/junior-linear",
        "@sentry/junior-notion",
        "@sentry/junior-sentry",
      ],
    }),
  ],
  routes: {
    "/**": { handler: "./server.ts" },
  },
});

See Plugins for the local-vs-package model.

What `junior init` created

If you need to wire Junior into an existing app, this is what junior init creates.

Server entry point

import { initSentry } from "@sentry/junior/instrumentation";
initSentry();

import { createApp } from "@sentry/junior";

const app = await createApp();

export default app;

Vercel config

junior init generates a nitro.config.ts that uses Nitro’s Vercel preset to build and deploy the app. The juniorNitro() module copies app/**/* and any declared pluginPackages content into the Vercel function bundle at build time.

Deploy to Vercel

junior init does not configure your Vercel project. You still need to add the deploy-specific pieces below.

Link the project

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

Configure build command

The scaffold includes a build script that runs snapshot warmup:

{
  "scripts": {
    "dev": "vite dev",
    "build": "junior snapshot create && vite build"
  }
}

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