Developers

Welcome to the Canopy IIIF developer documentation. This guide is for developers who customize Canopy installations, troubleshoot problems, integrate external scripts, or work locally. You’ll find instructions for setting up a development environment, navigating the codebase, and following best practices. Most developers begin with the canopy-iiif/template project; others may wish to explore the core Canopy application in canopy-iiif/app.

Architecture

Canopy templates are intentionally designed to be simple and modular. The project is structured to allow easy customization and extension by developers of varying skill levels. The core of Canopy is built using modern web technologies, including Markdown + JSX (MDX) for the frontend development and easy inlining of rich content.

├── .cache/                        # build cache (gitignored)├── app/│   ├── components/│   │   └── mdx.tsx                # registers custom React components for MDX│   ├── scripts/│   │   └── canopy-build.mts       # orchestrates Canopy build│   └── styles/│       └── index.css              # global CSS styles├── assets/                        # directory for files, e.g. robots.txt, favicon.ico, images/**/├── content/│   ├── _app.mdx                   # global wrapper for all pages│   ├── _layout.mdx                # inheritable layout for .mdx files│   ├── about/                     # example directory for contextual content│   ├── search/                    # special route for search results│   └── works/                     # special route for all IIIF works├── site/                          # generated site output (on build)├── canopy.yml                     # Canopy configuration file└── package.json                   # depends on @canopy-iiif/app

• .cache/ is where build artifacts are stored to speed up subsequent builds.
• app/ is intended for server-side scripts that developers could customize or extend.
• assets/ is for static files like images, fonts, scripts, or other resources.
• content/ is where all site content lives, including MDX files and IIIF work layouts.
• site/ is the output directory for the deployed static site.
• canopy.yml file is the main configuration file for your Canopy project.
• package.json manages dependencies, including the core Canopy application package.

Custom components

Projects that need reusable UI blocks can register React components under app/components/mdx.tsx. See Developers → Components for instructions covering both server-rendered components and browser-only runtimes.

Updating Canopy

Occasionally, new versions of Canopy are released with bug fixes, new features, and improvements. To update your Canopy installation to the latest version, you can use npm. Run the following command in the root of your Canopy project directory:

Updating in your local environment

If you have a local development environment set up, you can update @canopy-iiif/app by running the command below. The current latest version of v1.2.6 will be installed:

npm i @canopy-iiif/app@latest

Updating via GitHub Actions

If your project was created from the official Canopy template, you can also update @canopy-iiif/app without touching your local environment by running the Update Canopy App workflow in GitHub Actions:

1. Open your repository in GitHub, go to Actions, and select Update Canopy App in the sidebar.
2. Click Run workflow. You can optionally provide a specific version (for example 1.0.2); leave it blank to install the latest release.
3. The workflow installs the requested version and opens a pull request with the updated package.json / package-lock.json.

Review the pull request, run your usual tests, and merge when you are ready. This keeps Canopy dependencies current while giving you the chance to audit changes before deploying.

Cache

Canopy will write heavy build artifacts to .cache/ so repeat builds skip extra network and compile work. Cache will not stay alive in GitHub pages builds unless the directory is removed .gitignore and committed.

• .cache/iiif/: normalized collections, manifests, and thumbnails fetched during npm run build.
• .cache/mdx/: compiled MDX modules for faster server renders.
• .cache/search/: bundled search templates and helper assets.

Committing caches for stable projects

For mature projects that rarely change, you may drop .cache from .gitignore and commit the directory. New clones then inherit the warmed cache and cold builds speed up. Only do this when you expect the data in your IIIF Collections to be stable and unchanging or if the project has reached a frozen state.

Deleting caches for troubleshooting

Active projects should leave .cache untracked in their repository and delete it whenever you need a clean slate while working locally. Removing the folder (rm -rf .cache) forces the next build or dev server run to refetch IIIF data, recompile MDX, and rebuild search assets. It’s the fastest fix for stale thumbnails or mismatched manifest data.