admin/accounted
3
0
Fork 0
Code Issues 1 Pull Requests Actions Packages Projects Releases Wiki Activity

fix(docs): unbreak the website export script (server-only import chain) (#1251)

Browse Source 
* fix(docs): unbreak the website export script, stub server-only

scripts/export-docs-to-website.mts has been failing since PostHog landed:
lib/api/v1/load-routes pulls in every v1 route, which reaches lib/init ->
lib/analytics/posthog-observability -> posthog-server, and posthog-server
imports `server-only`, which throws outside a Next.js server-component graph.
The script only reads exported markdown builders, so it now neutralises that
module with a Module._load hook before importing anything.

Without this the docs cannot be regenerated at all, which is how
/docs/api/connect-claude stayed unported (the page exists here but the
redirect sends every request to the website repo, where it 404'd).

Refs #1247

* refactor(docs): scope the server-only stub to the imports that need it

Compliance-swarm finding (ISO 27001 A.8.28) on the export script: the
Module._load hook stayed patched for the rest of the process, silently
disarming the guard for anything imported later. Restore it in a finally block
around the three content imports.
This commit is contained in:
Jakob Wennberg
2026-07-27 19:57:07 +02:00
committed by GitHub
parent 63bf0d5ad7
commit e171bffa97
2 changed files with 29 additions and 3 deletions
Download Patch File Download Diff File Expand all files Collapse all files
scripts/export-docs-to-website.mts
+28 -3
View File
@@ -8,11 +8,36 @@
* changes.
*/
import { writeFileSync, mkdirSync } from 'node:fs'
import { createRequire } from 'node:module'
import { dirname, resolve } from 'node:path'
const errors = await import('@/lib/docs/content/errors')
const reference = await import('@/lib/docs/content/reference')
const connectClaude = await import('@/lib/docs/content/connect-claude')
// `server-only` throws on import outside a Next.js server-component graph. The
// reference builder pulls it in transitively (lib/api/v1/load-routes -> every
// v1 route -> lib/init -> lib/analytics/posthog-observability ->
// posthog-server), which broke this script the moment PostHog landed. Nothing
// here executes request-time code: it only reads exported markdown builders,
// so a no-op stub is the honest resolution.
const require = createRequire(import.meta.url)
const ModuleCtor = require('node:module') as {
_load: (request: string, ...rest: unknown[]) => unknown
}
const originalLoad = ModuleCtor._load
ModuleCtor._load = function (request: string, ...rest: unknown[]) {
if (request === 'server-only') return {}
return originalLoad.call(this, request, ...rest)
}
let errors, reference, connectClaude
try {
errors = await import('@/lib/docs/content/errors')
reference = await import('@/lib/docs/content/reference')
connectClaude = await import('@/lib/docs/content/connect-claude')
} finally {
// Scope the stub to the imports that need it: leaving a global loader hook
// patched for the rest of the process would silently disarm the guard for
// anything imported later (compliance swarm, ISO 27001 A.8.28).
ModuleCtor._load = originalLoad
}
const buildErrorReferenceMd = errors.buildErrorReferenceMd ?? (errors as { default?: typeof errors }).default?.buildErrorReferenceMd
const buildResourcePages = reference.buildResourcePages ?? (reference as { default?: typeof reference }).default?.buildResourcePages