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

v18.6.0

npm --version

8.13.2

React app setup

Use Create React App to initialize a new React project:

npm init react-app vitessce-demo-gh-pages --use-npm
cd vitessce-demo-gh-pages

Initialize the new React app directory as a Git repository:

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

Make 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

Install Vitessce:

npm install vitessce --save

React app development

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

export const myViewConfig = {
  version: "1.0.4",
  name: "My example config",
  description: "This demonstrates the JSON schema",
  datasets: [
    {
      uid: "D1",
      name: "Dries",
      files: [
        {
          url: "https://s3.amazonaws.com/vitessce-data/0.0.31/master_release/dries/dries.cells.json",
          type: "cells",
          fileType: "cells.json"
        },
        {
          url: "https://s3.amazonaws.com/vitessce-data/0.0.31/master_release/dries/dries.cell-sets.json",
          type: "cell-sets",
          fileType: "cell-sets.json"
        }
      ]
    }
  ],
  coordinationSpace: {
    dataset: {
      A: "D1"
    },
    embeddingType: {
      A: "UMAP",
      B: "t-SNE"
    },
    embeddingZoom: {
      A: 2.5
    }
  },
  layout: [
    {
      component: "scatterplot",
      coordinationScopes: {
        dataset: "A",
        embeddingType: "A",
        embeddingZoom: "A"
      },
      x: 6, y: 0, w: 6, h: 6
    },
    {
      component: "scatterplot",
      coordinationScopes: {
        dataset: "A",
        embeddingType: "B",
        embeddingZoom: "A"
      },
      x: 0, y: 0, w: 6, h: 6
    },
    {
      component: "cellSets",
      coordinationScopes: {
        dataset: "A"
      },
      x: 0, y: 6, w: 6, h: 6
    },
    {
      component: "cellSetSizes",
      coordinationScopes: {
        dataset: "A"
      },
      x: 6, y: 6, w: 6, h: 6
    }
  ],
  initStrategy: "auto"
};

In src/App.js:

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

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

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

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%;
}

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@v3
      - uses: actions/setup-node@v1
        with:
          node-version: 18
      - name: Install NPM dependencies
        run: npm ci
      - name: Build React app
        run: npm run build
      - uses: actions/upload-pages-artifact@v1
        if: ${{ github.event_name == 'push' && github.ref == 'refs/heads/main' }}
        with:
          path: ./build
  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@v1
    

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://keller-mark.github.io/vitessce-demo-gh-pages/.

NodeJS and NPM environment setup​

React app setup​

React app development​

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​