xm / starter_craft_3
Starter for creating Craft 5 sites at XM Media
Package info
github.com/xmmedia/starter_craft
Language:Twig
Type:project
pkg:composer/xm/starter_craft_3
Requires
- php: ~8.5.0
- ext-intl: *
- automattic/akismet-sdk: ^1.5.0
- born05/craft-assetusage: ^4.2.1
- craftcms/ckeditor: ^5.9.0
- craftcms/cms: ^5.12.1
- craftcms/contact-form: ^3.2.0
- craftcms/contact-form-honeypot: ^2.2.1
- ether/seo: ^5.0.0
- hybridinteractive/craft-contact-form-extensions: ^5.1.1
- nystudio107/craft-vite: ^5.0.2
- verbb/field-manager: ^4.0.12
- vlucas/phpdotenv: ^5.4
- wrav/oembed: ^3.2.2
Requires (Dev)
- craftcms/generator: ^2.2
- ergebnis/composer-normalize: ^2.54
- friendsofphp/php-cs-fixer: ^3.95
- friendsoftwig/twigcs: ^6.0
- phpstan/phpstan: ^2.2
- rector/rector: ^2.0
- yiisoft/yii2-shell: ^2.0.3
Suggests
None
Provides
None
Conflicts
None
Replaces
None
This package is auto-updated.
Last update: 2026-11-16 03:12:33 UTC
README
Used to create new projects using Craft CMS at XM Media.
Setting Up a New Site
Locally
- Create a new project (install Composer on the host first, if it isn't already):
composer create-project xm/starter_craft project-name --stability=dev --no-install --remove-vcs
- Update
composer.json:name,license(likelyproprietary) anddescription - Update
package.json:name,version,repository.url,license, and uncommentprivate - Remove or update the
LICENSEfile. - Find and make changes near the
@todo-craftcomments throughout the site, removing each once it's resolved:grep -rn '@todo-craft' --exclude-dir={node_modules,vendor,.git} .
- Copy
.env.example-localto.envand update it. DDEV supplies the database settings andPRIMARY_SITE_URL, so they aren't in it. - Start DDEV:
ddev start(if Lando is still running, see Running alongside Lando) - Install & update PHP packages:
ddev composer install && ddev composer update - Install & update JS packages:
ddev yarn && ddev yarn up -R '**' - Install Craft:
ddev craft install/craft– useadmin@xmmedia.comfor the admin email, or change--userin.mcp.jsonto match, otherwise the Craft MCP server won't start - Create new favicons: realfavicongenerator.net
- Update the starter's
README.mdfor the project, keeping Setting Up an Existing Project Locally.
The local site is at https://<name>.ddev.site/, from name in .ddev/config.yaml
(https://craftstarter.ddev.site/ in the starter); ddev describe lists it and phpMyAdmin.
Craft admin is located at /admin.
Running alongside Lando
While Lando sites are running, Lando's proxy holds ports 80 & 443. Put DDEV's router on other
ports with a git-ignored .ddev/config.local.yaml, then ddev restart:
#ddev-silent-no-warn router_http_port: "8080" router_https_port: "8443"
The site is then at https://<name>.ddev.site:8443/. Delete the file once Lando is no longer
running. To move an existing project from Lando, use the /xm:lando-to-ddev Claude skill. Run it after
pulling a project's switch to DDEV too: it moves your local databases from Lando into DDEV.
In the Craft Admin
These are saved to project config, so make them locally and commit the changes.
- Set the email Subject Text for contact form submissions in Settings > Plugins > Contact Form.
- Update the site name:
- In Settings > General
- In Settings > Sites
- In Entries > Site Information (content, so this one isn't in project config)
Server
- If using InterWorx, run
bin/provision_sitelocally — it provisions the whole site (see Provisioning a Site below) and prints the remaining manual steps. To do it by hand instead:- Upload
bin/setup_server.shto the domain dir and, as the site user, run:bash ./setup_server.sh - Complete
shared/.env(start from.env.example). - Set the GitLab CI/CD variables:
bin/setup_gitlab_ci_vars <group/project> - Add the CI public key to the site user's
~/.ssh/authorized_keys. - Add the every-minute Craft queue cron job — the queue doesn't run automatically outside dev.
- Upload
- Deploy from GitLab (both jobs are manual; Staging deploys from any branch, Production only from the default branch).
- Install Craft (
php craft install/craftin thecurrentdir) or import the local database.
The site can be accessed at https://[domain]/.
Setting Up an Existing Project Locally
- Copy
.env.example-localto.envand update it. DDEV supplies the database settings andPRIMARY_SITE_URL, so they aren't in it. - Start DDEV:
ddev start(ddev describelists the URLs, including phpMyAdmin) - Install packages:
ddev composer install && ddev yarn install - Import a database:
ddev import-db --file=<file.sql.gz>, thenddev craft up
If the project's local database is still in Lando, run the /xm:lando-to-ddev Claude skill
instead of steps 2–4: it moves the database into DDEV.
Provisioning a Site
For sites on an InterWorx server, bin/provision_site (run locally) does the whole setup:
1Password items, the SiteWorx account, the database, setup_server.sh, shared/.env, the
Craft queue cron job, the GitLab CI/CD variables and the CI public key in the site user's
~/.ssh/authorized_keys.
- Requires an ssh Host with passwordless sudo,
opsigned in,glabauthenticated andjqinstalled. - It asks whether you're provisioning staging or production, then prompts for everything else and shows a summary before making any changes.
- The remaining manual steps (DNS record, SSL certificate, completing
shared/.env, first deploy, Craft database) are printed at the end. The DNS record doesn't need to exist beforehand — it's only needed before generating the SSL certificate.
Related scripts:
bin/setup_server.sh– runs on the server as the site user, in the domain dir; creates thereleases/sharedstructure and symlinks. Normally run bybin/provision_site.bin/setup_gitlab_ci_vars <group/project>– sets the GitLab CI/CD variables for one scope (staging or production). Can be run on its own; see--help.
System Requirements
- PHP 8.5+
- MySQL 8.4
- Node 26
- Yarn v4
Commands
Everything runs in the DDEV web container — ddev yarn, ddev composer, ddev craft — so
PHP and Node (from .nvmrc) match the project rather than whatever the host has.
- Install JS packages:
ddev yarn install - Run all checks & fixes:
bin/check_full- Runs Composer Normalize, Rector & PHP CS Fixer (applying fixes), then
bin/check; run before pushing
- Runs Composer Normalize, Rector & PHP CS Fixer (applying fixes), then
- Check all code (no fixes):
bin/check- Runs
composer validate,composer normalize(dry run), linting (JS, CSS, YAML, Twig), PHP static analysis & security audits
- Runs
- Dev JS/CSS server with HMR:
ddev yarn dev(stop with Ctrl-C)- Assets are proxied through Apache at
https://[domain]/vite-dev/so they're same-origin with the site — that's what lets the SVG icon sprite work without a polyfill (<use href>can't cross origins). See.ddev/web-build/apache-vite.conf - A
503on a/vite-dev/…asset means the dev server isn't running — start it withddev yarn dev - Stop one left running:
ddev exec pkill -f '[v]ite/bin/vite.js'
- Assets are proxied through Apache at
- Compile check:
ddev yarn build:check- Builds to
node_modules/.build-check, so it's safe to run while the dev server is running
- Builds to
- Production JS/CSS build:
ddev yarn build- Don't use this to verify a change — it rewrites
public/build, clobbering the manifest a running dev server relies on
- Don't use this to verify a change — it rewrites
- Preview a production build:
ddev yarn preview- Serves
public/buildathttps://[domain]:4173/build/, mirroring the production paths
- Serves
- Linting:
- PHP CS Fixer:
ddev composer cs:fix - Rector:
ddev composer rector(dry run) orddev composer rector:fix - PHP Static Analysis (PHPStan):
ddev composer static - Security audits:
ddev yarn audit:moderateorddev yarn audit:high - Upgrade a JS package, ignoring the age gate:
ddev yarn up:bypass <package> - Import a database:
ddev import-db --file=<file.sql.gz>(replaces the database) - Xdebug:
ddev xdebug on/ddev xdebug off(off by default)
There are no tests in the starter — add them (and their scripts) as a project needs them.
Incorporated Libraries & Tools
- Frontend – full list of dependencies can be found in package.json
- Vue 3 – frontend framework
- Vite – frontend build tool and dev server with HMR
- Tailwind CSS 4 – utility-first styling framework
- @tailwindcss/typography – prose styling plugin
- ESLint – checks JS for conventions & errors
- Stylelint – checks CSS for conventions & errors
- SVGO – optimizes SVG files
- Backend – full list of dependencies can be found in composer.json
- Craft CMS 5 – CMS framework
- Twig – server-side templating language
- CKEditor – rich text editor plugin for Craft
- Contact Form – contact form plugin for Craft
- Contact Form Honeypot – spam protection for contact forms
- Contact Form Extensions – additional contact form features
- SEO (Ether) – SEO plugin for Craft
- Field Manager (Verbb) – field management plugin for Craft
- oEmbed – oEmbed support for Craft
- Asset Usage – shows where assets are used
- Craft Vite – Vite integration for Craft CMS
- Craft MCP – Craft's built-in MCP server, registered for agents in
.mcp.json
- GitLab – CI/CD and deployment
- Dev Tools
- DDEV – Docker-based local dev environment
- PHPStan – static analysis of PHP
- Vue Devtools
Updating PHP version
- Change version in
composer.json. - Update the PHP version in the following files:
.ddev/config.yaml–php_versionbin/setup_server.sh– 4 places.gitlab-ci.yml– 2 places (default image andSERVER_PHP_PATH)php_cs.dist– update the@PHP8x5Migrationrule to match the new version.
- Run
ddev restartto rebuild the web container with the new PHP version. - Run
ddev composer updateorcomposer updateto update the PHP dependencies. If running locally without DDEV, ensure your local PHP version matches the new version. - Update version in
README.mdandAGENTS.md.