@bandf/code-image

Browser-only code image rendering powered by Highlight.js and the Canvas API. The package takes source code and optional metadata, lays out a styled code card, and returns a PNG Blob. It does not use a server or send source code over the network.

Install

npm install @bandf/code-image

Use

import {renderCodeImage} from '@bandf/code-image';

const png = await renderCodeImage({
    code: 'const answer = 42;',
    language: 'javascript',
    title: 'answer.js'
});

png is a browser Blob with type image/png. Applications can write it to the clipboard, download it with an object URL, upload it, or display it.

React and bundlers

The package has no React dependency. Call it from a client-side event handler and keep presentation, loading state, and delivery of the resulting Blob in the application:

'use client';

import {renderCodeImage} from '@bandf/code-image';

export function CodeImageButton({code, language, onImage}) {
    const createImage = async () => {
        const png = await renderCodeImage({code, language});
        onImage(png);
    };

    return <button onClick={createImage}>Create image</button>;
}

The package is native ESM and uses a dynamic import for Highlight.js, allowing modern bundlers to keep the full language build in an on-demand chunk. It is verified with Vite's production bundler. Importing the module during server-side rendering is safe, but calling renderCodeImage requires DOM and Canvas browser APIs. React Server Components and other SSR applications must invoke it from a client boundary.

Highlighting

Highlight.js is a direct dependency and implementation detail of this package. Callers provide a language when they know it. If the language is missing or not recognized, the package uses Highlight.js automatic detection. If highlighting fails, rendering falls back to uncolored source text.

The full Highlight.js language build is used so the default package works without language registration or application-level highlighter configuration.

Themes

The default theme is light. A built-in dark theme is also available:

await renderCodeImage(input, {theme: 'dark'});

A custom theme can extend either built-in theme:

await renderCodeImage(input, {
    theme: {
        base: 'dark',
        codeBackground: '#101418',
        syntax: {
            keyword: '#7dd3fc'
        }
    }
});

Theme input is explicit. The renderer does not inspect the consuming page's CSS or global custom properties, so the same input and theme produce a consistent design across applications.

Exports

• renderCodeImage(input, options) returns a Promise for a PNG Blob.
• codeImageFilename(input) creates a filesystem-safe PNG filename.
• validateCodeImageSelection(input) validates and normalizes input.
• codeImageThemes exposes the built-in theme values.
• resolveCodeImageTheme(input) resolves names and partial custom themes.

Browser requirements

Rendering requires HTMLCanvasElement, a 2D Canvas context, and HTMLCanvasElement.toBlob(). Clipboard and download behavior deliberately remain the responsibility of the consuming application.

License

MIT