UniversalViewer and the open source viewer for mixed-format collections

What the viewer is for

The Universal Viewer, or UV, is described as a community-developed open source project with the mission of helping you share your content with the world. Concretely, the software can display images, 3D files and PDFs, and play audio and video files.

That list is the reason the project exists. A digital collection that mixes a manuscript scan, a 3D scan of a sculpture, a PDF article and an oral history recording has no single player. The usual outcome is four embeds, four integrations, four sets of access controls and four accessibility problems. UV collapses that into one embeddable widget whose configuration declares which format the item is in.

The audience is institutional in practice. The README talks about testers, developers and institutional users, the project is sponsored through Open Collective, and the demo sites are hosted to show sample items. The topics list names the domains the project is used in: 3d, audio, images, pdf, video, iiif and openseadragon. The hacktoberfest tag points to a contributor base that comes in through an annual event rather than a hiring pipeline.

The project is published to npm as universalviewer, and the README's install line is the whole onboarding for a developer who just wants the widget:

    npm install universalviewer --save

There is also a hosted option that requires no build at all. The stable demo page at uv-v4.netlify.app shows the latest stable version with sample items, the dev branch demo at universalviewer.dev shows the bleeding edge code, and version 3 of the viewer remains available separately at uv-v3.netlify.app for people who need the older behaviour.

The v4 browser requirement, stated plainly

The README carries a note that is short and worth repeating exactly, because it is the one hard compatibility boundary in the project.

UV v4 is designed to work on evergreen browsers. If you need IE11 support, the README points you to the v3 branch. The reasoning is given alongside it: Microsoft no longer supports IE11, and it reached end-of-life on 15 June 2022.

This is the kind of decision that ends support discussions quickly, and it is worth understanding what it means for a deployment. A viewer that runs on IE11 is a viewer that runs on a browser without modern JavaScript semantics, without current CSS, and without the fetch and module features that a modern frontend toolchain assumes. Building a viewer for that constraint means carrying a parallel code path forever, and the project chose not to.

The consequence is that the audience for v4 is anyone whose users are on current browsers, which for a cultural heritage institution means the general public and researchers but potentially not an old intranet terminal in a reading room. The v3 branch remains the answer for that case, and the demo site for it is still up, so the option is real rather than theoretical.

The current version is v4.4.4, and the release history shows the project is attentive to its own release quality. The tag for v4.4.3 is labelled DO NOT USE, which tells you the maintainers are willing to mark a published version as bad rather than leave it in the wild. That is a small signal, but a useful one about how releases are handled here.

The package layout and the build pipeline

The npm package is a library with several entry points, which tells you how it is meant to be consumed.

The package.json for version 4.4.4 declares the main entry as dist/cjs/index.js for CommonJS, the module entry as dist/esm/index.js for bundlers, typings at dist/cjs/index.d.ts and a web field pointing at dist/umd/UV.js for a script tag. The files list ships only dist/ and webpack-helpers.js, so the source is not published.

The engines field is strict:

  "engines": {
    "node": ">=22.15",
    "npm": ">=8.1.1"
  },

The build scripts show three separate pipelines. The main build is webpack with webpack.config.js, the development server is a separate webpack.dev-server.js configuration, and there is an esbuild path through esbuild.mjs. A third script, build-tsc, runs tsc with declaration output into dist/cjs, then copies the static assets, and it is that copy-files step that moves the SVG, GIF, PNG, LESS and CSS files into the CommonJS output, which is the kind of detail that breaks a package when it is skipped.

Around that sit the quality gates. There are separate lint scripts for code and for styles, a prettify script, a fix script that runs both, and a test script that runs jest. The end-to-end side is jest with puppeteer, given the jest-puppeteer.config.js and the global setup and teardown files, and there is an e2eserve script that serves the built dist on port 4444 for those tests.

Two smaller scripts are worth noticing because they show the project treats localisation as a first-class concern. checkLocaleUsage runs a locale validation script, and findMissingTranslations sits next to it in the truncated listing. For a viewer used by institutions in many countries, having the translation set machine-checked in the build is not optional.

Documentation, examples and the path to your first embed

The README routes a new user to three separate resources, and each covers a different need.

The examples in the wiki are for the how-to-use-it questions: how to embed the UV in various scenarios. The technical docs at docs.universalviewer.io are the API reference, described as covering the code and the available configuration options, and they are generated from the source, since the package has a typedoc.json and a docs script that writes the CNAME for the docs host. The manual in the dev branch is for using, configuring and developing with the UV, which is the document to read if you want to understand the model rather than copy a snippet.

The suggested route for someone who wants to contribute code is explicit in the README: fork the repository and run the examples from source, find an issue to work on, and submit a pull request. The dev branch is the working branch, with the default branch of the repository set to dev and the main branch used for the v3 line.

That is a slightly unusual arrangement for a modern project, and it is worth understanding the consequences. The npm release is built from the dev branch, the manual lives in the dev branch, and the demos are split between a stable deployment and a dev deployment. If you want to see exactly what a given published version does, the release tag is the reference point; if you want to see what the maintainers are working on, the dev branch demo is the reference point.

The technical configuration model is the part that most adopters will care about, and the docs site is where it lives. The set of configuration options is what lets one widget handle a 3D model and a PDF, and the fact that the project publishes those options as a formal API rather than a set of examples is what makes the viewer usable as a dependency rather than a copy-paste component.

Governance and how a community project stays funded

The README spends as much space on how to contribute as on how to use it, and that is a deliberate statement about what kind of project this is.

The governance document, the community team file and the code of conduct are all in the repository root, and the README asks people to read the governance document to learn about roles and responsibilities, support, membership and the decision making process. There is a Steering Group, referenced both for institutional contributors and for the people who decide where sponsorship money goes.

Contributions come through several channels. There is a Slack channel with regular community calls, a Google Group, GitHub issues for questions, feature requests and bugs, and a guide to contributing. The README also links a blog post about a recent community sprint, which is a concrete description of how the work gets organised: contributors gather, work through a set of issues together, and leave with a merged result.

The funding model is Open Collective. Individual contributors and institutional contributors both have paths there, and the Steering Group is where institutional sponsors take part in deciding how the funds are allocated. That is a different arrangement from a company-backed open source project, and it has a specific character: the money is pooled and directed by a steering group rather than by a roadmap set by one employer.

For an adopter, the practical question is what happens to the code if the funding dries up. The MIT licence on the source means that a fork is legally straightforward, which is the standard answer to that question, and the code of conduct and governance documents mean that the process of taking over is written down rather than improvised.

The licence question, and the accessibility commitment

The README states that the Universal Viewer is released under the MIT licence, linking to the LICENSE.txt file in the repository. The project metadata classifies the licence as a custom one that GitHub cannot classify, with a pointer to the LICENSE file, so the README statement and the file itself are the authoritative position rather than a recognised SPDX identifier in the metadata.

For a viewer meant to be embedded in institutional sites, that matters in a specific way. MIT is permissive: it allows commercial use, modification and redistribution, and requires only that the copyright notice and licence text travel with the code. An institution that wants to rebrand the viewer, ship it inside its own delivery platform, or bundle it with other software can do so, and the attribution obligation is a footer, not a negotiation.

The accessibility statement is a separate document in the wiki, and the README asks contributors to help update it. For a project used by libraries, archives and universities, a maintained accessibility statement is a procurement requirement in many institutions rather than a nice-to-have, and the fact that the statement lives in the wiki and is open to contributions means it is treated as a living document rather than a compliance artefact filed once.

Accessibility also shapes the engineering. A viewer that renders images, 3D models and video has to expose keyboard navigation, focus order and text alternatives for each of those modes, and the OpenSeadragon path used for high resolution imagery brings its own deep zoom keyboard model into that picture. The project carries the accessibility statement as a first-class link in its README for that reason, and the README even lists updating it among the ways to contribute code.

Editorial conclusion

Universal Viewer is a good fit for a library, archive or institution that has to expose images, 3D objects, PDFs and AV through a single embed rather than a separate viewer per format, because the configuration model handles the format differences in one place and the project is MIT licensed with an active steering group. It is a poor fit if you need to support Internet Explorer 11, since v4 targets evergreen browsers only and the README directs IE11 users to the v3 branch, and a poor fit if you want a commercial support contract on the code itself, since the institutional contribution route runs through sponsorship rather than a support agreement. Before adopting, read the manual in the dev branch and the configuration options in the technical docs, and pin the npm version rather than tracking the dev branch, since the release notes show a v4.4.3 that the maintainers marked DO NOT USE.

Frequently asked questions

Official sources

1. Issues
2. Project website
3. README
4. Releases
5. UniversalViewer/universalviewer on GitHub