feat-docs-wasm-attempt

Author: devdumpling

PLAN_MICRO.md

@@ -48,74 +48,62 @@ docs-api/
 ```typescript
 #!/usr/bin/env deno run --allow-net --allow-env
 
-import { doc } from "jsr:@deno/doc";
+import { doc } from 'jsr:@deno/doc'
 
 interface GenerateRequest {
-  package: string;
-  version: string;
+  package: string
+  version: string
 }
 
 function validateAuth(req: Request): boolean {
-  const authHeader = req.headers.get("Authorization");
-  const expectedToken = Deno.env.get("API_SECRET");
-  if (!expectedToken) return true;
-  return authHeader === `Bearer ${expectedToken}`;
+  const authHeader = req.headers.get('Authorization')
+  const expectedToken = Deno.env.get('API_SECRET')
+  if (!expectedToken) return true
+  return authHeader === `Bearer ${expectedToken}`
 }
 
 export default async function handler(req: Request): Promise<Response> {
   const headers = {
-    "Access-Control-Allow-Origin": "https://npmx.dev",
-    "Access-Control-Allow-Methods": "POST, OPTIONS",
-    "Access-Control-Allow-Headers": "Content-Type, Authorization",
-    "Content-Type": "application/json",
-  };
-
-  if (req.method === "OPTIONS") {
-    return new Response(null, { status: 204, headers });
+    'Access-Control-Allow-Origin': 'https://npmx.dev',
+    'Access-Control-Allow-Methods': 'POST, OPTIONS',
+    'Access-Control-Allow-Headers': 'Content-Type, Authorization',
+    'Content-Type': 'application/json',
+  }
+
+  if (req.method === 'OPTIONS') {
+    return new Response(null, { status: 204, headers })
   }
 
-  if (req.method !== "POST") {
-    return new Response(
-      JSON.stringify({ error: "method_not_allowed" }),
-      { status: 405, headers }
-    );
+  if (req.method !== 'POST') {
+    return new Response(JSON.stringify({ error: 'method_not_allowed' }), { status: 405, headers })
   }
 
   if (!validateAuth(req)) {
-    return new Response(
-      JSON.stringify({ error: "unauthorized" }),
-      { status: 401, headers }
-    );
+    return new Response(JSON.stringify({ error: 'unauthorized' }), { status: 401, headers })
   }
 
   try {
-    const body: GenerateRequest = await req.json();
-    
+    const body: GenerateRequest = await req.json()
+
     if (!body.package || !body.version) {
-      return new Response(
-        JSON.stringify({ error: "bad_request" }),
-        { status: 400, headers }
-      );
+      return new Response(JSON.stringify({ error: 'bad_request' }), { status: 400, headers })
     }
 
-    const specifier = `https://esm.sh/${body.package}@${body.version}?target=deno`;
-    const nodes = await doc(specifier);
-    
-    return new Response(JSON.stringify({ nodes }), { status: 200, headers });
+    const specifier = `https://esm.sh/${body.package}@${body.version}?target=deno`
+    const nodes = await doc(specifier)
+
+    return new Response(JSON.stringify({ nodes }), { status: 200, headers })
   } catch (error) {
-    const message = error instanceof Error ? error.message : "Unknown error";
-    
-    if (message.includes("Could not find")) {
-      return new Response(
-        JSON.stringify({ error: "not_found" }),
-        { status: 404, headers }
-      );
+    const message = error instanceof Error ? error.message : 'Unknown error'
+
+    if (message.includes('Could not find')) {
+      return new Response(JSON.stringify({ error: 'not_found' }), { status: 404, headers })
     }
-    
-    return new Response(
-      JSON.stringify({ error: "generation_failed", message }),
-      { status: 500, headers }
-    );
+
+    return new Response(JSON.stringify({ error: 'generation_failed', message }), {
+      status: 500,
+      headers,
+    })
   }
 }
 ```
@@ -139,7 +127,7 @@ async function runDenoDoc(packageName: string, version: string): Promise<DenoDoc
   const headers: Record<string, string> = {
     'Content-Type': 'application/json',
   }
-  
+
   if (DOCS_API_SECRET) {
     headers['Authorization'] = `Bearer ${DOCS_API_SECRET}`
   }
@@ -158,7 +146,7 @@ async function runDenoDoc(packageName: string, version: string): Promise<DenoDoc
     throw new Error(`Docs API error: ${error.message}`)
   }
 
-  return await response.json() as DenoDocResult
+  return (await response.json()) as DenoDocResult
 }
 
 export async function generateDocsWithDeno(
@@ -186,6 +174,7 @@ export async function generateDocsWithDeno(
 #### Remove Unused Code
 
 Delete from `server/utils/docs.ts`:
+
 - `execFileAsync` import
 - `DENO_DOC_TIMEOUT_MS`, `DENO_DOC_MAX_BUFFER` constants
 - `denoCheckPromise`, `isDenoInstalled()`, `verifyDenoInstalled()`
@@ -198,7 +187,7 @@ Keep subprocess as fallback for local dev:
 
 ```typescript
 async function runDenoDoc(packageName: string, version: string): Promise<DenoDocResult> {
-  if (process.dev && await isDenoInstalled()) {
+  if (process.dev && (await isDenoInstalled())) {
     return runLocalDenoDoc(packageName, version)
   }
   return runRemoteDenoDoc(packageName, version)

PLAN_WASM.md

@@ -1,110 +1,113 @@
 # Plan: WASM-based Documentation Generation
 
-> **Status**: Alternative approach. See PLAN_MICRO.md for recommended approach.
+> **Status**: ✅ Working! Uses official `@deno/doc` v0.189.1 with patches for Node.js compatibility.
 
-Replace the `deno doc` subprocess with `tsdoc-extractor`, a WASM build of `deno_doc` for Node.js.
+## Summary
 
-## Package
+Successfully replaced the `deno doc` subprocess with WASM-based documentation generation that runs directly in Node.js/Vercel serverless, using the official `@deno/doc` package from JSR.
 
-- **npm**: `tsdoc-extractor`
-- **Size**: 2.8MB WASM + ~25KB JS
-- **Last updated**: July 2023
-- **Output**: Same JSON format as `deno doc --json`
+## Package Used
 
-## Test Results
+- **Package**: `@deno/doc` (JSR - official Deno package)
+- **Version**: 0.189.1 (latest, Jan 2026)
+- **WASM size**: 4.7MB
+- **Install**: `pnpm install jsr:@deno/doc`
 
-```
-ufo@1.5.0:  58 nodes (works)
-vue@3.5.0:   4 nodes (re-exports not followed - WASM limitation)
+## Compatibility Issues & Fixes
+
+We encountered three issues when running `@deno/doc` in Node.js. All were resolved with a single patch file.
+
+### Issue 1: Invalid JavaScript exports ✅ Fixed
+
+```js
+// In mod.js - this is invalid JS, only works in Deno
+export * from './types.d.ts'
+export * from './html_types.d.ts'
 ```
 
-## Key Finding
+**Fix**: Patch removes these lines.
 
-esm.sh serves types URL in the `x-typescript-types` header, not at the main URL:
+### Issue 2: WASM loader doesn't support Node.js ✅ Fixed
 
-```bash
-$ curl -sI 'https://esm.sh/ufo@1.5.0' | grep x-typescript-types
-x-typescript-types: https://esm.sh/ufo@1.5.0/dist/index.d.ts
+```js
+// Original code throws error for Node.js + file:// URLs
+if (isFile && typeof Deno !== 'object') {
+  throw new Error('Loading local files are not supported in this environment')
+}
 ```
 
-## Architecture
+**Fix**: Patch adds Node.js fs support:
 
+```js
+if (isNode && isFile) {
+  const { readFileSync } = await import('node:fs')
+  const { fileURLToPath } = await import('node:url')
+  const wasmCode = readFileSync(fileURLToPath(url))
+  return WebAssembly.instantiate(decompress ? decompress(wasmCode) : wasmCode, imports)
+}
 ```
-Current:  [Request] -> [subprocess: deno doc --json] -> [parse JSON]
-New:      [Request] -> [fetch types] -> [tsdoc-extractor WASM] -> [parse JSON]
+
+### Issue 3: Bundler rewrites WASM paths ✅ Fixed
+
+When Nitro inlines the package, `import.meta.url` gets rewritten and WASM path becomes invalid.
+
+**Fix**: Don't inline `@deno/doc` in Nitro config - let it load from `node_modules/`:
+
+```ts
+// nuxt.config.ts - do NOT add @deno/doc to nitro.externals.inline
 ```
 
-## Implementation
+## Patch File
 
-### 1. Install
+All fixes are in `patches/@jsr__deno__doc@0.189.1.patch` (managed by pnpm).
+
+## Key Finding
+
+esm.sh serves types URL in the `x-typescript-types` header:
 
 ```bash
-pnpm add tsdoc-extractor
+$ curl -sI 'https://esm.sh/ufo@1.5.0' | grep x-typescript-types
+x-typescript-types: https://esm.sh/ufo@1.5.0/dist/index.d.ts
 ```
 
-### 2. Create `server/utils/docs-wasm.ts`
-
-```typescript
-import { doc, defaultResolver } from 'tsdoc-extractor'
-import type { DenoDocNode, DocsGenerationResult } from '#shared/types/deno-doc'
+## Architecture
 
-async function getTypesUrl(packageName: string, version: string): Promise<string | null> {
-  const url = `https://esm.sh/${packageName}@${version}`
-  const response = await fetch(url, { method: 'HEAD' })
-  return response.headers.get('x-typescript-types')
-}
+```
+[Request] -> [fetch x-typescript-types header] -> [@deno/doc WASM] -> [HTML]
+```
 
-function createResolver() {
-  return (specifier: string, referrer: string): string => {
-    if (specifier.startsWith('.')) {
-      return new URL(specifier, referrer).toString()
-    }
-    if (specifier.startsWith('https://esm.sh/')) {
-      return specifier
-    }
-    if (!specifier.startsWith('http')) {
-      return `https://esm.sh/${specifier}`
-    }
-    return defaultResolver(specifier, referrer)
-  }
-}
+## Files Changed
 
-export async function generateDocsWithWasm(
-  packageName: string,
-  version: string,
-): Promise<DocsGenerationResult | null> {
-  const typesUrl = await getTypesUrl(packageName, version)
-  
-  if (!typesUrl) {
-    return null
-  }
+- `server/utils/docs.ts` - Uses `@deno/doc` with custom loader/resolver
+- `server/utils/docs-text.ts` - Extracted text utilities
+- `patches/@jsr__deno__doc@0.189.1.patch` - Node.js compatibility patch
 
-  const nodes = await doc(typesUrl, {
-    resolve: createResolver(),
-  }) as DenoDocNode[]
+## Verified Working
 
-  if (!nodes || nodes.length === 0) {
-    return null
-  }
+- ✅ `ufo@1.5.0` - Generates full docs
+- ✅ `react@19.0.0` - Large package, generates full docs
+- ✅ All 361 tests pass
+- ✅ Dev server runs without errors
 
-  const flattenedNodes = flattenNamespaces(nodes)
-  const mergedSymbols = mergeOverloads(flattenedNodes)
-  const symbolLookup = buildSymbolLookup(flattenedNodes)
+## Pros/Cons
 
-  const html = await renderDocNodes(mergedSymbols, symbolLookup)
-  const toc = renderToc(mergedSymbols)
+**Pros**:
 
-  return { html, toc, nodes: flattenedNodes }
-}
-```
+- Single deployment (no microservice)
+- Uses official, maintained `@deno/doc` (latest version)
+- In-process, no network latency
+- 4.7MB WASM loaded once, cached
 
-## Limitations
+**Cons**:
 
-- **WASM from 2023**: Known issues with `export *` re-exports
-- **Rebuild requires Rust**: Need wasm-pack and deno_doc source to update
+- Requires patch for Node.js compatibility (may need updates per version)
+- 4.7MB added to server bundle
+- Patch maintenance burden
 
-## Pros/Cons
+## Alternative: Microservice Approach
 
-**Pros**: No external dependency, single deployment, faster cold starts
+See `PLAN_MICRO.md` for the microservice approach that runs actual Deno in a separate Vercel project. That approach:
 
-**Cons**: Old WASM with known issues, complex packages may fail, 2.8MB bundle increase
+- Requires no patches
+- Has network latency
+- Requires managing two deployments

app/components/AppHeader.vue

@@ -12,7 +12,10 @@ withDefaults(
 </script>
 
 <template>
-  <header aria-label="Site header" class="sticky top-0 z-50 bg-bg/80 backdrop-blur-md border-b border-border">
+  <header
+    aria-label="Site header"
+    class="sticky top-0 z-50 bg-bg/80 backdrop-blur-md border-b border-border"
+  >
     <nav aria-label="Main navigation" class="container h-14 flex items-center justify-between">
       <NuxtLink
         v-if="showLogo"

app/components/DocsVersionSelector.vue

@@ -112,7 +112,11 @@ function handleKeydown(event: KeyboardEvent) {
               v-for="tag in tags"
               :key="tag"
               class="text-[10px] px-1.5 py-0.5 rounded font-sans font-medium"
-              :class="tag === 'latest' ? 'bg-emerald-500/10 text-emerald-400' : 'bg-bg-muted text-fg-subtle'"
+              :class="
+                tag === 'latest'
+                  ? 'bg-emerald-500/10 text-emerald-400'
+                  : 'bg-bg-muted text-fg-subtle'
+              "
             >
               {{ tag }}
             </span>