Skip to main content
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 for a bug or an improvement.
  • Share Ship — tell anyone who might want to build products, not boilerplate.

​
Repo layout

Ship is a pnpm + Turborepo 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:
PackageWhat it does
app-constantsEnums and constants (USER_STATUSES, …) — the single source for z.enum(...), never inline strings.
@ship/dbThe DbService — a typed, soft-delete-aware wrapper over Drizzle that codegen-db.ts generates into apps/api/src/db.ts.
@ship/emailsReact Email templates with a preview server on port 4000.
@ship/cloud-storageS3-compatible file upload/download helpers.
eslint-configShared ESLint config.
prettier-configShared Prettier config.
tsconfigShared TypeScript base configs.
@ship/emails and @ship/cloud-storage arrive via the mailer and cloud-storage plugins; the rest are part of the base template.

​
Open a pull request

1

Fork and branch

Fork the project, then branch off main with a name that describes your change.
2

Make the change

Implement it and commit. CI runs build and lint checks on the PR — see GitHub Actions.
3

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).
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

1

Enter the template

cd template
2

Create the API env file

Copy apps/api/.env.example to apps/api/.env.
3

Install dependencies

pnpm i
4

Start everything

pnpm start
This brings up infrastructure, runs migrations, and starts every service.
The dev servers come up on:
ServiceURL
APIhttp://localhost:3001 (Scalar docs at /docs)
Webhttp://localhost:3002
Emails previewhttp://localhost:4000
Drizzle Studiorun pnpm dashboard

​
Run the docs

Ship’s docs use Mintlify and live in the /docs folder, written in MDX.
1

Install the Mintlify CLI

pnpm add -g mint
2

Run from the repo root

pnpm docs
This runs cd docs && mint dev --port 4100.
The docs open at 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.