Skip to content
htmlcsstoimagePublic

About

official n8n node for HTML/CSS to Image API

Resources

Stars

1 star

Watchers

0 watching

Forks

Repository files navigation

HTML/CSS to Image API for n8n

Generate images, website screenshots, PDFs, recordings, and signed render-on-demand URLs with the HTML/CSS to Image API.

n8n is a workflow automation platform.

Installation

Follow the installation guide in the n8n community nodes documentation.

The community package name is:

@html-css-to-image/n8n-nodes-html-css-to-image

Operations

  • Create an image or PDF from HTML and CSS
  • Take a screenshot of a webpage URL
  • Render a saved template with JSON values
  • Generate signed template or webpage URLs that render on demand
  • Delete an image by ID
  • Return image metadata, a binary PNG/JPG/WebP/PDF, or both
  • Create an MP4, WebM, or GIF recording from HTML/CSS or a webpage URL
  • Fetch a recording's status or delete a recording by ID
  • Return recording metadata, a binary media file, or both

Credentials

Create an HTML/CSS to Image API account, then copy the API ID and API Key from the dashboard. The credential uses HTTP Basic authentication and n8n stores both values in its encrypted credential store.

Compatibility

This package is built and tested using the current @n8n/node-cli scaffolding and Node.js LTS.

Usage

All fields support n8n expressions. For example, HTML from an earlier node can be rendered with {{$json.html}}. Choose binary output when the next node expects a file attachment, such as email, Slack, S3, or Google Drive.

Template values use n8n's typed field editor. Add each template variable by name and choose its value type, or use an expression that resolves to an object.

URL screenshots support custom request headers with a repeatable name/value editor, additional allowed header origins, subrequest forwarding, and HCTI request identification. The create operations also expose response URL format, deduplication duration, storage destinations, transparent backgrounds, and typed request override rules for blocking selected browser network requests.

Example workflows

Render HTML from an earlier node

  1. Add an HTML/CSS to Image API node.
  2. Select Create From HTML/CSS.
  3. Set HTML to {{$json.html}}.
  4. Add CSS or rendering options as needed.
  5. Leave Output as URL and Metadata, or select a binary output for file-based nodes.

Take a webpage screenshot

  1. Select Create From URL.
  2. Set URL to a fixed URL or an expression such as {{$json.url}}.
  3. Add viewport width and height together when a fixed viewport is required.
  4. Use the CSS option to inject page-specific overrides before rendering.

Render a saved template

  1. Select Create From Template and enter the template ID.
  2. Under Template Values, add fields matching the variables in the template.
  3. Choose the appropriate value type for each field, such as string, number, boolean, array, or object.
  4. Optionally provide a template version; otherwise the latest version is used.

Send the result as a file

  1. Set Output to Binary File or URL, Metadata, and Binary File.
  2. Choose PNG, JPG, WebP, or PDF.
  3. Set Binary Property to the property expected by the next node, such as data.
  4. Connect the node to an email, Slack, cloud storage, or other file-capable node.

Record HTML/CSS or a webpage

  1. Set Resource to Recording and choose Create From HTML/CSS or Create From URL.
  2. Enter the HTML or URL and the Duration MS. For example, 5000 requests five seconds.
  3. Under Media Options, optionally choose MP4, WebM, or GIF, frame rate, and scale.
  4. Add a Trigger to wait for an element or window.RecordingReady(), or leave it empty to start immediately.
  5. Add ordered Actions to scroll, pause, find or click elements, run JavaScript, or fail a branch.
  6. Leave Output as URL and Metadata to receive id, status_url, and recording_url immediately.

Recordings have no audio. Options includes duration mode, deferred rendering, viewport settings, CSS, and other browser settings from the official client. URL recordings support the same native custom-header editor as URL screenshots.

Action branches and scroll destinations use native editors. The editor supports three levels of actions; expressions can supply API action arrays with deeper branches. An empty JavaScript error branch preserves the API's fail-on-error behavior. Enable Ignore Script Errors to continue without fallback actions.

Choose Binary File or URL, Metadata, and Binary File to download the recorded media. The node requests the exact recording_url; that request waits for the recording to finish and starts rendering a deferred recording.

To check progress separately, select Fetch Status and set Recording ID to {{$json.id}}. This performs one status request and returns the lifecycle state, attempt count, and any recording error. Use a Wait node and an If or Switch node for polling. ready, failed, and cancelled are terminal states; awaiting_render indicates deferred rendering.

Select Delete under the Recording resource to permanently delete one recording per input item. Connect multiple input items to delete multiple recordings.

TypeScript client synchronization

The official TypeScript client is a git submodule under vendor/html-css-to-image-client. It is compiled into this package, so the published community node has no runtime dependencies.

The n8n option fields are generated from the client request types and their JSDoc:

git submodule update --init --recursive
npm run generate:client

When an API parameter is added to the TypeScript client, update the submodule and run the generator. Primitive string, number, boolean, string-array, and string-union parameters are added to the n8n UI automatically. Complex client types need an n8n-specific UI adapter only when their editor representation requires one.

To update the client:

git submodule update --remote vendor/html-css-to-image-client
npm run generate:client
npm test

Development

npm install
npm run lint
npm run build
npm test
npm run dev

Releasing

The version in package.json is the release switch. When a commit reaches main, CI runs lint, build, and tests first. Only after CI succeeds does the publish workflow check whether that exact version already exists on npm. If it is new, the workflow publishes the exact tested commit through npm Trusted Publishing and creates the matching Git tag automatically.

For a patch release:

npm version patch --no-git-tag-version

You can also update the version directly in package.json and package-lock.json. Update CHANGELOG.md, commit the version change, and push main with GitHub Desktop. Do not create a tag or run npm publish locally.

Ordinary pushes that do not change the package version are skipped.

Resources

About

official n8n node for HTML/CSS to Image API

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Contributors

Languages