https://github.com/kitschpatrol/unplugin-aphex
Unplugin for module-style image imports from your macOS Photos.app library.
https://github.com/kitschpatrol/unplugin-aphex
aphex apple-photos esbuild farm npm-package photos rolldown rollup rspack transform unplugin vite webpack
Last synced: 6 days ago
JSON representation
Unplugin for module-style image imports from your macOS Photos.app library.
- Host: GitHub
- URL: https://github.com/kitschpatrol/unplugin-aphex
- Owner: kitschpatrol
- License: mit
- Created: 2025-09-18T06:50:00.000Z (9 months ago)
- Default Branch: main
- Last Pushed: 2026-04-22T18:31:02.000Z (about 2 months ago)
- Last Synced: 2026-04-22T20:20:32.655Z (about 2 months ago)
- Topics: aphex, apple-photos, esbuild, farm, npm-package, photos, rolldown, rollup, rspack, transform, unplugin, vite, webpack
- Language: TypeScript
- Homepage:
- Size: 910 KB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: readme.md
- License: license.txt
Awesome Lists containing this project
README
# @kitschpatrol/unplugin-aphex
[](https://npmjs.com/package/@kitschpatrol/unplugin-aphex)
[](https://opensource.org/license/mit/)
[](https://github.com/kitschpatrol/unplugin-aphex/actions/workflows/ci.yml)
**Unplugin for module-style image imports from your macOS Photos.app library.**
> [!WARNING]
>
> **This plugin's underlying [Apple Photos Export (Aphex) library](https://github.com/kitschpatrol/aphex) 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](https://github.com/RhetTbull/osxphotos) instead**.
## Overview
This project wraps the [Aphex](https://github.com/kitschpatrol/aphex) Apple Photos Export library in a unified [unplugin](https://unplugin.unjs.io/) 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:
```ts
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](https://github.com/RhetTbull/osxphotos/discussions/1522).)
This readme only covers the basics of using the build plugin; please see the [Aphex project readme](https://github.com/kitschpatrol/aphex) for more details on the underlying functionality and export options.
## Getting started
### Dependencies
Requires macOS with Photos.app installed and [Node 22.18.0](https://nodejs.org/en/download/) 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](https://brew.sh). See the [Aphex readme](https://github.com/kitschpatrol/aphex) 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
```bash
# 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
Vite
```ts
// Your vite.config.ts
import Aphex from '@kitschpatrol/unplugin-aphex/vite'
import { defineConfig } from 'vite'
export default defineConfig({
plugins: [Aphex()],
})
```
Rollup
```ts
// Your rollup.config.js
import Aphex from '@kitschpatrol/unplugin-aphex/rollup'
export default {
plugins: [Aphex()],
}
```
Rolldown
```ts
// Your rolldown.config.js
import Aphex from '@kitschpatrol/unplugin-aphex/rolldown'
export default {
plugins: [Aphex()],
}
```
esbuild
```ts
import Aphex from '@kitschpatrol/unplugin-aphex/esbuild'
import { build } from 'esbuild'
build({
plugins: [Aphex()],
})
```
webpack
```js
// Your webpack.config.js
import Aphex from '@kitschpatrol/unplugin-aphex/webpack'
export default {
/* ... */
plugins: [Aphex()],
}
```
Rspack
```ts
// Your rspack.config.js
import Aphex from '@kitschpatrol/unplugin-aphex/rspack'
export default {
/* ... */
plugins: [Aphex()],
}
```
Farm
```ts
// Your farm.config.js
import Aphex from '@kitschpatrol/unplugin-aphex/farm'
export default {
plugins: [Aphex()],
}
```
Nuxt
```ts
// 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](https://www.typescriptlang.org/tsconfig#types) in tsconfig.json:
```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):
```ts
///
```
This step should take care of errors like:
```sh
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](https://github.com/un-ts/eslint-plugin-import-x) plugin or similar, you may need to ignore the `~aphex/` module prefix in the [import-x/no-unresolved](https://github.com/un-ts/eslint-plugin-import-x/blob/v4.16.1/docs/rules/no-unresolved.md) rule in your ESLint config:
```json
{
"rules": {
"import-x/no-unresolved": ["error", { "ignore": ["^~aphex/"] }]
}
}
```
#### 5. Install VS Code preview extension (Optional)
If you're using VS Code, an [extension](https://github.com/kitschpatrol/vscode-aphex-preview) is available to provide hover-previews for Aphex file paths:
Install the extension from the [Marketplace](https://marketplace.visualstudio.com/items?itemName=kitschpatrol.aphex-preview), or run the following in VS Code's command palette:
```sh
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](#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:
```ts
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](https://github.com/kitschpatrol)
## Contributing
[Issues](https://github.com/kitschpatrol/unplugin-aphex/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](https://github.com/kitschpatrol/shared-config) (via its `ksc` CLI) for linting and formatting, plus [MDAT](https://github.com/kitschpatrol/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](license.txt) © [Eric Mika](https://ericmika.com)