Create a Canopy Project

Have a project in mind? Let's get started! This guide will walk you through the process of creating a basic Canopy IIIF project using a readily provided IIIF Collection.

Open in StackBlitz (opens in a new tab)

Use Case

You are on a team at a university library seeking to create a digital exhibit for a Korean Literary (opens in a new tab) collection in your digital repository that is provided as a IIIF Collection (opens in a new tab). You want to create a discovery focused web site that allows users to search and browse the collection.


Create a project

Using a Github template


This method requires a GitHub account (opens in a new tab); however, it should be easier to follow for users of Canopy without a developer environment.

  1. Navigate to the Canopy IIIF repository (opens in a new tab) in GitHub
  2. Click the "Use this template" button
  3. Click the "Create a new repository" button
  4. Select the account you want to own the repository
  5. Enter a repository name and optional description
  6. Click the "Create repository" button

Using git clone

  1. In your terminal, navigate to the a working directory where you want to create your project
  2. Clone the canopy-iiif/canopy-iiif repository OR your Canopy repository instance
cd ~/Projects
git clone

Install dependencies

Navigate to your new project directory and install dependencies.

cd canopy-iiif
npm install

Create configuration file

Copy the sample configuration file and update collection, featured, and metadata properties.

cp config/canopy.sample.json config/canopy.json

In this example we will use the Korean Literary Collection (opens in a new tab) IIIF Collection URL provided by University of Washington Libraries.

  • collection is the IIIF Collection URI to be used as the root of your Canopy IIIF site
  • featured array is a list of Manifest URIs that will be promoted thoughout your Canopy IIIF site
  • metadata array is a list of metadata labels that match string values in your Manifest URI metadata entries to be used for discovery purposes

See Configuration for detailed documentation.

  "collection": "",
  "featured": [
  "metadata": ["Author", "Place of Publication"]

Ready to go!


If you are using GitHub, you can skip this step and run Canopy without a developer environment directly using GitHub Pages.

Now that you have a project and configuration set, you can run Canopy IIIF.

npm run dev

Build process

The build process may take a few minutes depending on the size of your IIIF Collection and provider response times. A Collection of ~100 items should build in 30 seconds or less.

  1. Building - Canopy retrieves the source IIIF Collection
  2. Create Manifest listing - Canopy retrives all IIIF Manifests in the Collection
  3. Create facets as IIIF Collections - Canopy anaylzes the Manifests and creates IIIF Collections for each unique metadata label and value
  4. Build search entries - Canopy is creates search entries for each Manifest from descriptive metadta
  5. Ready 🚀 - Canopy is ready to go!
Building Canopy from IIIF Collection...
Creating Manifest listing...
Aggregating 135 Manifest(s) in 14 chunk(s)...
Chunk (1/14)  200  200  200  200  200  200  200  200  200  200
## build continues...
Chunk (14/14)  200  200  200  200  200
135/135 Manifests(s) retrieved successfully.
Creating facets as IIIF Collections...
## build continues...
Building search entries...
...Ready 🚀
 Next.js 13.5.4
- Local:        http://localhost:5001
- Environments: .env

Browse your site

In your browser, navigate to http://localhost:5001 (opens in a new tab) to view your Canopy IIIF site.

Home page

Content on the home page is geared towards discovery of your IIIF Collection. The home page will render a hero component for featured Manifests and a slider components for defined metadata labels and their most common values.

canopy home page

Search page

All Manifests in your IIIF Collection are now represented as results at the /search route. In addition to full text search, results are filterable by defined metadata labels and available values. In the example Korean Literary Collection, there are 135 items available for search. A query for poems returns 43 results.

canopy search results for poems

Work page

All Manifests in your IIIF Collection are now available as statically generated pages with a /work/slug-generated-from-label pattern. Each work represents a single Manifest, its descriptive metadata, and various other IIIF properties. Clover IIIF (opens in a new tab) is the defacto deep-zoom and A/V capable viewer in Canopy IIIF but other IIIF viewers can be easily configured.

canopy work page for single result

Try Alternate IIIF Collections

A great way to visualize the agility of Canopy IIIF is to experiment with alternate IIIF Collections. Try copying one or all of the following config/canopy.json configurations to your project and re-running the build process.

Commedia dell'Arte

  "collection": "",
  "featured": [
  "metadata": ["Subject", "Date"]

Calahan Family Postcards

  "collection": "",
  "featured": [""],
  "metadata": ["Description", "Subject"]

Pacific Northwest Sheet Music Collection

  "collection": "",
  "featured": [
  "metadata": ["Composer", "Genre", "Date of Publication"]