README

Viget's Craft CMS Starter

Our Craft Site Starter is a quick way to spin up a new Craft CMS project. It's pre-configured with top-notch build tooling, common plugins and starter components based on Blueprint.

If you're a designer or developer at Viget working on a new project, view our Building with Craft Site Starter guide for more information.

Features

Local development powered by DDEV
Claude Code cloud sessions run the project in DDEV too, with Craft installed
Vite based front-end build tooling.
Automatic linting, formatting and typechecking
- Runs on git pre-commit hook with Husky
- Only processes staged files using lint-staged
- Prettier, eslint, PHPStan, PHP Easy Coding Standard
Common plugins come pre-installed
Local email is routed through Mailpit ( never worry about emailing a client or user)
htop is installed in the DDEV web container for debugging CPU and memory usage
Starter components based on Blueprint
A fully accessible header and navigation
A simple Matrix Field based block editor
Static message translations have been pre-filled for common elements.

Icons

Icons are bundled into a single SVG spritemap at build time by @spiriit/vite-plugin-svg-spritemap and referenced via <use href> from the Icon macro in templates/_components/icon.twig.

To add an icon, drop an SVG into src/icons/ and run npm run build

Getting Started

Create Project

Install DDEV

Choose a folder for your project and move into it:

cd /path/to/web/projects
mkdir my-project
cd my-project

Create The Project If you already have PHP and Composer running on your host machine (your computer, not Docker container or DDEV instance), you can run the following command
```
composer create-project viget/craft-site-starter=^5.0.0 ./ --ignore-platform-reqs
```
If you'd rather not set up PHP, you can create the project with a disposable Docker image (Thanks nystudio107).
```
docker run --rm -it -v "$PWD":/app -v ${COMPOSER_HOME:-$HOME/.composer}:/tmp composer create-project viget/craft-site-starter=^5.0.0 ./ --ignore-platform-reqs
```
Start DDEV & Install Craft
```
ddev start
ddev craft install
```
Run ddev launch to open the project in your browser

Debugging CPU Performance with htop and xhprof

htop is installed in the DDEV web container (see webimage_extra_packages in .ddev/config.yaml). It's an interactive process viewer that shows what is using CPU and memory inside the container: PHP-FPM workers, Craft console commands, Nginx and the Vite dev server.

ddev exec htop

Press q or F10 to quit. htop only sees processes in the web container, not your computer or the database container.

Once htop shows that PHP is the problem, DDEV's built-in xhprof profiler shows which PHP functions are using the time (step 5 below).

Common workflow: tracking down high CPU usage

Find the busy container. On your computer, run docker stats to see CPU per container.
- ddev-<project>-web runs PHP, Nginx and Vite. Continue to step 2.
- ddev-<project>-db runs MySQL. See what queries are running with ddev mysql -e "SHOW FULL PROCESSLIST".
- If neither is busy, the problem is on your computer (Mutagen sync, Docker itself, your editor), not in the project.
Open htop sorted by CPU, in tree view, so each process sits under the one that started it:
```
ddev exec htop --sort-key=PERCENT_CPU --tree
```
Key Action

P Sort by CPU

M Sort by memory

F5 Toggle tree view

F4 Filter by command, e.g. php-fpm or vite

F9 Kill the selected process (SIGTERM is the default)

You can also start htop already filtered: ddev exec htop --filter=php-fpm.
Reproduce the problem while htop is open. Reload the slow page, run the slow ddev craft command or save the entry, and watch the CPU% column. A process that sits at or near 100% is your culprit. Short spikes are normal.

Key	Action
`P`	Sort by CPU
`M`	Sort by memory
`F5`	Toggle tree view
`F4`	Filter by command, e.g. `php-fpm` or `vite`
`F9`	Kill the selected process (`SIGTERM` is the default)

Match the process to a likely cause.

Process at the top	Usually means	Next step
`php-fpm: pool www`	A slow web request: a heavy Twig template, N+1 element queries, or image transforms being generated. Queue jobs also run here, because Craft runs the queue through web requests by default.	Profile the request (step 5). Check Utilities → Queue Manager in the control panel for jobs.
`php ./craft …`	A long-running console command, such as `resave/entries` or `clear-caches/all`.	Let it finish, or kill it with `F9`.
`node …/vite` or `esbuild`	The Vite dev server (a `web_extra_daemons` entry) rebuilding after a file change.	If it stays high with nothing changing, run `ddev restart`.
`npm install`, `npm run build` or `composer`	Dependencies installing from the `post-start` hook or the Vite daemon, usually right after `ddev start`.	Wait for it to finish.

Profile slow PHP requests. Once htop points at php-fpm, find out which code is slow with DDEV's built-in xhprof profiler:
```
ddev xhprof on
```
Reload the slow page a few times, then open the results:
```
ddev xhgui
```
Turn the profiler off when you're done, since it slows down every request:
```
ddev xhprof off
```
For N+1 queries, Craft's debug toolbar shows how many database queries a page runs. Turn it on in the control panel under My Account → Preferences → Development → Show the debug toolbar on the front end.

Plugins

This starter includes common plugins that we use on most of our sites. This provides consistency and familiarity between client projects. You may not need every plugin, but avoid replacing standard plugins with similar alternatives (unless absolutely necessary).

Name	Composer	Usage	Year 1 Price	Renewal Price
Amazon S3	`craftcms/aws-s3`	This plugin integrates Craft CMS and Amazon S3 cloud storage service.	Free	Free
Autocomplete	`nystudio107/craft-autocomplete`	Provides Twig template IDE autocomplete of Craft CMS & plugin variables. Requires the PHPStorm Symfony Support Plugin	Free	Free
CKEditor	`craftcms/ckeditor`	Craft CMS’s official rich text plugin	Free	Free
Classnames	`viget/craft-classnames`	Conditionally join css class names together in Twig	Free	Free
Empty Coalesce	`nystudio107/craft-emptycoalesce`	Adds the `???` operator to Twig that will return the first thing that is defined, not null, and not empty.	Free	Free
Imager X	`spacecatninja/imager-x`	Image optimization and Imgix connector. Provides useful Twig shortcuts for generating transforms and placeholders.	$99.00	$59.00
Navigation	`verbb/navigation`	Simplifies management of complex navigation groups (main menus, footer menus, etc.)	$19.00	$5.00
Retour	`nystudio107/craft-retour`	Provides a Craft admin UI to set up redirects. Will automatically create redirects when URLs of entries change.	$59.00	$29.00
SEOMatic	`nystudio107/craft-seomatic`	A turnkey SEO plugin that follows modern SEO best practices.	$99.00	$49.00
Vite	`nystudio107/craft-vite`	Loads front-end files that are compiled by Vite.	Free	Free
Expanded Singles	`verbb/expanded-singles`	Change the entries index sidebar to list all singles, rather than grouping them under a 'Singles' menu item.	Free	Free

Contribute to this starter

Local Dev

Ideally, you should be able to clone this repo and make modifications to plugin & build tool configs with minimal fuss.

Run the following and make edits in a feature branch:

ddev start
ddev craft install

See ARCHITECTURE.md for details on technical goals & decisions.

Release Testing

Before releasing, run the following tests.

Verify project renaming scripts work

From within the Craft Site Starter repo, run ddev composer run-script post-create-project-cmd and follow the prompts.
Use your IDE's diff view to verify that files are renamed properly.

Show Example

Run the composer create script to create a new project.

docker run --rm -it -v "$PWD":/app -v ${COMPOSER_HOME:-$HOME/.composer}:/tmp composer create-project viget/craft-site-starter=5.x-dev ./ --ignore-platform-reqs

Follow the prompts to create a new local site.
Install Craft and ensure home page and Craft admin load.

Releasing

New versions are tagged and published by the Release workflow. Once the release tests above pass:

Go to Actions → Release → Run workflow on GitHub.
Under Use workflow from, choose the release branch (e.g. 5.x).
Choose the Version bump:
- patch (5.0.3 → 5.0.4) for fixes and package updates
- minor (5.0.3 → 5.1.0) for new features, components or plugins
- major (5.x → 6.0.0) only from a new major branch such as 6.x, since the starter's major version follows Craft's
Tick Dry run to preview the version number and release notes in the run summary without tagging anything.
Click Run workflow.

The workflow tags the latest commit on the branch, publishes a GitHub release listing every pull request merged since the previous version, and Packagist picks up the new version within a few minutes. composer-scripts/post-create-project.php deletes the workflow from new projects.

viget / craft-site-starter

Package info

Security

Statistics