{"id":50510093,"url":"https://github.com/kitschpatrol/unplugin-aphex","last_synced_at":"2026-06-02T19:30:53.821Z","repository":{"id":353174682,"uuid":"1059220911","full_name":"kitschpatrol/unplugin-aphex","owner":"kitschpatrol","description":"Unplugin for module-style image imports from your macOS Photos.app library.","archived":false,"fork":false,"pushed_at":"2026-04-22T18:31:02.000Z","size":932,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-22T20:20:32.655Z","etag":null,"topics":["aphex","apple-photos","esbuild","farm","npm-package","photos","rolldown","rollup","rspack","transform","unplugin","vite","webpack"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kitschpatrol.png","metadata":{"files":{"readme":"readme.md","changelog":null,"contributing":null,"funding":null,"license":"license.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-18T06:50:00.000Z","updated_at":"2026-04-22T18:31:05.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/kitschpatrol/unplugin-aphex","commit_stats":null,"previous_names":["kitschpatrol/unplugin-aphex"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/kitschpatrol/unplugin-aphex","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kitschpatrol%2Funplugin-aphex","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kitschpatrol%2Funplugin-aphex/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kitschpatrol%2Funplugin-aphex/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kitschpatrol%2Funplugin-aphex/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kitschpatrol","download_url":"https://codeload.github.com/kitschpatrol/unplugin-aphex/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kitschpatrol%2Funplugin-aphex/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33834010,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-02T02:00:07.132Z","response_time":109,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["aphex","apple-photos","esbuild","farm","npm-package","photos","rolldown","rollup","rspack","transform","unplugin","vite","webpack"],"created_at":"2026-06-02T19:30:53.257Z","updated_at":"2026-06-02T19:30:53.808Z","avatar_url":"https://github.com/kitschpatrol.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003c!-- title --\u003e\n\n# @kitschpatrol/unplugin-aphex\n\n\u003c!-- /title --\u003e\n\n\u003c!-- badges --\u003e\n\n[![NPM Package @kitschpatrol/unplugin-aphex](https://img.shields.io/npm/v/@kitschpatrol/unplugin-aphex.svg)](https://npmjs.com/package/@kitschpatrol/unplugin-aphex)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/license/mit/)\n[![CI](https://github.com/kitschpatrol/unplugin-aphex/actions/workflows/ci.yml/badge.svg)](https://github.com/kitschpatrol/unplugin-aphex/actions/workflows/ci.yml)\n\n\u003c!-- /badges --\u003e\n\n\u003c!-- short-description --\u003e\n\n**Unplugin for module-style image imports from your macOS Photos.app library.**\n\n\u003c!-- /short-description --\u003e\n\n\u003e [!WARNING]\n\u003e\n\u003e **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.**\n\u003e\n\u003e 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.\n\u003e\n\u003e 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.\n\u003e\n\u003e 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**.\n\n## Overview\n\nThis 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.).\n\nAphex 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:\n\n```ts\nimport photo from '~aphex/some-photos-album/img_1922.jpeg'\n\n// In Vite dev mode, photo resolves to something like:\nconsole.log(photo) // '/node_modules/.cache/aphex/img_1922-a1b2c3d4.jpeg'\n```\n\nRunning 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).)\n\nThis 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.\n\n## Getting started\n\n### Dependencies\n\nRequires 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.\n\nVarious 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.\n\n### Installation\n\n#### 1. Install the plugin package\n\n```bash\n# Optional: image-processing tools. Install only what you need.\nbrew install libavif mozjpeg imagemagick webp dssim ffmpeg guetzli oxipng\n\nnpm i -D @kitschpatrol/unplugin-aphex\n```\n\n#### 2. Add the plugin to your bundler's configuration file\n\n\u003cdetails open\u003e\n\u003csummary\u003eVite\u003c/summary\u003e\u003cbr\u003e\n\n```ts\n// Your vite.config.ts\nimport Aphex from '@kitschpatrol/unplugin-aphex/vite'\nimport { defineConfig } from 'vite'\n\nexport default defineConfig({\n  plugins: [Aphex()],\n})\n```\n\n\u003cbr\u003e\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eRollup\u003c/summary\u003e\u003cbr\u003e\n\n```ts\n// Your rollup.config.js\nimport Aphex from '@kitschpatrol/unplugin-aphex/rollup'\n\nexport default {\n  plugins: [Aphex()],\n}\n```\n\n\u003cbr\u003e\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eRolldown\u003c/summary\u003e\u003cbr\u003e\n\n```ts\n// Your rolldown.config.js\nimport Aphex from '@kitschpatrol/unplugin-aphex/rolldown'\n\nexport default {\n  plugins: [Aphex()],\n}\n```\n\n\u003cbr\u003e\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eesbuild\u003c/summary\u003e\u003cbr\u003e\n\n```ts\nimport Aphex from '@kitschpatrol/unplugin-aphex/esbuild'\nimport { build } from 'esbuild'\n\nbuild({\n  plugins: [Aphex()],\n})\n```\n\n\u003cbr\u003e\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003ewebpack\u003c/summary\u003e\u003cbr\u003e\n\n```js\n// Your webpack.config.js\nimport Aphex from '@kitschpatrol/unplugin-aphex/webpack'\n\nexport default {\n  /* ... */\n  plugins: [Aphex()],\n}\n```\n\n\u003cbr\u003e\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eRspack\u003c/summary\u003e\u003cbr\u003e\n\n```ts\n// Your rspack.config.js\nimport Aphex from '@kitschpatrol/unplugin-aphex/rspack'\n\nexport default {\n  /* ... */\n  plugins: [Aphex()],\n}\n```\n\n\u003cbr\u003e\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eFarm\u003c/summary\u003e\u003cbr\u003e\n\n```ts\n// Your farm.config.js\nimport Aphex from '@kitschpatrol/unplugin-aphex/farm'\n\nexport default {\n  plugins: [Aphex()],\n}\n```\n\n\u003cbr\u003e\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eNuxt\u003c/summary\u003e\u003cbr\u003e\n\n```ts\n// Your nuxt.config.ts\nexport default defineNuxtConfig({\n  aphex: {\n    // plugin options here\n  },\n  modules: ['@kitschpatrol/unplugin-aphex/nuxt'],\n})\n```\n\n\u003cbr\u003e\u003c/details\u003e\n\n#### 3. Configure TypeScript\n\n_Required for TypeScript projects. Skip this step if you're using plain JavaScript._\n\nAdd the extension declarations to your [types](https://www.typescriptlang.org/tsconfig#types) in tsconfig.json:\n\n```json\n{\n  \"compilerOptions\": {\n    \"types\": [\"@kitschpatrol/unplugin-aphex/client\"]\n  }\n}\n```\n\nAlternatively, you can add a triple-slash package dependency directive to your global types file (e.g. `env.d.ts` or similar):\n\n```ts\n/// \u003creference types=\"@kitschpatrol/unplugin-aphex/client\" /\u003e\n```\n\nThis step should take care of errors like:\n\n```sh\nCannot find module '~aphex/some-album/some-photo' or its corresponding type declarations.ts(2307)\n```\n\n#### 4. Notify ESLint (Optional)\n\nIf 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:\n\n```json\n{\n  \"rules\": {\n    \"import-x/no-unresolved\": [\"error\", { \"ignore\": [\"^~aphex/\"] }]\n  }\n}\n```\n\n#### 5. Install VS Code preview extension (Optional)\n\nIf you're using VS Code, an [extension](https://github.com/kitschpatrol/vscode-aphex-preview) is available to provide hover-previews for Aphex file paths:\n\nInstall the extension from the [Marketplace](https://marketplace.visualstudio.com/items?itemName=kitschpatrol.aphex-preview), or run the following in VS Code's command palette:\n\n```sh\next install kitschpatrol.aphex-preview\n```\n\n## Usage\n\nAny 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.\n\n### Options\n\n| Option                 | Type                                      | Default                         | Description                                                                                                                                                                                                       |\n| ---------------------- | ----------------------------------------- | ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `cacheDirectory`       | `string`                                  | `'./node_modules/.cache/aphex'` | Where exported images are stored.                                                                                                                                                                                 |\n| `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. |\n| `exportOptions`        | Aphex `ExportOptions` (partial)           | _sensible defaults_             | Forwarded to the underlying Aphex export pipeline.                                                                                                                                                                |\n| `processOptions`       | Aphex `ProcessOptions` (partial)          | _sensible defaults_             | Resizing, color profile enforcement, etc. Forwarded to Aphex.                                                                                                                                                     |\n| `interactiveSession`   | `boolean`                                 | `false`                         | Experimental: keep a single `aphex-swift` session alive across requests for higher throughput.                                                                                                                    |\n| `maxConcurrentExports` | `number`                                  | `4`                             | Cap on parallel exports. Lower this if Photos.app or your system feels overloaded.                                                                                                                                |\n| `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).  |\n| `returnMetadata`       | `boolean`                                 | `false`                         | Return a metadata object instead of a path string. See [Metadata mode](#metadata-mode) below.                                                                                                                     |\n| `validateMetadata`     | `boolean`                                 | `false`                         | Require certain (currently non-configurable) metadata fields to be present in the source files.                                                                                                                   |\n| `verbose`              | `boolean`                                 | `false`                         | Log per-export timing and cache decisions.                                                                                                                                                                        |\n\n### Metadata mode\n\nWhen `returnMetadata` is `true`, imports resolve to an object instead of a path:\n\n```ts\nimport photo from '~aphex/some-photos-album/img_1922.jpeg'\n\nconsole.log(photo)\n// {\n//   format: 'jpeg',           // ImageMimeType from @kitschpatrol/aphex\n//   height: 1080,\n//   src: 'img_1922-a1b2c3d4.jpeg',\n//   width: 1620,\n// }\n```\n\nThis 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.\n\n### Cache directory contents\n\nAlongside 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`.\n\n## Maintainers\n\n[kitschpatrol](https://github.com/kitschpatrol)\n\n\u003c!-- contributing --\u003e\n\n## Contributing\n\n[Issues](https://github.com/kitschpatrol/unplugin-aphex/issues) are welcome and appreciated.\n\nPlease open an issue to discuss changes before submitting a pull request. Unsolicited PRs (especially AI-generated ones) are unlikely to be merged.\n\nThis 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.\n\n\u003c!-- /contributing --\u003e\n\n## Disclaimer\n\nThis is an unofficial library and is not affiliated with or blessed by Apple Inc.\n\nThe underlying library's core export commands maintain a \"read-only\" relationship with your library.\n\nNone 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.\n\nThis tool has _not_ been tested with iCloud-based Photos libraries.\n\n\u003c!-- license --\u003e\n\n## License\n\n[MIT](license.txt) © [Eric Mika](https://ericmika.com)\n\n\u003c!-- /license --\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkitschpatrol%2Funplugin-aphex","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkitschpatrol%2Funplugin-aphex","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkitschpatrol%2Funplugin-aphex/lists"}