Spoke & Chain Craft Commerce Demo

Overview

Spoke & Chain is a fictitious bicycle shop custom-built to demonstrate Craft CMS and Craft Commerce. This repository houses the source code for our demo, which you can spin up for yourself by visiting craftcms.com/demo.

We’ve also included instructions below for setting up the demo in a local development environment with DDEV.

Spoke & Chain shows core Craft CMS features and a fully-configured Craft Commerce store:

• Articles and pages with custom layouts and flexible content.
• Front-end global search for products and articles.
• Categorized products with variants, categories, filtering, and sorting.
• Customer membership area with subscription-based services, order tracking and returns, and account management.
• Full, customized checkout process with coupon codes.
• Configured for healthy SEO and built targeting WCAG AA compliance.

Development Technologies

• Craft CMS 4
• Craft Commerce 4
• PostgreSQL (11.5+) / MySQL (5.7+)
• PHP (8.0.2+), built on the Yii 2 framework
• Native Twig templates with reactive Sprig components
• Node (12+) / npm (6+), managing and building front end resources

Front End Dependencies

• webpack
• Tailwind CSS
• Alpine.js
• Cypress

Local Development

Environment

If you’d like to get Spoke & Chain running in a local environment, we recommend using DDEV:

1. Clone the Spoke & Chain repository to your system.

   git clone [email protected]:craftcms/spoke-and-chain.git spokeandchain && cd spokeandchain

2. Initialize a DDEV project for the repo:

   ddev config --project-type=craftcms --project-name=spokeandchain --docroot=web && ddev start

3. Install the Composer dependencies:

   ddev composer install

4. Create your .env file:

   cp .env.example .env

5. Set the application ID and security key:

   ddev craft setup/keys

6. Restore the initial database

   curl -L https://github.com/craftcms/spoke-and-chain/raw/stable/seed.sql -o seed.sql && ddev import-db --src seed.sql

7. Optionally seed demo data:

   ddev craft demos/seed

   ⚠️ The Craft site is offline by default, and the seeder turns it on when it’s finished. If you skip this step, you’ll need to manually bring the site online by navigating to Settings → General Settings and switching System Status to “Online”.

8. Add a Craft account for yourself by following the prompts:

   ddev craft users/create --admin

💡 If you’re using a different local environment, see Craft’s Server Requirements and Installation Instructions.

Front End

Run npm ci with node 12. (If you’ve installed nvm run nvm use, then npm ci.)

If you’ve chosen a different environment setup, make sure your .env is configured for it. These environment variables are specifically used by webpack-dev-server:

• DEVSERVER_PUBLIC
• DEVSERVER_PORT
• DEVSERVER_HOST
• TWIGPACK_MANIFEST_PATH
• TWIGPACK_PUBLIC_PATH

You can then run any of the development scripts found in package.json:

• npm run serve to build and automatically run webpack with hot module reloading for local development
• npm run build to build front end assets for production

💡 When using npm run serve, switch your site’s URL from https:// to http://.

PurgeCSS

This project uses PurgeCSS to automatically remove redundant or unused styles generated by Tailwind CSS.

PurgeCSS is disabled by default for the serve script, meaning your site will be loaded with every available CSS class. It also means you’ll need to check the site after running build to be sure important classes aren’t inadvertently stripped away.

Classes actively being used should be detected automatically, but you can encourage them to be recognized by making sure full class names appear in your template, stylesheet, and JavaScript files.

❌ For example, don’t dynamically combine text-red- with a variable for this loop:

{% set classes = ['100', '500', '900'] %}
{% for class in classes %}
  <div class="text-red-{{ class }}"></div>	
{% endfor %}

✅ Loop through complete class names like so they each appear in full:

{% set classes = ['text-red-100', 'text-red-500', 'text-red-900'] %}
{% for class in classes %}
  <div class="{{ class }}"></div>	
{% endfor %}

If you can’t avoid programmatic concatenation, use Tailwind’s safelist option in tailwind.config.js.

Testing

Cypress tests cover multiple parts of the website:

• control panel – make sure the content structure is properly defined.
• front end – check that the website’s different sections work as expected.
• accessibility – evaluate the website for WCAG 2.0 compliance.

Set the environment variables Cypress needs to run by copying cypress.example.json to cypress.json and adjusting it:

cp cypress.config.example.js cypress.config.js

Open the Cypress Test Runner from the project root:

npx cypress open

Run accessibility tests only:

npx cypress run --spec "cypress/e2e/front/a11y/*.cy.js"

License

The source code of this project is licensed under the BSD Zero Clause License unless stated otherwise.

The imagery used by this project is the property of Marin Bikes, and used with permission. You are not free to use it for your own projects.