@kitschpatrol/unplugin-aphex

Unplugin for module-style image imports from your macOS Photos.app library.

[!WARNING]

This plugin's underlying Apple Photos Export (Aphex) library is still under development. The library, and this plugin, should not be considered suitable for general use until a 1.0 release.

This project is open-sourced as a curiosity and for my own convenience, but I suspect it's too niche to be of wide interest or utility. I don't currently plan to spend time adding features for more general use-cases.

It won't work in CI pipelines. It can only target the system's active Photos.app library. It requires an Apple Silicon Mac. It has not been tested against iCloud Photos libraries.

If you are looking for a proper Apple Photos.app mass-export or backup solution, I highly recommend using osxphotos instead.

Overview

This project wraps the Aphex Apple Photos Export library in a unified unplugin for integration with a range of bundlers and build pipelines (Vite, Rollup, etc.).

Aphex treats your Apple Photos.app library as a virtual file system, allowing you to import specific images by their album name / path from your JavaScript / TypeScript code via the ~aphex/ module prefix:

import photo from '~aphex/some-photos-album/img_1922.jpeg'

// In Vite dev mode, photo resolves to something like:
console.log(photo) // '/node_modules/.cache/aphex/img_1922-a1b2c3d4.jpeg'

Running against a cold cache can be extremely slow and can require foreground UI focus, because certain image export strategies have to manipulate the Photos.app GUI directly. (This is for regrettable but valid reasons.)

This readme only covers the basics of using the build plugin; please see the Aphex project readme for more details on the underlying functionality and export options.

Getting started

Dependencies

Requires macOS with Photos.app installed and Node 22.18.0 or newer. Currently, only an arm64 (Apple Silicon) build of the requisite native binary is provided by the bundled Aphex library.

Various image processing features (format conversion, resizing, compression, perceptual diffing, etc.) rely on external binaries installed via Homebrew. See the Aphex readme for which tool powers which feature. The brew line below installs every optional binary the plugin might invoke; install only the ones you need for the formats and operations you actually use.

Installation

1. Install the plugin package

# Optional: image-processing tools. Install only what you need.
brew install libavif mozjpeg imagemagick webp dssim ffmpeg guetzli oxipng

npm i -D @kitschpatrol/unplugin-aphex

2. Add the plugin to your bundler's configuration file

// Your vite.config.ts
import Aphex from '@kitschpatrol/unplugin-aphex/vite'
import { defineConfig } from 'vite'

export default defineConfig({
  plugins: [Aphex()],
})

// Your rollup.config.js
import Aphex from '@kitschpatrol/unplugin-aphex/rollup'

export default {
  plugins: [Aphex()],
}

// Your rolldown.config.js
import Aphex from '@kitschpatrol/unplugin-aphex/rolldown'

export default {
  plugins: [Aphex()],
}

import Aphex from '@kitschpatrol/unplugin-aphex/esbuild'
import { build } from 'esbuild'

build({
  plugins: [Aphex()],
})

// Your webpack.config.js
import Aphex from '@kitschpatrol/unplugin-aphex/webpack'

export default {
  /* ... */
  plugins: [Aphex()],
}

// Your rspack.config.js
import Aphex from '@kitschpatrol/unplugin-aphex/rspack'

export default {
  /* ... */
  plugins: [Aphex()],
}

// Your farm.config.js
import Aphex from '@kitschpatrol/unplugin-aphex/farm'

export default {
  plugins: [Aphex()],
}

// Your nuxt.config.ts
export default defineNuxtConfig({
  aphex: {
    // plugin options here
  },
  modules: ['@kitschpatrol/unplugin-aphex/nuxt'],
})

3. Configure TypeScript

Required for TypeScript projects. Skip this step if you're using plain JavaScript.

Add the extension declarations to your types in tsconfig.json:

{
  "compilerOptions": {
    "types": ["@kitschpatrol/unplugin-aphex/client"]
  }
}

Alternatively, you can add a triple-slash package dependency directive to your global types file (e.g. env.d.ts or similar):

/// <reference types="@kitschpatrol/unplugin-aphex/client" />

This step should take care of errors like:

Cannot find module '~aphex/some-album/some-photo' or its corresponding type declarations.ts(2307)

4. Notify ESLint (Optional)

If you use the eslint-plugin-import-x plugin or similar, you may need to ignore the ~aphex/ module prefix in the import-x/no-unresolved rule in your ESLint config:

{
  "rules": {
    "import-x/no-unresolved": ["error", { "ignore": ["^~aphex/"] }]
  }
}

5. Install VS Code preview extension (Optional)

If you're using VS Code, an extension is available to provide hover-previews for Aphex file paths:

Install the extension from the Marketplace, or run the following in VS Code's command palette:

ext install kitschpatrol.aphex-preview

Usage

Any module imports prefixed with ~aphex/ will be exported from Photos.app, processed, and cached to a project-local directory. By default, the import resolves to a string path to the exported image.

Options

| Option | Type | Default | Description | | ---------------------- | ----------------------------------------- | ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | cacheDirectory | string | './node_modules/.cache/aphex' | Where exported images are stored. | | cacheMode | 'enabled' \| 'aggressive' \| 'disabled' | 'enabled' | 'enabled' re-validates against Photos.app on each request, 'aggressive' reuses the first cached image without re-checking (fastest, may go stale — good for dev), 'disabled' forces a re-export every time. | | exportOptions | Aphex ExportOptions (partial) | sensible defaults | Forwarded to the underlying Aphex export pipeline. | | processOptions | Aphex ProcessOptions (partial) | sensible defaults | Resizing, color profile enforcement, etc. Forwarded to Aphex. | | interactiveSession | boolean | false | Experimental: keep a single aphex-swift session alive across requests for higher throughput. | | maxConcurrentExports | number | 4 | Cap on parallel exports. Lower this if Photos.app or your system feels overloaded. | | pruneCacheOnBuild | boolean | false | Delete files in cacheDirectory that weren't referenced by a production build. Skipped in dev (dev only sees imports for routes the user actually visits, so pruning would delete entries for unvisited pages). | | returnMetadata | boolean | false | Return a metadata object instead of a path string. See Metadata mode below. | | validateMetadata | boolean | false | Require certain (currently non-configurable) metadata fields to be present in the source files. | | verbose | boolean | false | Log per-export timing and cache decisions. |

Metadata mode

When returnMetadata is true, imports resolve to an object instead of a path:

import photo from '~aphex/some-photos-album/img_1922.jpeg'

console.log(photo)
// {
//   format: 'jpeg',           // ImageMimeType from @kitschpatrol/aphex
//   height: 1080,
//   src: 'img_1922-a1b2c3d4.jpeg',
//   width: 1620,
// }

This is useful for templating, srcset generation, or piping image dimensions into a layout system. The TypeScript ambient module declaration (@kitschpatrol/unplugin-aphex/client) types ~aphex/* imports as string | AphexImageResultMetadata, so consumers must narrow the union at the call site.

Cache directory contents

Alongside the exported images, a .aphex-plugin-cache.json file is written into cacheDirectory. It tracks which identifiers have been resolved to which files so subsequent runs can skip re-exporting unchanged assets. It's safe to delete (the plugin will rebuild it on the next run) and should not be checked into version control — keep cacheDirectory ignored in .gitignore.

Maintainers

kitschpatrol

Contributing

Issues are welcome and appreciated.

Please open an issue to discuss changes before submitting a pull request. Unsolicited PRs (especially AI-generated ones) are unlikely to be merged.

This repository uses @kitschpatrol/shared-config (via its ksc CLI) for linting and formatting, plus MDAT for readme placeholder expansion.

Disclaimer

This is an unofficial library and is not affiliated with or blessed by Apple Inc.

The underlying library's core export commands maintain a "read-only" relationship with your library.

None of the code paths should modify the contents of your Photos.app library. But regardless, strange things can happen — please back up your Photos.app library before using this tool.

This tool has not been tested with iCloud-based Photos libraries.

License

MIT © Eric Mika