Contribution Guide

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:

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 that `codegen-db.ts` generates into `apps/api/src/db.ts`.
`@ship/emails`	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; the rest are part of the base template.

Open a pull request

Fork and branch

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

Make the change

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

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

Enter the template

cd template

Create the API env file

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

Install dependencies

pnpm i

Start everything

pnpm start

This brings up infrastructure, runs migrations, and starts every service.

The dev servers come up on:

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

Run the docs

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

Install the Mintlify CLI

pnpm add -g mint

npm i -g mint

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.

Getting Started

Ship Components

Plugins

Contribution Guide

Ways to contribute

Repo layout

Shared packages

Open a pull request

Run the template

Run the docs

Deployment

​Ways to contribute

​Repo layout

​Shared packages

​Open a pull request

​Run the template

​Run the docs

​Deployment

Ways to contribute

Repo layout

Shared packages

Open a pull request

Run the template

Run the docs

Deployment