 
A modern Swift library for creating and manipulating Excel (.xlsx) files on macOS and iOS. XLKit provides a fluent, chainable API that makes Excel file generation effortless while supporting advanced features like image embedding, CSV/TSV import/export, cell formatting, and both synchronous and asynchronous operations. Built with Swift 6.0 and targeting macOS 12+ and iOS 15+, it offers type-safe operations, comprehensive error handling, and security features. iOS support is available and tested in CI/CD.
Purpose-built for MarkersExtractor - a tool for extracting markers from Final Cut Pro FCPXML files and generating comprehensive Excel reports with embedded images, CSV/TSV manifests, and structured data exports. Perfect for professional video editing workflows requiring pixel-perfect image embedding with all video and cinema aspect ratios.
Includes comprehensive security features for production use: rate limiting, security logging, file quarantine, input validation, and optional checksum verification to protect against vulnerabilities and supply chain attacks.
This codebase is developed using AI agents.
Important
XLKit has yet to be extensively tested in production environments, real-world workflows, or application integration. This library serves as a modernised foundation for AI-assisted development and experimentation with Excel file generation, and image embedding. While comprehensive testing has been performed, production deployment should be approached with appropriate caution and validation. Additionally, this project would not be actively maintained, so please consider this when planning long-term integrations.
- Features
- Requirements
- Installing
- Quick Start
- Documentation
- Credits
- License
- Reporting Bugs
- Contribution
- Effortless API: Fluent, chainable, and bulk data helpers
- Perfect Image Embedding: Pixel-perfect image embedding with automatic aspect ratio preservation
- Professional Video Support: All 17 video and cinema aspect ratios with zero distortion
- Auto Cell Sizing: Automatic column width and row height calculation to perfectly fit images
- Cell Formatting: Comprehensive formatting including font colours, backgrounds, borders, and text alignment (all 5 alignment options each for horizontal and vertical) with proper XML generation
- Border Support: Full border functionality with thin, medium, and thick styles, custom colors, and combined formatting
- Merge Support: Cell merging functionality with complex range support and proper Excel compliance
- CSV/TSV Import/Export: Built-in support for importing and exporting CSV/TSV data (powered by swift-textfile)
- Async & Sync Operations: Save workbooks with one line (async or sync)
- Type-Safe: Strong enums and structs for all data types
- Excel Compliance: OpenXML
.xlsxgeneration; the bundled test runner validates output with CoreXLSX - Minimal library dependencies: ZIPFoundation and swift-textfile (CoreXLSX is only linked by
XLKitTestRunnerfor validation, not by theXLKitlibrary product) - Comprehensive Testing: 59 tests with 100% API coverage, including all text alignment options (horizontal, vertical, combined), number formatting, border and merge functionality, column ordering validation, CSV/TSV edge cases, and automated validation
- Security Features: Comprehensive security features for production use
- macOS: 12.0+
- iOS: 15.0+ (builds and CLI scenarios are exercised in CI; see
.github/workflows/) - Swift: 6.0+
XLKit is available through Swift Package Manager. Add it to your project dependencies:
- In Xcode, go to File → Add Package Dependencies
- Enter the repository URL:
https://github.com/TheAcharya/XLKit.git - Click Add Package
- Select the XLKit product and click Add Package
Add XLKit to your Package.swift dependencies:
dependencies: [
.package(url: "https://github.com/TheAcharya/XLKit.git", from: "1.1.4")
]swift package add https://github.com/TheAcharya/XLKit.gitOnce installed, import XLKit in your Swift files:
import XLKitTest that XLKit is working correctly:
import XLKit
// Create a simple workbook
let workbook = Workbook()
let sheet = workbook.addSheet(name: "Test")
sheet.setCell("A1", value: .string("Hello, XLKit!"))
// Save to verify everything works
let safeURL = CoreUtils.safeFileURL(for: "test.xlsx")
try workbook.save(to: safeURL)
print("XLKit is working correctly!")import XLKit
// 1. Create a workbook and sheet
let workbook = Workbook()
let sheet = workbook.addSheet(name: "Employees")
// 2. Add headers and data (fluent, chainable)
sheet
.setRow(1, strings: ["Name", "Photo", "Age"])
.setRow(2, strings: ["Alice", "", "30"])
.setRow(3, strings: ["Bob", "", "28"])
// 3. Add formatting with font colours
sheet.setCell("A1", string: "Name", format: CellFormat.header())
sheet.setCell("B1", string: "Photo", format: CellFormat.header())
sheet.setCell("C1", string: "Age", format: CellFormat.text(color: "#FF0000"))
// 4. Add a GIF image to a cell with perfect aspect ratio preservation
let gifData = try Data(contentsOf: URL(fileURLWithPath: "alice.gif"))
try await sheet.embedImageAutoSized(gifData, at: "B2", of: workbook)
// 5. Save the workbook (sync or async)
try await workbook.save(to: URL(fileURLWithPath: "employees.xlsx"))
// or
// try workbook.save(to: url)
// iOS Note: For iOS apps, use CoreUtils.safeFileURL() to get a safe file path:
// let safeURL = CoreUtils.safeFileURL(for: "employees.xlsx")
// try await workbook.save(to: safeURL)- Documentation README – How the docs folder is organised
- Manual index – Table of contents and links to all chapters (overview, architecture, core model, CSV/TSV, images, formatting, security, iOS, testing, examples, full API reference)
Created by Vigneswaran Rajkumar
Licensed under the MIT license. See LICENSE for details.
For bug reports, feature requests and suggestions you can create a new issue to discuss.
Community contributions are welcome and appreciated. Developers are encouraged to fork the repository and submit pull requests to enhance functionality or introduce thoughtful improvements. However, a key requirement is that nothing should break—all existing features and behaviours and logic must remain fully functional and unchanged. Once reviewed and approved, updates will be merged into the main branch.