README

Used to create new projects using Craft CMS at XM Media.

Setting Up a New Site

Create a new project:

composer create-project xm/starter_craft project-name --stability=dev --no-install --remove-vcs

Update composer.json: name, license (likely proprietary) and description
Update package.json: name, version, git.url, license, private
Setup dev server:
1. If using InterWorx, run ./provision_site.sh locally — it provisions the whole site (see Provisioning a Site below) and runs setup_server.sh for you. To do it by hand instead, upload setup_server.sh to the domain dir and run: sh ./setup_server.sh
2. Upload the files (exclude files that are OS dependent like node_modules & .env or that are only for editing like .idea and .git and a lot of what's in .gitignore).
3. Install Composer (if not already installed)
4. Install PHP packages/vendors: php composer.phar install
5. Add .env (copy .env.example and update).
6. Run . ./node_setup.sh (this will setup node & install the JS packages – requires yarn to be installed).
7. Run yarn build (for production) to compile JS & CSS files.
8. Give executable perms to bin dir: chmod u+x craft
9. Ensure you have lando running.
10. Within lando ssh, install craft: ./craft install/craft
Remove or update the LICENSE file.
Install Composer locally (if not installed globally).
Composer install & update (locally): composer install && composer update
Run lando yarn && lando yarn up -R '**' locally.
Upload composer.lock and yarn.lock and on the server, run php composer.phar install and . ./node_setup.sh again.
Find and make changes near @todo-craft comments throughout the site. All changed files will need to uploaded to the server.
Create new favicons: realfavicongenerator.net
Set the email Subject Text for contact form submissions in Settings > Contact Form (under Plugins).
Delete or update the starter's README.md.
Update site name:
- In Settings -> General
- In Settings -> Sites
- Globals -> Site Information

Dev site can be accessed at https://[domain]/
Craft admin is located at /admin

Provisioning a Site

For sites on an InterWorx server, ./provision_site.sh (run locally) does the whole setup: 1Password items, the SiteWorx account, the database, setup_server.sh, the PHP restart sudoers entry, the Craft queue cron job and the GitLab CI/CD variables.

Requires an ssh Host with passwordless sudo, op signed in, glab authenticated and jq installed.
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, CI public key, 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:

setup_server.sh – runs on the server as the site user, in the domain dir; creates the releases/shared structure and symlinks. Normally run by provision_site.sh.
setup_gitlab_ci_vars.sh <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 24
Yarn v4

Commands

Yarn commands run inside the Lando node container via lando yarn <command>, so the Node version matches .nvmrc rather than whatever the host happens to have. Running them on the host with yarn <command> still works.

Install JS packages: lando yarn install
Run all checks & fixes: bin/check_full
- Runs Rector & PHP CS Fixer (applying fixes), then bin/check; run before pushing
Check all code (no fixes): bin/check
- Runs linting (JS, CSS, YAML, Twig), PHP static analysis & security audits
Dev JS/CSS server with HMR: lando vite (runs yarn install, then yarn dev, in the node container)
- Assets are proxied through the appserver 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 lando_apache_vite.conf
- Stop a server left running in the container: lando vite-stop
- A 503 on a /vite-dev/… asset means the dev server isn't running — start it with lando vite
- To run it on the host instead, just use yarn dev — Apache falls back to a host-run dev server, so the URLs and behaviour are the same
Compile check: lando yarn build:check
- Builds to node_modules/.build-check, so it's safe to run while lando vite is running
Production JS/CSS build: lando yarn build
- Don't use this to verify a change — it rewrites public/build, clobbering the manifest a running lando vite relies on
Preview a production build: lando yarn preview
- Serves public/build at https://localhost:9528/build/, mirroring the production paths (9528 is the only port the node service publishes)
Linting:
- JS (ESLint): lando yarn lint:js or lando yarn lint:js:fix
- CSS (Stylelint): lando yarn lint:css or lando yarn lint:css:fix
- Twig (twigcs): lando composer lint:twig
- YAML: lando composer lint:yaml
PHP CS Fixer: lando composer cs:fix
Rector: lando composer rector (dry run) or lando composer rector:fix
PHP Static Analysis (PHPStan): lando composer static
Security audits: lando yarn audit:moderate or lando yarn audit:high
Upgrade a JS package, ignoring the age gate: lando yarn up:bypass <package>

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
- Craft Vite – Vite integration for Craft CMS
- PHPStan – static analysis of PHP
GitLab – CI/CD and deployment
Dev Tools
- Vue Devtools

Updating PHP version

Change version in composer.json.
Update the PHP version in the following files:
- .lando.yml – config.php and services.appserver.type (if the Symfony recipe doesn't support the new version, you must override the appserver service with type: php:X.X)
- setup_server.sh – 4 places
- .gitlab-ci.yml – 3 places (default image, SERVER_PHP_PATH, and php-fpm service name)
- php_cs.dist – add the new version or update the @PHP8#Migration version to match the current version.
Run lando rebuild to rebuild the Lando container with the new PHP version.
Run lando composer update or composer update to update the PHP dependencies. If running locally without Lando, ensure your local PHP version matches the new version.
Update version in README.md and AGENTS.md.

consider: https://plugins.craftcms.com/image-toolbox?craft4

xm / starter_craft_3

Maintainers

Package info

Statistics

Security