Appxiom React SDK (@appxiom/4react)

@appxiom/4react initializes the Appxiom browser SDK and adds React-aware instrumentation for application lifecycle activity. It depends on @appxiom/web, which npm installs automatically.

Table of Contents

• Before You Begin
• Requirements
• Installation
• Test Integration
• Quick Start
• TypeScript
• Automatic React Instrumentation
• Vite
• SSR Frameworks
• Production Deployment
• Public API
• Error Types
• Troubleshooting

Before You Begin

1. Register for an Appxiom account at appxiom.com and log in to the dashboard.
2. Use the + at the top left corner to create an app.
3. Link your web application to Appxiom using the domain (eg: app.xyz.com) in the settings page. No PORT needs to be provided.
4. Copy the APP KEY and PLATFORM KEY from the Appxiom dashboard.
5. Integrate the Appxiom React package into your application as mentioned in installation section.
6. Test your integration to ensure monitoring and reporting are working as expected.

Requirements

• React 18 or React 19.
• A browser environment. The SDK uses browser APIs and must not run during server-side rendering.
• Node.js 18 or later for package installation and builds.

Installation

Install the React integration and React. @appxiom/web is installed automatically as a dependency.

npm install @appxiom/4react react

Test Integration

After installation, validate that your SDK is connected properly by triggering a temporary test issue from the initialized client. Call the helper method #sym:raiseTestIssue once in a safe debug path or temporary validation flow:

JavaScript

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

ax.raiseTestIssue();

TypeScript

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

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

ax.raiseTestIssue();

This creates a custom issue with a payload and stack trace so you can confirm the issue is being reported in the Appxiom dashboard. After successful validation, remove the call and any temporary debug trigger so the test issue is not left in production code.

Quick Start

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

JavaScript

import init from '@appxiom/4react';

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

TypeScript

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

const ax: AXReact = 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).

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.

Vite

@appxiom/4react depends on @appxiom/web, which includes a WebAssembly binary. During local development, exclude both packages from Vite dependency optimization so Vite preserves the binary's source-relative URL:

JavaScript

import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';

export default defineConfig({
  plugins: [react()],
  optimizeDeps: {
    exclude: ['@appxiom/4react', '@appxiom/web'],
  },
});

TypeScript

import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';

export default defineConfig({
  plugins: [react()],
  optimizeDeps: {
    exclude: ['@appxiom/4react', '@appxiom/web'],
  },
});

After adding the configuration, clear Vite's optimized-dependency cache and restart the development server:

rm -rf node_modules/.vite
npm run dev -- --force

This setting only affects Vite's development dependency optimizer. It is safe to keep in the configuration for production builds.

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.

JavaScript

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',
  );
}

TypeScript

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.

Production Deployment

Build and deploy the application normally. For a Vite application:

npm run build

The production build emits Appxiom's WebAssembly binary as an asset and rewrites its loader URL. Deploy the complete build output, including the generated .wasm file, without renaming or omitting assets.

Your CDN or web server must return this header for WebAssembly assets:

Content-Type: application/wasm

Ensure SPA fallback rules do not return index.html for .wasm requests. Returning HTML instead of the binary causes errors such as expected magic word 00 61 73 6d.

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.

JavaScript

ax.setCustomId('user-12345');
ax.startGoal('checkout');
ax.logActivity('Checkout started', { cartValue: 120 });
ax.endGoal('checkout', { orderId: 'ORD-10023' }, 120);

TypeScript

import type { IssueSeverity } from '@appxiom/web';

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',
});
ax.endGoal('checkout', { orderId: 'ORD-10023' }, 120);

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

Error Types

The SDK categorizes detected problems into a set of structured error types so that telemetry, debugging, and reporting are easier to analyze. The values below correspond to the internal error-type mapping used by the SDK.

• HTTPStatusError: Indicates that an HTTP request completed with a non-success status code such as 4xx or 5xx. This is commonly used for failed API responses or backend-side errors.
• HTTPDuplicateRequestError: Represents a situation where the same request was issued more than once, often causing duplicate work or duplicate network activity.
• HTTPDelayedResponseError: Signals that an HTTP request took longer than expected to respond. This usually points to latency, slow network conditions, or backend delays.
• HTTPExceptionError: Captures unexpected exceptions thrown during the HTTP request lifecycle, such as runtime failures, parsing issues, or transport-level exceptions.
• MemoryLeak: Indicates a suspected memory leak where memory usage grows over time without being released.
• MemoryAnomaly: Represents abnormal memory behavior that does not necessarily meet the threshold of a full leak, but still suggests unusual retention or allocation patterns.
• MemoryRisk: Marks a potential memory-related issue that should be monitored closely, even if it has not yet become a confirmed leak or spike.
• MemorySpike: Represents a sudden rise in memory consumption over a short time window, often indicating pressure from a temporary workload or an underlying issue.
• AutoCapturedError: Refers to errors that the SDK captures automatically from the runtime environment without requiring manual instrumentation.
• ResourceLoadError: Indicates that a critical resource such as an image, script, stylesheet, or other asset failed to load properly.
• CustomException: Represents an exception that your application reports manually through the SDK for domain-specific or application-level errors.
• CustomIssue: Denotes a manually reported issue that is not necessarily an exception, but still needs to be tracked as a meaningful product or engineering problem.
• FrameDrop: Signals a frame-rate drop or rendering anomaly that may indicate performance degradation, jank, or excessive main-thread work.

Troubleshooting

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

Add the Vite optimizeDeps.exclude configuration above, 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'.