Rtifact

Portable, Compressed HTML Artifacts from JSX

Turn .jsx into a portable, interactive .html artifact for humans.

About · Demo · AI Agent Skill · Getting Started · CLI · Themes · Output Modes · Examples · JSX Artifact Source · Custom Theme · Contributing

About

Rtifact turns a .jsx file into a portable .html artifact.

Why let your AI agent write HTML that consumes 2-5x tokens when it can write JSX? Let your agent write .jsx with React, Ant Design, Tailwind CSS, React Icons, and PrismJS. Rtifact handles the build and produces a finished artifact with gzip-compressed assets as one .html file starting at about 15.6 KB.

npx rtifact Artifact.jsx --output artifact.html

Or use it with a skill

/rtifact Create an easy-to-read documentation guide I can send to my colleague.

➡️ Get a finished, portable HTML artifact in one .html file.

See examples at website

Powered by React, Tailwind CSS, Ant Design, React Icons, and PrismJS.

Built With

React · Ant Design · Tailwind CSS · React Icons · PrismJS

Demo

Prompt:

1. /rtifact Create a quick, high-level new joiner onboarding guide for this repo ./hermes-agent
2. /rtifact-create-theme Create a theme based on this image [Image #1] and then apply hermes-agent-onboarding.jsx with new theme output to hermes-agent-onboarding.html

Another GIF demo

AI agent skill

Install the official Rtifact authoring skill through the universal Skills CLI or your agent's marketplace/plugin system.

🪄 Via Skills

The Skills CLI supports Codex, Claude Code, Gemini CLI, Antigravity, OpenCode, Cursor, and other coding agents:

npx skills add sirawats/rtifact --skill rtifact rtifact-create-theme

Add --global to make the skill available across projects.

🧩 Via Marketplace/Plugin

The agent-specific adapters are distributed through Git and are not included in the npm package.

Codex

codex plugin marketplace add sirawats/rtifact
codex plugin add rtifact@rtifact

Claude Code

/plugin marketplace add sirawats/rtifact
/plugin install rtifact@rtifact

Antigravity or Gemini CLI

agy plugin install https://github.com/sirawats/rtifact

# Gemini CLI
gemini extensions install https://github.com/sirawats/rtifact

OpenCode

Clone the repository, then add its adapter to your project or global opencode.json:

git clone https://github.com/sirawats/rtifact.git /path/to/rtifact

{
  "plugin": ["/absolute/path/to/rtifact/.opencode/plugins/rtifact.mjs"]
}

Both installation paths use the canonical skills/rtifact skill.

Quick start

After installing the skill, ask your preferred AI agent:

/rtifact Create an API testing report that's ready to send to my frontend engineer colleague

Your agent creates the JSX, builds it with Rtifact, and gives you a finished HTML artifact you can open, upload, or send. No local server or adjacent asset directory is needed.

Requires Node.js ^20.19.0 or >=22.12.0.

CLI

Usage: rtifact <entry.jsx|entry.tsx> [options]
       rtifact themes | rtifact --themes
       rtifact prism-themes | rtifact --prism-themes
       rtifact theme-inspect <theme-name> | rtifact --theme-inspect <theme-name>
       rtifact pack <directory> --output <file.html> [options]

Build a JSX component into one CDN-backed compressed HTML file by default.

Options:
      --output <path>        HTML output path (default: ./<EntryName>.html)
  -o, --out-dir <path>      Build a directory instead of one HTML file
      --base <path>         Directory-mode public base path (default: ./)
      --self-contained      Embed runtime dependencies for offline use
      --no-readable-source  Omit original JSX/TSX source from file output
      --theme <value>       Global theme preset or .ts/.jsx module (default: default)
      --themes               List available theme names
      --prism-themes         List available Prism theme names
      --theme-inspect <name> Print theme definition source code
      --single-file         Deprecated alias for the default file mode
      --force               Replace an existing protected output
  -h, --help                Show this help
  -v, --version             Show the installed version

Run `rtifact themes` or `rtifact prism-themes` to list available themes.

--output and --out-dir conflict. --base requires --out-dir. --self-contained applies only to direct HTML builds; pack is already self-contained.

Existing output requires confirmation. Non-interactive automation must pass --force. Rtifact rejects unsafe targets such as filesystem roots, symbolic links, the current directory, and outputs containing their source input. Builds are staged so a failed replacement preserves the last successful result.

Pick a theme

Build with any built-in theme preset:

npx rtifact Report.jsx --theme catppuccin-mocha

Themes style the document and Ant Design together: typography, colors, spacing, surfaces, controls, focus states, and code. Run npx rtifact themes to view all built-in presets (default, github-light, github-dark, catppuccin-mocha, obsidian-minimal, material, gruvbox, etc.).

Choose an output

Need	Command	Output	Measured Size	Runtime Dependencies
A portable file (Default)	npx rtifact App.jsx	App.html	~15.6 KB	Pinned React & AntD load from CDN URLs
A file that works offline	npx rtifact App.jsx --self-contained	App.html	189.9–686.2 KB	Embedded runtimes for zero network requests
A deployable static site	npx rtifact App.jsx --out-dir dist	dist/	Standard static assets	Bundled into conventional asset directory

• Portable HTML (Default): Writes a single compressed HTML file embedding app code, CSS, local assets, React Icons, and PrismJS modules while loading React & Ant Design from pinned CDN URLs (https://esm.sh).
• Offline HTML (--self-contained): Embeds all runtime dependencies directly for zero-network execution.
• Static Directory (--out-dir dist): Generates a standard asset directory (dist/) with index.html and static assets. Supports --base <path> for deployment subpaths.
• Package Existing Build (pack): Run rtifact pack dist --output index.html to package an existing directory build into self-contained HTML.

Direct .jsx and .tsx HTML builds also include the exact original entry source in an inert template#rtifact-source near the beginning of the file, before the compressed browser payload. This lets an AI agent understand the artifact without decoding the runtime representation. The source block contains only the direct entry file; selected themes and imported local modules are not copied into it. Pass --no-readable-source to omit both readable-source templates from a direct file; compiled application code remains in the compressed payload. Directory output and pack do not have this metadata.

Because the source is intentionally readable, comments, dead code, and unused strings may be visible to anyone who receives the HTML. Do not put secrets or private notes in source intended for a portable artifact.

Examples

Example	Theme	Demonstrates
APITestReport.jsx	github	Filterable API failures and request/response evidence
CodeReviewReport.jsx	github-dark-dimmed	Actionable findings, severity filters, suggested diffs
SetupGuide.jsx	gruvbox	Guided setup checklist, commands, troubleshooting
Techspec.jsx	github	Technical RFC, requirements, architecture, rollout
APIDocs.jsx	github-dark	Interactive endpoint reference and code samples
TaxCalculator.jsx	material	Stateful progressive tax calculator
SaaS.jsx	catppuccin	Product preview and responsive pricing
Analytics.jsx	one-dark	Operational metrics and service health
Editorial.jsx	obsidian-minimal	Long-form reading and typographic rhythm
AntD.jsx	default	Comprehensive Ant Design component catalog showcase

Try one from a repository clone:

npm run build
node lib/bin.js examples/APIDocs.jsx --theme github-dark

JSX Artifact Source

The entry must be a readable .jsx or .tsx module with a default-exported React component. Relative imports resolve from the entry file.

import { Button, Card } from "antd";
import { FiDownload } from "react-icons/fi";
import icon from "./icon.png";

export const RTIFACT = {
  title: "Release report",
  icon,
};

export default function Report() {
  return (
    <main className="min-h-screen p-8">
      <Card className="mx-auto max-w-xl">
        <h1>Release report</h1>
        <Button type="primary" icon={<FiDownload aria-hidden="true" />}>
          Download
        </Button>
      </Card>
    </main>
  );
}

The optional RTIFACT export sets the browser-tab title and favicon. The icon may be an imported local image or a remote or data URL.

Inspecting generated artifact source

An unfamiliar AI agent can read template#rtifact-source directly. For a decoded copy on macOS or Linux, use xmllint:

xmllint --html --xpath 'string(//template[@id="rtifact-source"])' artifact.html 2>/dev/null

If xmllint is unavailable, this Python standard-library fallback preserves the original source text and line endings:

python3 -c 'import html,re,sys; text=open(sys.argv[1], encoding="utf-8", newline="").read(); match=re.search(r"<template\b[^>]*\bid=\"rtifact-source\"[^>]*>(.*?)</template>", text, re.S); sys.stdout.write(html.unescape(match.group(1)))' artifact.html

Do not spend time decoding or decompressing rtifact-payload; it is the browser runtime representation, not the preferred authoring source. Artifacts built with --no-readable-source intentionally omit these templates.

The CLI supplies:

• React and React DOM
• Ant Design
• Tailwind CSS
• React Icons
• PrismJS and Prism Themes

Other bare package imports resolve from the input project's node_modules.

Prism themes

Each Rtifact theme supplies a matching PrismJS theme automatically. Override it for one artifact when needed:

export const RTIFACT = { prismTheme: "prism" };

Run npx rtifact prism-themes to discover installed Prism theme names. Unknown names warn and fall back to the selected Rtifact theme's default.

Custom Theme

Creating a custom theme allows you to define a product-specific visual identity, palette, and typography for your artifacts.

Creating custom themes with AI agents

We recommend using the official agent skill /rtifact-create-theme to automatically generate custom theme modules. You can provide an example image (e.g. brand screenshot, color palette, design mockup) or a website URL for your AI agent to analyze:

/rtifact-create-theme Read brand-design.png and create a custom light theme module for my company.

Your agent will analyze the visual identity and generate a complete theme file (e.g., ./custom-theme.jsx).

Applying custom theme modules

Pass your local custom .ts or .jsx theme module path via --theme:

rtifact Home.jsx --theme ./custom-theme.jsx

The default export of a theme module is a declarative theme manifest. Named exports remain ordinary components that your application can import directly:

// custom-theme.jsx
import { Button } from "antd";

export default {
  id: "custom",
  // colors, typography, rhythm, component values, and provenance
};

export function CustomAction({ children }) {
  return <Button type="primary">{children}</Button>;
}

// Home.jsx
import { CustomAction } from "./custom-theme.jsx";

export default () => <CustomAction>Continue</CustomAction>;

Important

Theme modules are trusted local build-time code. Selecting one compiles and executes its module graph before output is created.

Application JSX needs no theme provider or page-level theme class—it inherits global styling automatically. Use semantic Tailwind utilities when custom layout styling is needed (bg-background, text-foreground, border-border, font-sans, font-mono, rounded-md, etc.).

Browser and security notes

Important

Portable HTML requires native gzip DecompressionStream. Default output also requires import-map support and network access to https://esm.sh. File modes execute inline scripts and styles, so use directory output for a strict CSP. Compression is not a security boundary.

Current limitations include JSX-only input, one page per invocation, no dev-server/watch/SSR mode, no user Vite or HTML configuration, and no automatic public/ directory copying.

Development and support

npm ci
npm run verify

See CONTRIBUTING.md for repository development, SUPPORT.md for usage help, and SECURITY.md for private vulnerability reporting.

License

MIT