Sentry Plugin

@theholocron/holocron-plugin-sentry errors

npm · GitHub

Install

pnpm add -D @theholocron/holocron-plugin-sentry

Capabilities

Capability	Token
errors	HOLOCRON_SENTRY_TOKEN (sentry)

Self-contained activation

The Sentry plugin activates automatically at runtime when HOLOCRON_SENTRY_DSN (fallback: SENTRY_DSN) is present in the environment — no provider entry in holocron.config is required for the CLI to route errors to Sentry.

The errors provider entry is used by holocron setup — it calls ensureProject and pushes the DSN to every env key the capability declares (SENTRY_DSN and NEXT_PUBLIC_SENTRY_DSN) at repo scope via the secrets capability — and by holocron doctor (connectivity). Once setup has run, the env var alone is sufficient.

# Sentry activates in any environment where this is set
export SENTRY_DSN=https://...@sentry.io/...

Config

The provider entry is optional at runtime but required if you want holocron setup to provision the project for you:

providers: {
  errors: ["sentry", {
    // Required for setup: your Sentry organization slug
    org: "my-org",
  }],
}

Options

Option	Required	Description
org	Yes	Sentry organization slug
team	No	Default team slug for project creation. Defaults to org slug

Authentication

1. Go to sentry.io/settings/account/api/auth-tokens/
2. Click Create New Token
3. Enable scopes: project:read, project:write, org:read
4. Click Create Token and copy it

For CI, prefer an org-level token: Settings → [Your Org] → Developer Settings → Auth Tokens.

holocron auth set sentry <TOKEN>

Or via env var:

export HOLOCRON_SENTRY_TOKEN=<TOKEN>
# Also recognized:
export SENTRY_AUTH_TOKEN=<TOKEN>

What errors provides

• describe() — returns the provider name and required env var keys (SENTRY_DSN, NEXT_PUBLIC_SENTRY_DSN)
• whoami() — verifies the token by fetching the organization
• ensureProject(input) — create or retrieve a Sentry project, returning its DSN and whether it already existed

Example

import { createPlugin } from "@theholocron/holocron-plugin-sentry";

const plugin = createPlugin({
  token: process.env.HOLOCRON_SENTRY_TOKEN,
  org: "my-org",
});
const errors = plugin.capabilities.errors();

const { dsn, alreadyExists } = await errors.ensureProject({
  name: "my-app",
  platform: "node",
});
console.log(`DSN: ${dsn} (${alreadyExists ? "existing" : "created"})`);