BitmapText.js

BitmapText.js Runtime Bundles

Production-ready minified bundles for BitmapText.js bitmap text rendering library.

📦 Files

Browser Bundle

Node.js Bundle

🚀 Quick Start

Browser Usage

<!DOCTYPE html>
<html>
<head>
  <title>BitmapText Demo</title>
</head>
<body>
  <canvas id="myCanvas" width="400" height="100"></canvas>

  <!-- Single script tag - complete runtime -->
  <script src="dist/bitmaptext.min.js"></script>

  <script>
    // Create font configuration
    const fontProps = new FontProperties(
      1,          // pixelDensity (1.0 = standard, 2.0 = Retina)
      "Arial",    // fontFamily
      "normal",   // fontStyle
      "normal",   // fontWeight
      19          // fontSize in CSS pixels
    );

    // Optional: Configure font directory
    BitmapText.setFontDirectory('./font-assets/');

    // Load font and render
    const canvas = document.getElementById('myCanvas');
    const ctx = canvas.getContext('2d');

    BitmapText.loadFont(fontProps.idString).then(() => {
      BitmapText.drawTextFromAtlas(ctx, "Hello World", 10, 50, fontProps);
    });
  </script>
</body>
</html>

Node.js Usage

The Node.js bundle excludes platform-specific dependencies. You must provide your own Canvas implementation.

// Import Canvas implementation (user's choice)
import { createCanvas } from 'node-canvas';  // or 'skia-canvas', 'canvas', etc.

// Import BitmapText bundle
import './dist/bitmaptext-node.min.js';

// Configure with your Canvas
BitmapText.configure({
  fontDirectory: './font-assets/',
  canvasFactory: () => createCanvas()
});

// Create font configuration
const fontProps = new FontProperties(1, "Arial", "normal", "normal", 19);

// Load font and render
await BitmapText.loadFont(fontProps.idString);

const canvas = createCanvas(400, 100);
const ctx = canvas.getContext('2d');

BitmapText.drawTextFromAtlas(ctx, "Hello World", 10, 50, fontProps);

// Export canvas (requires separate PNG encoder)
import { PngEncoder } from './lib/PngEncoder.js';
import fs from 'fs';
fs.writeFileSync('output.png', PngEncoder.encode(canvas));

📚 What’s Included

The bundles contain everything needed for rendering bitmap text:

Core Runtime Classes

Font Loading

Atlas Management

Data Storage

Node.js Specific (node bundle only)

❌ What’s NOT Included

Browser Bundle

The browser bundle is complete for text rendering. No additional dependencies needed.

Node.js Bundle

You must provide separately:

  1. Canvas Implementation - User’s choice of:
    • node-canvas - Native Canvas API for Node.js (most popular)
    • skia-canvas - Hardware-accelerated alternative
    • canvas - Pure JavaScript Canvas implementation
    • Or any custom Canvas-compatible implementation
  2. PNG Encoder (optional) - For exporting images to filesystem:
    • lib/PngEncoder.js - Included in demo bundles but separate from library
    • Image I/O is not core rendering functionality

🎯 Bundle Sizes

Bundle Unminified Minified Reduction
Browser 149KB 32KB 79%
Node.js 153KB 33KB 79%

Note: Font asset files are separate (metrics ~1-2KB each, atlases ~2-5KB each).

🔨 Rebuilding

Quick Reference

Rebuild everything (recommended):

npm run build
# or
./scripts/build-runtime-bundle.sh --all

Rebuild specific bundles:

# Browser bundle only
./scripts/build-runtime-bundle.sh --browser
# or
npm run build-bundle

# Node.js bundle only
./scripts/build-runtime-bundle.sh --node
# or
npm run build-bundle-node

What Gets Built

Command Browser Bundle Node.js Bundle Output
npm run build ✅ ✅ Both bundles + source maps
npm run build-bundle ✅ ❌ Browser only
npm run build-bundle-node ❌ ✅ Node.js only
./scripts/build-runtime-bundle.sh ✅ ❌ Browser (default)
./scripts/build-runtime-bundle.sh --all ✅ ✅ Both bundles

Build Output

Each build creates:

When to Rebuild

Rebuild bundles after modifying any runtime source files:

Testing Bundles

Browser (open in browser):

npm run serve
# Then open http://localhost:8000/public/hello-world-demo-bundled.html

Node.js (run all demos):

./run-node-demos.sh

This builds bundles, runs 4 demos, and generates PNG output to verify everything works.

📖 Examples

See the bundled demo files for complete working examples:

🐛 Debugging

Using Source Maps

The minified bundles include source maps for debugging:

<!-- Browser DevTools will automatically load the source map -->
<script src="dist/bitmaptext.min.js"></script>

Set breakpoints in original source files, inspect variables, and see readable stack traces.

Using Unminified Bundle

For development, use the unminified version:

<!-- Easier to debug without source maps -->
<script src="dist/bitmaptext.js"></script>

Using Individual Source Files

For maximum debugging flexibility, use the individual source files:

<!-- Original demos load 17 separate files -->
<!-- See public/hello-world-demo.html for example -->

🔗 Additional Resources

📝 License

SEE LICENSE IN LICENSE

This site is open source. Improve this page.