project craft

nystudio107/craft

nystudio107 Craft 3 CMS scaffolding project

, _(*1)

About nystudio107/craft

This is an alternate scaffolding package for Craft 3 CMS projects to Pixel & Tonic's canonical craftcms/craft package., _(*2)

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., _(*3)

Vite is fast ⚡, _(*4)

The project

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:, _(*5)

• 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 using the @tailwindcss/jit
• 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 using the rollup-plugin-critical
• 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
• FastCGI Static Cache as per Static Page Caching with Craft CMS
• buddy.works atomic deployments

...and probably a bunch of other stuff too., _(*6)

The following Craft CMS plugins are used on this site: * FastCGI Cache Bust - to bust the FastCGI cache whenever entries are modified * ImageOptimize - for the optimized images and srcsets used on the site * Minify - to minify the HTML and inline JS/CSS * Retour - for setting up 404 redirects * 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 * Webperf - for monitoring web performance, _(*7)

You can read more about it in the Setting up a New Craft 3 CMS Project article., _(*8)

Using nystudio107/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:, _(*9)

composer create-project nystudio107/craft PATH --no-install

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

composer create-project nystudio107/craft craft3 --no-install

We use --no-install so that the composer packages for the root project are not installed., _(*11)

Setting Up Local Dev

You'll need Docker desktop for your platform installed to run devMode in local development, _(*12)

Ensure no other local development environments are running that might have port conflicts, then:, _(*13)

• Start up the site by typing make dev in terminal in the project's root directory (the first build will be somewhat lengthy)
• 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:, _(*14)

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:, _(*15)

vite_1        |   vite v2.3.2 dev server running at:
vite_1        |
vite_1        |   > Local:    http://localhost:3000/
vite_1        |   > Network:  http://172.22.0.5:3000/
vite_1        |
vite_1        |   ready in 1573ms.

The CP login credentials are initially set as follows:, _(*16)

Login: andrew@nystudio107.com \ Password: letmein, _(*17)

Obviously change these to whatever you like as needed., _(*18)

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)., _(*19)

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., _(*20)

Makefile Project Commands

This project uses Docker to shrink-wrap the devops it needs to run around the project., _(*21)

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:, _(*22)

• 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 - removes the cms/composer.lock & the entire cms/vendor/ directory as well as the buildchain/package-lock.json & the entire buildchain/node_modules/ directory
• make composer xxx - runs the composer command passed in, e.g. make composer install
• make craft xxx - runs the craft console command 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 nuke - restarts the project from scratch by running make clean (above), then shuts down the Docker containers, removes any mounted volumes (including the database), and then rebuilds the containers from scratch
• 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
• make ssh - opens up a Unix shell inside the PHP container for the project

Tip: If you try a command like make craft project-config/apply --force you’ll see an error, because the shell thinks the --force flag should be applied to the make command. To side-step this, use the -- (double-dash) to disable further option processing, like this: make -- craft project-config/apply --force, _(*23)

Other notes

To use Xdebug with VSCode install the PHP Debug extension and use the following configuration in your .vscode/launch.json:, _(*24)

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Listen for Xdebug",
            "type": "php",
            "request": "launch",
            "port": 9003,
            "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:, _(*25)

Roadmap

• Update to Tailwind CSS ^3.0.0

....., _(*26)

, _(*27)

About Craft CMS

Craft is a flexible and scalable CMS for creating bespoke digital experiences on the web and beyond., _(*28)

It features:, _(*29)

• 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., _(*30)

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., _(*31)

Installation

See the following documentation pages for help installing Craft 3:, _(*32)

• Server Requirements
• Installation Instructions
• Upgrading from Craft 2

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.