Skip to content

Development quickstart

This page describes how to run, test, and develop PrairieLearn. Ensure that you have already installed PrairieLearn either:

Development server

Run the server in development mode to automatically restart when changes are detected:

make dev

In a web-browser go to http://localhost:3000.

To stop the server, use Ctrl+C.

Production build

You can also build and run using pre-compiled versions of the server code to more closely mimic what will happen in production environments. View the running in production setup instructions for more information.

make build
make start

Workspaces

If you need support for workspaces, ensure Docker is installed and running, and then in a separate terminal run:

sudo make dev-workspace-host # or sudo make start-workspace-host
# Make sure to run PrairieLearn as root
sudo make dev

On a macOS native installation, you should set the following in your config.json:

config.json
{
  "workspaceDevContainerHostname": "localhost",
  "workspaceJobsDirectoryOwnerUid": 1001,
  "workspaceJobsDirectoryOwnerGid": 1001
}

More information can be found in the config.json documentation.

Troubleshooting workspaces

You can list the active hosts with:

SELECT * FROM workspace_hosts;

If you see no hosts, the workspace host is not running. If the ready_at column is an older date, the workspace host may also not be running.

Since PrairieLearn manages the workspace files, you need to also run PrairieLearn as root.

Documentation

If you want to preview the documentation, run:

make dev-docs

Testing

If you are contributing code to PrairieLearn, you must ensure that your changes work and pass our style guidelines. More information on debugging and testing can be found on the developer guide. Information on contributing can be found on the contribution guide.

Run the test suite (Docker must be installed and running):

make test-all

Or, to run just a specific subset of tests:

make test-js           # Javascript tests (both packages and applications)
make test-prairielearn # PrairieLearn application tests
make test-python       # Python tests
make test-e2e          # E2E tests (run `make e2e-deps` first)

JavaScript tests

The main JavaScript test suite can take on the order of 10+ minutes to run, so you may only run specific test files as you develop. To run specific test files, you first need to run make start-support to start the database and other services, and then you can run specific test files.

make start-support
cd apps/prairielearn
yarn vitest src/tests/getHomepage.test.ts

Package tests

To test a specific package, you can run yarn test from the package's directory.

cd packages/csv
yarn test

Linting

All changes to PrairieLearn must pass our linters before they get merged.

make lint

Or, to lint only specific kind of files:

make lint-js     # JavaScript only
make lint-python # Python only
make lint-all    # Additional linters

Formatting

You can format + autofix lint errors with:

make fix-js-cached
make format-python

To format all changed files (staged + unstaged + untracked) compared to HEAD:

make format-changed

This is faster than formatting the entire codebase since it only processes files you've modified.

If you develop code with VSCode, running these shouldn't be necessary, as we provide a set of recommended extensions and configuration defaults that will format files on save.

Updating dependencies

If you switch branches, pull new code, or edit Python dependencies, you will need to update the dependencies.

make deps

Working on packages

When working on something in the packages/ directory, you'll need to rebuild the package before any changes will become visible to other packages or apps that use the package. You can build everything with make build, or you can run the dev script in a package to rebuild it automatically whenever there are changes.

# From the root of the repository:
yarn workspace @prairielearn/postgres run dev

# From a specific package directory, e.g. `packages/postgres`:
yarn dev

More information

Most information about development is found in the developer guide. It outlines debugging and testing tips, best practices and style for coding, as well as details about various aspects of PrairieLearn (question rendering, databases schemas, etc.).