xcassets

xcassets is a Rust library for parsing Xcode asset catalogs.

It reads a single .xcassets directory into a typed tree, keeps unsupported folder types visible as opaque nodes, and reports non-fatal problems as diagnostics instead of stopping at the first issue.

Repository: https://github.com/WendellXY/xcassets

What It Supports Today

The current parser has first-class support for:

• catalog roots
• groups
• image sets
• named color sets
• app icon sets

Other typed asset folders are preserved as Node::Opaque so callers can still inspect the catalog tree without losing information.

Installation

Add the crate to your project:

cargo add xcassets

Enable the optional parallel parser when you want multi-threaded subtree walks:

cargo add xcassets --features parallel

Example

use xcassets::{parse_catalog, Node, Severity};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let report = parse_catalog("Assets.xcassets")?;

    for diagnostic in &report.diagnostics {
        if diagnostic.severity == Severity::Error {
            eprintln!(
                "{}: {}",
                diagnostic.path.display(),
                diagnostic.message
            );
        }
    }

    for child in &report.catalog.children {
        match child {
            Node::ImageSet(image_set) => {
                println!("image set: {}", image_set.name);
            }
            Node::ColorSet(color_set) => {
                println!("color set: {}", color_set.name);
            }
            Node::AppIconSet(app_icon_set) => {
                println!("app icon set: {}", app_icon_set.name);
            }
            Node::Group(group) => {
                println!("group: {}", group.name);
            }
            Node::Opaque(node) => {
                println!("unsupported folder type .{}", node.folder_type);
            }
        }
    }

    Ok(())
}

API Overview

The main entry point is:

pub fn parse_catalog(
    path: impl AsRef<std::path::Path>,
) -> Result<xcassets::ParseReport, xcassets::ParseError>

With the parallel feature enabled, you can also opt into sibling-directory parsing across the Rayon thread pool:

#[cfg(feature = "parallel")]
pub fn parse_catalog_parallel(
    path: impl AsRef<std::path::Path>,
) -> Result<xcassets::ParseReport, xcassets::ParseError>

ParseReport contains:

• catalog: the parsed AssetCatalog
• diagnostics: non-fatal issues found while parsing

The parallel entry point preserves the same child ordering and diagnostic ordering as the sequential parser so callers can compare results directly.

For callers that only need runtime lookup names such as icon, Colors/brand, or Game/coin, there is also a lightweight indexer:

pub fn index_asset_references(
    path: impl AsRef<std::path::Path>,
) -> Result<xcassets::AssetReferenceIndex, xcassets::ParseError>

This API reads the catalog tree and only consults folder Contents.json files when needed to resolve namespace-providing groups or sprite atlases. It does not parse leaf image-set or color-set rendition configs.

The returned reference order is not guaranteed. Callers that need a stable order should sort the references themselves.

ParseError is reserved for failures that prevent producing a report at all, such as passing a non-directory path or a path that is not a .xcassets catalog root.

Diagnostics

The parser currently emits diagnostics for cases like:

• missing required Contents.json
• invalid Contents.json
• missing referenced asset files
• unreadable files or directories
• unsupported typed asset folders

This makes the crate useful for tooling, validation, and migration workflows where partial results are still valuable.

Format Notes

The parser is intentionally lenient:

• root catalogs and groups may omit Contents.json
• supported nodes preserve unknown JSON fields in extras
• image renditions without filename are allowed
• filenames with spaces or non-ASCII characters are supported

This matches real-world Xcode projects more closely than a strict schema-only approach.

Development

Run the test suite with:

cargo test

You can also run the ignored smoke test against a real iOS project:

XCASSETS_REAL_PROJECT=/path/to/ios/project \
XCASSETS_REAL_PROJECT_LIMIT=25 \
  cargo test --test parser parses_real_project_catalogs_when_requested -- --ignored --nocapture

This test walks the project tree, finds .xcassets catalogs, and verifies a bounded set of them can be parsed without fatal failures. It defaults to 10 catalogs so it stays fast enough for normal development, and you can raise the limit when you want a broader smoke pass.

License

MIT