Instalación

DocMind se publica en npm bajo el scope @dragon708. Este playground fija líneas publicadas estables (véase la tabla; @dragon708/docmind-pdf va en 2.x). Los cambios incompatibles deberían ir en notas de versión; revisa el changelog al actualizar.

Instalación mínima

Navegador / cliente

npm install @dragon708/docmind-browser@^1.6.0 @dragon708/docmind-shared@^1.2.0

Para DOCX en el navegador, añade el paquete de formato e impórtalo una vez para que el bundler incluya el analizador (igual que en src/lib/docmind-client.ts de este repo):

npm install @dragon708/docmind-docx@^1.8.0

import "@dragon708/docmind-docx";

Node / servidor

npm install @dragon708/docmind-node@^1.10.0 @dragon708/docmind-shared@^1.2.0

@dragon708/docmind-shared aporta tipos compartidos, analyzeText, detectFileKind, DocMindError, isDocMindError, AnalysisResult, tipos de salida estructurada (StructuredDocumentResult, normalizeToStructuredResult, …) y los tipos Epic 1 de getCapabilities / explainAnalysisPlan. @dragon708/docmind-browser y @dragon708/docmind-node exportan analyzeFile más extractText, extractMetadata, convertToHtml, runOcr, extractStructuredData, detectFileKind, getCapabilities y explainAnalysisPlan (véase Primeros pasos).

Paquetes en este playground (package.json)

No necesitas todas las filas para un uso mínimo: docmind-browser y docmind-node traen dependencias de formato para sus pipelines. En apps de navegador, declara docmind-docx si quieres soporte DOCX cableado en el bundle.

Requisitos

• TypeScript o JavaScript con bundler que resuelva el paquete de navegador.
• Node compatible con tu toolchain (para docmind-node y este playground).

Next.js y Vercel (PDF.js y Tesseract)

Aplica a apps Next.js que usan pdfjs-dist y/o @dragon708/docmind-ocr (o tesseract.js) en el servidor—por ejemplo un Route Handler como POST /api/analyze en este playground. Importa sobre todo en Vercel (u otro host que despliegue el bundle traced de Next en funciones Node serverless).

Qué falla: (1) pdf.mjs carga pdf.worker.mjs por una ruta que el tracer estático suele no seguir → Setting up fake worker failed / Cannot find module '.../pdf.worker.mjs' (p. ej. pdf-extract-text-by-page). (2) Tesseract usa worker_threads bajo node_modules/tesseract.js/src/worker-script/ y dependencias hoisteadas (bmp-js, …) que el tracer no incluye → MODULE_NOT_FOUND (Cannot find module '..' / bmp-js, etc.) aunque npm install sea correcto en local.

Qué hace este repo (copia autoritativa en next.config.ts en la raíz del repositorio):

outputFileTracingIncludes

Los globs van asociados a la ruta App Router /api/analyze para que el lambda de esa ruta incluya los árboles completos:

outputFileTracingIncludes: {
  "/api/analyze": [
    "./node_modules/pdfjs-dist/**/*",
    "./node_modules/tesseract.js/**/*",
    "./node_modules/tesseract.js-core/**/*",
    "./node_modules/bmp-js/**/*",
    "./node_modules/wasm-feature-detect/**/*",
    "./node_modules/regenerator-runtime/**/*",
    "./node_modules/is-url/**/*",
    "./node_modules/is-electron/**/*",
    "./node_modules/@dragon708/docmind-markdown/**/*",
  ],
},

Nota: @dragon708/docmind-markdown ≥ 1.2.2 incluye la pila PDF → Markdown para Node dentro del paquete; el glob de la carpeta del paquete arrastra el node_modules anidado del tarball en Vercel. No hace falta listar por separado peers hoisteados de esas dependencias (p. ej. file-type) en la raíz. Con 1.2.1, pasa a 1.2.2 cuando esté publicado o mantén globs / dependencias directas.

Si añades otra entrada de servidor con el mismo stack PDF/OCR, añade una clave (glob de ruta) o repite estos patrones. Con pnpm o installs anidados, apunta los globs a las rutas reales bajo tu node_modules.

serverExternalPackages

Los paquetes listados no entran en el bundle del servidor; Node los resuelve desde node_modules en runtime. Así se evitan transformaciones del bundler que rompen los import() dinámicos dentro de @dragon708/docmind-markdown (véase DOCX y Markdown en servidor (Turbopack) abajo) y se mantienen fuera del empaquetado los motores pesados de PDF/OCR.

Lista del playground (copia autoritativa en next.config.ts en la raíz del repo):

serverExternalPackages: [
  "@dragon708/docmind-markdown",
  "mammoth",
  "turndown",
  "turndown-plugin-gfm",
  "@napi-rs/canvas",
  "pdf-parse",
  "pdfjs-dist",
  "tesseract.js",
],

Para PDF/OCR, externalizar no incluye automáticamente workers, WASM ni dependencias hoisteadas en el artefacto serverless: por eso sigue siendo necesario outputFileTracingIncludes arriba.

DOCX y Markdown en servidor (Turbopack)

Aplica cuando ejecutas extractMarkdown de @dragon708/docmind-node / @dragon708/docmind-markdown en un Route Handler de Next.js (p. ej. extract-markdown en POST /api/analyze de este playground).

Síntoma: HTTP 500 con Cannot find module as expression is too dynamic al procesar .docx, mientras que PDF → Markdown puede seguir funcionando.

Motivo: El paquete markdown carga mammoth, turndown y (si hay tablas) turndown-plugin-gfm con import() dinámico, y (en Node) resuelve código adicional para PDF → Markdown vía createRequire. Turbopack (dev de Next y parte de los builds de servidor) suele inlinear @dragon708/docmind-markdown; entonces no acepta resoluciones no estáticas y falla en runtime.

Solución: Añade @dragon708/docmind-markdown más mammoth, turndown y turndown-plugin-gfm a serverExternalPackages. Usa @dragon708/docmind-markdown ≥ 1.2.2 para que los conversores anidados del servidor vayan empaquetados dentro de ese paquete y no necesites globs extra de outputFileTracingIncludes para sus dependencias hoisteadas. Usa el array de arriba.

Cliente vs servidor: serverExternalPackages solo afecta compilaciones de servidor. El bundle de navegador sigue resolviendo @dragon708/docmind-browser → @dragon708/docmind-markdown en su propia compilación; externalizar en servidor no desactiva el uso en cliente.

Ver también Guía OCR — Serverless (Next.js y Vercel) y Guía Node — Next.js / Vercel.

Siguientes pasos

• Primeros pasos — arquitectura y navegador vs Node
• Inicio rápido — analyzeFile, APIs facetadas y opciones