Next.js API: Export Endpoints
Relevant source files
The following files were used as context for generating this wiki page:
The cheMD export endpoints provide server-side capabilities to transform structured chemical Markdown documents into various distribution formats, primarily Microsoft Word (DOCX). This system bridges the gap between the web-based Semantic AST and professional document processing tools like Pandoc.
These endpoints are designed with high-concurrency safety and strict input validation to ensure the stability of the Node.js runtime during intensive document compilation tasks.
Sources: chemd-v0.1-architecture.md:92-105, apps/web/tests/docx-route.test.ts:40-50
Architecture and Data Flow
The export system operates as a multi-stage pipeline. A request typically contains the raw cheMD source, which is then parsed, resolved, and passed to a specific renderer or bridge. For DOCX, the system utilizes a "bridge" pattern where a structured payload is prepared for an external document converter.
Export Pipeline Flow
The following diagram illustrates the lifecycle of an export request from the client to the final document generation.
The system enforces strict limits on request size and concurrency to protect the server's resources. If the server is currently processing an export, subsequent requests may receive a 503 Service Unavailable with a Retry-After header.
Sources: apps/web/tests/docx-route.test.ts:74-105, chemd-v0.1-architecture.md:107-123
DOCX Export Endpoint
The DOCX export endpoint (typically /api/export/docx) is the primary mechanism for generating human-readable reports. It consumes cheMD source text and returns a serialized document.
Technical Implementation
The implementation relies on the @chemd/compiler package to handle the heavy lifting of document transformation. The process involves:
- Source Sanitization: Ensuring the input is valid JSON with a
sourcefield. - Media Type Check: Rejecting non-JSON content types with a
415 Unsupported Media Typeerror. - Payload Preparation: Using
createDocxBridgePayloadto include AST, metadata, and render options. - Tool Hand-off: Invoking
pandocwith specific arguments such as--from gfmand--to docx.
Sources: apps/web/tests/docx-route.test.ts:40-60, packages/renderer-docx/src/index.ts:161-175, packages/compiler/tests/compiler-node.test.ts:6-20
Configuration Constants
| Parameter | Type | Default Value | Description |
|---|---|---|---|
MAX_DOCX_EXPORT_REQUEST_BYTES | number | Config Dependent | Maximum size of the incoming source payload. |
DOCX_EXPORT_BUSY_RETRY_AFTER_SECONDS | number | Config Dependent | Seconds suggested to client to wait before retrying. |
executionTimeoutMs | number | 25ms (in tests) | Timeout for the Pandoc process execution. |
Sources: apps/web/src/app/api/export/docx/config.ts, apps/web/tests/docx-route.test.ts:65-70, packages/compiler/tests/compiler-node.test.ts:88-95
The DOCX Bridge Payload
To facilitate transition between the web application and external tools, the system generates a DocxBridgePayload. This structure contains everything needed for a downstream process to reconstruct the document with appropriate styling.
The bridge payload specifically recommends pandoc as the tool for the html-or-markdown-to-docx pipeline.
Sources: packages/renderer-docx/src/index.ts:7-24, packages/renderer-docx/tests/renderer-docx.test.ts:14-25
Node.js Compiler Integration
The server-side logic utilizes a specific Node.js runner to execute binary commands. This allows the system to interact with the host file system for temporary file creation and binary execution.
Pandoc Argument Construction
When exporting to DOCX, the compiler generates a specific command-line sequence:
[
"input.md",
"--from", "gfm",
"--to", "docx",
"--output", "out.docx",
"--reference-doc", "template.docx",
"--standalone"
]
Sources: packages/compiler/tests/compiler-node.test.ts:6-20
Error Handling and Timeouts
The export logic is wrapped in robust error handling to manage external process failures:
- Binary Check: Validates that the Pandoc binary exists before execution to prevent cryptic shell errors.
- Execution Timeout: Prevents zombie processes by killing Pandoc if it exceeds a defined time limit.
- Concurrency Control: Prevents the server from becoming unresponsive under heavy load.
Sources: packages/compiler/tests/compiler-node.test.ts:80-95, apps/web/tests/docx-route.test.ts:74-85
Summary
Next.js API Export Endpoints serve as the critical infrastructure for transforming semantic chemical data into professional documents. By leveraging a pipeline architecture, strict validation, and a standardized bridge payload, cheMD ensures that chemical experimental data remains portable and accessible outside the primary web interface.