Welcome to the OpenPRA Monorepo, the unified codebase for the OpenPRA application suite. This repository uses the Nx build system, which encapsulates and manages a collection of packages. Together, these packages facilitate the maintenance of OpenPRA App, including the frontend, backend, wrappers for underlying C/C++ engines, shared TypeScript definitions, and utility packages for common functions.
For instance, the mef-schema
package centralizes the
OpenPRA-MEF (Model Exchange Format) definitions,
while the
shared-types
package leverages these definitions to create TypeScript types
and other shared data structures.
Additional documentation can be found in the Extended README section.
Included within this monorepo are the following packages:
engine-scram-node
: Node.js wrappers for theSCRAM
C/C++ engine.frontend-web-editor
: A React v18 and TypeScript-based frontend UI.mef-schema
: OpenPRA MEF JSON Schema definitions.model-generator
: A tool for creating models from predefined schemas.shared-types
: Shared TypeScript definitions for consistent data structuring.web-backend
: A NestJS and TypeScript backend service.
Before setting up the project, please ensure the following tools are installed on your system, instructions for which are provided in the following sections.
pnpm
(Package Manager)nvm
(Node Version Manager)- Node.js
lts/iron
- MongoDB (for hosting a database)
- [Optional] Native Mongo App
- [Optional] Docker Desktop & Compose
- A Chromium-based web browser (for debugging in-browser Javascript with breakpoints)
- React Developer Tools
- Linux: Installation instructions can be found here.
- Windows: Download and install nvm-setup.exe.
- MacOS: Install Homebrew if not present with
/bin/bash -c "$(curl -fsSL https://github.com/raw/Homebrew/install/master/install.sh)"
- then
brew install nvm
Once installed, nvm
can be used to download and use the node
version of
choice. Install it using nvm
with the
following commands:
nvm install 20.9.0
nvm use 20.9.0
- Windows:
winget install pnpm
. - macOS: Install Homebrew if not present with
/bin/bash -c "$(curl -fsSL https://github.com/raw/Homebrew/install/master/install.sh)"
- then
brew install pnpm
- Linux: Refer to the PNPM installation guide for your distribution.
Choose one of the two options below, not both!
-
- Install the Docker Desktop app for your OS.
- Then, follow the instructions to install Docker Compose v2.
- Be sure to skip the
Native App
step in this case.
-
- For ease of development on Linux/MacOS, we have typically been
using
Docker
anddocker compose
to spin up MongoDB. - However, you can also just download MongoDB for your OS and run it directly. If you intend to do this, follow the official MongoDB installation guide for your OS.
- For ease of development on Linux/MacOS, we have typically been
using
- Install the React Developer Tools for your browser.
- Verify the installation by going to the React Website and opening
Developer Tools
on your Browser. - You should have two additional tabs along with the already present ones -
Profiler
andComponents
.
Once prerequisites are installed, initialize the project with these commands:
pnpm setup
pnpm install
pnpm install --global nx@17.1.2
nx migrate 17.1.2
pnpm install --no-frozen-lockfile
## if migrations.json was created, run:
nx migrate --run-migrations
For Windows users experiencing issues with nx
, adjust the PowerShell script
execution policy:
Set-ExecutionPolicy -ExecutionPolicy Bypass -Scope Process
Review the WebStorm Config - Prettier & ESLint README.
Using one of the two options below, spin up an instance of the database
-
- Set up a Docker-managed database environment with:
docker compose -f docker/docker-compose.yml up -d
- Set up a Docker-managed database environment with:
-
- You will need to figure out how to start the mongo server.
To debug the frontend in JetBrains WebStorm using nx
scripts:
- Open the project in WebStorm.
- Go to
Run
>Edit Configurations
. - Add a new
Nx
configuration by choosing theweb-backend
. - Save the configuration.
- Click the run icon to start the backend server. Once up, the debugger will attach to the running process.
To debug the backend in JetBrains WebStorm using nx
scripts:
- Open the project in WebStorm.
- Navigate to
Run
>Edit Configurations
. - Create a new
Nx
configuration for theweb-editor
. - Save and run the configuration.
- Set up browser debugging following WebStorm's guide.
To debug any other build targets, or CommonJS
, Typescript
, or Node.js
packages, follow these general steps:
- Open the project in WebStorm.
- Go to
Run
>Edit Configurations
. - Click the
+
button to add a new configuration. - Choose
Node.js
for CommonJS or Node.js packages, orTypeScript
for TypeScript packages. - In the
JavaScript file
field, specify the path to the file you want to run or debug. - For Node.js applications, you can also specify environment variables, node parameters, and the working directory if needed.
- Save the configuration by clicking
OK
. - Click the run icon to start the application or the debug icon to start debugging.
You can always use the command line to serve or build any of the targets. nx
supports a wide range of commands, so be
sure to check out its documentation.
Some very basic examples include:
- Serve packages concurrently
nx run-many -t serve --all
- Serve packages individually:
nx serve web-editor
nx serve web-backend
nx serve shared-types
- Run Jest unit tests and linting across the project with:
nx run-many -t test
- Run ES linting across the project with:
nx run-many -t lint
When working within the monorepo, it's important to understand the distinction
between scoped packages and workspace-related packages.
Scoped packages are those that are specific to a particular package within the
monorepo, while the workspace package is the one defined
by the package.json
at the repo root.
To install a new package, use the following commands:
- For scoped packages (specific to a project):
pnpm --filter=<project-name> install --save-exact <package-name>
- For workspace-related packages (global to the monorepo):
pnpm -w install --save-exact <package-name>
The --save-exact
flag is enforced to ensure that the exact version of a
package is installed, which helps in maintaining consistency
and avoiding issues with minor updates that may introduce breaking changes.
When installing packages, you also need to decide whether to use --save-dev
or --save
:
- Use
--save-dev
(or-D
) for packages that are only needed during development or for building the project, such as linters, type definitions, or compilers.pnpm --filter=<project-name> install --save-dev --save-exact <package-name>
- Use
--save
(or no flag) for packages that are required at runtime by your package.pnpm --filter=<project-name> install --save --save-exact <package-name>
For package specific testing documentation, refer to the package's corresponding README.md file.
- If dependency issues arise, check for proper camel casing in frontend component filenames and adjust as necessary.
- If
docker compose
fails to work, you can confirm that your configuration is valid by runningdocker compose -f docker/docker-compose.yml config
This project is under the GNU AGPLv3 license, which requires that any networked use of a modified version of the software must make the source code available. For more information, visit AGPL-3.0 license details.