Serverpod is built by the community for the community. We welcome contributions from everyone, regardless of your experience level. This document will guide you through the process of contributing to the Serverpod project.
There are multiple ways to contribute to the Serverpod project. Here are some of the most common ways:
- Code: Contribute code to the Serverpod project.
- Documentation: Contribute to the Serverpod documentation.
- Support: Help others get started or expand their Serverpod projects.
- File issues: Suggest new features or improvements to Serverpod.
Serverpod's roadmap outlines the features and improvements that are planned for the project. The roadmap is subject to change, but provides a good overview over work in progress and what is planned for the future.
If you are considering contributing code to Serverpod, please check the roadmap to see if your contribution aligns with the project's goals.
Pull request are very much welcome. If you are working on something more significant than just a smaller bug fix, please declare your interest on an issue first. This way we can discuss the changes to ensure that they align with the project's goals and prevent duplicated work.
A good starting point is to look at our list of good first issues. These are issues that are relatively easy to fix and are a good way to get started with the project.
We understand that many contributors use AI tools to brainstorm, summarize, or speed up implementation work. That is fine, but please treat those tools as assistants, not as substitutes for your own judgment.
If you submit an AI-assisted pull request, please make sure that you:
- Understand the code you changed and can explain why the implementation is correct.
- Respond to reviewer questions and comments yourself. Code review is a conversation between humans, and you should be able to explain and defend the design and behavior of your changes.
- Have validated the behavior yourself, including relevant tests and edge cases. You are the first reviewer of your own changes.
- Keep the scope manageable for your familiarity with the codebase. If you are new to a repository of this size, starting with smaller changes is usually the best way to contribute successfully.
- Submit only changes that you have personally reviewed, understood, and judged to be correct.
If a pull request shifts the work of judging agent-generated changes onto the reviewer, the contributor is acting as a proxy for the agent rather than taking responsibility for the change. This consumes more time from reviewers and harms progress for the entire community.
We may decline contributions that appear to be low-quality, unreviewed AI output, or changes that the author cannot reasonably verify and maintain. This is not meant to discourage new contributors, but to keep the project healthy and reviewable for everyone.
Serverpod is a large project and contains many parts. Here is a quick overview of how Serverpod is structured and where to find relevant files required to contribute.
Here, you find the core serverpod Dart packages.
serverpod: Contains the main Serverpod package, the ORM, basic authentication, messaging, and cache. It also contains the endpoints of the Serverpod Insights API.serverpod_client: Classes used by the generated client, these are not generated by the CLI tooling.serverpod_flutter: Client code that relies on Flutter. It contains implementations of classes defined inserverpod_client.serverpod_serialization: Code for handling serialization, which is shared between theserverpodpackage andserverpod_client.serverpod_service_client: This is the generated API for Serverpod Insights.serverpod_shared: Code that is shared between serverpod and Serverpod's tooling (i.e.,serverpod_cli).serverpod_test: Contains code used by the test framework.
The templates directory contains templates for the project.
serverpod_templates: Contains templates used when creating a new project with theserverpod createcommand.pubspec_templates: Templates for the pubspec files in the repository. To generate the real pubspec files from the templates, use theutil/update_pubspecsscript.
Here, you will find the code for Serverpod's tooling.
serverpod_cli: Serverpod's command line interface. The CLI also contains code for Serverpod's analyzer and code generation.serverpod_vs_code_extension: The VS Code extension is built around the CLI.
These are 1st party modules for Serverpod. Currently, we maintain an authentication module and a chat module. Modules contain server, client, Flutter code, and definitions for database tables.
These are integrations for 3rd party services, such as Cloud storage.
Here, you will find example projects that demonstrate how to use Serverpod.
This directory contains tests for the Serverpod project.
bootstrap_project: Tests that validate that all variations of a project can be created and run.docker: Docker configuration required for running the tests.serverpod_cli_e2e_test: End to end tests for the CLI.serverpod_test_server: Contains tests that require a complete Serverpod project. The folder contains tests from both the client and server side.serverpod_test_flutter: Contains tests for Flutter components used by the client.serverpod_test_client: Tests that only require the client.serverpod_test_module: General module tests.
Below is a list of tools required to contribute to Serverpod.
- Dart: Serverpod is written in Dart, so you need to have Dart installed on your machine. You can download Dart from the Dart website.
- Flutter: Some parts of the project require Flutter to be installed on your machine. You can download Flutter from the Flutter website.
- Docker (optional for most work): The PostgreSQL-backed test suites provision an embedded database on demand, so they do not need Docker. Docker is still required for the generated-project Dockerfile and Compose checks in the bootstrap suite and for the Dockerized Flutter integration suite. You can download Docker from the Docker website.
- Git: Serverpod is hosted on GitHub, so you need to have Git installed on your machine. You can download Git from the Git website.
- Melos: Serverpod uses Melos to manage the monorepo. Melos is a dev dependency of the workspace, so
dart run melos ...works without installing anything. - bash: Some scripts require bash to be installed on your machine. If you are on Windows, you can install Git Bash from the Git website.
After the required tools have been installed, you will need a local clone of the repository. We recommend forking the repository and then cloning your fork.
After the repository is cloned, run the following command from the root of the repository to install all dependencies:
$ dart run melos bootstrapTip
If you have recently configured a Serverpod project, you can add the --offline flag to the script above to use cached versions of the dependencies.
Important
Use bootstrap rather than a plain dart pub get. Both resolve the pub workspace, but only bootstrap also resolves the packages that are deliberately not workspace members, which are listed with the reason for each in util/non_workspace_packages. After a plain dart pub get those packages will not analyze, test, or resolve in your IDE.
The project is now set up and ready for development.
Activate the serverpod command from your cloned repository by running the following commands:
$ cd tools/serverpod_cli
$ dart pub get
$ dart pub global activate --source path .Depending on your Dart version you may need to run the dart pub global command above every time you've made changes in the Serverpod tooling.
Tip
At the time of writing, a bug in pub global activate prevents changes from being picked up in activated libraries, tracked here.
If you are experiencing issues with the CLI not picking up changes, you can try running the workarounds listed in the issue.
When projects are created using your cloned version of the CLI, all serverpod dependencies in the pubspec.yaml files will point to your cloned repo.
To use templates from your cloned repository, e.g. to create a new project with your local version of Serverpod, you will need to set the SERVERPOD_HOME environment variable. It should point to the root your cloned serverpod monorepo. (E.g. /Users/myuser/MyRepos/serverpod)
Serverpod uses the Dart linter to enforce a consistent code style. The linter is run as part of the CI checks, so it is important that the code follows the linter rules. When you write code, make sure to use dart format and dart analyze to ensure that the code follows the linter rules.
We try to follow the Effective Dart guidelines as much as possible. But above all, we care about code readability and maintainability. Therefore, we encourage you to write code that is easy to read and understand for future contributors.
Serverpod has a comprehensive test suite that covers the core functionality of the project. The tests are run as part of the CI checks, but to speed up development it can be good to run the tests locally before submitting a pull request.
The database-backed host suites provision their own embedded PostgreSQL on
demand, so no database server needs to be running. The first run downloads the
exact published bundle pinned by this Serverpod revision; it does not build a
missing bundle automatically. To validate an unpublished bundle or changes to
its build recipe, run dart run melos run test_integration_embedded_pg_build
with the native build toolchain installed.
Some test flows use host aliases. The e2e client expects
serverpod_test_server, while redis-tagged integration tests look for a Redis
with password password at redis. Those tests fail when Redis is unavailable;
exclude them explicitly with -x redis only when Redis coverage is outside the
scope of a direct test run:
127.0.0.1 serverpod_test_server
127.0.0.1 redis
dart run melos run test runs the primary host workflow—unit, bootstrap, and
integration tests—and is the quickest way to validate a change across
packages. On non-Windows hosts, its bootstrap group includes generated-project
Dockerfile and Compose checks, so the complete workflow requires Docker. It
also requires Redis at redis:6379 with password password. See the melos:
section in pubspec.yaml for the individual test_* scripts.
Scripts that run groups of tests are located in the util directory and their
names start with run_tests. Common test scripts include:
| Script | Description |
|---|---|
run_tests_integration |
Run all non concurrent integration tests in the test project. |
run_tests_integration_concurrently |
Run all concurrent integration tests in the test project. |
run_tests_integration_embedded |
Run a single server package's integration tests against embedded PostgreSQL (also run_tests_{auth,module,nonvector}_integration_embedded). |
run_tests_database_integration_embedded |
Run the focused pgvector/PostGIS extension contract against embedded PostgreSQL. |
run_tests_integration_embedded_pg_build |
Build the host PostgreSQL bundle and run the embedded PostgreSQL and host integration suites against it. |
run_tests_sqlite_integration |
Run the SQLite test project's integration tests. |
run_tests_flutter_integration |
Run all Flutter integration tests in the flutter test project. |
run_tests_e2e_host |
Run the end to end tests against a host server (vm or firefox). |
run_tests_migrations_e2e |
Run all migration end to end tests (also run_tests_sqlite_migrations_e2e). |
run_tests_bootstrap |
Run all bootstrap tests. |
run_tests_update_pubspecs |
Ensure that all pubspec files are up to date with the templates. |
run_tests_analyze |
Run the code analysis tests. |
To run any script, navigate to the root of the repository and run the script, e.g.:
$ util/run_tests_integrationMost suites run directly with dart test from their package directory, and
the database-backed suites provision embedded PostgreSQL themselves. The e2e
and migration suites have dedicated launchers because they require a live
server and a controlled database lifecycle. See TESTING.md for
how each suite runs, the variants (loaded machines, redis, parallel runs,
external databases), and the contracts of the e2e suites.
Adding new dependencies to the project should be done with care. We are very restrictive with adding new dependencies to the project. If dependencies are added, they must be well maintained, have a permissive open-source license, and must have a good reason for being added.
Modifications to pubspec.yaml files should be done in the templates directory. The pubspec.yaml files for all libraries are generated from these templates. After a templates has been modified, run the util/update_pubspecs script to update the pubspec.yaml files.
$ util/update_pubspecsAll pull requests should be submitted to the main branch. The pull request should contain a description of the changes and a reference to the issue that the pull request is addressing.
All code changes should come with tests that validate the changes. If the changes are not testable, please explain why in the pull request.
To keep the projects git history clean, we will squash PRs before merging. Therefore, it is essential that each pull request only contains a single feature or bug fix. Keeping pull requests small also makes it easier to review the changes which in turn speeds up the review process.
Before the Serverpod team can review your pull request, it must pass the CI checks. If the CI checks fail, the pull request will not be reviewed.
Feel free to post on Serverpod's discussion board if you have any questions. We check the board daily.
Help us improve the Serverpod documentation by submitting pull requests to the serverpod_docs repository. We have a list of documentation issues that are a good starting point for contributing.
We encourage you to support others in their Serverpod projects by sharing your knowledge and experiences. You can help by answering questions on the discussion board, participating in conversations on filed issues, or contributing your insights through tutorials and blog posts about Serverpod.
Help us make Serverpod better by filing issue for bugs, feature requests, or improvements. When filing an issue, please provide as much information as possible to help us understand the problem or suggestion.