Quickstart

This guide takes you from a new account to your first issue. You need an app that you can run locally or deploy. You can connect it in four ways:

SDK: Next.js, Node.js, or the browser. Sends errors with stack traces.
Log drain: Vercel, Railway, Render, and other hosts. No code changes.
OpenTelemetry: any language with an OTLP exporter, including Python, Go, and Rust.
Coding agent: copy one prompt into your coding agent, and it does the setup. See Set up with a coding agent.

For the first three, follow the steps below. Connect your app has a tab for each.

Create an account

Open app.squasher.ai/signup.
Enter your email and select Create account.
Open the sign-in link that Squasher sends to your email. There is no password.

Next time, you can also sign in with Continue with Google.

Create your organization and project

After your first sign-in, Squasher asks for three things:

An organization name, for example your company.
A project name, for example the service you want to monitor.
A platform. This one is optional.

Select Create project. Squasher makes you the owner of the organization and opens the new project’s Setup page. If you join an organization that has no projects, owners and admins see the same form. Other members see a message to ask an owner for access.

Create an ingest key

On the Setup page of your project:

Under 1. Create an ingest key, select Create ingest key. Squasher shows the key only once.
Save the key in your secret store as SQUASHER_API_KEY.
Under 2. Connect your application, select Manual. Save the Project ID as SQUASHER_PROJECT_ID.

Only owners, admins, and security admins can create keys. If your workspace shows No projects yet, ask an owner of your organization to give you access to a project.

Connect your app

Next.js
Node.js
Browser
Log drains
OpenTelemetry

Install the SDK

npm install @squasher-ai/nextjs

bun add @squasher-ai/nextjs

Add SQUASHER_API_KEY and SQUASHER_PROJECT_ID to .env.local.

Create instrumentation.ts

Add this file to your project root, or to src/ if you use a src folder.

instrumentation.ts

export async function register() {
  if (process.env.NEXT_RUNTIME === "nodejs") {
    const { init } = await import("@squasher-ai/nextjs");
    init({
      apiKey: process.env.SQUASHER_API_KEY!,
      projectId: process.env.SQUASHER_PROJECT_ID!,
      environment: process.env.NODE_ENV,
    });
  }
}

The SDK runs on the Node.js runtime only. It does not capture errors on the Edge runtime.

Send a test error

Create a route that throws, then open /api/squasher-test once.

app/api/squasher-test/route.ts

import { squasherApiHandler } from "@squasher-ai/nextjs";

export const GET = squasherApiHandler(async () => {
  throw new Error("Squasher test error");
});

For middleware, Server Components, and the browser, see the Next.js SDK.

Install the SDK

npm install @squasher-ai/node

bun add @squasher-ai/node

Initialize it before your app code

src/index.ts

import { init, installGlobalHandlers } from "@squasher-ai/node";

init({
  apiKey: process.env.SQUASHER_API_KEY!,
  projectId: process.env.SQUASHER_PROJECT_ID!,
  environment: process.env.NODE_ENV,
});

installGlobalHandlers();

installGlobalHandlers() captures uncaught exceptions and unhandled promise rejections.

Send a test error

import { captureError, flush } from "@squasher-ai/node";

await captureError(new Error("Squasher test error"));
await flush();

The SDK sends events in batches every 5 seconds. flush() sends them now, so a short script does not exit first. See the Node.js SDK for more.

Install the SDK

npm install @squasher-ai/browser

Initialize it when your app starts

src/main.ts

import { init } from "@squasher-ai/browser";

init({
  apiKey: import.meta.env.VITE_SQUASHER_API_KEY,
  projectId: import.meta.env.VITE_SQUASHER_PROJECT_ID,
  environment: import.meta.env.MODE,
});

The SDK captures uncaught errors, unhandled promise rejections, and Web Vitals. Session replay is on by default. To turn it off, add replay: { enabled: false }.

Send a test error

Throw new Error("Squasher test error") from a button handler in your app, and select the button. See the Browser SDK for more.

Set the exporter variables

export OTEL_EXPORTER_OTLP_ENDPOINT=https://ingest.squasher.ai
export OTEL_EXPORTER_OTLP_HEADERS="x-squasher-key=$SQUASHER_API_KEY"
export OTEL_SERVICE_NAME=my-service

OTLP requests do not need the project ID. Squasher finds the project from the key.

Restart your service

Restart it so the OpenTelemetry SDK reads the new variables.

Send a test error

Record an exception on a span and set the span status to error, or log a line at error level. See OpenTelemetry for each language.

See your first issue

On the Setup page, under 3. Verify a signal, select Check again. When Squasher finds an event from the last 24 hours, the page shows Recent event received.
Select Issues in the sidebar. Your test error is at the top of the list.
Open the issue to see its event count, when it was first and last seen, and the AI triage summary.

AI triage runs on its own for new issues in the production environment. To triage your test error, open the issue and select Run triage in the Squasher triage card. If the error does not appear, see Troubleshooting.

Next steps

Set up notifications

Send incidents to Slack, PagerDuty, email, or Telegram.

Read AI triage

Learn what the triage summary tells you.

Add uptime monitors

Check your endpoints and open incidents when they fail.

Connect GitHub

Link a repository so that auto-fix can open pull requests.

Get started

Guides

Create an account

Create your organization and project

Create an ingest key

Connect your app

See your first issue

Next steps

Set up notifications

Read AI triage

Add uptime monitors

Connect GitHub

​Create an account

​Create your organization and project

​Create an ingest key

​Connect your app

​See your first issue

​Next steps

Set up notifications

Read AI triage

Add uptime monitors

Connect GitHub

Create an account

Create your organization and project

Create an ingest key

Connect your app

See your first issue

Next steps