Photo Sphere Viewer is developed in TypeScript and SASS . The repository is a Turborepo monorepo containing the core package, official adapters, and plugins. Builds are powered by tsup (an esbuild-based toolkit). Documentation is generated with VitePress and TypeDoc . Linting uses ESLint and Stylelint . Tests run with Mocha (unit) and Cypress (end-to-end).
Prerequisites Node.js 24 or later is required. Older versions are not supported.
The repository uses Yarn 1 (Classic) as its package manager. Install dependencies from the repo root:
Repo structure repo/ ├── packages/ # Core, adapters, and plugins (one package per directory) ├── docs/ # VitePress documentation site ├── cypress/ # Cypress end-to-end tests ├── build/ # Build scripts and utilities └── package.json # Root scripts (Turbo)
All packages/* entries are Yarn workspaces. Turbo is used to run tasks across all workspaces in the correct dependency order.
Development commands
Dev server Launch a live-reloading dev server for all packages.
Documentation Serve the VitePress documentation site locally.
Linting Run ESLint and Stylelint across the entire repo.
Tests Run unit tests (Mocha) and end-to-end tests (Cypress).
Dev server # Start the dev server (watches all packages) npm run serve # Watch only selected packages (interactive prompt) npm run serve-filter
Documentation # Serve docs locally npm run doc:serve # Build the documentation npm run doc:build
Building # Build all packages npm run build
Linting # Run all linters npm run lint
Testing Unit tests
End-to-end tests
Unit tests are written with Mocha and live alongside each package. # Open the Cypress interactive runner npm run e2e:open # Run Cypress tests headlessly npm run e2e:run
End-to-end tests use Cypress and are located in the cypress/ directory. npm link To test local changes in a consuming project, register all packages with npm link:
This runs npm link for every package in packages/*, making them available globally so you can link them into your project with npm link @photo-sphere-viewer/<package>.
Making changes
Fork and clone the repository
Fork the repo on GitHub, then clone your fork: git clone https://github.com/ < your-usernam e > /Photo-Sphere-Viewer.git cd Photo-Sphere-Viewer yarn install
Start the dev server
Run the dev server to watch for changes across all packages: Use npm run serve-filter to watch only the packages you are actively editing.
Make your changes
Edit source files inside packages/<package-name>/src/. TypeScript and SASS files are compiled automatically while the dev server is running.
Run linting and tests
Before opening a pull request, make sure linting and tests pass: npm run lint npm run test
Open a pull request
Push your branch and open a pull request against main on the upstream repository.
Credits The following photos and videos are used across the demos:
Demo Author sphere, sphere-tiles, cubemap, cubemap-tilesDamien Sorel sphere-tiles-24k, cubemap-tiles-24kGreg Zaal artist-workshopOliksiy Yakovlyev equirectangular-videoMettle Communications cubemap-videoThe Dalí Museum dualfisheyeJonna Luostari
