English | 日本語

swift-cached-remote-image

A SwiftUI package for displaying remote images with memory and disk caching.

📚 Full Documentation

Overview

swift-cached-remote-image is a package for efficiently loading remote images in SwiftUI with two-layer memory and disk caching. It provides async image loading, retry policies, and fully customizable placeholders.

Features

• ✅ Native SwiftUI API — Seamlessly integrated with SwiftUI
• ✅ Memory & Disk Cache — Automatic two-layer caching for fast display
• ✅ Async Image Loading — Modern concurrency with async/await
• ✅ Flexible ImageSource — Load from URL, URL string, or image ID
• ✅ Image ID Support — Fetch images through ImageService from a resource endpoint
• ✅ Customizable Retry Policy — Fixed count or exponential backoff
• ✅ Customizable Placeholder & Error Views — Fully replaceable UI
• ✅ Cache Management — Separate control of resource and data caches
• ✅ iOS 17.0+ and macOS 14.0+ — Cross-platform support

Requirements

• iOS 17.0+
• macOS 14.0+
• Swift 6.0+

Dependencies

• swift-api-client — HTTP client

Prerequisites

When using .imageId, a REST API that returns responses in the format below is required.

Required API Endpoints

1. GET /images/{imageId} — Fetch image resource
2. POST /images — Upload image (Base64-encoded JSON)
3. DELETE /images/{imageId} — Delete image

Required Response Format (JSON)

{
  "id": "img_123",
  "url": "https://example.com/images/photo.jpg"
}

When using .url or .urlString directly, no API server is required.

Installation

Swift Package Manager

Add the following to your Package.swift:

dependencies: [
    .package(url: "https://github.com/no-problem-dev/swift-cached-remote-image.git", from: "1.1.5")
]

Or in Xcode:

1. File > Add Package Dependencies
2. Enter the package URL: https://github.com/no-problem-dev/swift-cached-remote-image.git
3. Select version: 1.1.5 or later

Quick Start

The simplest usage:

import SwiftUI
import CachedRemoteImage

CachedRemoteImage(
    source: .url(URL(string: "https://example.com/image.jpg")!)
)

This handles image loading, caching, and default loading indicator automatically.

Usage

Basic Example

import SwiftUI
import CachedRemoteImage

struct ContentView: View {
    var body: some View {
        CachedRemoteImage(
            source: .url(URL(string: "https://example.com/image.jpg")!)
        ) { image in
            image
                .resizable()
                .aspectRatio(contentMode: .fit)
        } placeholder: {
            ProgressView()
        }
    }
}

Load from URL String

CachedRemoteImage(
    source: .urlString("https://example.com/image.jpg")
) { image in
    image.resizable()
}

ImageSource Options

// 1. From a URL object
let url = URL(string: "https://example.com/image.jpg")!
CachedRemoteImage(source: .url(url))

// 2. From a URL string (automatically converted)
CachedRemoteImage(source: .urlString("https://example.com/image.jpg"))

// 3. From an image ID (fetches resource via ImageService)
CachedRemoteImage(source: .imageId("img_12345"))

Note: .imageId requires ImageService to be injected into the environment.

Using ImageService with Image ID

import APIClient
import CachedRemoteImage

@main
struct MyApp: App {
    let imageService: ImageService

    init() {
        let apiClient = APIClientImpl(baseURL: URL(string: "https://api.example.com")!)
        imageService = ImageServiceImpl(
            apiClient: apiClient,
            imagesPath: "/images",
            maxResourceCacheSize: 100
        )
    }

    var body: some Scene {
        WindowGroup {
            ContentView()
                .imageService(imageService)
        }
    }
}

struct ImageView: View {
    let imageId: String

    var body: some View {
        CachedRemoteImage(
            source: .imageId(imageId)
        ) { image in
            image
                .resizable()
                .aspectRatio(contentMode: .fit)
        }
    }
}

Cache Configuration

Resource Cache Size

let imageService = ImageServiceImpl(
    apiClient: apiClient,
    imagesPath: "/images",
    maxResourceCacheSize: 200  // up to 200 resource entries
)

Clearing Cache

// Clear resource cache
await imageService.clearResourceCache()

// Clear image data cache
await imageService.clearImageCache()

// Get disk cache size
let cacheSize = await imageService.diskCacheSize()
print("Current cache size: \(cacheSize) bytes")

Per-Image Configuration

CachedRemoteImage(
    source: .url(imageURL),
    configuration: CachedRemoteImageConfiguration(
        cachePolicy: .metadataOnly,
        retryPolicy: .exponentialBackoff(maxRetries: 3)
    )
) { image in
    image.resizable()
}

Available options:

• cachePolicy: .all (default), .metadataOnly, .imageOnly, .none
• retryPolicy: .none (default), .fixed(count:), .exponentialBackoff(maxRetries:, baseDelay:)

License

This project is released under the MIT License. See the LICENSE file for details.

Support

For bug reports or feature requests, please open an issue on GitHub.