Installation

Your first file.

Cabinet requires Swift 6.3. Apple deployment targets start at iOS 18, macOS 15, tvOS 18, watchOS 11, and visionOS 2.

Add the package

Add this dependency to your Swift package, or enter the repository URL in Xcode’s package dependency dialog. Until the first tagged release, select the main branch; pin a commit for reproducible builds.

.package(url: "https://github.com/modern-swift-dev/cabinet-swift.git", branch: "main")

Add the core library product to your target:

.product(name: "Cabinet", package: "cabinet-swift")

For archives, also add .product(name: "CabinetZip", package: "cabinet-swift") and import CabinetZip where it is used.

Create a directory and save JSON

import Cabinet
import Foundation

struct Preferences: Codable {
    var showsHiddenFiles: Bool
}

let directory = try Cabinet.Directory.applicationSupport
    .subdirectory(named: "MyApplication")
try directory.create()

let file = try directory.file(named: "preferences.json")
try file.writeJSON(Preferences(showsHiddenFiles: false), policy: .replace)

let preferences = try file.readJSON(Preferences.self)

Creating a typed child location does not create the item on disk. Create the directory before writing its files. Choose .replace here because saving preferences updates the previous contents; omit it when an existing destination should cause an error.

Work with existing URLs

let file = try Cabinet.File(URL(fileURLWithPath: "/path/to/preferences.json"))
let preferences = try file.readJSON(Preferences.self)

Use a file URL for each typed location. I/O failures and decoding failures propagate to the caller. All operations are synchronous.

Choose the next guide

Read about overwrite behavior and migration, or explore the Cabinet API and CabinetZip API.