We welcome all kinds of contributions. You don't need to be an expert in frontend or Python development to help out.
Contributions are made through pull requests. Before sending a pull request, make sure to do the following:
- Lint, typecheck, and format your code
- Write tests
- Run tests and check that they pass
Please reach out to the marimo team before starting work on a large contribution. Get in touch at Github issues or on Discord.
You'll need to build marimo from source to edit and test code.
Build dependencies. To build marimo from source, you'll need to have Node.js, pnpm, GNU make, and Python (>=3.8) installed.
- Install Node.js
- Install pnpm with
npm install -g pnpm
- Install GNU Make (you may already have it installed)
- Install Python. (You may already it installed. To see your version, use
python -v
at the command line.)
Build from source. After installing the dependencies, run the following in a fresh Python virtual environment (such as venv or virtualenv):
make fe && make py
make fe
builds the frontend. make py
does an editable install of marimo.
(All make
commands should be run in the project's root directory.)
All checks.
make check
Frontend.
make fe-check
Python.
make py-check
We have frontend unit tests, Python unit tests, and end-to-end tests. Code changes should be accompanied by unit tests. Some changes should also be accompanied by end-to-end tests.
To run all tests:
make test
This can take some time. To run just frontend tests, just Python tests, or just end-to-end tests, read below.
In the root directory, run:
make fe-test
In the root directory, run
make py-test
We use playwright to write and run end-to-end tests, which exercise both the marimo library and the frontend.
(The first time you run, you may be prompted by playwright to install some dependencies; follow those instructions.)
For best practices on writing end-to-end tests, check out the Best Practices doc.
Run end-to-end tests.
In the root directory, run:
make e2e
Run tests interactively.
In frontend/
:
npx playwright test --ui
Run a specific test.
In frontend/
:
npx playwright test <filename> --ui
# e.g.
npx playwright test cells.test.ts --ui
or
npx playwright test --debug <filename>
To open Storybook, run the following:
cd frontend/
pnpm storybook
You can develop on marimo with hot reloading on the frontend and/or development mode on the server (which automatically restarts the server on code changes). These modes especially helpful when you're making many small changes and want to see changes end-to-end very quickly.
For the frontend, you can run either
# starts a dev server on localhost:3000 and proxy requests to your marimo server
# has hot reloading and the fastest way to develop the frontend
# read caveats below
pnpm dev
OR
# OR, in order to test closer to production, you can build the frontend and watch for changes
pnpm build:watch
For the backend, you can start marimo in development mode with
marimo -d edit
- When to run with hot-reloading?: When you are developing on the frontend and want to see changes immediately. This is useful for styling, layout, new plugins, etc. Developing through the Vite server may have inconsistent behavior due to proxied api/websocket request and since the marimo Python server is not serving the HTML.
- When to develop with the frontend in watch mode?: When you are making few frontend changes, or when you want to test the frontend in a way that is closer to production.
- When to run marimo CLI with development mode?: When you are making changes to the backend and you want your changes to be auto-reloaded so you don't have to restart the server every time you make a change. If you are running the frontend in watch mode, you will want to run the marimo server in debug mode so that it will reload on changes.
Caveats for running pnpm dev
Running pnpm dev
will serve the frontend from a Vite dev server, not from the
marimo server. This means that:
- You will want to run your marimo server with
--headless
so it does not open a new browser tab, as it will interfere with the frontend dev server. - You should open an existing notebook instead of creating a new one, as the frontend dev server will not be able to create or save notebooks.
- marimo normally sets the filename, mode, and config. These will be mocked/disabled when running in the frontend in dev mode.
- The tradeoff of using the frontend dev server is that it is faster to develop on the frontend, but you will not be able to test the frontend in the same way that it will be used in production.
If use use vscode, you might find the following settings.json
useful:
{
"editor.formatOnSave": true,
"editor.formatOnPaste": false,
"[typescript]": {
"editor.defaultFormatter": "esbenp.prettier-vscode"
},
"[typescriptreact]": {
"editor.defaultFormatter": "esbenp.prettier-vscode"
},
"prettier.configPath": "./frontend/.prettierrc.json"
}