> ## Documentation Index
> Fetch the complete documentation index at: https://ship.paralect.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Contribution Guide

> How to run Ship locally, where the code lives, and how to open a pull request.

Thanks for wanting to contribute to Ship. This page covers the repo layout, how to run the template and docs locally, and how to open a pull request.

## Ways to contribute

* **Fix the docs** — bad wording, missing examples, anything inaccurate.
* **Fix the template** — squash bugs or improve the scaffolded app in `/template`.
* **Report or suggest** — open an [issue](https://github.com/paralect/ship/issues) for a bug or an improvement.
* **Share Ship** — tell anyone who might want to build products, not boilerplate.

## Repo layout

Ship is a [pnpm](https://pnpm.io/) + [Turborepo](https://turbo.build/repo/docs) monorepo. The pieces you'll touch most:

```
ship/
  template/        # the scaffolded app the CLI ships
    apps/api/      # Hono + oRPC + Drizzle API
    apps/web/      # TanStack Start web app
    packages/      # shared packages (see below)
    bin/           # setup + run scripts
    .github/       # CI workflows copied into generated projects
    .husky/        # pre-commit hook
  plugins/         # opt-in features (auth-starter, admin, notes, ai-chat, ...)
  packages/        # repo tooling — create-ship-app CLI
  deploy/          # deployment configs per target
  docs/            # this documentation (Mintlify)
```

## Shared packages

The `template/packages/` folder holds the packages every generated app shares:

| Package               | What it does                                                                                                                                             |
| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `app-constants`       | Enums and constants (`USER_STATUSES`, …) — the single source for `z.enum(...)`, never inline strings.                                                    |
| `@ship/db`            | The `DbService` — a typed, soft-delete-aware wrapper over [Drizzle](https://orm.drizzle.team/) that `codegen-db.ts` generates into `apps/api/src/db.ts`. |
| `@ship/emails`        | [React Email](https://react.email/) templates with a preview server on port 4000.                                                                        |
| `@ship/cloud-storage` | S3-compatible file upload/download helpers.                                                                                                              |
| `eslint-config`       | Shared ESLint config.                                                                                                                                    |
| `prettier-config`     | Shared Prettier config.                                                                                                                                  |
| `tsconfig`            | Shared TypeScript base configs.                                                                                                                          |

`@ship/emails` and `@ship/cloud-storage` arrive via the `mailer` and `cloud-storage` [plugins](/docs/plugins/overview); the rest are part of the base template.

## Open a pull request

<Steps>
  <Step title="Fork and branch">
    Fork the [project](https://github.com/paralect/ship/fork), then branch off `main` with a name that describes your change.
  </Step>

  <Step title="Make the change">
    Implement it and commit. CI runs build and lint checks on the PR — see [GitHub Actions](/docs/github-actions).
  </Step>

  <Step title="Open the PR">
    Push and open a pull request against `main`. Attach three labels: **To Review**, a functionality type (Feature / Bug / Improvement), and an edit location (docs, create-ship-app, or template).
  </Step>
</Steps>

A maintainer reviews it. If it's good, it merges to `main`. Otherwise we leave comments and label it **Changes Requested** — make the fixes, then reattach **To Review**.

## Run the template

<Steps>
  <Step title="Enter the template">
    ```bash theme={null}
    cd template
    ```
  </Step>

  <Step title="Create the API env file">
    Copy `apps/api/.env.example` to `apps/api/.env`.
  </Step>

  <Step title="Install dependencies">
    ```bash theme={null}
    pnpm i
    ```
  </Step>

  <Step title="Start everything">
    ```bash theme={null}
    pnpm start
    ```

    This brings up infrastructure, runs migrations, and starts every service.
  </Step>
</Steps>

The dev servers come up on:

| Service            | URL                                                                     |
| ------------------ | ----------------------------------------------------------------------- |
| **API**            | [http://localhost:3001](http://localhost:3001) (Scalar docs at `/docs`) |
| **Web**            | [http://localhost:3002](http://localhost:3002)                          |
| **Emails preview** | [http://localhost:4000](http://localhost:4000)                          |
| **Drizzle Studio** | run `pnpm dashboard`                                                    |

## Run the docs

Ship's docs use [Mintlify](https://mintlify.com/) and live in the `/docs` folder, written in [MDX](https://mdxjs.com/).

<Steps>
  <Step title="Install the Mintlify CLI">
    <CodeGroup>
      ```bash pnpm theme={null}
      pnpm add -g mint
      ```

      ```bash npm theme={null}
      npm i -g mint
      ```
    </CodeGroup>
  </Step>

  <Step title="Run from the repo root">
    ```bash theme={null}
    pnpm docs
    ```

    This runs `cd docs && mint dev --port 4100`.
  </Step>
</Steps>

The docs open at [http://localhost:4100](http://localhost:4100).

## Deployment

Ship ships configs for four targets — **AWS** (EKS), **DigitalOcean Kubernetes**, **DigitalOcean Apps**, and **Render** — under `/deploy`. The CLI copies the config for the target you pick into your generated project.

To test a target end to end, scaffold a fresh project with `npx @paralect/ship init`, choose the deployment target, and follow the [deployment instructions](/docs/deployment/digital-ocean-apps).