Get in here and contribute to OpenMarch! Learn our stack and codebase here.
We’d reccommend to take a look at all of our tasks, and pick some you’d like to work on. The ones with good first issue and help wanted tags are good for getting started.
Feel free to ask questions in the Discord if you’re having problems with anything.
Download the code via git from the main branch (if you’re contributing, make a fork and clone your own repo): git clone https://github.com/OpenMarch/OpenMarch.git
You might need to download git for this. You can also use other methods like the GitHub CLI
Install dependencies: npm install (may take a while)
You might get a bunch of scary npm errors after installing. If running the app doesn’t work after, follow these steps to fix it.
Run the dev environment: npm run dev
If you see a bunch of errors, you may need to run npm run app:prepare first. More on this in the running tests section
Codebase Structure
Our simplified directory structure:
/electron - The “main” process, the backend of the app, with database and system functionality
/database
/main
/preload - Preload script for IPC
/src - the “renderer” process, this is our react frontend.
/components - In here you find all the components of OpenMarch, the sidebars, titlebar, dialogs, UI component primitives. All of them are in their subfolder.
/context - React Context for the app of some sort of state/value
/global - Classes, objects and functions for various items in the app, such as Page, Marcher, MarcherShape, etc.
/stores - Global stores for certain items and actions, such as the list of Pages and Marchers
App.tsx - the main app file
Most of the directories like stores, context, database also have a __test__ directory. These are Vitest or Playwright tests, which test the functionalites of certain things. Tests are important, please write them!
Running Tests
Since Electron has to rebuild better-sqlite3 (the package used to interact with the database), we must follow a few steps when transitioning between running automated tests and running the app.
Prepare for testing
These steps only apply for tests involving database interactions.
You don’t need to rebuild any packages if you’re only testing frontend components.
If you don’t, though, the entire test suite will not pass.
For frontend specific tests, ignore the steps below and just run npm run test.
Using the Vitest extension in VSCode is also handy.
Close the app if it’s running
Rebuild the better-sqlite3 package
Terminal window
npmruntest:prepare
This will rebuild better-sqlite3 to run on the same version of Node.js that the rest of the packages are on
If the tests didn’t start, run them again
Terminal window
npmruntest
You can see other test scripts in the package.json
Running the app after testing
Since we rebuilt better-sqlite3 with npm, we must rebuild it so that it can run in our Electron main process.
Also do this if you ever see this error. It indicates that better-sqlite3 has not been rebuilt with the same version of Node.js as the Electron main process:
Failed to connect to database:
PLEASE RUN 'node_modules/.bin/electron-rebuild -f -w better-sqlite3' to resolve this
Stop any tests if they are running.
Rebuild better-sqlite3 for Electron
Terminal window
npmrunapp:prepare
This will rebuild better-sqlite3 to run on the same version of Node.js that the Electron main process is on
The app should launch on its own, but if it doesn’t you can run npm run dev to launch it.