{"id":30019664,"url":"https://github.com/veupathdb/web-monorepo","last_synced_at":"2026-05-07T20:11:23.846Z","repository":{"id":146804587,"uuid":"617587365","full_name":"VEuPathDB/web-monorepo","owner":"VEuPathDB","description":"A monorepo that contains all frontend code for VEuPathDB websites","archived":false,"fork":false,"pushed_at":"2026-01-31T18:26:06.000Z","size":567131,"stargazers_count":3,"open_issues_count":286,"forks_count":0,"subscribers_count":15,"default_branch":"main","last_synced_at":"2026-02-01T06:39:16.043Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/VEuPathDB.png","metadata":{"files":{"readme":"README.adoc","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2023-03-22T17:39:45.000Z","updated_at":"2026-01-29T20:07:26.000Z","dependencies_parsed_at":"2026-01-06T11:00:49.965Z","dependency_job_id":null,"html_url":"https://github.com/VEuPathDB/web-monorepo","commit_stats":null,"previous_names":[],"tags_count":541,"template":false,"template_full_name":null,"purl":"pkg:github/VEuPathDB/web-monorepo","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/VEuPathDB%2Fweb-monorepo","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/VEuPathDB%2Fweb-monorepo/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/VEuPathDB%2Fweb-monorepo/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/VEuPathDB%2Fweb-monorepo/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/VEuPathDB","download_url":"https://codeload.github.com/VEuPathDB/web-monorepo/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/VEuPathDB%2Fweb-monorepo/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29047789,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-03T14:55:20.264Z","status":"ssl_error","status_checked_at":"2026-02-03T14:55:19.725Z","response_time":96,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-08-06T01:20:26.283Z","updated_at":"2026-05-07T20:11:23.839Z","avatar_url":"https://github.com/VEuPathDB.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"ifdef::env-github[]\n:note-caption: :information_source:\nendif::[]\n\n= web-monorepo\nThese are instructions to work with the VEuPathDB UI either by executing a single workspace’s yarn script -using the nx task runner- (eg the mblast UI or the EDA UI), or by accessing the complete UI by starting a local site. In both cases a webpack server will be started and a new browser tab will be opened. The backend will be accessed via a remote site stated in your monorepo (packages/sites/*website) .env file.\n:toc:\n\n== Prerequisites\n\nThis project requires a system that can handle **Node.js 18.12+** (most Linux distributions from ~2019 onwards, macOS 10.15+, Windows 10+) and on which you can install https://volta.sh/[Volta] for version management (see https://docs.volta.sh/guide/#installing-volta for system requirements)\n\nThen the installation process detailed below will be able to bootstrap the following:\n\n- **Node.js 24+** (specified in package.json for this project)\n- **Corepack** (a Node.js tool that automatically manages package manager versions)\n- **Yarn 4.12.0** (which itself requires Node.js 18.12+)\n\n== Setup\n\n=== Setup with Volta (Recommended)\n\nhttps://volta.sh/[Volta] is recommended for Node version management. It will automatically use Node 24 when working in this repository.\n\nTo set up Volta with Corepack:\n\n[source, shell]\n----\n# Install volta if you haven't already\ncurl https://get.volta.sh | bash\n----\n\nOpen a new terminal for Volta to take effect\n\n[source, shell]\n----\nvolta install node\nvolta install yarn\nvolta install corepack\ncorepack enable --install-directory ~/.volta/bin\n----\n\nThis configuration allows Volta to manage Node versions while Corepack manages Yarn versions based on the `packageManager` field in `package.json`.\n\n=== Install yarn dependencies\n\nFrom anywhere in the repo:\n\n[source, shell]\n----\nyarn\n----\n\n*Note:* This repository uses immutable installs for security. The `yarn.lock` file must be committed to git and cannot be modified by `yarn install`. Commands like `yarn add \u003cpackage\u003e` and `yarn remove \u003cpackage\u003e` work normally and will update the lockfile as expected. This prevents accidental mass upgrades (e.g., deleting and regenerating yarn.lock would upgrade many packages to newer versions). All dependency upgrades should be intentional and reviewed.\n\n=== Set up git hooks\n\nA pre-commit hook will run `prettier` to normalise formatting of files touched by the commit. This irons out inter-developer IDE formatting differences and is essential to avoid confusion and uninformative formatting-only diffs in the history.\n\nRun this once after cloning to enable pre-commit formatting checks:\n\n[source, shell]\n----\nnpx husky install\n----\n\nNOTE: `yarn install` only runs the `postinstall` script in `package.json` when the dependency tree changes, so new clones won't get the hooks automatically. **You must run `npx husky install` manually once per clone.**\n\n== Development on Cedar Server\n\nFollow the instructions above in a regular terminal (not a dev site environment after sourcing `etc/setenv`) to set up Volta, Node, Yarn and Corepack.\n\nTo work smoothly in a dev site environment (any time after sourcing `etc/setenv`), you need to address a PATH configuration issue that can shadow Volta's yarn with an older system version.\n\n=== The Issue\n\nIntranet dev site configurations use `etc/setenv` scripts that prepend legacy paths to PATH. This causes the system's old yarn to take precedence over Volta's managed version, breaking the build.\n\n=== The Fix\n\nChoose one of these approaches:\n\n*Option 1: Using a helper shell function in regular workflow (Recommended)*\n\nAdd this function to your shell profile (`~/.bashrc`, `~/.zshrc`, etc.):\n\n[source, bash]\n----\n# Prepend directory to PATH, moving it to front if already present elsewhere\npath_prepend() {\n  case \"$PATH\" in \"$1\":*|\"$1\"|\"\") PATH=\"$1\"; return ;; esac  # already first or empty\n  PATH=\":$PATH:\"          # add sentinels for matching anywhere\n  PATH=\"${PATH//:$1:/:}\"  # remove exact match (colon-bounded)\n  PATH=\"$1$PATH\"          # prepend (leading colon already exists)\n  PATH=\"${PATH%:}\"        # strip trailing colon\n}\n----\n\nThen update your standard workflow to include one additional step after sourcing `etc/setenv`:\n\n[source, shell]\n----\n# 1. Start terminal session\n# 2. cd /var/www/PlasmoDB/plasmo.bmaccallum\n# 3. source etc/setenv\n# 4. Restore Volta to front of PATH:\npath_prepend ~/.volta/bin\n----\n\nThis avoids modifying shared files and is easy to remember.\n\n*Option 2: Edit etc/setenv directly*\n\nEdit your dev site's `etc/setenv` file (typically `$BASE_GUS/etc/setenv`) to append instead of prepend:\n\n[source, bash]\n----\n# Change from:\nexport PATH=$GUS_HOME/bin:$PROJECT_HOME/install/bin:$PATH\n\n# To:\nexport PATH=$PATH:$GUS_HOME/bin:$PROJECT_HOME/install/bin\n----\n\nThis ensures Volta's yarn (from `~/.volta/bin`) remains first in PATH.\n\n=== Package Manager Verification\n\n*IMPORTANT:* This project requires Yarn. Using `npm install` will fail with dependency resolution errors because this monorepo uses Yarn-specific features (workspace protocol, etc.) that npm doesn't support.\n\nCorepack enforces the correct Yarn version automatically via the `packageManager` field in `package.json`. If you see errors about wrong Yarn version, refer to the setup instructions above.\n\n== Overview\n\nThis repository is a \"monorepo\", using the https://nx.dev[nx] build system and https://yarnpkg.com/[yarn@4] dependency manager. The source code is divided into one of three types of packages: \"config\", \"lib\", and \"site\".\n\n- \"config\" packages (`./packages/configs`) include various build and development configurations and tools.\n- \"lib\" packages (`./packages/libs`) include standalone library and webapp source code.\n- \"site\" packages (`./packages/sites`) include complete website source code.\n\nMany \"lib\" and \"site\" packages include development tools, such as development servers, test scripts, etc.\n\nMany commands require a reference to the package name. All package names are currently prefixed with `@veupathdb/`. For example, the eda package name is `@veupathdb/eda`.\n\nThe repository is currently configured as a \"package based repository\". This is subject to change, in the future (see https://nx.dev/concepts/integrated-vs-package-based to read about the differences between package based and integrated repos).\n \n== Common Tasks\n\nThe following tasks are common performed by developers. This serves as a reference guide, and is not exhaustive in any way. If you feel something is missing, create an issue, or open a pull request.\n\n_All commands are expected to be run in the repository's root directory, unless otherwise specified._\n\n=== Start a local dev site\n\n\"Site\" projects are stored in the `packages/sites` directory. Each one corresponds to a \"cohort\". For example, `packages/sites/genomics-site`\ncontains the code used to build the client code for a genomics website.\n\nEach cohort contains a `.env.sample` file. Copy this to a sibling `.env` file. You may need to modify some values, such as usernames,\npasswords, etc. You can also specify a website to use for various services. Typically a deployed QA site will suffice, but you can also run a \"local backend\" via various methods. (TODO: link to relevants docs/repos).\n\nOnce you have created a `.env` file, you can run the local dev site with the command:\n\n[source, shell]\n----\nyarn nx start \u003cpackage name\u003e\n----\n\nFor example, if you want to run a local clinepi site, you would run the command:\n\n[source, shell]\n----\nyarn nx start @veupathdb/clinepi-site\n----\n\nOnce the website has been compiled, the dev server will output some build statistics and automatically open a browser tab. You can kill the local dev server with `CTRL-C` in the terminal where you started it. \n\n=== Modifying code (and updating a running local dev site)\n\nWhen a local dev site is running, it will detect when build dependencies are updated and reload the active webpage.\n\n__Note: the following refers to code tracked by the monorepo, and not third-party dependencies from npm.__\n\nThere are two types of souce code that can be updated:\n\n1. Source code within the package being served.\n2. Source code within a dependent package.\n\nChanges to code within the package being served will be detected automatically. The local dev service should reompile the affected module and reload the website without intervention.\n\nChanges to code within a dependent workspace package will require a build command for the local dev server to detect the change.\n\nFor example, if you change code in `packages/libs/eda`, you will need to run this command in a new terminal window, from the repository root:\n\n[source, shell]\n----\nyarn workspace @veupathdb/eda build-npm-modules\n----\n\nOnce this command completed, the running dev server will see the updated build artifacts, recompile the website, and reload the webpage. There are some cases where this might not work as expected, such as if the recompile step fails. In those cases, you may need to restart the local dev server. You can monitor the progress of the recompilation step in the terminal where you started the dev server.\n\n=== View workspace dependency graph\n\nFrom the root `package.json`:\n\n[source, shell]\n----\nyarn nx graph\n----\n\n=== Execute a workspace's yarn script using the `nx` task runner\n\nFrom the root `package.json`:\n\n[source, shell]\n----\nyarn nx run \u003cworkspaceName\u003e:\u003cscriptName\u003e\n----\n\nFor example, you can start the MultiBLAST dev server by running\n\n[source, shell]\n----\nyarn nx run @veupathdb/multi-blast:start\n----\n\n=== Rebuild dependencies when running a development server\n\nWhen running a development server (such as `yarn nx start @veupathdb/eda` or `yarn nx start @veupathdb/clinepi-site`),\nuse the following command to rebuild changes made to dependencies, and to have the dev site reload with the changes:\n\n[source, shell]\n----\ncd packages/libs/\u003cpackage\u003e\nyarn build-npm-modules\n----\n\n**Note: You may need to manually reload your website to see the changes the first time.**\n\n_Using the equivalent `nx` command (`yarn nx build-npm-modules @veupathdb/\u003cpackage\u003e`) has proven inadequate in this scenario._\n\n== Notes on individual packages\n\n=== EDA dev server\n\nDirectory: `packages/libs/eda`\n\nYou will need to configure the server with a `packages/libs/eda/.env.local` file that sets various environment variables.\n\nFor more documentation see the link:packages/libs/eda/README.md[package README] and link:packages/libs/eda/.env.local.sample.localservices[this sample file].\n\n=== VEuPathDB sites\n\nDirectory: `packages/sites/{site name}-site`\n\nCopy the `packages/sites/{site name}-site/.env.sample` file to `packages/sites/{site name}-site/.env` and configure the new file with passwords and the desired backend for the site.\n\nRun `yarn` to update dependencies if necessary.\n\nRun the command `yarn nx start @veupathdb/{site name}-site`. For example, to run the ortho site use `yarn nx start @veupathdb/ortho-site`.\n\n== IDE hints\n\n=== emacs tide\n\nIf it is showing errors for tsx imports (especially in `eda`) and\n`tide-verify-setup` mentions tsserver version 3.x then it is time to\nupgrade emacs tide (to, at time of writing 4.5.4):\n\n[source]\n----\nM-x package-reinstall \u003cret\u003e tide \u003cret\u003e\n----\n\n== Client Bundle Server 🐉\n\n**Warning. There be dragons! This section has not been maintained for a long time.**\n\nThe Client Bundle Server is a Docker image based on NGINX that is used to serve\nVEuPathDB client code over HTTP.\n\nAs the client code comes in 2 flavors (bundles), legacy and modern, this NGINX\nserver has an internal path rewrite based on the requesting browser's user agent\nstring to the appropriate client bundle component on request.\n\nThis means using a modern browser, requesting the file\n`genomics/site-client.bundle.js` will cause the server to actually return\n`modern/genomics/site-client.bundle.js` whereas requesting that same file from\nan older or unsupported browser (such as CURL or Postman) the server will return\n`legacy/genomics/site-client.bundle.js`.\n\n=== Browsers\n\nWhether a browser is considered modern or legacy is dependent on the version of\nthe browser compared to a RegEx constructed by the\nlink:https://github.com/browserslist/browserslist-useragent-regexp[browserslist-useragent-regexp]\nlibrary using the input query constructed in the\nlink:packages/configs/browserslist-config[browserslist-config] package of\nthis repo.  (See link:packages/configs/browserslist-config/index.js[index.js]\nfor the raw queries)\n\n=== Docker Image\n\nThe docker image is based on NGINX-Perl and includes NodeJS for executing a\nscript based on\nlink:https://github.com/browserslist/browserslist-useragent-regexp[browserslist-useragent-regexp]\nthat determines which path a specified file should be served from.\n\nThe image build is multi-staged with the first stage compiling primary contents\nof this repository, and the second stage setting up NGINX and the secondary JS\nscript included in the link:docker/[docker] directory\n(link:docker/makeSupportedBrowsersScript.js[makeSupportedBrowsersScript.js]).\n\n=== Paths\n\nContent is served from the following paths from the root path used to reach a\nrunning instance of the built Docker image:\n\n[source]\n----\n{URL}/clinepi/{target-file}\n{URL}/genomics/{target-file}\n{URL}/mbio/{target-file}\n{URL}/ortho/{target-file}\n----\n\nThese paths correspond to the following container internal paths:\n\n[source]\n----\n/var/www/legacy/clinepi/{target-file}\n/var/www/modern/clinepi/{target-file}\n\n/var/www/legacy/genomics/{target-file}\n/var/www/modern/genomics/{target-file}\n\n/var/www/legacy/mbio/{target-file}\n/var/www/modern/mbio/{target-file}\n\n/var/www/legacy/ortho/{target-file}\n/var/www/modern/ortho/{target-file}\n----\n\n=== Testing\n\nThe Docker image may be tested locally by performing the following steps from\nthe link:docker/[docker/] subdirectory:\n\n. Build and Start the image:\n+\n[source, shell]\n----\nmake docker-build\nmake docker-run\n----\n\n. Using your favorite HTTP request making tool such as Postman, CURL, or a web\nbrowser, make a request to\nhttp://localhost/genomics/site-client.bundle.js.LICENSE.txt . If the service is\nworking you should receive a LICENSE text file's contents as the response with\na 200 status code.  If it is not working you will receive a 403 or 404 error.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fveupathdb%2Fweb-monorepo","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fveupathdb%2Fweb-monorepo","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fveupathdb%2Fweb-monorepo/lists"}