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 v14.0.0 and NPM v6.14.16.

node --version

npm install -g npm@6.14.16
npm --version

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 craco which enables customization of the Webpack configuration:

npm install @craco/craco@5.8.0 --save-dev

Install Vitessce:

npm install vitessce --save

Create a new file craco.config.js with the following contents (see the Vitessce README for why this is required):

module.exports = {
  webpack: {
    configure: {
      resolve: {
        alias: {
          'txml/txml': 'txml/dist/txml',
        },
      },
    },
  },
};

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';
import 'vitessce/dist/es/production/static/css/index.css';

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

jobs:
  deploy:
    runs-on: ubuntu-18.04
    name: Build React app and deploy to GitHub Pages
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-node@v1
        with:
          node-version: 14
          registry-url: https://registry.npmjs.org/
      - name: Install NPM dependencies
        run: npm ci
      - name: Build React app
        run: npm run build
      - name: Deploy docs to gh-pages branch
        uses: alex-page/blazing-fast-gh-pages-deploy@v1.1.0
        with:
          repo-token: ${{ secrets.GH_TOKEN }}
          site-directory: build

Create a Personal access token

To allow the GitHub Action to modify the gh-pages branch of the repository, we need to provide it with a Personal access token that has the appropriate permissions. This can be generated in GitHub by going to the user Settings page and then Developer settings (or https://github.com/settings/tokens).

Click "Generate new token" (which may require you to log in).

Provide a name and update the expiration date appropriately.

Under "Select scopes", check repo (the sub-checkboxes should then be checked automatically).

Once the token has been generated, copy it to somewhere safe to keep track of it.

Set the Personal access token as a Repository secret

In the GitHub repository's Settings tab, go to Security > Secrets > Actions.

Click the "New repository secret" button.

Name the secret GH_TOKEN, and provide the Personal access token as the value.

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​

Create a Personal access token​

Set the Personal access token as a Repository secret​

Set the homepage property in package.json​

Commit and push to GitHub​

Test the deployment​

Complete example​