دليل Next.js مع AllStak

التثبيت

ثبّت الحزمة من npm.

npm install @allstak/next

الإعداد

سجّل AllStak على الخادم في instrumentation.ts، وحمّل تهيئة العميل من instrumentation-client.ts (App Router).

// instrumentation.ts
export async function register() {
  const { registerAllStak } = await import('@allstak/next');

  registerAllStak({
    apiKey: process.env.ALLSTAK_API_KEY,
    environment: process.env.NODE_ENV ?? 'production',
    release: process.env.NEXT_PUBLIC_RELEASE,
  });
}

// instrumentation-client.ts (project root)
export * from '@allstak/next/client';

مثال أساسي

غلّف معالج مسار للإبلاغ عن الأعطال مع القياسات.

import { withAllStakRouteHandler } from '@allstak/next';

export const GET = withAllStakRouteHandler(async () => {
  return Response.json({ ok: true });
});

التقاط الأخطاء

التقط الاستثناءات صراحةً، أو غلّف مكوّنًا بحدّ الأخطاء.

import { captureException } from '@allstak/next';

await captureException(new Error('checkout failed'), { route: '/checkout' });

// or, in a client component:
import { withAllStakErrorBoundary } from '@allstak/next';
export default withAllStakErrorBoundary(PageContent, { fallback: <p>Something went wrong.</p> });

تتبّع الطلبات

تُجهَّز نداءات fetch الصادرة تلقائيًا (enableOutboundHttp، الافتراضي true)، فتُلتقط وتُحقن ترويسات traceparent و baggage بمعيار W3C. استخدم withAllStakRouteHandler / withAllStakServerAction لنقاط دخول الخادم.

أفضل الممارسات

• استخدم خطّاف instrumentation ليُراقَب الخادم من البدء البارد.
• وفّر الإصدار عبر NEXT_PUBLIC_RELEASE للتجميع لكل نشر.
• اضبط المتصفح عبر متغيّرات البيئة NEXT_PUBLIC_ALLSTAK_*.