A monorepo for parsing and rendering GIMP XCF files in TypeScript/JavaScript.
- Combined code coverage across both packages: 87.85%
- xcfreader: 87.54% | ui-xcfimage: 95%
- Coverage measured using c8 (xcfreader) and Playwright V8 coverage (ui-xcfimage)
- CI enforces minimum 80% coverage (warning at 85%)
| Package | Description | Links |
|---|---|---|
| xcfreader | Core XCF parser library for Node.js and browser | README · npm |
| ui-xcfimage | <gpp-xcfimage> web component for rendering XCF files |
README · npm |
| ha-xcfimage-card | Home Assistant custom card with entity-based layer control | README |
| vscode-xcfviewer | VS Code extension for previewing XCF files with layer control | README |
Parse and render GIMP XCF files in Node.js or the browser.
Node.js:
import { XCFParser, XCFPNGImage } from "@theprogrammingiantpanda/xcfreader/node";
const parser = await XCFParser.parseFileAsync("./image.xcf");
const image = new XCFPNGImage(parser.width, parser.height);
parser.createImage(image);
await image.writeImage("./output.png");Browser:
import { XCFParser, XCFDataImage } from "@theprogrammingiantpanda/xcfreader/browser";
const arrayBuffer = await file.arrayBuffer();
const parser = XCFParser.parseBuffer(arrayBuffer);
const image = new XCFDataImage(parser.width, parser.height);
parser.createImage(image);
ctx.putImageData(image.imageData, 0, 0);See full xcfreader documentation →
Render XCF files with zero JavaScript required:
<!-- Standalone bundle - includes xcfreader -->
<script src="path/to/gpp-xcfimage.iife.min.js"></script>
<!-- Render all visible layers -->
<gpp-xcfimage src="/images/artwork.xcf"></gpp-xcfimage>
<!-- Render specific layers by index -->
<gpp-xcfimage src="/images/artwork.xcf" visible="0,3,5"></gpp-xcfimage>After loading, the element exposes a layers attribute with the full layer hierarchy as JSON, including unique indices for each layer.
See full web component documentation →
- TypeScript source: Full type safety with strict mode
- Native ESM: Modern ES modules throughout
- Promise-based API: Async/await support
- Dual platform: Works in Node.js and browsers
- GIMP 2.10+ support: Full XCF v011 64-bit pointer format compatibility
- Multiple color modes: RGB/RGBA, Grayscale, and Indexed (paletted) images
- High bit-depth: 8-bit, 16-bit, 32-bit integer; 16-bit (half), 32-bit, 64-bit float
- High performance: Optimized rendering with 27% improvement through zero-allocation compositing, bulk copy operations, and specialized fast paths
- Type-safe compositing: All blend modes via the
CompositerModeenum
Browser bundles require ES2022 support:
| Browser | Minimum Version |
|---|---|
| Chrome/Edge | 94+ (Sept 2021) |
| Firefox | 101+ (May 2022) |
| Safari | 15.4+ (March 2022) |
Internet Explorer is not supported. Node.js version 18+ is required for server-side usage.
npm install @theprogrammingiantpanda/xcfreader
# For Node.js PNG output (optional)
npm install pngjsnpm install @theprogrammingiantpanda/ui-xcfimageOr use the standalone IIFE bundle directly in <script> tags (no build step required).
- GIMP versions: 2.10.x (v011 64-bit), 2.8.x (v010 32-bit), and earlier
- XCF versions: v010, v011, and v012
- Color modes: RGB/RGBA, Grayscale, and Indexed
- Bit depths: 8-bit, 16-bit, 32-bit integer; 16-bit (half), 32-bit, 64-bit float
# Install dependencies
npm install
# Build all packages
npm run build
# Run tests
npm test
# Run browser tests
npm run test:browser
# Generate coverage report
npm run coverageHaving issues? Check our comprehensive guides:
- Troubleshooting Guide - Common issues and solutions
- FAQ - Frequently asked questions
- GitHub Issues - Report bugs or request features
We welcome contributions from the community! You can help by:
- Contributing Guide - Setup instructions and guidelines
- Reporting bugs or suggesting features via issues
- Submitting pull requests for bugfixes, new features, or documentation improvements
- Reviewing open issues and helping other users
- Improving tests, benchmarks, or examples
Whether you're a first-time contributor or a seasoned developer, your input is valued. Thank you for helping make xcfreader better!
- API Documentation - TypeDoc API reference (auto-generated)
- Architecture Guide - System architecture, data flow, and package relationships
- Troubleshooting Guide - Common issues and solutions
- Contributing Guide - How to contribute
- xcfreader API - Core library documentation
- ui-xcfimage Web Component - Web component documentation
- CHANGELOG.md - Version history and release notes
- example-xcf/browser-demo.html - Interactive browser demo
MIT License. See LICENSE for details.