Appxiom React SDK Integration

Detailed documentation is available at Appxiom React SDK.

Initialize the SDK once from browser-only application startup code. Retain the returned ax instance to call its public API elsewhere in your application.

Quick Start

JavaScript

import init from '@appxiom/4react';

const ax = await init(
  'YOUR_APP_KEY',
  'YOUR_PLATFORM_KEY',
  'YOUR_APP_VERSION',
  'YOUR_BUILD_IDENTIFIER',
);

TypeScript

@appxiom/4react ships first-party TypeScript declarations. No separate @types package is required. init(...) returns Promise<AXReact>, and AXReact extends the public AX API from @appxiom/web.

import init, { type AXReact } from '@appxiom/4react';
import type { IssueSeverity } from '@appxiom/web';

const ax: AXReact = await init(
  'YOUR_APP_KEY',
  'YOUR_PLATFORM_KEY',
  'YOUR_APP_VERSION',
  'YOUR_BUILD_IDENTIFIER',
);

const severity: IssueSeverity = 1;

ax.setCustomId('user-12345');
ax.startGoal('checkout');
ax.logActivity('Checkout started', { cartValue: 120 });
ax.reportCustomIssue('Payment failed', 'Gateway timed out.', severity, {
  orderId: 'ORD-10023',
});

IssueSeverity is limited to 0 (Minor), 1 (Major), or 2 (Fatal).

Diagnose Issues with AI Coding Assistants? Connect your IDE and AI agents to Appxiom using MCP Server Integration to inspect real-time crashes, occurrence telemetry, Quality Score metrics, and Goal Friction Impact (GFI) analytics directly within your editor.

Automatic React Instrumentation

After initialization, the integration adds automatic browser-side observation for React hook activity. It records lifecycle activity associated with useEffect, useLayoutEffect, useState, useReducer, useMemo, and useCallback. It also tracks useRef instances for leak analysis.

Initialize the package before rendering the application so the instrumentation is available when components begin rendering. These integrations are installed once per page and do not require component-level wrappers or hooks. React 18 and React 19 use different internal dispatcher locations; @appxiom/4react resolves the compatible location automatically.

SSR Frameworks

For Next.js, Nuxt, SvelteKit, Remix, or any other server-rendered application, load and initialize the SDK only on the client. Do not import or initialize it from server components, route handlers, or server rendering code.

if (typeof window !== 'undefined') {
  const { default: init } = await import('@appxiom/4react');

  const ax = await init(
    'YOUR_APP_KEY',
    'YOUR_PLATFORM_KEY',
    'YOUR_APP_VERSION',
    'YOUR_BUILD_IDENTIFIER',
  );
}

For React client applications, initialize in the browser entry point before createRoot(...).render(...). For Next.js, use a Client Component or another client-only initialization path.

Public API

init(appKey, platformKey, version, buildIdentifier)

Initializes the core SDK, installs the React instrumentation, and returns Promise<AXReact>.

Parameter	Type	Description
appKey	string	Appxiom application key.
platformKey	string	Appxiom platform key.
version	string	Application version.
buildIdentifier	string	Optional build or release identifier.

Inherited AX methods

The returned AXReact instance inherits these supported methods from @appxiom/web:

• setCustomId(customId): associates telemetry with an application user or account identifier.
• startGoal(name): starts a named goal.
• endGoal(name, properties?, value?): ends a named goal with optional metadata and numeric value.
• logActivity(name, properties?): records a custom activity with optional metadata.
• reportCustomIssue(title, description, severity, data?, stacktrace?): reports an application-defined issue.

For the complete core API and deployment details, see the @appxiom/web package documentation.

Troubleshooting

Vite development reports a WASM MIME type or expected magic word error

Add the Vite optimizeDeps.exclude configuration, delete node_modules/.vite, and restart the development server with --force.

Production reports expected magic word 00 61 73 6d

Confirm that the generated .wasm asset was deployed, that no SPA fallback rewrites its request to index.html, and that the response MIME type is application/wasm.

The SDK runs during server rendering

Move the package import and init(...) call to browser-only code. Use a client component, framework client plugin, browser entry point, or a dynamic import guarded by typeof window !== 'undefined'.

---

Connect to MCP Server

Appxiom provides a Model Context Protocol (MCP) server that connects AI coding assistants and IDEs (such as Claude Code, Cursor, Windsurf, and VS Code) directly to Appxiom's real-time diagnostic engine. Once connected, your AI agents can inspect real-time application issues, occurrence telemetry, Quality Score (QS) metrics, and Goal Friction Impact (GFI) analytics directly within your editor.

For setup and configuration instructions, see the MCP Server Integration guide.