# Contributing to EmDash

> How to set up a development environment and contribute to EmDash.

Source: https://emdashcmseverything.com/official-docs/contributing/

EmDash is a pnpm monorepo. The main package is `packages/core`, published as `emdash`; it contains the Astro integration, REST API, database layer, schema management, and plugin system. The React admin UI lives in `packages/admin`.

This page gives you the quickest path to a working development environment. [`CONTRIBUTING.md`](https://github.com/emdash-cms/emdash/blob/main/CONTRIBUTING.md) is the canonical source for prerequisites, repository layout, contribution policy, required checks, changesets, and pull request requirements.

## Local setup

1. **Clone, install, and build the workspace.**

   ```bash
   git clone https://github.com/emdash-cms/emdash.git
   cd emdash
   pnpm install
   pnpm build
   ```

2. **Start the primary development demo.**

   ```bash
   cd demos/simple
   pnpm dev
   ```

   The demo runs on Node.js with SQLite at `http://localhost:4321`. On the first request, it applies the schema from `seed/seed.json`; the development bypass in the next step also adds its sample content.

3. **Open the admin panel.**

   For the fastest local setup, open [the development bypass](http://localhost:4321/_emdash/api/setup/dev-bypass?redirect=/_emdash/admin). It runs migrations, creates a development administrator, signs you in, and redirects to the admin panel.

   To test the passkey setup flow instead, open [the admin panel](http://localhost:4321/_emdash/admin). The setup wizard creates the database, runs migrations, and prompts you to create an administrator account.

## Development workflow

### Watch mode

When you change `packages/core` while running the demo, use two terminals so the package rebuilds automatically:

```bash
# Terminal 1 — rebuild packages/core on change
cd packages/core && pnpm dev

# Terminal 2 — run the demo
cd demos/simple && pnpm dev
```

### Checks

Run the required checks from the repository root before you commit:

```bash
pnpm typecheck    # TypeScript
pnpm lint         # full type-aware lint
pnpm format       # auto-format with oxfmt and Prettier
```

> **Caution**
>
> Type checking and linting must both pass. Don't commit with known failures.

### Tests

#### All tests

```bash
pnpm test
```

#### Core only

```bash
cd packages/core && pnpm test
```

#### Watch mode

```bash
cd packages/core && pnpm test --watch
```

#### E2E

```bash
pnpm test:e2e    # starts its own server
```

Tests use real in-memory SQLite databases instead of database mocks. Each test gets a fresh database.

## Choose a contribution path

Bug fixes, documentation, tests, translations, chores, and behavior-preserving refactors or performance changes can go directly to an implementation pull request. A feature needs an accepted [feature plan or RFC](https://github.com/emdash-cms/emdash/tree/main/proposals) before implementation. Read the full [contribution policy](https://github.com/emdash-cms/emdash/blob/main/CONTRIBUTING.md#contribution-policy) before starting work so you know which path applies.

[`CONTRIBUTING.md`](https://github.com/emdash-cms/emdash/blob/main/CONTRIBUTING.md#project-processes) also links the canonical governance, roadmap, triage, review, proposal, and AI policies.

Documentation changes must also follow the [documentation style guide](https://emdashcmseverything.com/official-docs/contributing/docs-style-guide/).

For the main execution paths through EmDash, read [Architecture (internals)](https://emdashcmseverything.com/official-docs/contributing/architecture/). Code-level patterns and invariants are documented in [`AGENTS.md`](https://github.com/emdash-cms/emdash/blob/main/AGENTS.md).