This monorepo contains code for most of BlueDot Impact's custom software. Reading this README carefully can save you a lot of time.
This includes:
The following key parts of our software are not in this repository because they are built in 3rd party services that are hard to open-source the code for:
The following key parts of our software are not in this repository because they use substantially different toolchains, and are a pain to set up in a monorepo:
We welcome contributions! To help improve BlueDot Impact's software:
For simple edits e.g. typos or editing documentation, you should be able to search for the text in this repository and make edits in the GitHub UI.
For more complex edits, check you have the core skills to contribute, then follow the developer setup instructions below.
If you run into any difficulties, raise an issue or contact us.
We recommend most contributors learn how to:
brew install gitsudo apt install -y git-allbrew install nodecurl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash - && sudo apt-get install -y nodejsbrew install dockerbrew install colima && brew services start colima && docker context use colimabrew install kubectlbrew install --cask visual-studio-codegit clone git@github.com:bluedotimpact/bluedot.git npm installThen find the app or library you want to contribute to. It should follow the general package structure. Usually this means you can change directory into the relevant folder, put any necessary values in .env.local (if present), before editing code in src, run
npm run startor
npm run testSome packages have their own README with further developer setup instructions specific to that app, plus useful information about how the app works. Read this!
Over time other people will make changes to the repository. Usually to get up to date with those changes, you'll need to pull the latest changes from the master branch, then re-run
npm installThis repository is split up into packages in the folders:
libraries: code that is reused or shared across applicationsapps: final products that actually get deployed, usually as web servicesFor example, the shared UI code for common components like buttons is a library. This would be consumed by multiple apps, such as the time availability form.
Inside each package folder, the common files you'll find are:
package.json: defines the NPM scripts, dependencies, and sometimes other package configuration. The package.json should usually identify the entrypoint (for libraries) or have at least a start script (for apps). Common scripts include:
npm run start: Start the application locally. The port should usually be printed to the terminal, and then you can visit localhost:<port> in your browser e.g. localhost:8000.npm run test: Run automated tests, usually defined the files ending in .test.ts or .test.tsx. Most packages use vitest - see the vitest CLI docs for help.npm run test:watch: Run the automated tests in an interactive watch mode. This runs the relevant tests automatically each time you edit the code.npm run lint: Check for lint issues. Visual Studio Code should usually highlight these for you already.npm run build: Build the application. This usually finds any type errors, which Visual Studio Code should usually highlight for you already.npm run postinstall: Perform any extra steps to setup the application for development. Usually things like creating configuration files for local development. You usually don't need to run this manually, as it runs when you run npm install.npm run deploy:prod: Actually deploy the app into the production (real-world) environment. You usually don't need to run this manually, as it is run by CD tooling when you merge your changes into the master branch.README.md: documentation to explain what the package does, how to use it, and how to contributesrc: most of the code usually lives here. You usually want to edit files in this folder.
pages: pages in the web app. For example pages/some-page.tsx usually corresponds to app.bluedot.org/some-page. The api folder contains API routes rather than webpages (learn more in the Next.js docs).components: components reused within the web app. If the component is likely to be useful for multiple applications, consider moving it to the ui package.lib: helper scripts for use around the application, that aren't componentsindex.ts: usually the entrypoint, i.e. what runs when starting or deploying an app, or the what is imported when importing a library.public: static files for web hosting directly, usually fonts or images .env.*: environment files, usually to set secrets or configuration.
.env.local: for local development, e.g. when running npm run start. This isn't synced to git, so you can put real secrets in here. If you have issues with your environment, try deleting this file and running npm install again (maybe save the values first if they're important secrets!) - this should usually replace it with the template file..env.local.template: intended to help people create their own .env.local file. This is synced to git, so you should only put example or non-secret values here..env.test: for the test environment, e.g. when running npm run test.tools: custom tools helpful for developing the app, often referred to by NPM scripts.Dockerfile: (apps only) code to help transform the package into a Docker container to be easily deployed.dist, .turbo: built or transformed outputs are put here. You can usually ignore this folder.node_modules: any special dependencies for this specific package, that can't be put at the workspace root usually because of clashing versions. You can usually ignore this folder.In terms of tools and external libraries, we usually use:
tools folder)yyyyMMdd.hhmmss.git_short_hash (via environment variable VERSION_TAG).className util: clsxIn general, we try to keep to the above structure and tools as much as possible between packages. This reduces the mental effort required to switch between working on different packages, and eases maintenance burden. We're fans of boring technology.