مانیتورینگ خطای React و Next.js با Source Map در دیدبان

در production، React و Next.js کد را به chunkهای کوچک و minify‌شده تبدیل می‌کنند. نتیجه این است که stack trace ممکن است فقط به یک فایل hashدار و خط اول اشاره کند. بدون Source Map، پیدا کردن کامپوننت و خط اصلی زمان‌بر می‌شود.

دیدبان Source Map را بر اساس سه مقدار تطبیق می‌دهد: اپلیکیشن، release و مسیر bundle تولیدشده. اگر این سه مقدار هماهنگ باشند، stack فشرده به فایل TypeScript یا TSX اصلی برمی‌گردد.

توکن SDK را در متغیر محیطی قرار دهید و release را هنگام build تزریق کنید:

```ts Didban.init({ apiKey: process.env.NEXT_PUBLIC_DIDBAN_API_KEY, appName: 'customer-panel', config: { release: process.env.NEXT_PUBLIC_DIDBAN_RELEASE, }, }); ```

برای release از Git SHA، tag یا شناسه یکتای pipeline استفاده کنید. استفاده از عبارتی ثابت مانند `production` باعث می‌شود Source Map چند نسخه با هم اشتباه شود.

Error Boundary برای خطاهای render و lifecycle مناسب است. علاوه بر ثبت exception، نام بخش یا route را به‌صورت tag بفرستید تا رخدادهای مشابه بهتر بررسی شوند.

خطاهای event handler، callbackهای async و درخواست شبکه الزاماً وارد Error Boundary نمی‌شوند. این مسیرها باید نزدیک محل مدیریت خطا capture شوند.

برای request ناموفق، URL پالایش‌شده، method، status و مدت پاسخ مفید است. body، header احراز هویت و اطلاعات شخصی را بدون پالایش ارسال نکنید.

Breadcrumbهای قبل از خطا کمک می‌کنند بفهمید کاربر روی چه دکمه‌ای کلیک کرده، از کدام route آمده و آخرین API ناموفق چه بوده است.

Source Map باید در مرحله build تولید شود، اما لازم نیست کنار فایل‌های JavaScript به کاربر سرو شود. روش پیشنهادی این است:

1. build را اجرا کنید. 2. فایل‌های map را با CLI دیدبان آپلود کنید. 3. بعد از موفقیت همه آپلودها، mapها را از artifact نهایی حذف کنید. 4. سپس deploy را انجام دهید.

نمونه برای Vite:

```bash npx @getdidban/cli sourcemaps upload \ --directory dist \ --release "$GITHUB_SHA" \ --url-prefix /assets \ --delete-after-upload ```

نمونه برای Next.js، وقتی ریشه فایل‌ها `.next` است:

```bash npx @getdidban/cli sourcemaps upload \ --directory .next \ --release "$GITHUB_SHA" \ --url-prefix /_next \ --delete-after-upload ```

توکن CLI از نوع `source_maps:write` است و فقط می‌تواند برای همان اپلیکیشن Source Map بفرستد. از توکن SDK برای CI استفاده نکنید.

اگر stack trace مسیر `/_next/static/chunks/app-123.js` را نشان می‌دهد، artifact دیدبان نیز باید همین مسیر عمومی را داشته باشد. گزینه `--url-prefix` مسیر محلی build را به URL واقعی تبدیل می‌کند.

پیش از ارسال می‌توانید با `--dry-run` mapping فایل‌ها را ببینید:

```bash npx @getdidban/cli sourcemaps upload --directory .next --url-prefix /_next --release test --dry-run ```

ترکیب Error Boundary، ثبت خطاهای async و Source Map نسخه‌بندی‌شده باعث می‌شود خطای React و Next.js از یک stack مبهم به فایل و خط قابل اقدام تبدیل شود. قرار دادن آپلود در CI/CD نیز این فرآیند را از کار دستی و فراموش‌شدنی خارج می‌کند.