Development

This section covers the tools, workflows, and conventions used across all development projects. If you are setting up a new machine, work through the sections below in order.

Local development

Laravel Herd is the standard local server for macOS. Install it from herd.laravel.com, then install MariaDB and Redis via Homebrew (the free tier does not bundle a database):

brew install mariadb redis
brew services start mariadb
brew services start redis

For projects that run on Docker instead (older or third-party projects), see the Docker guide.

Use Mailpit to capture outbound email during development.

Git

Read the Git guide before making your first commit. Key rules:

• Commit messages follow Conventional Commits: type: [JIRA-123] Description, imperative mood
• Branch names follow the pattern JIRA-123/brief-description
• Always use fast-forward merges – never merge commits
• Never let work reside solely on your local machine overnight

Project READMEs

Every project's README.md should let a new developer get the project running locally without help. See Project READMEs for what to include and a template to start from.

Package management

Always use Yarn – never npm or pnpm. Enable Corepack once per machine, then it manages the Yarn version automatically per project:

corepack enable

New projects are set up with corepack use yarn@stable. See the Yarn guide for full setup details.

For PHP dependencies, check recommended packages before installing third-party alternatives, and use the internal GitLab registry for private morphsites packages.

Code style & linting

All code should follow Spatie's style guides for PHP, Laravel (if applicable), and JavaScript.

For modern projects, linters are enforced in CI and must pass before merging. Run them locally before pushing:

Tool	What it checks	Command
PHPStan	PHP static analysis (level 8, 6 for legacy projects)	composer analyse
Pint	PHP code style, Blade templates	composer format
Prettier	CSS, JS, TS, Vue	yarn format