كل حِزم SDK

JavaScript / Browser / Node

v0.3.1

@allstak/js

AllStak/allstak-js

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

OptionDescription
apiKeyProject API key from AllStak.
environmentDeployment environment, for example production or staging.
releaseApp version, commit SHA, or build identifier.
tagsTags added to every event. Use tags.service for service filtering.
sampleRateError sample rate from 0 to 1.
tracesSampleRateSpan sample rate from 0 to 1.
httpBodyCaptureEnables request and response body capture with redaction.
beforeSendOptional 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

License

MIT

العودة إلى التوثيق