Contributing to Core

We welcome contributions to Sitepins Core! This guide walks through setting up your local development environment, running test suites, and adhering to our architectural standards.

Sitepins Core is released as open source under the GNU AGPLv3 .

Local Development Setup

1. Fork & Clone


git clone https://github.com/<your-username>/sitepins.git
cd sitepins
pnpm install

2. Configure Local Environments


cp api/.env.example api/.env
cp app/.env.example app/.env

Generate your secrets using openssl:


openssl rand -base64 32 # BETTER_AUTH_SECRET
openssl rand -hex 32    # JWT_SECRET, SANDBOX_ENCRYPTION_KEY, INTERNAL_API_SECRET

3. Run Development Servers

Run both servers concurrently:


pnpm dev

Or run them in separate terminal tabs:


# Terminal 1: Express API (Port 4000)
pnpm dev:api
 
# Terminal 2: Next.js Web App (Port 3000)
pnpm dev:app

Quality Verification Gates

Before submitting a pull request, run the exact verification checks executed by our GitHub Actions CI pipeline (.github/workflows/ci.yml):

1. Build API TypeScript


pnpm build:api

2. Verify Next.js Types


pnpm --filter sitepins exec next typegen
pnpm --filter sitepins exec tsc --noEmit

3. Run Unit & Integration Tests


pnpm test

Or test subsystems individually:


pnpm test:api   # Vitest across api/
pnpm test:app   # Vitest across app/

4. Code Formatting


pnpm format

Architectural Rules for Core Contributions

To keep Sitepins Core modular and vendor-neutral, all contributions must respect these rules:

Rule	Rationale
No Billing or Plan Gates in Core	Core has no concept of plans or paid tiers. Features must be shipped fully unlocked.
No `if (isCloud)` Branching	Core must remain unaware of cloud SaaS wrappers. Use modular extension hooks or component stubs.
Preserve White-Label Defaults	Avoid hardcoding brand names or domains. Reference `@/lib/brand.ts` so self-hosters can white-label via `.env`.
Never Gitignore Files in `app/src/`	Tailwind CSS v4’s scanner silently ignores any path matched by `.gitignore`.
Add Git Provider Endpoints in Pairs	If you add functionality for GitHub, provide the equivalent implementation for GitLab.
Lossless Content Serialization	Any change to content parsing must preserve unknown frontmatter keys, inline HTML blocks, and YAML/TOML comments.
Support All 12 Locales	When introducing new user-facing strings, add translation keys across all 12 supported locales under `app/src/i18n/`.

Writing Tests

We use Vitest for testing across both api/ and app/:

Test files live directly beside the code they test: <name>.test.ts.
Pure functions, parser utilities, schema converters, and authorization checkers should always include tests.
When adding support for a new generator or file format, include a round-trip serialization test in content-serializer.test.ts.

Reporting Security Vulnerabilities

Please do not report security vulnerabilities through public GitHub issues. Email our security team at hi.sitepins@gmail.com with reproduction steps and impacted versions. We respond within 72 hours.