@tanglemedia/directus-extension-bundle-qr

A Directus extension bundle that adds a QR code module into your Directus project. The package will install the following:

• A collection named tngl_qr
• A hook that generates a print-ready QR code the moment an item is created:
  • an SVG (vector — professional print) and a 2048 px PNG (general print/download)
  • dark modules use the organization's brand color (tngl_org_branding.primary_color) when it has enough contrast against white (>= 3.0:1), otherwise black
  • both files are uploaded to a "QR Codes" folder in the file library and attached to the item
• An endpoint POST /tngl-qr/scan/{id} that records each scan as a row in tngl_page_views (page-views bundle)

Each QR code encodes a fixed, deterministic URL the platform controls: ${SITE_BASE_URL}/qr/{uuid}/. The generated image never changes — clients can print and distribute it safely. The destination the page redirects to is a plain editable field (destination_url) and can be changed at any time without reprinting.

It automatically sets the following:

• Website policy: READ on tngl_qr (so the Hugo build token can pull the collection)
• Staff policy: CREATE / READ / UPDATE / DELETE on tngl_qr
• The generated fields (qr_url, qr_svg, qr_png, colors) are locked — updates to them are stripped by a filter hook, at the API level, not just in the UI

Requirements

• Directus >= 10.10.1
• Node >= 18.x.x

You should have the following extensions installed:

• @tanglemedia/directus-core-settings (provides the Website/Staff policies and shared migration helpers)
• @tanglemedia/directus-extension-bundle-page-views (provides tngl_page_views — scan analytics land there; without it, scans are silently not recorded)
• directus-extension-display-link (nicer display for the qr_url field)

Install

1. Add the following variables to your Directus env file:

   • SITE_BASE_URL (public base URL of the site, e.g. https://aurora-ab.ca — baked into every generated QR image)

2. npm i @tanglemedia/directus-extension-bundle-qr

3. npx directus bootstrap to update your database and restart directus

Hugo site setup

1. Add the collection to params.cmsModules in the site's Hugo config:

   - table: tngl_qr
     output: content/qr
     fields: "*"
     limit: -1
     headless: false

2. Add the layouts/qr/single.html (redirect + scan beacon) and layouts/qr/list.html (stub) templates to the site theme, plus the archetypes/qr.md schema record. See the aurora-2026 site for the reference implementation.

Editorial workflow

1. Create a QR Code item (name + destination URL). The image generates within a second or two — refresh the item to see it.
2. Click Publish Site so the /qr/{uuid}/ page goes live.
3. Only distribute the image after the page is live — scan the PNG yourself first.
4. Change destination_url whenever needed, then Publish Site again. The printed image keeps working.

Behavioral notes

• Generation happens once. Later edits (including branding changes) never regenerate existing images.
• Deliberate escape hatch: delete the two generated files from the file library (the item's file fields go empty), then re-save the item — it regenerates at the current brand color. The encoded URL is the same, so printed codes keep working.
• Items default to published status so a freshly created QR page goes live on the next build. Archive an item to take its page down (the printed code will then 404 — archive with care).
• Scan counting is fire-and-forget from the page (navigator.sendBeacon); the endpoint always answers 204 and never blocks the visitor's redirect.