Contributing to Sailor

Thank you for considering contributing to Sailor CMS!

Getting Started

Prerequisites:

• Node.js 20+
• Git
• Basic knowledge of SvelteKit, TypeScript

Setup:

1. Fork and clone the repository
2. Run bun install (or npm install)
3. Copy .env.example to .env and fill in BETTER_AUTH_SECRET and DATABASE_URL
4. Run npx sailor db:update
5. Run bun dev (or npm run dev)
6. Visit http://localhost:5173/sailor

Project Structure

src/lib/sailor/
├── templates/      # User-edited content type definitions (input to schema gen)
├── generated/      # Auto-generated by `npx sailor db:update` — never edit by hand
├── core/           # CMS internals (auth, db, hooks, services, content, editor, files, ui)
├── remote/         # Server RPC endpoints (*.remote.ts, gated by experimental remoteFunctions)
├── utils/          # Consumer-facing helpers (data, files, ui)
├── composables/    # Shared Svelte 5 runes helpers
├── assets/         # Static assets shipped with the admin
├── i18n/           # Translations (Paraglide / inlang)
├── styles/         # CMS styling
└── scripts/        # Utility scripts

src/routes/sailor/           # Admin UI routes (served at /sailor)
src/lib/components/sailor/   # Admin UI components
src/lib/components/ui/       # shadcn-svelte primitives (don't modify unless asked)

Development Guidelines

Code Style:

• TypeScript for all new code
• Run npm run lint and npm run check before submitting (typecheck via svelte-check; no test runner is wired up)
• Follow existing patterns

Before Contributing:

1. Check existing issues
2. Open an issue for new features
3. Keep PRs focused
4. Test your changes

Types of Contributions

Bug Fixes: Include reproduction steps and reference issue number

New Features: Discuss in issue first, follow existing patterns

Documentation: Fix typos, add examples, keep current

UI/UX: Follow design patterns, test on mobile/desktop

Development Workflow

Adding Collections/Blocks:

1. Create template under src/lib/sailor/templates/
2. Register in the appropriate index.ts
3. Run npx sailor db:update to regenerate schema/types and apply migrations
4. Commit the template change together with the regenerated generated/ files and any new migration under drizzle/
5. Test in admin interface

Important Rules:

• Never edit generated files
• Always use templates for schema changes
• Test with existing data

Pull Request Process

1. Create feature branch from develop (active integration branch; master stays at the last shipped tag)
2. Make changes following guidelines
3. Test thoroughly (bun dev, npm run lint, npm run check)
4. Commit with clear message
5. Open PR with description and screenshots

What Not to Do

• Don’t edit generated files in src/lib/sailor/generated/
• Don’t write Drizzle schema or migrations by hand — let npx sailor db:update do it
• Don’t modify src/lib/components/ui/ (shadcn-svelte) unless explicitly asked
• Don’t commit database files (sailor.sqlite, etc.)
• Don’t include sensitive data

Getting Help

• GitHub Issues for bugs and features
• Check existing documentation first
• Run npx sailor doctor if your dev environment falls out of sync (configs, stale imports, duplicate framework deps)

---

Thank you for helping make Sailor CMS better!