fix: Pre-compute doc tree at build time to avoid runtime ENOENT errors (#15637)

sergical · web-flow · commit 495ac79d8d9e · 2025-11-28T13:26:09.000+01:00
diff --git a/.gitignore b/.gitignore
@@ -103,3 +103,5 @@ public/og-images/*
 # yalc
 .yalc
 yalc.lock
+/public/doctree.json
+/public/doctree-dev.json
diff --git a/develop-docs/application-architecture/dynamic-sampling/extrapolation.mdx b/develop-docs/application-architecture/dynamic-sampling/extrapolation.mdx
@@ -1,6 +1,7 @@
 ---
 title: Extrapolation
 sidebar_order: 5
+og_image: /og-images/application-architecture-dynamic-sampling-extrapolation.png
 ---
 
 Client and server-side sampling reduces the amount of data ingested, to help with both performance and cost. When configured, a fraction of the data is ingested according to the specified sample rates within a project. For example, if you sample 10% of 1000 requests to your site in a given timeframe, you will see 100 spans in Sentry. 
@@ -77,4 +78,4 @@ When there is not enough data to properly extrapolate, Sentry will indicate low
 
 - Extrapolation offers benefits in many parts of the product but brings some inherent complexity.
 - Some aggregates can be extrapolated, others cannot.
-- A lot of care should be taken about how to expose extrapolation in the product, and especially in offering switching modes to a user.
+- A lot of care should be taken about how to expose extrapolation in the product, and especially in offering switching modes to a user.
diff --git a/docs/concepts/key-terms/extrapolation.mdx b/docs/concepts/key-terms/extrapolation.mdx
@@ -1,7 +1,10 @@
 ---
 title: Extrapolation
 sidebar_order: 80
-description: "Learn how extrapolation provides accurate metrics from sampled data so you can trust your dashboards and alerts even when you're not capturing every event." 
+description: >-
+  Learn how extrapolation provides accurate metrics from sampled data so you can
+  trust your dashboards and alerts even when you're not capturing every event.
+og_image: /og-images/concepts-key-terms-extrapolation.png
 ---
 
 When you use [sampling](/concepts/key-terms/sample-rates/) to control the volume of data sent to Sentry, you're only capturing a portion of your app's actual traffic. For example, if you sample 10% of 1000 requests, Sentry receives 100 spans. But how do you easily see the actual traffic and performance metrics for your app? 
diff --git a/docs/organization/integrations/cursor/index.mdx b/docs/organization/integrations/cursor/index.mdx
@@ -1,7 +1,10 @@
 ---
 title: Cursor Agent
 sidebar_order: 1
-description: "The Cursor Agent integration allows you to launch Cursor Cloud Agents directly from Seer to help debug, fix issues, and create pull requests for you."
+description: >-
+  The Cursor Agent integration allows you to launch Cursor Cloud Agents directly
+  from Seer to help debug, fix issues, and create pull requests for you.
+og_image: /og-images/organization-integrations-cursor.png
 ---
 
 You can trigger Cursor Cloud Agents from your [Seer Issue Fix](/product/ai-in-sentry/seer/issue-fix/) tab. The Cloud Agents will be provided with Seer's Root Cause Analysis alongside the issue context to help the Cloud Agent understand the issue and generate a solution.
diff --git a/docs/platforms/apple/guides/ios/size-analysis/insights.mdx b/docs/platforms/apple/guides/ios/size-analysis/insights.mdx
@@ -2,6 +2,7 @@
 title: Insights
 sidebar_order: 5250
 description: See how Size Analysis surfaces trends for your iOS builds.
+og_image: /og-images/platforms-apple-guides-ios-size-analysis-insights.png
 ---
 
 Size Analysis Insights point out opportunities to reduce your iOS app's size. They spot patterns like duplicate files, oversized media, or unneeded assets, and list exactly what to fix along with the estimated size savings.
diff --git a/docs/platforms/godot/user-feedback/index.mdx b/docs/platforms/godot/user-feedback/index.mdx
@@ -1,8 +1,12 @@
 ---
 title: Set Up User Feedback
 sidebar_title: User Feedback
-description: "Learn more about collecting user feedback when an event occurs. Sentry pairs the feedback with the original event, giving you additional insight into issues."
+description: >-
+  Learn more about collecting user feedback when an event occurs. Sentry pairs
+  the feedback with the original event, giving you additional insight into
+  issues.
 sidebar_order: 6000
+og_image: /og-images/platforms-godot-user-feedback.png
 ---
 
 Sentry makes it possible to collect user feedback, and optionally associate it with an error event.
diff --git a/docs/platforms/native/advanced-usage/external-crash-reporter/index.mdx b/docs/platforms/native/advanced-usage/external-crash-reporter/index.mdx
@@ -1,7 +1,8 @@
 ---
 title: External Crash Reporter
-description: "How to configure an external crash reporter with the Native SDK."
+description: How to configure an external crash reporter with the Native SDK.
 sidebar_order: 2100
+og_image: /og-images/platforms-native-advanced-usage-external-crash-reporter.png
 ---
 The Native SDK can be configured to work with an external crash reporter, which
 can be used to display crash information to the user, collect user feedback, or
diff --git a/docs/product/explore/metrics/index.mdx b/docs/product/explore/metrics/index.mdx
@@ -1,7 +1,10 @@
 ---
-title: "Metrics"
+title: Metrics
 sidebar_order: 75
-description: "Send counters, gauges, and distributions from your code to track application health and drill down into related traces, logs, and errors."
+description: >-
+  Send counters, gauges, and distributions from your code to track application
+  health and drill down into related traces, logs, and errors.
+og_image: /og-images/product-explore-metrics.png
 ---
 
 <Alert level="info">
diff --git a/docs/product/size-analysis/index.mdx b/docs/product/size-analysis/index.mdx
@@ -2,6 +2,7 @@
 title: Size Analysis
 sidebar_order: 136
 description: Monitor mobile builds for size changes before they reach users.
+og_image: /og-images/product-size-analysis.png
 ---
 
 <Include name="size-analysis/ea" />
diff --git a/docs/product/size-analysis/integrating-into-ci.mdx b/docs/product/size-analysis/integrating-into-ci.mdx
@@ -2,6 +2,7 @@
 title: Integrating Into CI
 sidebar_order: 40
 description: Set up the integration in CI to receive automated size change notifications
+og_image: /og-images/product-size-analysis-integrating-into-ci.png
 ---
 
 <Include name="size-analysis/github-only" />
diff --git a/package.json b/package.json
@@ -16,9 +16,10 @@
     "dev": "yarn enforce-redirects && concurrently \"yarn sidecar\" \"node ./src/hotReloadWatcher.mjs\" \"next dev\"",
     "dev:developer-docs": "yarn enforce-redirects && NEXT_PUBLIC_DEVELOPER_DOCS=1 yarn dev",
     "build:developer-docs": "yarn enforce-redirects && git submodule init && git submodule update && NEXT_PUBLIC_DEVELOPER_DOCS=1 yarn build",
-    "build": "yarn enforce-redirects && yarn generate-og-images && next build && yarn generate-md-exports",
+    "build": "yarn enforce-redirects && yarn generate-og-images && yarn generate-doctree && next build && yarn generate-md-exports",
     "generate-md-exports": "node scripts/generate-md-exports.mjs",
     "generate-og-images": "ts-node scripts/add-og-images.ts",
+    "generate-doctree": "esbuild scripts/generate-doctree.ts --bundle --platform=node --packages=external --outfile=.next/generate-doctree.mjs --format=esm && node .next/generate-doctree.mjs",
     "vercel:build:developer-docs": "yarn enforce-redirects && git submodule init && git submodule update && NEXT_PUBLIC_DEVELOPER_DOCS=1 yarn build",
     "start:dev": "NODE_ENV=development yarn build && yarn start",
     "start": "next start",
diff --git a/scripts/generate-doctree.ts b/scripts/generate-doctree.ts
@@ -0,0 +1,56 @@
+#!/usr/bin/env node
+/* eslint-disable no-console */
+/**
+ * Pre-compute the doc tree at build time and save it as JSON.
+ * This prevents runtime filesystem access in serverless functions.
+ */
+
+import {mkdir, writeFile} from 'fs/promises';
+import path from 'path';
+
+const root = process.cwd();
+
+async function main() {
+  console.log('🌲 Generating doc tree...');
+
+  try {
+    // Dynamically import to respect NEXT_PUBLIC_DEVELOPER_DOCS at build time
+    const {getDocsRootNodeUncached} = await import('../src/docTree');
+    const {isDeveloperDocs} = await import('../src/isDeveloperDocs');
+
+    // Generate the doc tree
+    const tree = await getDocsRootNodeUncached();
+
+    // Save to both .next (for standalone) and public (for serverless)
+    const nextDir = path.join(root, '.next');
+    const publicDir = path.join(root, 'public');
+
+    await mkdir(nextDir, {recursive: true});
+    await mkdir(publicDir, {recursive: true});
+
+    const treeJSON = JSON.stringify(tree, (key, value) =>
+      key === 'parent' ? undefined : value
+    );
+
+    // Use different filename based on which docs we're building
+    const filename = isDeveloperDocs ? 'doctree-dev.json' : 'doctree.json';
+
+    // Save to .next for standalone builds
+    const nextPath = path.join(nextDir, filename);
+    await writeFile(nextPath, treeJSON, 'utf-8');
+
+    // Save to public for serverless (will be accessible as static file)
+    const publicPath = path.join(publicDir, filename);
+    await writeFile(publicPath, treeJSON, 'utf-8');
+
+    console.log(
+      `✅ Doc tree saved to ${nextPath} and ${publicPath} (isDeveloperDocs: ${isDeveloperDocs})`
+    );
+  } catch (error) {
+    console.error('❌ Error generating doc tree:', error);
+    console.error(error);
+    process.exit(1);
+  }
+}
+
+main();
diff --git a/src/docTree.ts b/src/docTree.ts
@@ -34,11 +34,66 @@ export function getDocsRootNode(): Promise<DocNode> {
   if (getDocsRootNodeCache) {
     return getDocsRootNodeCache;
   }
-  getDocsRootNodeCache = getDocsRootNodeUncached();
+  getDocsRootNodeCache = getDocsRootNodeCached();
   return getDocsRootNodeCache;
 }
 
-async function getDocsRootNodeUncached(): Promise<DocNode> {
+function reconstructParentReferences(node: DocNode, parent?: DocNode): void {
+  if (parent) {
+    node.parent = parent;
+  }
+  node.children.forEach(child => reconstructParentReferences(child, node));
+}
+
+async function getDocsRootNodeCached(): Promise<DocNode> {
+  // In development, scan filesystem for hot reloading
+  // In production (including CI builds), load from pre-computed JSON
+  if (process.env.NODE_ENV === 'development') {
+    return getDocsRootNodeUncached();
+  }
+
+  const fs = await import('fs/promises');
+  const path = await import('path');
+  const root = process.cwd();
+
+  // Load the correct tree based on whether this is developer docs or regular docs
+  const filename = isDeveloperDocs ? 'doctree-dev.json' : 'doctree.json';
+
+  // Try public/ first (for serverless), then .next/ (for standalone)
+  const paths = [path.join(root, 'public', filename), path.join(root, '.next', filename)];
+
+  let lastError: Error | undefined;
+  for (const treePath of paths) {
+    try {
+      const treeData = await fs.readFile(treePath, 'utf-8');
+      const tree = JSON.parse(treeData);
+      // Reconstruct parent references for tree traversal functions
+      reconstructParentReferences(tree);
+      return tree;
+    } catch (error) {
+      // Only continue to next path if file doesn't exist
+      // Other errors (corrupt JSON, parse failures) should fail immediately
+      if (
+        error &&
+        typeof error === 'object' &&
+        'code' in error &&
+        error.code === 'ENOENT'
+      ) {
+        lastError = error as Error;
+        continue;
+      }
+      // Re-throw non-ENOENT errors (JSON parse errors, corruption, etc.)
+      throw error;
+    }
+  }
+
+  throw new Error(
+    `Pre-computed doc tree not found (${filename}). Build may have failed or doctree was not generated with matching NEXT_PUBLIC_DEVELOPER_DOCS flag.`,
+    {cause: lastError}
+  );
+}
+
+export async function getDocsRootNodeUncached(): Promise<DocNode> {
   return frontmatterToTree(
     await (isDeveloperDocs ? getDevDocsFrontMatter() : getDocsFrontMatter())
   );
