GitHub - SimplePhotoGallery/core: Create beautiful photo galleries from collections in 1 minute

Simple Photo Gallery

Create beautiful photo galleries from collections in just 30 seconds. No configuration required to get started—simply run two commands in your photos folder and create a static gallery website you can self-host.

This is a free, open-source tool that you can use to generate galleries and self-host them. If you don't want to use the command line or bother with self-hostting, please check out simple.photo for a hosted solution.

Example Gallries

More examples

• California Road Trip
• Visiting Australia
• Discovering Japan

Features

📸 Automatically scan directories with photos and videos
📝 Show descriptions for photos and videos
📂 Divide the gallery into sections to tell a story
🖼️ Create optimized thumbnails for fast loading
🎥 Play videos directly in the gallery
📱 Generate galleries that work on all devices
⚡ Optimized to be fast and lightweight
🔧 Generate a static HTML gallery that you can self-host

Quick Start

To create a gallery you need to install he simple-photo-gallery package globally and then you can use the spg command:

npm install -g simple-photo-gallery@latest
spg init
spg build

Alternatively you can use npx to run the commands directly:

npx simple-photo-gallery@latest init
npx simple-photo-gallery@latest build

This will:

1. Install the simple-photo-gallery package from NPM (if you don't already have it)
2. Prompt you for your gallery title, description, and header image
3. Scan your photos and create a gallery.json file
4. Generate optimized thumbnails
5. Build a static HTML gallery that you can open in your browser and self-host

Installation Requirements

• Node.js 20+ - Download here
• FFmpeg (for video support) - Install via:
  • macOS: brew install ffmpeg
  • Ubuntu/Debian: sudo apt install ffmpeg
  • Windows: Download from ffmpeg.org

Development

This is a monorepo using Yarn workspaces. To set up the development environment:

1. Clone the repository

   git clone https://github.com/SimplePhotoGallery/core.git
   cd spg-core

2. Install dependencies

3. Build the common package (required for TypeScript/ESLint to resolve @simple-photo-gallery/common)

   yarn workspace @simple-photo-gallery/common build

4. Build the gallery package (optional, for testing CLI changes)

   yarn workspace simple-photo-gallery build

5. Run the CLI in development mode

   yarn workspace simple-photo-gallery gallery

Workspace Packages

• common/ - Shared types, schemas, and utilities used by both the CLI and themes
  • Gallery types and Zod validation schemas
  • Theme utilities (data loading, path resolution, markdown parsing)
  • Client-side utilities (PhotoSwipe, blurhash, CSS helpers)
  • See common/README.md for full API documentation
• gallery/ - CLI tool (simple-photo-gallery)
  • Includes base theme template bundled at gallery/src/modules/create-theme/templates/base/
• themes/modern/ - Default theme package (reference implementation)

Building Packages

Each workspace package can be built individually:

• yarn workspace @simple-photo-gallery/common build
• yarn workspace simple-photo-gallery build
• yarn workspace @simple-photo-gallery/theme-modern build

Supported Formats

Images: JPEG, PNG, WebP, GIF, TIFF
Videos: MP4, MOV, AVI, WebM, MKV

Architecture

This project uses a multi-theme architecture:

• Common package provides shared utilities for all themes
• Themes focus only on layout and presentation
• CLI handles gallery generation and theme orchestration

See the Architecture Documentation for details on how the system works, including:

• Package structure and dependencies
• Data flow from photos to static HTML
• Theme system design and resolution
• Multi-theme support implementation
• Guidelines for adding new features

Detailed Documentation

For advanced usage, customization, and deployment options, see the comprehensive documentation:

• Commands Reference - Detailed guide for all CLI commands
  • init - Initialize new galleries
  • build - Generate static HTML galleries
  • thumbnails - Generate optimized thumbnails
  • clean - Remove gallery files
  • create-theme - Scaffold a new theme package
  • telemetry - Manage anonymous telemetry preferences
• Gallery Configuration - Manual editing of gallery.json and advanced features like sections
• Custom Themes - Create and use custom themes
• Common Package API - Utilities and types for theme development
• Deployment Guide - Guidelines for hosting your gallery

Python Version

The old Python version of Simple Photo Gallery V1 is still available here, but is now deprecated.

License

Simple Photo Gallery is licensed under the MIT License - see LICENSE file for details.