Craft CMS Boilerplate

A Craft CMS boilerplate utilizing JIT resource fetching, offline first content strategy, context-specific progressive enhancements, and Pjax navigation. The goal of this boilerplate is to provide developers with a sturdy foundation to build upon, the client an accessible and high performant website, and the content editors a simple and rich experience.

NOTICE: This is an opinionated system. It is built around the idea that one matrix field can be used to create a dynamic page builder. It uses Matrix Mate and the Smith plugins to provide an organized and customized content editing experience. Designs should be split into blocks and added to the content matrix field. When blocks become too complicated they should be split into several smaller, simpler blocks.

Key Beliefs

• Blocks should follow the KISS principle (keep it stupid simple).
  • Use Matrix Mate to group fields within a block.
  • Use Matrix Mate to group blocks into intuitive categories.
• Blocks should be opinionated.
• Hicks Law will be observed when creating blocks.
• A website is a living project and as a clients needs change blocks should be added.
• Leverage the benefits of modular programming.
• Resources should only be loaded when they are needed. Read the JINT Methodology for additional information about JIT resource management concept.

Getting Started

Download the latest release to get started.

Requirements

• Craft 3 server requirements
• Redis
• NodeJS >= v12

First Time Setup

Run the setup command npm run setup

Open the generated .env file and input your environment details.

Development

This boilerplate uses a handful of custom build tools. Feel free to uninstall them and write your own.

• DjinnJS is an ES Module based JavaScript framework for working with Web Components.
• CSSMonster transpiles SASS into CSS using node-sass.
• Brixi is a CSS variable based CSS utility framework.
• Snowpack bundles NPM packages into ES Modules.

Commands

# Development Build
npm run build

# Production Build
npm run production

# Generate Brixi CSS
npm run brixi

# Bundle NPM Packages
npm run bundle

Writing Code

All TypeScript/JavaScript, CSS/SASS, and HTML/Twig should be written in the templates/ directory. To keep everything organized follow these guidelines:

1. All directories and files must follow the kebab case format.
2. Group related files.
3. Code within a template directory should only be used on that template.

Code Organization

In the example directory structure below a web component will be included in the template custom-page

custom-page
├── custom-component
│   ├── custom-component.scss
│   ├── custom-component.ts
│   └── index.twig
└── index.twig

In the example above we are locking the custom-component usage to the custom-page template. If custom-component is needed on several templates it should be relocated higher up within the templates/ directory. The placement of files is irrelevant during the JavaScript/CSS build process allowing custom-component to be relocated at any time.

Why?

The organization of code is restricted as a measure of preventing breaking changes. Developers should not have to hunt through several directories to find the file they need to edit. Also when several developers work on the same project conflicts can arise when one developer includes a component from another template and the second developer is unaware of the include. If they make a change to the component for the original template it could break the component for the second template.

So why not just test the pages?

As sites grow it can be difficult and time-consuming to test every page and every possible combination of every page. It's much easier and faster to update a few {% include %} tags to point to a new location.

Code Architecture

This boilerplate is build around the model-view-viewmodel-controller software architecture pattern. For your convenience several custom import paths have been predefined in the tsconfig.json file.

1. Web Components can globally access controllers using the controllers/ import.
2. Web Components can globally access 3rd party JavaScript libraries using the lib/ import.
3. Web Components and Web Workers can globally access TypeScript definition files using the types/ import.