README

This is an alternate scaffolding package for Craft 3 CMS projects to Pixel & Tonic's canonical craftcms/craft package.

Vite buildchain

This project uses a Vite.js for the build system as per Vite.js Next Generation Frontend Tooling + Craft CMS, as opposed to the usual webpack buildchain.

Vite is fast ⚡

The project is based on Craft CMS using a unique templates/_boilerplate system for web/AJAX/AMP pages, and implements a number of technologies/techniques:

Docker Docker is used for local development; see Setting Up Local Dev below for details
A base Twig templating setup as described in An Effective Twig Base Templating Setup
Vite.js is used for the build system as per Vite.js Next Generation Frontend Tooling + Craft CMS
TypeScript for strictly typed JavaScript code
Vue.js 3.0 is used for some of the interactive bits on the website, and Vue.js 3.x allows us to leverage the Composition API
Tailwind CSS for the site-wide CSS
JSON-LD structured data as per Annotated JSON-LD Structured Data Examples
Google AMP versions of the podcast episode and other pages
Image transforms are done via a Serverless Image Handler lambda function, as described in the Setting Up Your Own Image Transform Service article
Static assets are stored in AWS S3 buckets with CloudFront as the CDN, as per the Setting Up AWS S3 Buckets + CloudFront CDN for your Assets article
Implements a Service Worker via Google's Workbox as per Service Workers and Offline Browsing
Critical CSS as per Implementing Critical CSS on your website
Frontend error handling as per Handling Errors Gracefully in Craft CMS
A custom site module as per Enhancing a Craft CMS 3 Website with a Custom Module
CLI-based queue as per Robust queue job handling in Craft CMS
buddy.works atomic deployments

...and probably a bunch of other stuff too.

The following Craft CMS plugins are used on this site:

AWS S3 - adding Amazon S3 volume type
Feed Me - to import entries and entry data from XML, RSS or ATOM feeds.
Redactor - Edit rich text content using Redactor by Imperavi.
Mailgun - Mailgun mailer adapter for Craft CMS
Position Fieldtype - Adds a position fieldtype
ImageOptimize - for the optimized images and srcsets used on the site
Minify - to minify the HTML and inline JS/CSS
Eager Beaver - to handle eager loading on entry pages
SEOmatic - for handling site-side SEO
Vite - for loading vite-generated manifest.json resources in a modern way
Typogrify - for smart quotes and other typographic ligatures
Colour Swatches - for adding color palettes
Timeloop - for creating repeatable dates
Super Table - Field Type to create powerful tables
Spoon - Organising our matrix fields

Using percipioglobal/craft

This project package works exactly the way Pixel & Tonic's craftcms/craft package works; you create a new project by first creating & installing the project:

`composer create-project percipioglobal/craft:dev-craft-v4-vite PATH --no-install --remove-vcs`

Make sure that PATH is the path to your project, including the name you want for the project, e.g.:

`composer create-project percipioglobal/craft:dev-craft-v4-vite vitecraft --no-install --remove-vcs`

We use --no-install so that the composer packages for the root project are not installed.

Setting Up Local Dev

You'll need Docker desktop for your platform installed to run the project in local development

Start up the site by typing make dev in terminal in the project's root directory (the first build will be somewhat lengt hy)
Navigate to http://localhost:8000 to use the site; the vite-dev-server runs off of http://localhost:3000

Wait until you see the following to indicate that the PHP container is ready:

php_1         | Craft is installed.
php_1         | Applying changes from your project config files ... done
php_1         | [01-Dec-2020 18:38:46] NOTICE: fpm is running, pid 22
php_1         | [01-Dec-2020 18:38:46] NOTICE: ready to handle connections

...and the following to indicate that the Vite container is ready:


The CP login credentials are initially set as follows:

Login: `support@percipio.london` \
Password: `letmein`

Obviously change these to whatever you like as needed.

Build the production assets by typing `make build` to build the critical CSS, fonts, and other production assets. They will appear in `cms/web/dist/` (just double-click on the `report-legacy.html` and `report-modern.html` files to view them).

**Important:** To find the correct credentials for `LOCAL_DB_CONTAINER` run `docker-compose up` and once the docker container is running, use the command `docker container ls` to find the correct name of the container.
If your project is called `test` the container will be somewhere along the lines of `test_mysql_1`. That's the value you do have to enter.

**N.B.:** Without authorization & credentials (which are private), the `make pulldb` will not work (it just runs `scripts/docker_pull_db.sh`). It's provided here for instructional purposes.

## Makefile Project Commands

This project uses Docker to shrink-wrap the devops it needs to run around the project.

To make using it easier, we're using a Makefile and the built-in `make` utility to create local aliases. You can run the following from terminal in the project directory:

- `make dev` - starts up the local dev server listening on `http://localhost:8000/`
- `make build` - builds the static assets via the Vite buildchain
- `make clean` - shuts down the Docker containers, removes any mounted volumes (including the database), and then rebuilds the containers from scratch
- `make update` - causes the project to update to the latest Composer and NPM dependencies
- `make update-clean` - completely removes `node_modules/` & `vendor/`, then causes the project to update to the latest Composer and NPM dependencies
- `make composer xxx` - runs the `composer` command passed in, e.g. `make composer install`
- `make craft xxx` - runs the `craft` [console command](https://craftcms.com/docs/3.x/console-commands.html) passed in, e.g. `make craft project-config/apply` in the php container
- `make npm xxx` - runs the `npm` command passed in, e.g. `make npm install`
- `make pulldb` - runs the `scripts/docker_pull_db.sh` script to pull a remote database into the database container; the `scripts/.env.sh` must be set up first
- `make restoredb xxx` - runs the `scripts/docker_restore_db.sh` script to restore a local database dump into the database container; the `scripts/.env.sh` must be set up first

### Other notes

To update to the latest Composer packages (as constrained by the `cms/composer.json` semvers) and latest npm packages (as constrained by the `buildchain/package.json` semvers), do:

make update


To start from scratch by removing `buildchain/node_modules/` & `cms/vendor/`, then update to the latest Composer packages (as constrained by the `cms/composer.json` semvers) and latest npm packages (as constrained by the `buildchain/package.json` semvers), do:

make update-clean


To use Xdebug with VSCode install the [PHP Debug extension](https://marketplace.visualstudio.com/items?itemName=felixfbecker.php-debug ) and use the following configuration:
```json
{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Listen for Xdebug",
            "type": "php",
            "request": "launch",
            "port": 9001,
            "log": true,
            "externalConsole": false,
            "pathMappings": {
                "/var/www/project/cms": "${workspaceRoot}/cms"
            },
            "ignore": ["**/vendor/**/*.php"]
        }
    ]
}

Below is the entire intact, unmodified README.md from Pixel & Tonic's craftcms/craft:

.....

About Craft CMS

Craft is a flexible and scalable CMS for creating bespoke digital experiences on the web and beyond.

It features:

An intuitive Control Panel for administration tasks and content creation.
A clean-slate approach to content modeling and front-end development.
A built-in Plugin Store with hundreds of free and commercial plugins.
A robust framework for module and plugin development.

Learn more about it at craftcms.com.

Tech Specs

Craft is written in PHP (7+), and built on the Yii 2 framework. It can connect to MySQL (5.5+) and PostgreSQL (9.5+) for content storage.

Installation

See the following documentation pages for help installing Craft 3:

Popular Resources

Documentation – Read the official docs.
Guides – Follow along with the official guides.
#craftcms – See the latest tweets about Craft.
Discord – Meet the community.
Stack Exchange – Get help and help others.
CraftQuest – Watch unlimited video lessons and courses.
Craft Link List – Stay in-the-know.
nystudio107 Blog – Learn Craft and modern web development.

percipioglobal / craft

Maintainers

Details