🖼️ capacitor-widget-image-store

A lightweight Capacitor plugin to save, delete, and list base64-encoded images in a shared app container — perfect for widget integrations on iOS and Android.

Supports:

✅ iOS (App Group container)
✅ Android (internal file storage)
✅ Resize on save (optional)
✅ Cleanup helpers like deleteExcept and exists

🚀 Install

npm install capacitor-widget-image-store
npx cap sync

📱 Platform Behavior

iOS

• Uses FileManager.default.containerURL(forSecurityApplicationGroupIdentifier:)
• Only image files (.jpg, .jpeg, .png, .webp) are listed or deleted
• Non-image metadata is automatically filtered from list()
• appGroup is required

Android

• Uses internal app files directory via getContext().getFilesDir()
• Ignores appGroup
• Same image file filtering applies

💡 Why this plugin?

Native widgets require local image file paths, not base64 strings. This plugin bridges the gap by storing base64-encoded images as accessible files — great for:

• iOS Widgets (via App Group)
• Android Widgets
• Local image caching for offline use
• Shared asset cleanup via deleteExcept

📘 API

• save(...)
• delete(...)
• deleteExcept(...)
• list(...)
• exists(...)
• getPath(...)
• Interfaces

Capacitor plugin interface for saving, deleting and listing images.

save(...)

save(options: WidgetImageStoreSaveOptions) => Promise<{ path: string; }>

Saves a base64 image to storage.

| Param | Type | | ------------- | ----------------------------------------------------------------------------------- | | options | WidgetImageStoreSaveOptions |

Returns: Promise<{ path: string; }>

delete(...)

delete(options: WidgetImageStoreFileOptions) => Promise<void>

Deletes a previously saved image.

| Param | Type | | ------------- | ----------------------------------------------------------------------------------- | | options | WidgetImageStoreFileOptions |

deleteExcept(...)

deleteExcept(options: WidgetImageStoreDeleteExceptOptions) => Promise<void>

Deletes all images from storage except for the ones explicitly listed in keep.

This is useful for cleaning up unused images after refreshing or regenerating widget data.

| Param | Type | | ------------- | --------------------------------------------------------------------------------------------------- | | options | WidgetImageStoreDeleteExceptOptions |

list(...)

list(options: WidgetImageStoreListOptions) => Promise<{ files: string[]; }>

Lists all saved image filenames.

| Param | Type | | ------------- | ----------------------------------------------------------------------------------- | | options | WidgetImageStoreListOptions |

Returns: Promise<{ files: string[]; }>

exists(...)

exists(options: WidgetImageStoreFileOptions) => Promise<{ exists: boolean; }>

Checks if the given image exists.

| Param | Type | | ------------- | ----------------------------------------------------------------------------------- | | options | WidgetImageStoreFileOptions |

Returns: Promise<{ exists: boolean; }>

getPath(...)

getPath(options: WidgetImageStoreFileOptions) => Promise<{ path: string; }>

Returns the full path to the image file.

| Param | Type | | ------------- | ----------------------------------------------------------------------------------- | | options | WidgetImageStoreFileOptions |

Returns: Promise<{ path: string; }>

Interfaces

WidgetImageStoreSaveOptions

Options for saving an image to storage.

| Prop | Type | Description | | -------------- | -------------------- | -------------------------------------------------------------- | | base64 | string | Base64 encoded image string, optionally with data URL prefix | | filename | string | Filename to store the image under (e.g. example.jpg) | | appGroup | string | App Group ID (iOS), ignored on Android | | resize | boolean | Whether to resize image to max 1024px before saving (optional) |

WidgetImageStoreFileOptions

Options for deleting an image.

| Prop | Type | Description | | -------------- | ------------------- | -------------------------------------- | | filename | string | Filename of the image to delete | | appGroup | string | App Group ID (iOS), ignored on Android |

WidgetImageStoreDeleteExceptOptions

Options for deleting all images except specific ones.

| Prop | Type | Description | | -------------- | --------------------- | ------------------------------------------------------------ | | keep | string[] | List of filenames to keep. All other images will be deleted. | | appGroup | string | App Group ID (iOS), ignored on Android. |

WidgetImageStoreListOptions

Options for listing all saved images.

| Prop | Type | Description | | -------------- | ------------------- | -------------------------------------- | | appGroup | string | App Group ID (iOS), ignored on Android |