Skip to content
Switch branches/tags

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time

Picture Gallery beta

This is a work in progress 🚧

I’m using it to practice with new tools and to share photos with friends 🦊 🐶

How to make your own gallery

Quick start

You can remix this Glitch project to make your own gallery 🎏

Creating a gallery

If you’d like to work locally instead of using Glitch–you can follow these steps to create images and data for your albums.

NOTE: Some of these tools may only be available on macOS (in particular, ImageOptim and cavif)

  1. Install Node 14.15.3 LTS or newer

  2. Install ImageOptim

  3. Install ImageMagick

  4. Clone this project with Git (or download it)

  5. Add your pictures to the _pictures folder, grouped by album name


You may also want to delete the example pictures, and the LICENSE file:


You can also make groups of albums.

  1. Add information about your gallery and featured albums to _api/index.json
  "title": "A name for your gallery",
  "date": "2019 to 2020",
  "albums": [

You may also want to remove the japan and wildflowers examples from the list in _api/index.json.

  1. Open your project folder in a terminal and install dependencies:
npm install
  1. Create data and responsive images
npm run create
  1. Start the server
npm start
  1. Visit http://localhost:4000

To stop the server, press “control C”

Editing a gallery

You can edit the JSON files that were created for you in the _api folder:


For example, you may want to change the title and add a date for each album:

"title": "A name for your album",
"date": "February & March, 2020",

To see your changes, you may need to stop the server (press “control C”) and then restart the server (npm start).

It’s okay to commit the generated files in these folders:


These files are your data and will only change if you re-run the npm run create script or edit them yourself.

Running npm run create a second time will skip any existing files, even if they would ideally be updated–for example, .zip files in the _archives folder. You can work around this by removing any files or folders that you want to re-create.

How to add a new album

  1. Add your pictures to the _pictures folder:
  1. Create data for your new album:
npm run create
  1. Edit the data file for your album (optional):
  1. Add your album to the index.json file to feature it on your gallery’s home page (optional):
  "title": "A name for your gallery",
  "date": "2019 to 2020",
  "albums": [

How to publish your gallery

The build command will create a _site folder that can be published on any web server.

npm run build

You can browse the static site locally with this command:

npm run serve

And then visit http://localhost:4000

You can publish your copy of this project to a static host like Netlify using these settings:

Build command
npm run build

Publish directory

This will automatically rebuild and publish your site as you push changes to your copy of this GitHub repository.

Deploy to Netlify

Secret albums

If you want to publish an album to share with friends without making it public, you can leave it out of the api/index.json file. That way, it won’t appear on the home page of your picture gallery site.

To make the album name hard to guess, you may want to include a UUID as part of the name. For example:


You can also ask search engines not to index your album by setting askSearchEnginesNotToIndex to true in the JSON file for your album.

  "uri": "your-secret-album-0c64f7ea-ad3d-4101-b379-fb5098aed301",
  "title": "A name of your secret album",
  "date": "February & March, 2019",
  "askSearchEnginesNotToIndex": true,

This will add a noindex meta element to your page.

And you can ask search engines not to index your entire gallery (including the home page) by setting askSearchEnginesNotToIndex to true in the _config.js file:

"askSearchEnginesNotToIndex": true

If your gallery is stored in a public place like GitHub, it may also be a good idea to make your repository private.

Group albums

To group several albums together and show them on a single web page, create a new folder using the name of your group–and place the albums inside it.


And then visit http://localhost:4000/your-group-of-related-albums/

Social sharing image

To make an open graph image available for each page in your gallery, add your domain name to the _config.js file:

"host": ""

How to add a story about an album

If you’d like to include some words about your album, create a markdown file with the same name as your album’s .json file and place it in the _api folder. For example:


Your story will appear along with the images, on the page for your album.

Image file storage

You may want to use Git LFS, if your repository is getting close to 1 GB in size. See GitHub disk quota

How to move existing files into Git LFS

Here are some commands that I used to migrate large files to Git LFS, when they were already in my Git commit history.

$ git lfs migrate import --everything --include="*.jpg,*.jpeg,*.png,*.zip"
$ git status
$ git push --force-with-lease


This project was originally created with Snowpack 1, and hasn’t yet been migrated to Snowpack 2.

In the mean time, you can run this command to update the web_modules folder:


State machine visualization


Project goals

This project is an experiment to see how easily the following goals can be achieved in a reactive single-page application on the web…

User experience

  • Essential content/features are available in any web browser
  • Browser features (like forward/back and bookmarks) are supported
  • Site is just as accessible as it would be with static HTML and page refreshes
  • Site is just as findable by search engines and archivable as it would be if it were made of static HTML pages
  • First page renders as quickly as static HTML
  • The application works well on a slow network
  • The application has cues that are equivalent to a normal browsing experience, like a page loading indicator
  • The application is still usable when things go wrong, like if a CSS file doesn’t load or a JavaScript error happens
  • Gesture-driven animations and transitions between pages can be added

Editor experience

  • Content can be created with a simple language like markdown
  • Content can be added, edited and removed using a simple mechanism like files and folders
  • The gallery can be hosted anywhere and kept private, if desired

Developer experience

  • The application’s logic is easy to understand and reason about (Thanks XState!)
  • Large features can be broken up into smaller components and modules
  • Code for templates and logic can be used on the client or server side
  • The application can be continuously deployed in a way that is reliable, scalable and secure
  • New features can be added with confidence that things won’t break
  • The code is easy to read
  • The app can be ported to another framework without too much rework

Helpful resources

These projects and guides have been super helpful to me, while working on the gallery…


The code for this project is available under an open source license.

The example photos and recipes are available under a creative commons license.