This repository contains the OpenCloning frontend monorepo, which includes the main React application and shared packages. Before going further, please go to the main project README, where you can find an introduction.
A hosted version of this application can be found at https://opencloning.org/.
This is a monorepo managed with Yarn workspaces:
apps/opencloning/- The main OpenCloning applicationpackages/- Shared packages:@opencloning/store- Redux store and cloning logic@opencloning/ui- UI components@opencloning/utils- Utility functions
If you want to quickly set up a local instance of the frontend and backend of the application using Docker, check getting started in 5 minutes in the main repository.
We use node 22.17, to manage different versions of node, we use nvm. Installation instructions here.
# Install node 22.17 (first time only)
nvm install 22.17
# Activate node 22.17
nvm use 22.17To handle dependencies and build the site, yarn 3 is used.
# Enable yarn 3 in the project (first time only)
corepack enable
# Install dependencies (every time you pull changes)
yarn install
# If you want to serve the development site locally at http://localhost:3000/
yarn start
# If you want to build the static assets of the production site in apps/opencloning/build
yarn buildFor the application to work, you must have a running backend. For that, see the backend installation instructions.
By default, if you run the dev server with uvicorn opencloning.main:app, the backend will be running at http://localhost:8000/. That's where the dev server of the frontend (ran with yarn start) will send the requests to by default.
The backend URL can be changed by setting a different value in the config.json (see next section).
See also connecting to the frontend section in the backend repo.
The configuration of the frontend is done in the file that will be served from /config.json. In the dev server, this file is served from apps/opencloning/public/config.json. That file is not included in the repository, and is generated from apps/opencloning/public/config.dev.json when you run yarn start. For the production site, config.prod.json is used. The things you can configure are:
backendUrl: The URL of the backend. By default, it ishttp://localhost:8000/.showAppBar: Whether to show the top app bar (blue with buttons for examples, etc.). By default, it istrue.noExternalRequests: Whether to block requests to external services. By default, it isfalse.database: For integrations, provide the database name. This is not documented, but for an example seepackages/ui/src/components/eLabFTW.
For production: when building the site with yarn build, simply replace apps/opencloning/build/config.json with your settings. This is what is done in this docker-compose file.
If you want to serve the full site (backend and frontend) with docker, check getting started in 5 minutes in the main repository.
If you want to serve only the frontend from a docker container, an image is available at manulera/opencloningfrontend. The image is built from the Dockerfile in the root of this repository and exposes the port 3000. To run it:
docker pull manulera/opencloningfrontend
docker run -p 3000:3000 manulera/opencloningfrontendCheck contribution guidelines in the main repository.
For the eslint to work, you will need the eslint module
To run the tests, first run the dev server with yarn start.
To run most tests, you will need the backend to be running at http://localhost:8000/. You can see how to do run it in the backend repo. For the github actions tests, a submodule is used (see below).
To run the tests:
# Open cypress UI
yarn cypress open
# Run a particular test in the command line
yarn cypress run --spec cypress/e2e/source_genome_region.cy.js
# Run a few tests in parallel from the command line (edit file if needed)
bash run_tests_in_parallel.sh
# If the tests fail, you can see screenshots of the failed tests in the folder cypress/screenshots
For these, you don't have to run the yarn start command, but you need the backend server as above. To run them:
yarn cypress openThese are run with vitest. To run them:
yarn vitestThe tests run with cypress in github actions require the submodule OpenCloning_backend to be included. If you want to include it locally:
git submodule update --initIf you want to change the commit of the submodule:
cd OpenCloning_backend
git checkout -b the-branch
git pull origin the-branch
cd ..
# commit the frontend repo normallyTo update which files are excluded from coverage, edit the .nycrc.json file.
You can configure website analytics using umami by setting the env var VITE_UMAMI_WEBSITE_ID to the website id. When building the site, the analytics script will be included in the build. See apps/opencloning/index.html and apps/opencloning/vite.config.js to see how this is done (using ejs templating).
Settings (they can also be set as env vars or passed with flags).
module.exports = defineConfig({
video: true,
viewportWidth: 1000,
viewportHeight: 1000,
...Then, when running the video.
CYPRESS_NO_COMMAND_LOG=1 yarn cypress run --spec cypress/e2e/source_genome_region.cy.js
The API keys should be in the ignored file .env.local
Example file:
VITE_ELABFTW_BASE_URL=https://localhost
VITE_ELABFTW_API_READ_KEY=<key>
VITE_ELABFTW_API_WRITE_KEY=<key>To build the image for local testing:
docker build -t manulera/opencloningfrontend:local --build-arg BASE_URL=/opencloning/ .There is probably a better way to do this, but this is what I have found for now.
It can be useful to run scripts to test a few things without running the whole frontend. The only way I have found to do this is running the script as a test.
- Create file with pattern
script.test.js - Run
yarn vitest run script.test.js
The file content should be something like this:
import { ab1ToJson } from '@teselagen/bio-parsers';
import fs from 'fs';
describe('ab1ToJson', () => {
it('should convert an AB1 file to JSON', () => {
const a = 1;
console.log(a);
});
});npx -y yarn-update-indirect form-data
When making changes that affect packages or apps, you need to create a changeset. This documents what changed and helps determine version bumps.
To create a changeset:
yarn changesetThis will prompt you to:
- Select which packages are affected (
@opencloning/store,@opencloning/ui,@opencloning/utils, or apps) - Choose the type of change (patch, minor, or major)
- Write a description of the changes
The changeset file will be created in .changeset/ directory. Commit this file along with your changes.
Note: When creating a PR, you will be warned if no changeset is included for changes that affect packages or apps. This helps ensure all changes are properly documented and versioned.
Packages (@opencloning/store, @opencloning/ui, @opencloning/utils) are automatically released to npm on every commit to master. The release workflow creates a PR with version bumps and changelog updates, and once merged, publishes the packages to npm.
Currently relies on the patch in .yarn/patches/@changesets-cli-npm-2.29.8-52df46efd2.patch to publish to npm, coming from this PR. It's pending on the resolution of this other PR.
For manual publishing:
YARN_NPM_AUTH_TOKEN=<> yarn changeset publish
Apps (like opencloning) are not automatically deployed. They need to be manually released by calling the App Release workflow with the app name (e.g., opencloning). This creates a GitHub release and tag for the app. When you publish the release, the action App Post Release is triggered to build the Docker image and deploy the app to Netlify.
Note that app version numbers will automatically increase when their dependencies (packages) are updated, even if the app itself is not deployed. This ensures version consistency across the monorepo.
For manual releases or when not using the automated workflow:
yarn pre:enter
# make changes
# Create changeset
yarn changeset version
yarn release