@fmfl-devteam/discord-html-transcripts

Create secure, responsive, standalone HTML transcripts from Discord channels or already loaded discord.js messages. The package targets discord.js 14.27.x and renders classic interactive message components as well as Components V2 display components.

The generated document contains its CSS and requires no JavaScript, framework, CDN stylesheet, or web font. It supports light, dark, automatic, mobile, and print layouts.

Repository note: the repository, homepage, and issue URLs in package.json use the visible example.invalid placeholder because no canonical public repository URL was available when this package was created. Replace those metadata values before the first publication.

Requirements

• Node.js 20 or newer
• discord.js ^14.27.0
• ViewChannel and ReadMessageHistory permissions when fetching a channel

Installation

npm install @fmfl-devteam/discord-html-transcripts discord.js

pnpm add @fmfl-devteam/discord-html-transcripts discord.js

yarn add @fmfl-devteam/discord-html-transcripts discord.js

Quick Start

import { createTranscript } from "@fmfl-devteam/discord-html-transcripts";

const transcript = await createTranscript(channel, {
  filename: `transcript-${channel.id}.html`,
  theme: "dark",
  includeComponents: true,
  includeAttachments: true,
});

await targetChannel.send({
  files: [transcript.attachment],
});

createTranscript() fetches up to 100 messages per request, follows the oldest message ID with before, removes duplicate IDs, and produces a stable oldest-to-newest transcript. The default maximum is 10,000 messages. Discord API and permission failures are wrapped in a TranscriptFetchError with channel and permission context.

Loaded Messages

import { generateFromMessages } from "@fmfl-devteam/discord-html-transcripts";

const transcript = await generateFromMessages(messages, {
  title: "Ticket Transcript",
  theme: "auto",
});

The input may be a Collection<string, Message> or a readonly Message[]. Input order does not matter; messages are sorted chronologically. A limit keeps the newest N messages.

Save to Disk

import { writeFile } from "node:fs/promises";
import { createTranscript } from "@fmfl-devteam/discord-html-transcripts";

const transcript = await createTranscript(channel, {
  title: "Audit Transcript",
  poweredBy: false,
});

await writeFile(transcript.filename, transcript.html, "utf8");

API

interface TranscriptOptions {
  limit?: number;
  filename?: string;
  title?: string;
  description?: string;
  includeSystemMessages?: boolean;
  includeAttachments?: boolean;
  includeComponents?: boolean;
  includeEmbeds?: boolean;
  includeReactions?: boolean;
  includeAvatars?: boolean;
  includeUserIds?: boolean;
  includeChannelId?: boolean;
  poweredBy?: boolean;
  saveImages?: boolean;
  maxInlineMediaBytes?: number;
  maxSingleMediaBytes?: number;
  theme?: "light" | "dark" | "auto";
  timezone?: string;
  locale?: string;
  generatedAt?: Date;
}

| Option | Default | Description | | ----------------------- | ------------------- | --------------------------------------------------------------------------------------- | | limit | 10000 | Newest messages to fetch or retain; integer from 1 through 10,000. | | filename | transcript.html | Attachment filename. Unsafe filesystem characters are replaced and .html is appended. | | title | Channel-based title | Transcript heading and document title. | | description | none | Plain-text description in the document header. | | includeSystemMessages | true | Include Discord system event messages. | | includeAttachments | true | Render image, video, audio, text, and generic file attachments. | | includeComponents | true | Render classic components and Components V2. | | includeEmbeds | true | Render rich embeds. | | includeReactions | true | Render reaction emoji and counts. | | includeAvatars | true | Render author avatars; initials are used otherwise. | | includeUserIds | false | Add author IDs as data-author-id metadata. | | includeChannelId | false | Include the channel ID in header metadata. | | poweredBy | true | Include the package attribution footer. | | saveImages | false | Inline supported Discord-CDN raster images as data URLs. | | maxInlineMediaBytes | 26214400 | Total inlined-image budget, at most 100 MiB. | | maxSingleMediaBytes | 8388608 | Per-image budget, at most 100 MiB. | | theme | auto | Light, dark, or operating-system color scheme. | | timezone | UTC | IANA timezone used for message and embed timestamps. | | locale | en-US | Intl locale used for dates and numbers. | | generatedAt | current time | Explicit archive creation time, useful for deterministic exports. |

The result contains the complete html, the sanitized filename, and a ready-to-send discord.js AttachmentBuilder.

Components V2

Message components are not assumed to be Action Rows. discord.js structures are converted through their toJSON() representation and normalized into a recursive discriminated union.

Supported message component types from discord.js 14.27.x and Discord API v10:

• Action Rows with Primary, Secondary, Success, Danger, Link, and Premium buttons
• String, User, Role, Mentionable, and Channel Select menus
• Containers with accent color, spoiler state, and ordered nested content
• Text Displays with the same safe Discord Markdown renderer as message content
• Sections containing Text Displays with a Button or Thumbnail accessory
• Separators with Small or Large spacing and visible or invisible dividers
• responsive Media Galleries with item descriptions and per-item spoilers
• File display components, including attachment://filename resolution
• Thumbnails with descriptions, spoilers, and unavailable-media fallbacks

Modal-only Text Inputs, Labels, File Uploads, Radio Groups, and Checkboxes are not treated as message components. Unknown future message component types render a small static fallback and never abort the transcript.

Content Support

Messages include author and display names, bot/webhook badges, optional IDs, avatars, timestamps, edits, pins, TTS, system events, threads, replies, unavailable references, embeds, attachments, and reactions. Replies are resolved when the referenced message is present in the provided/fetched set.

The Markdown renderer supports bold, italic, underline, strikethrough, spoilers, inline and fenced code, headings, lists, blockquotes, masked and plain links, Discord timestamps, user/role/channel mentions, Unicode emoji, and custom Discord emoji.

Security

All Discord-controlled strings are HTML-escaped before markup is produced. The renderer never passes message HTML through, does not emit scripts, and adds a restrictive Content Security Policy. URLs are parsed centrally and allow only HTTPS for embedded media; ordinary links additionally allow HTTP. javascript:, arbitrary data:, file:, malformed attachment references, inline styles from message data, and SVG/data payloads supplied by messages are rejected. Generated links use noopener, noreferrer, and nofollow.

saveImages is deliberately constrained:

• only HTTPS hosts in Discord's discordapp.com and discordapp.net media domains are fetched;
• redirects are rejected;
• only PNG, JPEG, GIF, WebP, and AVIF response types are accepted;
• response streams stop at the configured per-item and total byte budgets;
• failures leave the original secure URL in place and do not fail transcript generation.

Inlining makes the HTML larger. The generated file can still reference external HTTPS media when inlining is disabled, a file exceeds its budget, or a CDN request fails.

Known Limitations

• Discord CDN links can expire and externally hosted media can disappear.
• Only referenced messages included in the input set can be expanded; missing messages use a safe unavailable-reference marker and no extra API request is made.
• Discord Markdown edge cases can evolve independently of this package. The renderer intentionally favors predictable, escaped output over executing arbitrary HTML or matching every client quirk.
• Media fallbacks are structural. A standalone HTML file cannot detect a later image load failure without JavaScript.
• saveImages does not inline videos, audio, SVG, arbitrary hosts, or generic files.

Development

npm install
npm run lint
npm run typecheck
npm test
npm run build
npm pack --dry-run

npm test builds first so the test suite also validates the scoped package-root import. See CONTRIBUTING.md for fixture and pull-request expectations. A complete discord.js bot example is in examples/basic.ts. Biome performs formatting, import organization, and lint checks through npm run format and npm run lint.

Publishing

This package is configured as the public scoped package @fmfl-devteam/discord-html-transcripts. Tagged releases are published by .github/workflows/release.yml. A tag must be exactly v followed by the version in package.json. The workflow runs the complete prepublish check, publishes the public npm package, and creates a GitHub Release with generated release notes.

Configure npm Trusted Publishing for this package with these values:

• Provider: GitHub Actions
• Organization: fmfl-devteam
• Repository: discord-html-transcripts
• Workflow filename: release.yml
• Allowed action: npm publish

Trusted Publishing uses short-lived OIDC credentials and requires no permanent npm token. The workflow uses a GitHub-hosted Node.js 24 runner and has the required id-token: write permission. If the package has not been published before and npm does not yet allow configuring its Trusted Publisher, add a granular publishing token temporarily as the NPM_TOKEN repository secret for the initial release. Configure Trusted Publishing afterward and delete that secret.

Create a release by updating the version and pushing its generated tag:

npm version patch
git push origin main --follow-tags

Use minor or major instead of patch when appropriate. prepublishOnly runs Biome, strict typechecking, tests, and the dual ESM/CommonJS build. Workflow retries are safe: an existing npm version and an existing GitHub Release are detected and skipped. Never commit npm tokens or put them in workflow files.

Contributing

Contributions are welcome under the process in CONTRIBUTING.md. Changes to Discord structures should use payloads from Discord API v10 and types/classes exported by the supported discord.js version, with security and snapshot coverage for renderer changes.

License

MIT © Fmfl-Devteam. See LICENSE.