@artim-industries/stacktrace-sdk-react

React SDK for Artim Stacktrace.

This package provides a lightweight React integration for capturing exceptions, messages, and user context in your React application and sending them to the Artim Stacktrace backend.

Installation

npm install @artim-industries/stacktrace-sdk-react

Usage

Basic Setup

import { ArtimStacktrace } from "@artim-industries/stacktrace-sdk-react";

ArtimStacktrace.init({
  apiKey: "your-api-key",
});

Environment and release are detected automatically — pass them only to override the detection:

ArtimStacktrace.init({
  apiKey: "your-api-key",
  environment: "staging",
  release: "1.0.0",
});

Environment detection

One project holds several environments (development, staging, production, plus any custom ones). The SDK reports which one it is running in, resolved in this order:

1. environment passed to init()
2. ARTIM_ENV, NEXT_PUBLIC_ARTIM_ENV, REACT_APP_ARTIM_ENV, VITE_ARTIM_ENV
3. <meta name="artim-environment" content="staging">
4. Hosting provider variables — VERCEL_ENV / NEXT_PUBLIC_VERCEL_ENV (preview → staging), Netlify's CONTEXT
5. NODE_ENV — development or test → development
6. Hostname heuristic:
   • localhost, 127.0.0.1, *.local, 192.168.*, 10.* → development
   • staging.*, stage.*, preview.*, dev.*, qa.*, *.vercel.app, *.netlify.app, *.pages.dev → staging
7. otherwise production

Aliases are normalized: dev, local, debug → development; stage, stg, preview → staging; prod, live → production. Any other value is kept as a custom environment and registered on the project automatically.

Release detection

The browser cannot read package.json at runtime, so the version has to come from the build. Resolved in this order:

1. release passed to init()
2. ARTIM_RELEASE, NEXT_PUBLIC_ARTIM_RELEASE, REACT_APP_ARTIM_RELEASE, VITE_ARTIM_RELEASE, NEXT_PUBLIC_APP_VERSION, VITE_APP_VERSION, npm_package_version
3. VERCEL_GIT_COMMIT_SHA / NEXT_PUBLIC_VERCEL_GIT_COMMIT_SHA, Netlify's COMMIT_REF
4. <meta name="artim-release" content="1.2.3">
5. "unknown" plus a console warning

Next.js example:

// next.config.mjs
export default {
  env: {
    NEXT_PUBLIC_ARTIM_RELEASE: process.env.npm_package_version,
  },
}

Static hosting example:

<meta name="artim-release" content="1.2.3" />
<meta name="artim-environment" content="staging" />

To check what the SDK resolved:

ArtimStacktrace.getEnvironment() // "production"
ArtimStacktrace.getRelease()     // "1.2.3"

Capture errors manually

try {
  // some code that throws
} catch (error) {
  ArtimStacktrace.captureException(error as Error);
}

Capture messages

ArtimStacktrace.captureMessage("A recoverable warning occurred", "warning");

Set user context

ArtimStacktrace.setUser({
  id: "user-123",
  email: "[email protected]",
  username: "jane.doe",
});

Identify user

ArtimStacktrace.identify("user-123");

React integration

For React apps, use the exported React helpers.

Error boundary

// providers/ErrorProvider.tsx

"use client";

import { useRef } from "react";

import { ArtimErrorBoundary } from "@artim-industries/stacktrace-sdk-react/react";
import { ArtimStacktrace } from "@artim-industries/stacktrace-sdk-react";

export default function ErrorProvider({
  children,
}: {
  children: React.ReactNode;
}) {
  const initialized = useRef(false);

  if (typeof window !== "undefined" && !initialized.current) {
    ArtimStacktrace.init({
      apiKey: "your_api_key",
    });
    initialized.current = true;
  }

  return (
    <ArtimErrorBoundary errorComponent={<h1>Custom Error Component</h1>}>
      {children}
    </ArtimErrorBoundary>
  );
}

//layout.tsx

import ErrorProvider from "@/providers/ErrorProvider";

export default function RootLayout({
  children,
}: Readonly<{
  children: React.ReactNode;
}>) {
  return (
    <html lang="de">
      <body>
        <ErrorProvider>{children}</ErrorProvider>
      </body>
    </html>
  );
}

Hook for user context

import { useArtimUser } from "@artim-industries/stacktrace-sdk-react/react";

function App({ user }) {
  useArtimUser(user);

  return <YourApp />;
}

API

ArtimStacktrace.init(config)

Initializes the SDK with required configuration.

• apiKey (string): API key for authenticating requests.
• environment (string, optional): Overrides the detected environment.
• release (string, optional): Overrides the detected release version.
• endpoint (string, optional): Overrides the ingest endpoint.

ArtimStacktrace.captureException(error, level?)

Captures an exception and sends it to the backend.

• error (Error): Error object.
• level (error | warning | fatal, default error): Event severity.

ArtimStacktrace.captureMessage(message, level?)

Captures a custom message.

• message (string): Text message.
• level (error | warning | fatal, default warning): Event severity.

ArtimStacktrace.setUser(user)

Sets the current user context for future events.

ArtimStacktrace.identify(userId)

Sets the current user identity.

ArtimStacktrace.getEnvironment() / ArtimStacktrace.getRelease()

Returns the environment and release the SDK reports events with.

Build

npm run build

Package exports

• @artim-industries/stacktrace-sdk-react — core SDK
• @artim-industries/stacktrace-sdk-react/react — React helpers

License

MIT

Important

Does not work if there's already a error boundary (like in Next.js a error.tsx in root etc.)