directus-extension-endpoint-xlsx-export

Export Directus collection items as real XLSX files through a custom endpoint.

This package exposes a fixed endpoint root:

/xlsx/:collection

Example:

/xlsx/aulas?filter[id][_eq]=18

Features

• Exposes a stable endpoint root: /xlsx
• Uses real XLSX output, not CSV renamed as XLSX
• Forwards native Directus query parameters such as filter, fields, sort, limit, offset, page, search, deep, and alias
• Defaults limit to -1 when omitted, so exports include all matching rows
• Converts nested arrays and objects to JSON strings so spreadsheets open cleanly
• Supports optional filename and sheet query parameters

Requirements

• Directus 11.x
• A self-hosted Directus project
• Node.js and npm for local development

Route

GET /xlsx/:collection

Query Parameters

All standard Directus query parameters are forwarded to ItemsService.readByQuery().

Additional custom query parameters:

• filename: overrides the downloaded file name
• sheet: overrides the worksheet name

Examples:

/xlsx/aulas?filter[id][_eq]=18
/xlsx/posts?fields=id,title,status&sort=-date_created
/xlsx/orders?filter[status][_eq]=paid&filename=paid-orders
/xlsx/users?limit=50&sheet=Users

Build

npm install
npm run build

Build output will be written to:

dist/index.js

Local Installation in a Directus Project

Build the extension first:

npm install
npm run build

Then copy the built package into your Directus extensions directory:

mkdir -p /path/to/directus/extensions/directus-extension-endpoint-xlsx-export
cp -R dist package.json README.md LICENSE /path/to/directus/extensions/directus-extension-endpoint-xlsx-export/

Restart Directus.

If your Directus project is running in Docker and mounts ./extensions:/directus/extensions, copy the built package into that mounted local extensions directory.

Installation from npm in a Custom Directus Image

After publishing this package to npm, install it in your custom Directus image.

Example Dockerfile:

FROM directus/directus:latest

USER root
RUN corepack enable
USER node

RUN pnpm install directus-extension-endpoint-xlsx-export

Then rebuild and restart your Directus stack:

docker compose build
docker compose up -d

Development with Auto Reload

If you are mounting a local extensions directory into Directus, enable auto reload in your Directus container environment:

EXTENSIONS_AUTO_RELOAD: true

Then run:

npm install
npm run dev

Usage

Export a Single Item by ID

/xlsx/aulas?filter[id][_eq]=18

Export Selected Fields

/xlsx/aulas?filter[id][_eq]=18&fields=id,titulo,data

Custom File Name

/xlsx/aulas?filter[id][_eq]=18&filename=aula-18

Custom Sheet Name

/xlsx/aulas?filter[id][_eq]=18&sheet=Aula%2018

Publish to npm

Before publishing:

npm install
npm run build
npm pack --dry-run

Then publish:

npm publish

If you change to a scoped package name, publish it as public:

npm publish --access public

Notes

• The public endpoint root is controlled by id: "xlsx" in src/index.ts
• You can change the npm package name without changing the public route
• If the exact npm package name is already taken, only change package.json.name
• Large exports can still be capped by Directus QUERY_LIMIT_MAX
• This package provides an API endpoint only. It does not add a Directus UI button