https://github.com/theacharya/xlkit
A modern Swift library for creating Excel (.xlsx) files on macOS with image embedding
https://github.com/theacharya/xlkit
excel excel-export images ios ios-swift macos macos-swift spredsheet swift vibe-coding vibecoding xlsx xlsxwriter
Last synced: about 1 month ago
JSON representation
A modern Swift library for creating Excel (.xlsx) files on macOS with image embedding
- Host: GitHub
- URL: https://github.com/theacharya/xlkit
- Owner: TheAcharya
- License: mit
- Created: 2025-07-06T01:04:48.000Z (9 months ago)
- Default Branch: main
- Last Pushed: 2025-09-25T01:56:50.000Z (6 months ago)
- Last Synced: 2025-10-03T11:50:08.298Z (6 months ago)
- Topics: excel, excel-export, images, ios, ios-swift, macos, macos-swift, spredsheet, swift, vibe-coding, vibecoding, xlsx, xlsxwriter
- Language: Swift
- Homepage: https://tech.theacharya.co
- Size: 3.48 MB
- Stars: 62
- Watchers: 2
- Forks: 2
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Security: SECURITY.md
Awesome Lists containing this project
README
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](https://github.com/TheAcharya/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.
## Table of Contents
- [Features](#features)
- [Recent Improvements](#recent-improvements)
- [Requirements](#requirements)
- [Installing](#installing)
- [Quick Start](#quick-start)
- [Documentation](#documentation)
- [Credits](#credits)
- [License](#license)
- [Reporting Bugs](#reporting-bugs)
- [Contribution](#contribution)
## Features
- 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
- Async & Sync Operations: Save workbooks with one line (async or sync)
- Type-Safe: Strong enums and structs for all data types
- Excel Compliance: Full OpenXML compliance with CoreXLSX validation
- No Dependencies: Pure Swift, macOS 12+, Swift 6.0+
- Comprehensive Testing: 55 tests with 100% API coverage, including all text alignment options (horizontal, vertical, combined), number formatting, border and merge functionality, column ordering validation, and automated validation
- Security Features: Comprehensive security features for production use
## Recent Improvements
### Column Ordering Fix (2025-10-18)
Fixed critical column ordering bug for sheets with more than 26 columns (A-Z, AA, AB, etc.). The issue was resolved by implementing proper numeric column sorting in XLSXEngine.generateWorksheetXML() to ensure Excel-compliant column order. This fix ensures proper Excel column order: A, B, ..., Z, AA, AB, ..., BA, BB, ... in all generated files, maintaining full backward compatibility with existing APIs and storage model. All generated Excel files now open correctly in Excel without repair warnings.
## Requirements
- macOS: 12.0+
- iOS: 15.0+ (available but not tested)
- Swift: 6.0+
## Installing
### Swift Package Manager
XLKit is available through Swift Package Manager. Add it to your project dependencies:
#### Xcode
1. In Xcode, go to **File** → **Add Package Dependencies**
2. Enter the repository URL: `https://github.com/TheAcharya/XLKit.git`
3. Click **Add Package**
4. Select the XLKit product and click **Add Package**
#### Package.swift
Add XLKit to your `Package.swift` dependencies:
```swift
dependencies: [
.package(url: "https://github.com/TheAcharya/XLKit.git", from: "1.0.12")
]
```
#### Command Line
```bash
swift package add https://github.com/TheAcharya/XLKit.git
```
### Import
Once installed, import XLKit in your Swift files:
```swift
import XLKit
```
### Verify Installation
Test that XLKit is working correctly:
```swift
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!")
```
## Quick Start
```swift
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
Full manual and reference documentation has been moved to the **Documentation** folder:
- **[Documentation/README.md](Documentation/README.md)** – Overview of documentation contents
- **[Documentation/Manual.md](Documentation/Manual.md)** – Complete user manual, including:
- Security features (SecurityManager, rate limiting, logging, quarantine, checksums)
- Performance considerations and file format support
- iOS support and file system considerations
- Core concepts (Workbook, Sheet, cells, coordinates)
- Basic and advanced usage with code examples
- CSV/TSV import and export
- Image support and aspect ratio preservation
- Number formats, text alignment, and cell formatting
- Error handling
- Testing, validation, and code style
## Credits
Created by [Vigneswaran Rajkumar](https://bsky.app/profile/vigneswaranrajkumar.com)
## License
Licensed under the MIT license. See [LICENSE](https://github.com/TheAcharya/XLKit/blob/main/LICENSE) for details.
## Reporting Bugs
For bug reports, feature requests and suggestions you can create a new [issue](https://github.com/TheAcharya/XLKit/issues) to discuss.
## Contribution
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.
