Inline Source CLI: HTML Resource Inliner

2.0.0 · active · verified Wed Apr 22

The `inline-source-cli` package offers a dedicated command-line interface (CLI) for the `inline-source` library, a utility designed to embed external resources such as CSS stylesheets, JavaScript code, and image data directly into an HTML file. This functionality is crucial for scenarios requiring self-contained HTML documents, such as preparing email templates, optimizing static site assets for single-file deployment, or creating portable web components. The package is currently at stable version 2.0.0, with a release cadence that appears driven by dependency updates or minor feature enhancements like the addition of stdin support. Its primary advantage lies in providing a straightforward, opinionated command-line tool that abstracts away the programmatic complexity of resource inlining, making it easy to integrate into existing build scripts and CI/CD pipelines without writing custom JavaScript code. Developers can quickly achieve asset optimization and delivery benefits without deep diving into the underlying library's API, using standard shell commands.

Common errors

```
Error: Command failed with exit code 1
```
cause A generic error indicating the CLI process encountered an unhandled error or failed validation.

fix Check the `stderr` output from the CLI for more specific error messages, often related to file paths, invalid options, or issues with the input HTML structure.
```
Error: ENOENT: no such file or directory, stat 'path/to/your/file.html'
```
cause The specified input HTML file or a linked resource (CSS, JS, image) could not be found at the given path.

fix Verify that the input HTML file path is correct and that all referenced local assets exist relative to the `--root` directory or the HTML file's location.
```
Error: Unknown option '--some-new-option'
```
cause Attempting to use a CLI option that does not exist or is deprecated in the current `inline-source-cli` version.

fix Consult the `inline-source --help` output or the package documentation for available command-line options and their correct syntax.

Warnings

breaking Version 2.0.0 bumped the minimum required Node.js version to `8.3.0`. Older Node.js environments will not be supported.
Fix: Upgrade your Node.js runtime to version 8.3.0 or higher.
gotcha Breaking changes or new features in the underlying `inline-source` library may implicitly affect `inline-source-cli`'s behavior or output. Always review the changelog for `inline-source` when `inline-source-cli` receives dependency updates.
Fix: Consult the changelog of the `inline-source` package (e.g., `npm view inline-source versions`) for changes in its major versions.
gotcha Incorrect `root` path configuration is a common source of errors, leading to resources not being found or inlined correctly.
Fix: Ensure the `--root` argument points to the correct base directory for resolving relative paths of your inlined resources (e.g., CSS, JS, images). It should be the directory where the source HTML and its dependencies reside.

Install

npm install inline-source-cli npm
yarn add inline-source-cli yarn
pnpm add inline-source-cli pnpm

Imports

inline-source-cli executable
wrong:
```
import { runCli } from 'inline-source-cli';
```
correct:
```
import { spawn } from 'child_process';
spawn('inline-source', ['--root', './', 'file.html'], { stdio: 'inherit' });
```
This package is a command-line interface (CLI) and does not export programmatic symbols. Its primary interaction is via the `inline-source` executable. Programmatic use involves spawning a child process.
Programmatic execution (using execa)
wrong:
```
const inlineSourceCli = require('inline-source-cli/cli');
```
correct:
```
import { execa } from 'execa';
await execa('inline-source', ['--root', './', 'file.html']);
```
For robust programmatic execution from Node.js, external libraries like 'execa' are commonly used. Directly requiring internal CLI files is unsupported and highly unstable.
Type definitions
wrong:
```
import type { InlineSourceOptions } from 'inline-source-cli';
```
correct:
```
/* This CLI package does not export types for programmatic use. */
```
As a pure CLI wrapper, this package does not provide TypeScript type definitions for its own use. Type definitions for the underlying inlining options would come from the `inline-source` library directly.

Quickstart

Demonstrates how to programmatically execute `inline-source-cli` from a Node.js script, creating dummy files, running the inliner, and capturing its output.

import { spawn } from 'child_process';
import path from 'path';
import fs from 'fs';

// Create a dummy HTML file and resources for demonstration
const buildDir = path.join(process.cwd(), 'build-cli-demo');
if (!fs.existsSync(buildDir)) fs.mkdirSync(buildDir, { recursive: true });

fs.writeFileSync(path.join(buildDir, 'style.css'), 'h1 { color: blue; }');
fs.writeFileSync(path.join(buildDir, 'script.js'), 'console.log(\'Script inlined!\');');
fs.writeFileSync(path.join(buildDir, 'index.html'), `<!DOCTYPE html>\n<html>\n<head>\n    <link rel=\"stylesheet\" href=\"./style.css\">\n</head>\n<body>\n    <h1>Hello, Inliner!</h1>\n    <script src=\"./script.js\"></script>\n</body>\n</html>`);

console.log('Created dummy files in:', buildDir);

// Resolve the path to the inline-source CLI executable
const inlineSourceCliPath = path.resolve(process.cwd(), 'node_modules', '.bin', 'inline-source');

// Execute the inline-source CLI tool
const child = spawn(inlineSourceCliPath, [
  '--compress', 'false',
  '--root', buildDir,
  path.join(buildDir, 'index.html')
], { stdio: 'pipe' });

let output = '';
child.stdout.on('data', (data) => {
  output += data.toString();
});

child.stderr.on('data', (data) => {
  console.error(`stderr: ${data}`);
});

child.on('close', (code) => {
  if (code === 0) {
    console.log('\n--- Inlined HTML Output ---');
    console.log(output);
    fs.writeFileSync(path.join(buildDir, 'bundle.html'), output);
    console.log('\nOutput written to', path.join(buildDir, 'bundle.html'));
  } else {
    console.error(`CLI process exited with code ${code}`);
  }
  // Clean up dummy files
  fs.unlinkSync(path.join(buildDir, 'index.html'));
  fs.unlinkSync(path.join(buildDir, 'style.css'));
  fs.unlinkSync(path.join(buildDir, 'script.js'));
  fs.unlinkSync(path.join(buildDir, 'bundle.html'));
  fs.rmdirSync(buildDir);
  console.log('Cleaned up dummy files.');
});

view raw JSON →