Tutorial: Deploy Vitessce instance to GitHub Pages

This tutorial covers how to embed Vitessce as a React component in a website that can be deployed to GitHub Pages (GitHub's free static website hosting service).

NodeJS and NPM environment setup

Be sure to install NodeJS.

This tutorial was written using the following versions of NodeJS and NPM:

node --version

v23.6.0

npm --version

10.9.2

React app setup

Use Vite to initialize a new React project:

npm create vite@latest vitessce-demo-gh-pages -- --template react
cd vitessce-demo-gh-pages
npm install
npm install react@18.0.0 react-dom@18.0.0 
npm run dev
# Press Ctrl-C to stop the development server.

Notes: React version 18 is compatible with Vitessce. At the time of writing, the latest version of Vite is 6.3.5.

Initialize the new React app directory as a Git repository:

git init
git add .
git commit -m "Initial commit"
git branch -M main

Repo setup

Create a new GitHub repository (https://github.com/new) (here I called the repository vitessce-demo-gh-pages) and set it as the remote origin:

# Replace my-username with your GitHub username in the following line:
git remote add origin git@github.com:my-username/vitessce-demo-gh-pages.git
git push -u origin main

Troubleshooting

If you encounter an error in pushing to the main branch, try the following and commit the changes in the editor:

git pull origin main --allow-unrelated-histories --no-rebase

Install Vitessce

Install the Vitessce NPM package to be able to use the React component in the app:

# from within the `vitessce-demo-gh-pages` directory
npm install vitessce --save

React app development

Make a new file src/my-view-config.js:

export const myViewConfig = {
  version: "1.0.17",
  name: "Habib et al., 2017 Nature Methods",
  description: "Archived frozen adult human post-mortem brain tissue profiled by snRNA-seq (DroNc-seq)",
  datasets: [
    {
      uid: "habib-2017",
      name: "Habib 2017",
      files: [
        {
          fileType: "anndata.zarr",
          url: "https://storage.googleapis.com/vitessce-demo-data/habib-2017/habib17.processed.h5ad.zarr",
          coordinationValues: {
            embeddingType: "UMAP",
          },
          options: {
            obsFeatureMatrix: {
              path: "X",
              initialFeatureFilterPath: "var/top_highly_variable",
            },
            obsEmbedding: {
              path: "obsm/X_umap",
            },
            obsSets: [
              {
                name: "Cell Type",
                path: "obs/CellType",
              },
            ],
          },
        },
      ],
    },
  ],
  initStrategy: "auto",
  coordinationSpace: {
    embeddingType: {
      UMAP: "UMAP",
    },
    featureValueColormapRange: {
      A: [0, 0.35],
    },
  },
  layout: [
    {
      component: "obsSets",
      h: 4, w: 4, x: 4, y: 0,
    },
    {
      component: "obsSetSizes",
      h: 4, w: 4, x: 8, y: 0,
    },
    {
      component: "scatterplot",
      h: 4, w: 4, x: 0, y: 0,
      coordinationScopes: {
        embeddingType: "UMAP",
        featureValueColormapRange: "A",
      },
    },
    {
      component: "heatmap",
      h: 4, w: 8, x: 0, y: 4,
      coordinationScopes: {
        featureValueColormapRange: "A",
      },
      props: {
        transpose: true,
      },
    },
    {
      component: "featureList",
      h: 4, w: 2, x: 8, y: 4,
    },
    {
      component: "description",
      h: 4, w: 2, x: 10, y: 4,
    },
  ],
};

In src/App.jsx:

import React from 'react';
import { Vitessce } from 'vitessce';
import { myViewConfig } from './my-view-config.js';

export default function App() {
  return (
    <Vitessce
      config={myViewConfig}
      theme="light"
    />
  );
}

For more information about the React component, see the documentation page.

In src/index.css (which is imported by src/main.jsx):

html {
  height: 100%;
}

body {
  font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', 'Roboto', 'Oxygen',
    'Ubuntu', 'Cantarell', 'Fira Sans', 'Droid Sans', 'Helvetica Neue',
    sans-serif;
  -webkit-font-smoothing: antialiased;
  -moz-osx-font-smoothing: grayscale;
  display: flex;
  flex-direction: column;
  flex: 1;
  height: 100%;
  margin: 0;
}

.vitessce-container {
  height: max(100%, 100vh);
  width: 100%;
}

Configure Vite project

Edit the vite.config.mjs file to allow Vite to serve correctly from a subpath like https://my-username.github.io/vitessce-demo-gh-pages/

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'

// https://vite.dev/config/
export default defineConfig({
  plugins: [react()],
  base: '/vitessce-demo-gh-pages/',
})

Run app locally

To try out the app locally, run the following in the terminal:

npm run dev

This starts the Vite development server, which should auto-reload the web application upon code changes.

Data deployment

When you deploy the React app to the internet via GitHub Pages, the data URLs referenced in your Vitessce configuration (defined in src/my-view-config.js) must point to static files that are hosted remotely on the internet. AWS S3 is one example of a static file hosting service (in this case, an object storage system) that can be configured such that other websites (e.g., GitHub Pages sites) can load its hosted files.

If you are using AWS S3 to host the data that is referenced in your Vitessce configuration, ensure that the S3 bucket is configured according to our AWS S3 data hosting documentation.

GitHub Pages deployment

To deploy a website to GitHub pages one time, the gh-pages package can be installed from NPM and run as a command line utility. However, in this tutorial we will describe how to use a GitHub Action which will automatically re-deploy the React app to the GitHub Pages website upon each push to the main branch of its GitHub repository.

Create a new file at .github/workflows/deploy.yml with the following contents:

name: Deploy

on:
  push:
    branches:
      - main


permissions:
  contents: read
  pages: write
  id-token: write

jobs:
  build:
    runs-on: ubuntu-22.04
    name: Build React app and deploy to GitHub Pages
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 23.6.0
      - name: Install NPM dependencies
        run: npm ci
      - name: Build React app
        run: npm run build
      - name: Upload build artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: dist
  deploy:
    runs-on: ubuntu-22.04
    needs: build
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - name: Deploy to GitHub Pages
        if: ${{ github.event_name == 'push' && github.ref == 'refs/heads/main' }}
        id: deployment
        uses: actions/deploy-pages@v4
    

Allow GitHub Pages to be deployed from GitHub Actions

To allow the GitHub Action to modify the gh-pages branch of the repository, we need to update the settings at https://github.com/{my-username}/vitessce-demo-gh-pages/settings/pages (or navigate to Settings -> Pages for the repo).

Under Build and deployment, select GitHub Actions in the Source dropdown menu.

Set the homepage property in package.json

In order for relative file paths to be resolved correctly, specify the GitHub pages URL as the website's homepage.

In package.json (replacing my-username with your GitHub username):

  ...,
  "homepage": "https://my-username.github.io/vitessce-demo-gh-pages/",
  ...,

Commit and push to GitHub

The changes to the Git repository will need to be committed and pushed to GitHub in order for the GitHub Action to be executed and the GitHub Pages site to be subsequently deployed.

git add .
git commit -m "Second commit"
git push

Test the deployment

Check that the GitHub Action has executed successfully in the "Actions" tab of the GitHub page for the repository. Then, go to the GitHub Pages URL to load the website (replacing my-username with your GitHub username):

https://my-username.github.io/vitessce-demo-gh-pages/

Complete example

For reference, a complete example can be found in the vitessce-demo-gh-pages GitHub repository with corresponding deployment at https://vitessce.github.io/vitessce-demo-gh-pages/.

NodeJS and NPM environment setup​

React app setup​

Repo setup​

Troubleshooting​

Install Vitessce​

React app development​

Configure Vite project​

Run app locally​

Data deployment​

GitHub Pages deployment​

Allow GitHub Pages to be deployed from GitHub Actions​

Set the homepage property in package.json​

Commit and push to GitHub​

Test the deployment​

Complete example​