JavaScript / Browser / Node SDK · AllStak

AllStak JavaScript SDK for Node.js, Express, browser apps, React helpers, Vite, Webpack, Next.js, logs, request telemetry, spans, and source maps.

Install

npm install @allstak/js

Create a project in app.allstak.sa, copy the project API key, and expose it to your app:

export ALLSTAK_API_KEY=ask_live_xxx
export [email protected]

Node.js

import { AllStak } from '@allstak/js';

AllStak.init({
  apiKey: process.env.ALLSTAK_API_KEY!,
  environment: process.env.NODE_ENV ?? 'production',
  release: process.env.ALLSTAK_RELEASE,
  tags: { service: 'worker' },
});

AllStak.logger.info('worker started');

await AllStak.trace('jobs.send-email', async () => {
  // your work here
});

try {
  throw new Error('payment failed');
} catch (error) {
  AllStak.captureException(error as Error);
}

await AllStak.flush();

Express

import express from 'express';
import { AllStak } from '@allstak/js';
import { allstakExpress } from '@allstak/js/express';

AllStak.init({
  apiKey: process.env.ALLSTAK_API_KEY!,
  environment: process.env.NODE_ENV ?? 'production',
  release: process.env.ALLSTAK_RELEASE,
  tags: { service: 'api' },
  httpBodyCapture: {
    request: true,
    response: true,
  },
});

const app = express();
app.use(express.json());
app.use(allstakExpress.requestHandler());

app.post('/checkout', async (_req, res) => {
  res.json({ ok: true });
});

app.use(allstakExpress.errorHandler());
app.listen(3000);

Browser

import AllStak from '@allstak/js/browser';

AllStak.init({
  apiKey: import.meta.env.VITE_ALLSTAK_API_KEY,
  environment: import.meta.env.MODE,
  release: import.meta.env.VITE_ALLSTAK_RELEASE,
  autoBreadcrumbs: true,
});

React helpers

@allstak/js/react provides lightweight helpers when you want to keep the core JS package:

import { AllStakErrorBoundary } from '@allstak/js/react';

export function App() {
  return (
    <AllStakErrorBoundary fallback={<p>Something went wrong.</p>}>
      <AppRoot />
    </AllStakErrorBoundary>
  );
}

For the full React provider API, install @allstak/react.

Vite source maps

import { defineConfig } from 'vite';
import { allstakVitePlugin } from '@allstak/js/vite';

export default defineConfig({
  build: { sourcemap: true },
  plugins: [
    allstakVitePlugin({
      release: process.env.ALLSTAK_RELEASE,
      uploadToken: process.env.ALLSTAK_UPLOAD_TOKEN,
    }),
  ],
});

Next.js source maps

const { withAllStak } = require('@allstak/js/next');

module.exports = withAllStak({
  release: process.env.ALLSTAK_RELEASE,
  uploadToken: process.env.ALLSTAK_UPLOAD_TOKEN,
}, {
  reactStrictMode: true,
});

Useful API

AllStak.captureException(error);
AllStak.captureMessage('deploy started', 'info');
AllStak.logger.warn('payment retry', { orderId: 'ord_123' });
AllStak.setUser({ id: 'user_123', email: '[email protected]' });
AllStak.setTag('region', 'me-central-1');
AllStak.continueTrace('4bf92f3577b34da6a3ce929d0e0e4736', '00f067aa0ba902b7', true);
AllStak.startSpan('checkout.authorize').finish('ok');
await AllStak.flush();

continueTrace(traceId, parentSpanId, sampled) accepts only valid W3C IDs (traceId = 32 lowercase hex, parentSpanId = 16 lowercase hex). It returns false and leaves the current trace unchanged when inbound IDs are malformed.

Configuration

Option	Description
`apiKey`	Project API key from AllStak.
`environment`	Deployment environment, for example `production` or `staging`.
`release`	App version, commit SHA, or build identifier.
`tags`	Tags added to every event. Use `tags.service` for service filtering.
`sampleRate`	Error sample rate from `0` to `1`.
`tracesSampleRate`	Span sample rate from `0` to `1`.
`httpBodyCapture`	Enables request and response body capture with redaction.
`beforeSend`	Optional hook to modify or drop error events before sending.

Privacy

The SDK redacts common sensitive fields such as authorization headers, cookies, passwords, tokens, secrets, and API keys. Keep secrets out of custom metadata and use beforeSend for app-specific redaction.

Troubleshooting

No events: confirm ALLSTAK_API_KEY is set and the project is active.
Minified stack traces: set the same release in the SDK and source-map upload plugin.
App shutdown: call await AllStak.flush() before a short-lived process exits.
Browser requests blocked: allow https://api.allstak.sa in your content security policy.

Contributing and Support

Report bugs with the GitHub bug report template: https://github.com/AllStak/allstak-js/issues/new/choose
Open pull requests using the checklist in CONTRIBUTING.md.
Report security vulnerabilities privately through SECURITY.md.

License

MIT