{"id":29536818,"url":"https://github.com/theacharya/xlkit","last_synced_at":"2026-02-12T06:20:26.420Z","repository":{"id":303671024,"uuid":"1014562988","full_name":"TheAcharya/XLKit","owner":"TheAcharya","description":"A modern Swift library for creating Excel (.xlsx) files on macOS with image embedding","archived":false,"fork":false,"pushed_at":"2025-09-25T01:56:50.000Z","size":3649,"stargazers_count":62,"open_issues_count":0,"forks_count":2,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-10-03T11:50:08.298Z","etag":null,"topics":["excel","excel-export","images","ios","ios-swift","macos","macos-swift","spredsheet","swift","vibe-coding","vibecoding","xlsx","xlsxwriter"],"latest_commit_sha":null,"homepage":"https://tech.theacharya.co","language":"Swift","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/TheAcharya.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":["TheAcharya"]}},"created_at":"2025-07-06T01:04:48.000Z","updated_at":"2025-09-25T01:55:00.000Z","dependencies_parsed_at":"2025-09-17T02:38:14.588Z","dependency_job_id":null,"html_url":"https://github.com/TheAcharya/XLKit","commit_stats":null,"previous_names":["theacharya/xlkit"],"tags_count":10,"template":false,"template_full_name":null,"purl":"pkg:github/TheAcharya/XLKit","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TheAcharya%2FXLKit","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TheAcharya%2FXLKit/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TheAcharya%2FXLKit/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TheAcharya%2FXLKit/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/TheAcharya","download_url":"https://codeload.github.com/TheAcharya/XLKit/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TheAcharya%2FXLKit/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279010803,"owners_count":26084807,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-12T02:00:06.719Z","response_time":53,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["excel","excel-export","images","ios","ios-swift","macos","macos-swift","spredsheet","swift","vibe-coding","vibecoding","xlsx","xlsxwriter"],"created_at":"2025-07-17T03:09:45.820Z","updated_at":"2026-02-12T06:20:26.413Z","avatar_url":"https://github.com/TheAcharya.png","language":"Swift","funding_links":["https://github.com/sponsors/TheAcharya"],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/TheAcharya/XLKit\"\u003e\u003cimg src=\"Assets/XLKit_Icon.png\" height=\"200\"\u003e\n  \u003ch1 align=\"center\"\u003eXLKit\u003c/h1\u003e\n\u003c/p\u003e\n\n\n\u003cp align=\"center\"\u003e\u003ca href=\"https://github.com/TheAcharya/XLKit/blob/main/LICENSE\"\u003e\u003cimg src=\"http://img.shields.io/badge/license-MIT-lightgrey.svg?style=flat\" alt=\"license\"/\u003e\u003c/a\u003e\u0026nbsp;\u003ca href=\"https://github.com/TheAcharya/XLKit\"\u003e\u003cimg src=\"https://img.shields.io/badge/platform-macOS%20%7C%20iOS-lightgrey.svg?style=flat\" alt=\"platform\"/\u003e\u003c/a\u003e\u0026nbsp;\u003ca href=\"https://github.com/TheAcharya/XLKit/actions/workflows/build.yml\"\u003e\u003cimg src=\"https://github.com/TheAcharya/XLKit/actions/workflows/build.yml/badge.svg\" alt=\"build\"/\u003e\u003c/a\u003e\u0026nbsp;\u003ca href=\"https://github.com/TheAcharya/XLKit/actions/workflows/codeql.yml\"\u003e\u003cimg src=\"https://github.com/TheAcharya/XLKit/actions/workflows/codeql.yml/badge.svg\" alt=\"codeql\"/\u003e\u003c/a\u003e\u003c/p\u003e\n\nA 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.\n\nPurpose-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.\n\nIncludes 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.\n\nThis codebase is developed using AI agents.\n\n\u003e [!IMPORTANT]\n\u003e 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.\n\n## Table of Contents\n\n- [Features](#features)\n- [Recent Improvements](#recent-improvements)\n- [Requirements](#requirements)\n- [Installing](#installing)\n- [Quick Start](#quick-start)\n- [Documentation](#documentation)\n- [Credits](#credits)\n- [License](#license)\n- [Reporting Bugs](#reporting-bugs)\n- [Contribution](#contribution)\n\n## Features\n\n- Effortless API: Fluent, chainable, and bulk data helpers\n- Perfect Image Embedding: Pixel-perfect image embedding with automatic aspect ratio preservation\n- Professional Video Support: All 17 video and cinema aspect ratios with zero distortion\n- Auto Cell Sizing: Automatic column width and row height calculation to perfectly fit images\n- 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\n- Border Support: Full border functionality with thin, medium, and thick styles, custom colors, and combined formatting\n- Merge Support: Cell merging functionality with complex range support and proper Excel compliance\n- CSV/TSV Import/Export: Built-in support for importing and exporting CSV/TSV data\n- Async \u0026 Sync Operations: Save workbooks with one line (async or sync)\n- Type-Safe: Strong enums and structs for all data types\n- Excel Compliance: Full OpenXML compliance with CoreXLSX validation\n- No Dependencies: Pure Swift, macOS 12+, Swift 6.0+\n- 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\n- Security Features: Comprehensive security features for production use\n\n## Recent Improvements\n\n### Column Ordering Fix (2025-10-18)\n\nFixed 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.\n\n## Requirements\n\n- macOS: 12.0+\n- iOS: 15.0+ (available but not tested)\n- Swift: 6.0+\n\n## Installing\n\n### Swift Package Manager\n\nXLKit is available through Swift Package Manager. Add it to your project dependencies:\n\n#### Xcode\n1. In Xcode, go to **File** → **Add Package Dependencies**\n2. Enter the repository URL: `https://github.com/TheAcharya/XLKit.git`\n3. Click **Add Package**\n4. Select the XLKit product and click **Add Package**\n\n#### Package.swift\nAdd XLKit to your `Package.swift` dependencies:\n\n```swift\ndependencies: [\n    .package(url: \"https://github.com/TheAcharya/XLKit.git\", from: \"1.0.12\")\n]\n```\n\n#### Command Line\n```bash\nswift package add https://github.com/TheAcharya/XLKit.git\n```\n\n### Import\n\nOnce installed, import XLKit in your Swift files:\n\n```swift\nimport XLKit\n```\n\n### Verify Installation\n\nTest that XLKit is working correctly:\n\n```swift\nimport XLKit\n\n// Create a simple workbook\nlet workbook = Workbook()\nlet sheet = workbook.addSheet(name: \"Test\")\nsheet.setCell(\"A1\", value: .string(\"Hello, XLKit!\"))\n\n// Save to verify everything works\nlet safeURL = CoreUtils.safeFileURL(for: \"test.xlsx\")\ntry workbook.save(to: safeURL)\nprint(\"XLKit is working correctly!\")\n```\n\n## Quick Start\n\n```swift\nimport XLKit\n\n// 1. Create a workbook and sheet\nlet workbook = Workbook()\nlet sheet = workbook.addSheet(name: \"Employees\")\n\n// 2. Add headers and data (fluent, chainable)\nsheet\n    .setRow(1, strings: [\"Name\", \"Photo\", \"Age\"])\n    .setRow(2, strings: [\"Alice\", \"\", \"30\"])\n    .setRow(3, strings: [\"Bob\", \"\", \"28\"])\n\n// 3. Add formatting with font colours\nsheet.setCell(\"A1\", string: \"Name\", format: CellFormat.header())\nsheet.setCell(\"B1\", string: \"Photo\", format: CellFormat.header())\nsheet.setCell(\"C1\", string: \"Age\", format: CellFormat.text(color: \"#FF0000\"))\n\n// 4. Add a GIF image to a cell with perfect aspect ratio preservation\nlet gifData = try Data(contentsOf: URL(fileURLWithPath: \"alice.gif\"))\ntry await sheet.embedImageAutoSized(gifData, at: \"B2\", of: workbook)\n\n// 5. Save the workbook (sync or async)\ntry await workbook.save(to: URL(fileURLWithPath: \"employees.xlsx\"))\n// or\n// try workbook.save(to: url)\n\n// iOS Note: For iOS apps, use CoreUtils.safeFileURL() to get a safe file path:\n// let safeURL = CoreUtils.safeFileURL(for: \"employees.xlsx\")\n// try await workbook.save(to: safeURL)\n```\n\n## Documentation\n\nFull manual and reference documentation has been moved to the **Documentation** folder:\n\n- **[Documentation/README.md](Documentation/README.md)** – Overview of documentation contents\n- **[Documentation/Manual.md](Documentation/Manual.md)** – Complete user manual, including:\n  - Security features (SecurityManager, rate limiting, logging, quarantine, checksums)\n  - Performance considerations and file format support\n  - iOS support and file system considerations\n  - Core concepts (Workbook, Sheet, cells, coordinates)\n  - Basic and advanced usage with code examples\n  - CSV/TSV import and export\n  - Image support and aspect ratio preservation\n  - Number formats, text alignment, and cell formatting\n  - Error handling\n  - Testing, validation, and code style\n\n## Credits\n\nCreated by [Vigneswaran Rajkumar](https://bsky.app/profile/vigneswaranrajkumar.com)\n\n## License\n\nLicensed under the MIT license. See [LICENSE](https://github.com/TheAcharya/XLKit/blob/main/LICENSE) for details.\n\n## Reporting Bugs\n\nFor bug reports, feature requests and suggestions you can create a new [issue](https://github.com/TheAcharya/XLKit/issues) to discuss.\n\n## Contribution\n\nCommunity 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.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftheacharya%2Fxlkit","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftheacharya%2Fxlkit","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftheacharya%2Fxlkit/lists"}