Contributing code

Earthstar is a non-profit project aiming to create a freer, fairer internet. As such it relies on freely given contributions of volunteers to progress. If you'd like to contribute, please read the below.


The goal of this project is to make it easy for people and communities to have their own communications infrastructure, independent of big tech companies and people with specialized tech skills.

This communications infrastructure should be non-capitalist and under local control. This is accomplished by having a distributed network of p2p connections and small servers which are each cheap and easy to run.


We aim to serve people such as:

Although Earthstar lets you use small servers under your own control, it does NOT provide enough anonymity to keep you safe from governments. It would fit our values but it's a hard problem beyond the scope of this project. You can use Earthstar through other network-privacy tools such as Tor.

We explicitly do NOT want to help hate groups and people doing harm who have been deplatformed by large tech companies.

If you are using Earthstar for the purpose of harming people or hosting communities that are about harming people, you will be banned from the project.

Code of conduct

Code of Conduct

The software we make, and the community here in which we make it, should be accessible to everyone -- especially people who are not historically privileged in tech spaces.

Communication, collaboration, and decision making

Discuss ideas

Pull requests are welcome! If they are new ideas, consider discussing the idea first.

Sam Gwilym is the Benevolent Steward For Now and has decision-making power. Sam will step back from this role once there are enough contributors.


While Earthstar is young and not widely used, you can discuss security issues on Github.

Otherwise, report security issues to Sam Gwilym. See the code of conduct document for contact information.

Code style

Use async/await when handling promises.

Prefer const over let when possible, but it's not a strict rule. Don't use var.

Null and undefined

Avoid using undefined when possible. undefined tends to occur accidentally (when looking up an object property that doesn't exist), and it can also be ambiguous when an object has an undefined property vs. not having the property at all.

Instead, use null.

Errors and exceptions

When a function can have expected kinds of errors, return an Error from the function instead of throwing it. This helps Typescript to understand the function better and ensures the people calling the function later will be aware of all the possible errors.

// return result or Error
let divideNumbers(a: number, b: number): number | EarthstarError => {
    if (b === 0) { return new EarthstarError("can't divide by zero"); }
    return a / b;

// check for errors like this:
let n = divideNumbers(1, 2);
if (n instanceof EarthstarError) {
    // do something
} else {
    // n is a number

// or use the helper functions from types.ts
if (isErr(n)) { ... }
if (notErr(n)) { ... }

Use subclasses of the built-in node Error class. They're defined in types.ts. Prefer these specific errors to the generic built-in Error.

class EarthstarError extends Error { ... }

class ValidationError extends EarthstarError { ... }
class StorageIsClosedError extends EarthstarError { ... }
... etc ...

It's ok to throw an error in these cases:

Limited dependencies

Avoid adding new dependencies. Choose dependencies carefully; favor well-known and mature modules with few dependencies of their own.

Code formatting

Use deno fmt and the codebase will be formatted automatically.