Local Development Setup for TruCMS

Get a copy of TruCMS running on your machine, then build assets, run the tests and keep the code formatted. Use a separate development copy for plugin and theme work, never a live site.

Requirements

PHP 8.4 or newer, with the extensions the installer checks: cURL, BCMath, Ctype, Fileinfo, JSON, Mbstring, PDO, Intl, OpenSSL, Tokenizer, XML, EXIF and GD. Add zip for plugin and template packages.
MySQL or MariaDB for the site. The test suite uses SQLite, so the pdo_sqlite extension is needed for tests.
Composer 2, and Node.js with npm for asset builds.
A local web server that points at the public/ folder. Laravel Herd works well and serves the folder at https://<folder-name>.test.

Set up a development copy

Get the code and dependencies
Start from the TruCMS release package (it includes vendor/ and built assets) or from a source checkout. For a source checkout, install the dependencies:
```
composer install
npm install
npm run build
```
A source checkout has no .env. Copy .env.example to .env and run php artisan key:generate so the application can start; leave APP_INSTALLED=false.
Create an empty database
Create a MySQL database and a user for it. Do not run migrations yourself.
Run the web installer
Open the site in a browser. Every request redirects to the installer at /install/pre-installation until installation is finished. It checks the server, verifies the purchase, then asks for the database, the administrator account and the site details, and creates everything: schema, seed data, application key, storage link and .env values. The end-user installation guide that ships with TruCMS walks through each screen.
Switch the copy to development mode
The installer writes production values. In .env set APP_ENV=local and APP_DEBUG=true, then run:
```
php artisan optimize:clear
```
The installer caches config and routes on its last step; clearing them means your code changes show up immediately.
Add demo content (optional)
To see the bundled modules with realistic data, import a website template from Appearance → Website templates. It replaces pages, menus and theme options, which is exactly what you want on a development copy and never what you want on a live site.

Day-to-day commands

Task	Command
Build assets once / watch	`npm run build` / `npm run dev`
Refresh the compiled theme CSS after a build	Appearance → Theme options → Advanced → Regenerate Theme CSS
Run a narrow set of tests	`php artisan test --compact tests/Feature/ResponseCacheTest.php` or `vendor/bin/pest --filter=name`
Run a module's tests	`php artisan test --compact Modules/Booking/tests`
Format PHP	`vendor/bin/pint --dirty` (or `composer lint` for the whole tree)
Static analysis	`composer types:check` (PHPStan level 4)
Format template-library HTML	`composer format:html`
Clear every cache	`php artisan optimize:clear`
List routes under a prefix	`php artisan route:list --path=admin/bookings`
Pick up a new or edited `theme.json`	`php artisan theme:refresh-cache`
Pick up a newly added module	`composer dump-autoload`

When a change "does nothing"

Three caches cause most surprises on a development copy: cached routes and config (saving some settings re-caches them; run php artisan optimize:clear), the compiled theme CSS (regenerate it after npm run build), and the full-page cache if you switched it on in Settings → Cache.

The test environment

phpunit.xml runs tests with APP_ENV=testing, SQLite at database/testing.sqlite (create the empty file on a fresh copy), the array cache, the sync queue and the response cache off. The base test case marks the app as installed, renders views without Vite and blocks real HTTP calls, so tests need neither a build nor network access. Details and helpers: Testing.

Run the whole suite once on a clean copy before you start and note any tests that already fail there, so you can tell your regressions from existing ones.

Area rules in the source repository

The source repository keeps short rule files in .ai/rules/ for areas with decisions the code cannot express (Echo Sass, header components, page templates, binding sources, website templates). .ai/rules/index.md maps paths to rules. Read the matching file before you change those paths; the essentials are summarised in Conventions and rules.

Next steps

Learn the conventions your code should follow.
Build something: Tutorial: build a plugin.