Marzipano-TS

Note: This project was originally created by Google. Pixel & Process maintains this fork to keep the project alive and up-to-date with modern web standards.

A 360° media viewer for the modern web.

This is not an official Google product.

Please report bugs using the issue tracker.

User guide

You can include Marzipano-TS in your project in several ways:

• Install Marzipano-TS as a dependency using the npm package manager:

  npm install marzipano-ts

• ES Modules (Recommended):

  import { Viewer, Scene, ImageUrlSource, RectilinearView, CubeGeometry } from 'marzipano';

• CommonJS (Legacy):

  const { Viewer, Scene, ImageUrlSource, RectilinearView, CubeGeometry } = require('marzipano');

Note: As of version 1.0.0+, Marzipano-TS uses ES6 modules. See MIGRATION.md for migration guidance from older versions.

Developer guide

This is an npm-based project. A Node.js installation is required for development.

Some dependencies expect the Node.js interpreter to be called node. However, on Debian and Ubuntu systems, the binary installed by the nodejs package is called nodejs. To work around this, install the nodejs-legacy package, or use nvm instead.

Run npm install to install the dependencies. If you haven't in a while, bring them up to date with npm update.

Development:

npm run dev          # Start Vite dev server with HMR at http://localhost:5173
npm run test:watch   # Run tests in watch mode with Vitest
npm run test:ui      # Run tests with Vitest UI

Testing:

npm test             # Run all tests with Vitest
npm run coverage     # Generate test coverage report

The build system uses Vite for fast development and ES module support. Tests use Vitest with a Mocha-compatible API.

Maintainer guide

Automated CI/CD: This project uses GitHub Actions for continuous integration and automated releases:

• CI Pipeline: Automatically runs tests, linting, and builds on all pushes and PRs
• Release Pipeline: Automatically creates GitHub releases when you push a version tag
• Dependency Updates: Dependabot automatically checks for and proposes dependency updates

Creating a Release:

1. Ensure all tests pass locally: npm test
2. Update the CHANGELOG file with release notes
3. Bump the version number in package.json
4. Create a commit: git commit -am "Release vX.Y.Z"
5. Create and push a tag: git tag vX.Y.Z && git push --tags
6. GitHub Actions will automatically:
   • Run tests and build the project
   • Create a GitHub release with artifacts
   • Publish to npm (if NPM_TOKEN secret is configured)

Manual Release (if needed):

• npm run build - Build production bundle
• npm publish - Publish to npm registry