Convert DOCX to Markdown in a Next.js function

Add a DOCX-to-Markdown endpoint to a Next.js application. This guide covers the Node.js route handler and the assets needed for serverless deployment.

For installation, runtime requirements, and export options, use the DOCX to Markdown package documentation. The examples below assume you have installed the converter and its Core peer dependency.

Run the Server starter

Download the Server starter to try conversion before adding an endpoint. Extract it, open the server directory, and save a DOCX file as document.docx. With Node.js 22.12 or later, run:

npm install
npm run convert

The script prints Markdown and page output, then writes Markdown, images, and metadata to output. The directory must be new or empty; rename or move it before running again. The starter uses installed packages and reads bundled fonts and WASM directly from them. Commit the generated lockfile to retain your resolved versions.

To match the interactive demo, select Match demo in the website's Server example and use those imports and options in convert.ts. This enables HTML image dimensions and Google Fonts fallback. The starter already includes @docx-editor.dev/fonts; remote fallback requires CDN access. The following Next.js configuration is for deploying conversion as an endpoint.

Configure Next.js

Run conversion in the Node.js runtime and keep the packages external so Node.js can load their fonts and WebAssembly assets:

// next.config.ts
const config = {
  serverExternalPackages: [
    '@docx-editor.dev/docx-to-markdown',
    '@docx-editor.dev/core',
    '@docx-editor.dev/fonts',
  ],
};

export default config;

In the route that handles conversion, set export const runtime = 'nodejs'. Edge runtimes are not supported.

For a complete request handler, see the Next.js integration example.

Run in serverless functions

Use a Node.js serverless runtime that supports WebAssembly. Include the converter, Core, and font packages with their runtime assets in the deployed function. For Next.js, use the external-package configuration above and set runtime = 'nodejs' in the route handler.

The following handler accepts DOCX bytes as the request body and returns a Markdown response:

// app/api/convert/route.ts
import { exportMarkdown } from '@docx-editor.dev/docx-to-markdown';

export const runtime = 'nodejs';

export async function POST(request: Request) {
  const bytes = new Uint8Array(await request.arrayBuffer());
  const result = await exportMarkdown(bytes, { signal: request.signal });

  return new Response(result.markdown, {
    headers: { 'Content-Type': 'text/markdown; charset=utf-8' },
  });
}

Add your application's upload limits and error handling before exposing the route. Fit concurrency and document size to the function's memory and execution limits. Conversion includes synchronous parsing and layout; an abort signal does not interrupt work that is already running.

For Vercel, select the Node.js runtime. Inspect the deployment bundle to confirm font and WASM files are included; see including files in Vercel Functions. Validate conversion with representative documents on the deployed function. This guide does not imply support for Edge runtimes.

Fonts affect page breaks. Supply the document's original font files through fonts when they must override bundled substitutes; use fallbackFonts for additional sources afterward. Include local font files in the function bundle, or allow outbound requests for a remote resolver. See the package's font configuration and fallback example. Keep result.fontResolution with your export when page citations must be reproducible.

Return images with the result

The handler returns Markdown text without image files. To include images, export with images: true and return a ZIP or upload the assets to your storage service. See Markdown and image delivery.

Next steps

• Build a browser download without a conversion endpoint.
• Use page output for citations.
• Read the package documentation.