A modern, high-performance photo gallery platform for photographers
Official SaaS • Documentation • Live Examples • Self-Hosting
Afilmory (/əˈfɪlməri/, "uh-FIL-muh-ree") is a comprehensive photo gallery solution that combines Auto Focus (AF), Aperture (light control), Film (vintage medium), and Memory (captured moments). Built with React + TypeScript, it offers automatic photo synchronization from multiple storage sources, a GPU-accelerated image viewer (WebGPU first, WebGL fallback) with HDR gain-map support, professional EXIF metadata display, and a native iOS companion app.
👉 Get Started at afilmory.art - Zero setup, live in minutes!
The easiest way to create your photo gallery. No deployment, no servers, no maintenance required.
Why Choose SaaS?
- ✅ Zero Configuration - Sign up and go live immediately
- ✅ Live CMS - Edit photos, titles, and metadata in real-time
- ✅ Custom Domains - Bind your own domain with DNS verification
- ✅ Auto Updates - Always running the latest features
- ✅ Managed Infrastructure - We handle scaling, backups, and maintenance
For developers who need full control over their deployment:
Docker (Recommended)
# See our Docker deployment guide
https://github.com/Afilmory/dockerManual Installation
# 1. Clone and install
git clone https://github.com/Afilmory/Afilmory.git
cd Afilmory
pnpm install
# 2. Configure
cp config.example.json config.json
cp builder.config.default.ts builder.config.ts
# Edit both files with your settings
# 3. Build manifest and thumbnails
pnpm run build:manifest
# 4. Start the application
pnpm devFor detailed self-hosting instructions, see DEVELOPMENT.md and Documentation.
See Afilmory in action:
- afilmory.innei.in - Creator's personal gallery
- gallery.mxte.cc
- photography.pseudoyu.com
- afilmory.magren.cc
- 🖼️ WebGPU Image Viewer - Custom GPU viewer that renders through WebGPU by default and falls back to WebGL when
navigator.gpuis unavailable; smooth zoom, pan, pinch, and double-tap cycling between fit, fill, and 100% - 🧩 Tiled Rendering - Large photos are decoded off the main thread in a worker and streamed to the GPU as tiles
- 📱 Responsive Masonry Layout - Powered by Masonic, adapts seamlessly to any screen size
- 🎨 Modern UI/UX - Tailwind CSS 4 with the A 8000 pple UIKit color palette, glass materials, and spring motion
- ⚡ Incremental Sync - Smart change detection processes only new or modified photos
- 🌐 Internationalization - English, 简体中文, 繁體中文 (HK/TW), 日本語, and 한국어
- 🔗 Social Sharing - Dynamic OpenGraph images and SEO metadata for rich previews
- 📲 Native iOS App - Swift/UIKit client for browsing galleries, with push notifications
- 🔄 Format Support - Automatic conversion of HEIC/HEIF, TIFF, and BMP
- 🖼️ Smart Thumbnails - Multi-size thumbnail generation for optimized loading
- 📊 Complete EXIF Display - Camera, lens, focal length, aperture, ISO, GPS, and more (via ExifTool)
- 🌈 ThumbHash Placeholders - Compact placeholders for a smooth progressive loading experience
- 📱 Live Photos - Detection and playback of iPhone Live Photos
- ☀️ HDR Gain Maps - Renders JPEG gain-map HDR (including Apple HDR photos) on HDR-capable displays
- 🎛️ Fujifilm Recipes - Display Fujifilm film simulation settings
- 🗂️ Multi-Storage Support - S3-compatible storage, Backblaze B2, GitHub, Eagle, and local file system
- 🏷️ File System Tags - Auto-generated tags based on directory structure
- ⚡ Concurrent Processing - Worker-thread and cluster modes for fast builds
- 🔌 Builder Plugins - Lifecycle hooks for thumbnail storage, reverse geocoding, repo sync, and custom logic
- 🗺️ Interactive Map - Geographic visualization with GPS coordinates using MapLibre
- 💬 Comments & Reactions - Visitor engagement in backend-powered galleries
- 📷 Share & Embed - Share images to social media or embed them via the SDK
afilmory/
├── apps/
│ ├── web/ # Gallery SPA (Vite + React 19 + React Router 7)
│ ├── ssr/ # Next.js host: serves the SPA, injects manifest, OG/SEO
│ ├── mobile/ # Native iOS app (Swift / UIKit, XcodeGen)
│ ├── site/ # Marketing site (Astro)
│ ├── docs/ # Documentation site (Vite + MDX)
│ └── promo/ # Promo videos (Remotion)
├── be/ # Backend services
│ ├── apps/
│ │ ├── core/ # Core API server (Hono + @tsuki-hono)
│ │ ├── dashboard/ # Admin dashboard SPA
│ │ └── oauth-gateway/# Standalone OAuth broker
│ └── packages/
│ ├── db/ # Database schemas & migrations (Drizzle ORM)
│ ├── redis/ # Redis client
│ ├── task-queue/ # Job queue
│ └── utils/ # Shared backend utilities
├── packages/
│ ├── builder/ # Photo processing pipeline CLI
│ ├── webgl-viewer/ # GPU image viewer (WebGPU + WebGL fallback)
│ ├── viewer-motion/ # Framework-agnostic viewer motion primitives
│ ├── renderer/ # OG image renderer (Satori + resvg)
│ ├── data/ # PhotoLoader + bundled manifest
│ ├── typing/ # Shared photo/manifest types
│ ├── sdk/ # Public SDK + share embed script
│ ├── ui/ # Shared UI components
│ ├── hooks/ # React hooks library
│ └── utils/ # Utility functions
└── plugins/ # ESLint / Vite tooling plugins
- React 19 - With the React Compiler
- TypeScript 6 - Full type safety
- Vite 8 - Lightning-fast build tool
- React Router 7 - File-based routing
- Tailwind CSS 4 - Utility-first CSS with the Apple UIKit color palette
- Radix UI / Headless UI - Accessible component primitives
- Motion - Spring-based animations
- Jotai - Atomic state management
- TanStack Query - Data fetching and caching
- MapLibre GL - Interactive maps
- i18next - Internationalization
- WebGPU - Primary renderer, with worker-side texture decoding and tiled uploads
- WebGL - Automatic fallback for browsers without WebGPU
- HDR Gain Maps - JPEG gain-map parsing and HDR compositing on
dynamic-range: highdisplays
- Next.js 16 - Serves the SPA, injects the manifest, and renders dynamic OG images and SEO metadata
- Hono - Ultra-fast web framework
- @tsuki-hono - NestJS-style modules, controllers, and decorators on top of Hono, with
tsyringeDI - Drizzle ORM - Type-safe database toolkit
- PostgreSQL - Primary database
- Redis - Caching and task queue
- Better Auth - Authentication
- Server-Sent Events - Real-time updates
- Satori + resvg - OG image rendering
- Swift 6 / UIKit - Native iOS 18+ app, with Liquid Glass on newer iOS versions
- XcodeGen -
project.ymlas the project source of truth
- Node.js - Server-side runtime
- Sharp - High-performance image processing
- ExifTool - Metadata extraction (via
exiftool-vendored) - ThumbHash - Placeholder generation
- AWS SDK - S3 storage operations
- Worker Threads / Cluster - Parallel processing
Designed with adapter pattern for flexibility:
- S3-Compatible - AWS S3, MinIO, RustFS, Alibaba Cloud OSS, and more
- Backblaze B2 - Native B2 API provider
- GitHub - Use GitHub repository as storage
- Eagle - Import from Eagle app library
- Local File System - For development and testing
- Node.js (current LTS)
- pnpm 11+
- Xcode 16+ (only for the iOS app)
# Install dependencies
pnpm install
# Copy configuration files
cp config.example.json config.json
cp builder.config.default.ts builder.config.ts
# Set up environment variables
cp .env.template .env
# Edit .env with your credentials# Development
pnpm dev # Start web + SSR
pnpm dev:be # Start backend services
pnpm --filter web dev # Web app only
pnpm --filter @afilmory/ssr dev # SSR only
pnpm --filter @afilmory/dashboard dev # Admin dashboard
pnpm dev:mobile # Build and run the iOS app in Simulator
pnpm site:dev # Marketing site
# Build
pnpm build # Build production web app
pnpm build:manifest # Generate photo manifest (incremental)
pnpm build:manifest -- --force # Full rebuild
pnpm build:manifest -- --force-manifest # Regenerate manifest only
pnpm build:manifest -- --force-thumbnails # Regenerate thumbnails only
# Documentation
pnpm docs:dev # Start docs dev server
pnpm docs:build # Build documentation
# Code Quality
pnpm lint # Lint and fix
pnpm format # Format code
pnpm type-check # Type checkingconfig.json - Site presentation config:
{
"name": "My Gallery",
"title": "My Photography",
"description": "Capturing beautiful moments",
"url": "https://gallery.example.com",
"accentColor": "#007bff",
"author": {
"name": "Your Name",
"url": "https://example.com",
"avatar": "https://example.com/avatar.jpg"
},
"social": {
"github": "username",
"twitter": "username"
},
"map": ["maplibre"],
"mapStyle": "builtin",
"mapProjection": "mercator"
}builder.config.ts - Photo processing config:
import { defineBuilderConfig } from '@afilmory/builder'
export default defineBuilderConfig(() => ({
storage: {
provider: 's3',
bucket: 'my-photos',
region: 'us-east-1',
// ... other S3 settings
},
system: {
processing: {
defaultConcurrency: 10,
enableLivePhotoDetection: true,
},
observability: {
showProgress: true,
showDetailedStats: true,
},
},
}))Implement the StorageProvider interface:
import type { StorageProvider, StorageObject } from '@afilmory/builder'
class MyStorageProvider implements StorageProvider {
async getFile(key: string): Promise<Buffer | null> {
// Your implementation
}
async listImages(): Promise<StorageObject[]> {
// Your implementation
}
// ... other required methods
}Create a plugin that hooks into the build lifecycle:
import type { BuilderPlugin } from '@afilmory/builder'
export default function myPlugin(): BuilderPlugin {
return {
name: 'my-plugin',
hooks: {
beforeBuild: async ({ logger }) => {
logger.main.info('Starting build')
},
afterSaveManifest: async ({ payload }) => {
// payload.manifest, payload.cameras, payload.lenses
},
},
}
}Register it in builder.config.ts under plugins.
- Official Documentation - Complete guides and API reference
- Quick Start Guide - Get running in 5 minutes
- SaaS Mode - Learn about hosted galleries
- Storage Providers - Setup guides for all storage options
- Deployment Guides - Deploy to various platforms
- API Reference - Backend API documentation
We welcome contributions! See AGENTS.md for architecture notes and DESIGN.md for the web design system.
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Make your changes
- Run linting and type checks (
pnpm lint && pnpm type-check) - Commit your changes (
git commit -m 'Add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
Attribution Network License (ANL) v1.0 © 2025 Afilmory Team
See LICENSE for more details.
- Official SaaS - Hosted gallery service
- Documentation - Full documentation
- GitHub - Source code
- Creator's Website - Project creator
Built with love by the Afilmory team and contributors. Special thanks to all photographers using Afilmory to share their work with the world.
If this project helps you, please give it a ⭐️ Star!