https://github.com/zooniverse/front-end-monorepo
A rebuild of the front-end for zooniverse.org
https://github.com/zooniverse/front-end-monorepo
hacktoberfest zooniverse
Last synced: 4 months ago
JSON representation
A rebuild of the front-end for zooniverse.org
- Host: GitHub
- URL: https://github.com/zooniverse/front-end-monorepo
- Owner: zooniverse
- License: apache-2.0
- Created: 2018-04-16T08:34:38.000Z (about 8 years ago)
- Default Branch: main
- Last Pushed: 2026-01-30T23:19:05.000Z (4 months ago)
- Last Synced: 2026-01-31T11:37:41.067Z (4 months ago)
- Topics: hacktoberfest, zooniverse
- Language: JavaScript
- Homepage: https://www.zooniverse.org
- Size: 54.7 MB
- Stars: 109
- Watchers: 10
- Forks: 28
- Open Issues: 256
-
Metadata Files:
- Readme: README.md
- Contributing: docs/CONTRIBUTING.md
- License: LICENSE.md
Awesome Lists containing this project
README
# Zooniverse Front-End Monorepo
[](https://github.com/zooniverse/front-end-monorepo/blob/main/LICENSE.md)
---
**Table of Contents**
- [Requirements](#requirements)
- [Monowhat?](#monowhat)
- [Getting started](#getting-started)
- [Helpful Guides](#helpful-guides)
- [Packages](#packages)
- [Helpers](#helpers)
- [Conventions](#conventions)
- [NPM](#npm)
- [Packages directory](#packages-directory)
- [Deployment](#deployment)
- [License](#license)
## Requirements
- [Browser support](docs/arch/adr-4.md)
- Node 22
- Git
- pnpm
Node, git, and pnpm can be installed through [homebrew](https://brew.sh/) on MacOS. If you need to support more than one version of node at the same time, you can consider installing it though [nvm](https://github.com/nvm-sh/nvm) instead of homebrew
## Monowhat?
This monorepo is managed with pnpm Workspaces
Workspaces allow us to maintain package modularity for javascript projects that have interdependency. Organizationally, they allows us to track issues, pull requests, and progress for all related packages in one place.
## Getting started
### Debugging the production release
Make sure you have pulled the latest production version.
```sh
git pull --tags -f
```
Check out the latest production release.
```sh
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.
```sh
pnpm bootstrap
```
### Docker
You can run the code locally in Docker, which avoids needing to install Node or pnpm.
```sh
git clone git@github.com: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.
```sh
# 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:
```sh
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`.
### With Node and pnpm
Alternatively, you can install Node and pnpm and build the monorepo packages.
```sh
git clone git@github.com: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.
## 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/fe-project** | `packages/app-project` | Server-side rendered application for a project (anything at `/projects/owner/display_name`) |
| **@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 |
## 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
Deploys to production and staging are handled by [Jenkins](https://jenkins.zooniverse.org/job/Zooniverse%20GitHub/job/front-end-monorepo/) using [Docker images](#docker-images).
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 new NextJS app while the rest of sub-domain redirects to PFE. 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. `https://www.zooniverse.org/projects/:project-owner/:project-name/classify` proxy redirects to the new NextJS app while the rest of the domain redirects to PFE. Currently the only project that is configured to do this is Planet Hunters TESS. Eventually more projects will migrate when they migrate to the new classifier.
More information is available in [ADR 12](docs/arch/adr-12.md) and [ADR 17](docs/arch/adr-17.md)
### Deploying Storybook
FEM's storybook can be viewed at [https://zooniverse.github.io/front-end-monorepo/](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`.
### Environment variables
- `PANOPTES_ENV`: sets which Panoptes API endpoint to use.
- `production` will use `https://www.zooniverse.org/api`
- `staging` 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](https://webpack.js.org/configuration/mode/) for libraries and the NextJS apps (production, development or undefined.)
- `APP_ENV`: the deployment environment, logged as the [Sentry environment](https://docs.sentry.io/product/sentry-basics/environments/) 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](https://www.npmjs.com/), first cd into the repo you would like to deploy (within the packages folder), then:
1. Update changelog and commit
1. `pnpm version --major|--minor|--patch --no-git-tag-version` (use the desired semvar here)
1. 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
1. `git push origin name-of-branch`
1. Merge branch
1. Checkout `main`, pull for latest
1. Build the package with `pnpm build` from the package dir, where available
1. 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.