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.
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: Docker is used to run Postgres and Redis for the development environment. 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. You can install Melos by running
pub global activate melos. - 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 to install all dependencies:
$ util/pub_get_allTip
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.
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.
To ensure all tests work as expected, it is recommended to add an entry for the test server, postgres and redis at the end of your /etc/hosts file.
127.0.0.1 serverpod_test_server
127.0.0.1 postgres
127.0.0.1 redis
Scripts that run groups of tests are located in the util directory and their name start with run_tests. The following test scripts are available:
| Script | Description |
|---|---|
run_tests_unit |
Run all unit tests. |
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_flutter_integration |
Run all Flutter integration tests in the flutter test project. |
run_tests_e2e |
Run all server end to end tests in the test project. |
run_tests_migrations_e2e |
Run all migration end to end tests. |
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. |
run_tests_update_pubspecs |
Ensure that all pubspec files are up to date with the templates. |
To run any script, navigate to the root of the repository and run the script, e.g.:
$ util/run_tests_unitAll unit tests can be run with the test command. But for some tests, you may need to perform additional steps to set up a test environment. Listed below are the tests that require additional setup.
To run any integration test in the tests/serverpod_test_server/test_integration directory you will need to follow these steps:
-
Start the Docker container for the test server.
$ cd tests/serverpod_test_server/docker-local $ docker compose up --build --detach -
Start the test server and apply migrations.
$ cd tests/serverpod_test_server $ dart bin/main.dart --apply-migrations
To run end to end tests in the tests/serverpod_test_server/test_e2e directory, you will need to follow these steps:
-
Start the Docker container for the test server.
$ cd tests/serverpod_test_server/docker-local $ docker compose up --build --detach -
Start the test server and apply migrations.
$ cd tests/serverpod_test_server $ dart bin/main.dart --apply-migrations -
Run an individual test
$ cd tests/serverpod_test_server $ dart test test_e2e/connection_test.dart
To run migration tests in the tests/serverpod_test_server/test_e2e_migrations directory, you will need to follow these steps:
-
Remove any existing test database.
$ cd tests/serverpod_test_server/docker-local $ docker compose down -v -
Start a new Docker container for the test server.
$ cd tests/serverpod_test_server/docker-local $ docker compose up --build --detach
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.