Skip to content

Development

Requirements

CloudScope Web application development requires:

Documentation development additionally requires Python with the packages pinned in requirements-docs.txt.

Install the web application

Check out the two repositories as siblings:

cs_project/
├── cloudscope-web/
└── mapmanager-web-components/

Build the shared NicePool package, then install CloudScope Web's locked dependencies:

cd ../mapmanager-web-components
npm ci
npm run build --workspace @mapmanager/nicepool
cd ../cloudscope-web
npm ci

CloudScope Web uses the local @mapmanager/nicepool package. Its GitHub Pages workflow performs the same steps after checking out the current mapmanager-web-components/main branch. A NicePool push is picked up the next time the CloudScope Web workflow runs; it does not independently trigger a CloudScope Web deployment.

Start the Vite development server:

npm run dev

The default local URL is typically:

http://localhost:5173/

Open a local exported collection

A local CloudScope-compatible OME-Zarr collection can be exposed through the Vite development server:

ACQSTORE_OME_ZARR_ROOT=/absolute/path/to/collection.ome.zarr npm run dev

The development server mounts the configured directory at:

/__dev_collection__/

Startup source priority is:

  1. an explicit collection query parameter in the page URL
  2. ACQSTORE_OME_ZARR_ROOT when running the Vite development server
  3. the configured default hosted sample

Tests and quality checks

Run the test suite:

npm test

Run the complete application verification configured by the repository:

npm run check

The current npm configuration runs formatting checks, linting, sample verification, tests, type checking, the Vite production build, and final production-artifact verification.

Production application build

Build the application with:

npm run build

Vite writes the static application to:

dist/

The Vite configuration uses a relative base so the application can be deployed at a project path rather than requiring the web-server root.

Large OME-Zarr datasets are intentionally hosted separately from the application and should not be bundled into dist/.

Documentation development

Install the pinned documentation dependencies:

python3 -m pip install -r requirements-docs.txt

Preview the documentation locally:

npm run docs:serve

By default MkDocs serves its preview on:

http://127.0.0.1:8000/

Build the documentation with strict validation:

npm run docs:build

The MkDocs configuration writes documentation into:

dist/docs/

The build order for a combined deployment is therefore important: build the Vite application first, then build MkDocs. A Vite production build recreates dist/, while MkDocs adds the documentation beneath the finished application tree.

Running mkdocs locally

Follow this script to run mkdocs serve using local install Python

python3 -m venv .venv-docs
source .venv-docs/bin/activate
python -m pip install -r requirements-docs.txt

mkdocs serve

The docs site will then be available locally at:

http://127.0.0.1:8000/cloudscope-web/docs

Source organization

Key source locations are:

  • src/components/ — Vue presentation components
  • src/composables/ — viewer orchestration and reactive state
  • src/config/ — application and hosted-sample configuration
  • src/data/ — data sources, format loaders, viewport helpers, and caching
  • src/models/ — collection, image, and serialized-manifest TypeScript contracts
  • src/plots/ — plot specifications and analysis registry
  • src/raster-viewer/ — shared raster-viewer implementation
  • tests/ — unit and component tests
  • docs/ — MkDocs documentation source

Documentation deployment layout

The production deployment combines the two static outputs:

dist/
├── index.html          # CloudScope Web application
├── assets/             # Vite application assets
└── docs/
    └── index.html      # MkDocs documentation

This produces the public layout:

/cloudscope-web/        CloudScope Web application
/cloudscope-web/docs/   CloudScope Web documentation