@ssvg/core

Core sSVG compiler for parsing sSVG files into SVG and HTML files with SVG blocks.

For more information about sSVG, how it works, and why, visit SimpleSVG.dev.

This package exports two main functions (asynchronous in Node, synchronous in browser):

• compileSSVG: Compiles .ssvg files to .svg
• compileHTML: Compiles <ssvg> blocks within HTML to valid HTML with <svg> blocks

Installation

npm install @ssvg/core

Usage

Node (ESM/CommonJS)

import { compileSSVG, compileHTML } from '@ssvg/core';

const svgResult = await compileSSVG(ssvgContent, options);
const htmlResult = await compileHTML(htmlContent, options);

Browser Build

A dedicated browser build is available via:

import { compileSSVG, compileHTML } from '@ssvg/core/browser';

const svgResult = compileSSVG(ssvgContent, options);   // Synchronous API
const htmlResult = compileHTML(htmlContent, options);  // Synchronous API

• The browser build exposes the synchronous compileSSVG and compileHTML functions.
• Both return the same CompileResult structure as in Node, but synchronously.
• Imports are supported only from local files (using XMLHttpRequest). Remote URLs and Node.js modules (fs, node-fetch) are NOT supported.
• Use the baseDir option to set the base path for local imports (relative to site root).

Exports

The package uses conditional exports in package.json:

"exports": {
  ".": {
    "types": "./dist/index.d.ts",
    "import": "./dist/index.js",
    "require": "./dist/index.cjs"
  },
  "./browser": {
    "import": "./dist/browser.js",
    "default": "./dist/browser.js"
  }
}

API

Parameters

• ssvgContent (string): The sSVG markup as a string.
• htmlContent (string): The HTML markup containing <ssvg> blocks as a string.
• options (optional object):
  • baseDir (string): Base directory for resolving relative imports. Defaults to process.cwd() (Node) or '' (browser).
  • prettyDecimals (number | null): Number of decimal places for numeric values in output. If null, no rounding is applied.

Return Value

Both functions return a Promise<CompileResult> (Node) or CompileResult (browser) where CompileResult is:

{
  ok: boolean;           // true if compilation succeeded
  body?: string;         // The compiled SVG or HTML string on success
  error?: {              // Error details if ok is false
    message: string;
    code?: string;
    details?: any;
  };
  warnings?: string[];   // Array of warning messages
  stats?: {              // Compilation statistics
    durationMs?: number;
  };
  configUsed?: {         // The options that were actually used
    prettyDecimals?: number | null;
    baseDir?: string;
  };
}

License

MIT