async-html-inline
v1.4.2
Published
Asynchronously inline javascript, stylesheets, images, video, and fonts to an html page.
Maintainers
fwalzelReadme
async-html-inline
Asynchronously inline external resources (JavaScript, CSS, images, videos, fonts) into a single HTML file.
Converts all external resource references to base64 data URIs, creating a self-contained HTML file. Supports resources from both local file system and external URLs. Uses streams for efficient data handling and includes full TypeScript support.
Install
npm install async-html-inlineImport
As CommonJS:
const { asyncHtmlInline } = require('async-html-inline');As ES Module:
import { asyncHtmlInline } from 'async-html-inline';What Can Be Inlined?
async-html-inline supports inlining the following resource types:
| Resource Type | HTML Tags / CSS Properties | Output Format |
| ------------------------- | ----------------------------------------------------------------------------- | ------------------------------------ |
| Stylesheets | <link rel="stylesheet" href="..."> | Inline<style> tags |
| JavaScript | <script src="..."></script> | Inline<script> tags |
| Images | <img src="..."> | Base64 data URI insrc attribute |
| SVG Images | <image href="..."> (SVG element) | Base64 data URI inhref attribute |
| Video Posters | <video poster="..."> | Base64 data URI inposter attribute |
| Video Sources | <source src="..."> (within <video>) | Base64 data URI insrc attribute |
| Object Data | <object data="..."> | Base64 data URI indata attribute |
| Embed Sources | <embed src="..."> | Base64 data URI insrc attribute |
| CSS Background Images | background-image: url(...) | Base64 data URI in CSS |
| Fonts | @font-face { src: url(...) } | Base64 data URI in CSS |
| Font Imports | <link href="fonts.googleapis.com"> or @import url('fonts.googleapis.com') | Inline<style> with embedded fonts |
Supported File Formats
- Images: JPG, PNG, GIF, SVG, WebP, BMP, ICO, TIFF
- Videos: MP4, WebM, OGG
- Fonts: WOFF, WOFF2, TTF, OTF, EOT
- Stylesheets: CSS (including preprocessed CSS)
- Scripts: JavaScript (including ES modules)
Resource Sources
- Local files: Relative or absolute file paths
- Remote URLs: HTTP/HTTPS resources from any domain
- CDN resources: Google Fonts, Bootstrap CDN, etc.
Usage
(async function() {
await asyncHtmlInline('input.html', 'output.html');
})();The input.html like this
<html>
<head>
<title>Example inlined</title>
<link rel="stylesheet" href="styles.css" />
<script src="hello.js"></script>
<body>
<img src="https://avatars.githubusercontent.com/u/2675925?v=4">
</body>
</html>renders to the output.html
<html>
<head>
<title>Example inlined</title>
<style>.red {
color: red;
}</style>
<script>console.log('hello world');</script>
<body>
<img src="data:image/jpeg;base64,/9j/2wCEAAgGBgcGBQgHBwcJCQgKDBQNDAsLDBk.../UUAf/2Q==" />
</body>
</html>Exclusions
You can selectively exclude specific resource types from being inlined by passing an array as the third argument.
Available Exclusion Options
| Option | Description | Excludes |
| --------------- | --------------------- | ----------------------------------------------------------------------------------- |
| 'stylesheets' | Skip CSS stylesheets | <link rel="stylesheet">, <style> tags |
| 'scripts' | Skip JavaScript files | <script src="..."> |
| 'images' | Skip all images | <img>, <image>, <video poster>, <object>, <embed>, CSS background-image |
| 'videos' | Skip video files | <source src="..."> within <video> tags |
| 'fonts' | Skip font files | Font URLs in@font-face, Google Fonts, @import for fonts |
Examples
Exclude stylesheets and scripts:
const ignore = ['stylesheets', 'scripts'];
await asyncHtmlInline('input.html', 'output.html', ignore);Exclude only videos (useful for large video files):
const ignore = ['videos'];
await asyncHtmlInline('input.html', 'output.html', ignore);Exclude fonts and videos:
const ignore = ['fonts', 'videos'];
await asyncHtmlInline('input.html', 'output.html', ignore);Inline everything (default behavior):
await asyncHtmlInline('input.html', 'output.html');
// or explicitly
await asyncHtmlInline('input.html', 'output.html', []);CLI Usage
You can also use async-html-inline from the command line.
Installation
Install globally to use the CLI:
npm install -g async-html-inlineBasic Usage
html-inline <input> <output>Example:
html-inline input.html output.htmlOptions
--ignore-stylesheets - Skip inlining CSS stylesheets
--ignore-scripts - Skip inlining JavaScript files
--ignore-images - Skip inlining images
--ignore-videos - Skip inlining video files
--ignore-fonts - Skip inlining font files
--help, -h - Show help message
Examples
Inline all resources:
html-inline input.html output.htmlIgnore images from being inlined:
html-inline input.html output.html --ignore-imagesIgnore videos (useful for large video files):
html-inline input.html output.html --ignore-videosIgnore fonts (keep external font links):
html-inline input.html output.html --ignore-fontsIgnore multiple resource types:
html-inline input.html output.html --ignore-stylesheets --ignore-scripts
html-inline input.html output.html --ignore-fonts --ignore-videosDisplay help:
html-inline --helpExample
In this repo do
npm run exampleand see the output.html in the example folder.
Tests
To perform unit tests run
npm testHappy Coding.
License
Copyright (c) 2023–26 Florian Walzel, MIT License