Zooniverse Front-End Monorepo
Table of Contents
Monowhat?
Learn more about this codebase in its Wiki.
This monorepo is managed with pnpm Workspaces. Workspaces allow us to maintain package modularity for javascript projects that have interdependency. Organizationally, they allow us to track issues, pull requests, and progress for all related packages in one place.
Requirements
Node, git, and pnpm can be installed through homebrew on MacOS. If you need to support more than one version of node at the same time, you can consider installing it though nvm instead of homebrew
Getting started
Debugging the production release
Make sure you have pulled the latest production version.
git pull --tags -f
Check out the latest production release.
git checkout production-release
Run the bootstrap script to build all the libraries and apps. You can use bootstrap:es6 here for a faster build if you don't want to run the tests.
pnpm bootstrap
With Node and pnpm
You can install Node and pnpm and build the monorepo packages.
git clone [email protected]:zooniverse/front-end-monorepo.git
cd front-end-monorepo
pnpm bootstrap
The bootstrap script will install the dependencies and build any local packages used as dependencies.
With Docker
Alternatively, you can run the code locally in Docker, which avoids needing to install Node or pnpm.
git clone [email protected]:zooniverse/front-end-monorepo.git
cd front-end-monorepo
# build first
docker compose build
# run all services in the background (no authentication available)
# app-project at http://localhost:3002/projects/[owner]/[project-name]
# app-root at http://localhost:3003
docker compose up -d
# shut down the running containers when you're finished
docker compose down
You can supply a service name (from docker-compose.yml) to docker compose if you only want to run a single service eg.
# only build the project app
docker compose build fe-project
# only run the project app
docker compose up -d fe-project
Development environments for individual packages can be run from the package directories. See the READMEs in individual packages for detailed instructions. For example:
cd packages/app-project
docker compose build
docker compose up -d
docker compose down
Tip: If you're an occasional Docker Desktop user, remember to docker image prune or docker system prune.
Packages
See each package's folder for more specific documentation.
| package name | folder | description |
|---|
| @zooniverse/async-states | packages/lib-async-states | Frozen object of async states to use in data stores |
| @zooniverse/classifier | packages/lib-classifier | Classifier view components and state which can be exported modularly or altogether as a working classifier |
| @zooniverse/content | packages/lib-content | Library of components used in content pages such as About Zooniverse, Get Involved, Policies, and signed-out Homepage |
| @zooniverse/fe-project | packages/app-project | Server-side rendered application for a Zooniverse project (anything at /projects/owner/display_name) |
| @zooniverse/fe-root | packages/app-root | Server-side rendered application for all Zooniverse routes other than those in app-project |
| @zooniverse/grommet-theme | packages/lib-grommet-theme | The style definitions for a Zooniverse theme to use with Grommet |
| @zooniverse/panoptes-js | packages/lib-panoptes-js | Panoptes API javascript client. Functional HTTP request helpers built on top of superagent |
| @zooniverse/react-components | packages/lib-react-components | A set of Zooniverse-specific React components, built using Grommet |
| @zooniverse/subject-viewers | packages/lib-subject-viewers | A library of subject viewer UI components. For now, this library contains only the VolumetricViewer. |
| @zooniverse/user | packages/lib-user | A library for the Zooniverse user stats, user group stats, and user-related components of the home page. |
Conventions
NPM
All packages built from this monorepo should be scoped to zooniverse, e.g. grommet-theme becomes @zooniverse/grommet-theme.
packages directory
Libraries for publishing to NPM should have their directory names prefixed with lib-, e.g. /grommet-theme becomes /lib-grommet-theme.
Apps should have their directory names prefixed with app-, e.g. /project becomes /app-project.
Deployment
Deployments to a staging Kubernetes instance that uses Panoptes production are triggered by merges to main. This is used for manual end-to-end behavior testing for new code and design reviews. https://frontend.preview.zooniverse.org/projects/:project-owner/:project-name/ proxy redirects to the NextJS app. Staging projects can be loaded by adding this query param to the URL: ?env=staging.
Deployments to a production Kubernetes instance are triggered by committing a production-release git tag on main. This can either be done using the git CLI or using the lita deploy command on slack.
More information is available in ADR 12 and ADR 17
Deploying Storybook
FEM's storybook can be viewed at https://zooniverse.github.io/front-end-monorepo/.
To deploy the latest version FEM's storybook, make sure you have pulled the latest production version and run pnpm bootstrap then pnpm deploy-storybook. This command is included when using lita deploy for FEM in Slack.
Environment variables
PANOPTES_ENV: sets which Panoptes API endpoint to use.
production will use https://www.zooniverse.org/apistaging will use https://panoptes-staging.zooniverse.org/api.
The pnpm build scripts default to production for libraries if PANOPTES_ENV is not specified. The apps are always built to the production API.
NODE_ENV: the webpack build mode for libraries and the NextJS apps (production, development or undefined.)APP_ENV: the deployment environment, logged as the Sentry environment with errors:
development: local development on localhost or local.zooniverse.org.branch: PR branch deploys on fe-project-branch.preview.zooniverse.org.staging: staging on frontend.preview.zooniverse.org.production: the Zooniverse web site, www.zooniverse.org.
CONTENTFUL_ACCESS_TOKEN: access token for the Contentful API. Should be kept secret.CONTENTFUL_SPACE_ID: space ID for Zooniverse About pages in Contentful. Should be kept secret.NEWRELIC_LICENSE_KEY: License key for New Relic logging. Should be kept secret.COMMIT_ID: the latest git commit hash. Used for versioning Sentry releases and recorded in classification metadata.
Docker images
zooniverse/front-end-monorepo-staging: Built from the Dockerfile in the root directory. It runs pnpm install and builds all the libraries and apps from the latest main branch commit.zooniverse/front-end-monorepo-production: Built from the Dockerfile in the root directory. It runs pnpm install and builds all the libraries and apps from the production_release tag.
Publishing
When publishing an individual package to npm, first cd into the repo you would like to deploy (within the packages folder), then:
- Update changelog and commit
pnpm version --major|--minor|--patch --no-git-tag-version (use the desired semvar here)- Update other packages to reference the newly updated package version
- Ex: If updating lib-react-components to 1.0.0 from 0.7.2
- lib-classifier should point to the new 1.0.0 version of lib-react-components
git push origin name-of-branch- Merge branch
- Checkout
main, pull for latest
- Build the package with
pnpm build from the package dir, where available
- Publish using
npm:
- Sanity check: if you're using
nvm (Node Version Manager), make sure you've switched to the latest version of node/npm
- Check that you're publishing the correct version by running
npm publish --dry-run from the package dir
- When you're happy, run
npm publish from the package dir
- You can optionally login to npm prior to this using
npm login and store an auth token in a .npmrc file
License
Copyright 2018 Zooniverse
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
