madebykind/craft-vue-tailwind-nanobox

Fork of craft-vue template that integrates the Tailwind CSS utility framework & removes unused CSS with Purgecss.

Vue-cli 💕 CraftCMS 💕 Fractal 💕 Tailwind 💕 Nanobox 💕 Oh my!

What is it?

Fork of craft-vue-tailwind composer project template that integrates:

• Nanobox for development environments
• git-flow as a branching/release strategy
• CraftCMS for content management
• Fractal as a living styleguide
• Tailwind utility first CSS framework
• Purgecss for build optimisation
• Jest for front end unit tests
• Vuejs for fancypants JavaScript stuff
• Husky for git hooks
• Hygen for scaffolding components
• eslint & Prettier for linting and code formatting

Via the combined magic of composer and vue-cli to give you an all singing, all dancing, pre-configured dev environment

What's included?

• Webpack + vue-loader for single file Vue components
• State preserving hot-reload
• Page reloading on file edits (twig, html, etc)
• State preserving compilation error overlay
• Lint-on-save with ESLint
• Source maps
• Fractal living styleguide with asset sync
• Load styleguide twig templates in Craft by prefixing include name with @

Requirements

This template requires the following software / packages to be installed in the host machine

• Nanobox (requiress free account signup)
• PHP 7.3
• git and git-flow
• Composer
• Node.js
• Yarn
• vue-cli

Installing on a new machine? Not actually a developer? Install homebrew and then grab all the above apart from Nanobox at once:

brew install php composer node yarn git git-flow

NB if installing Nanobox for the first time be sure to follow the post-install instructions for recent versions of macOS

How to use

Creating a new project

# create & install project
composer create-project madebykind/craft-vue-tailwind <path>
cd <path>
# install deps and basic setup
./scripts/project/after-install
# customise the project
yarn project:configure
# apply environment settings
yarn project:apply-env
# install Craft in nanobox
nanobox run
# once you're inside the nanobox container
yarn project:setup-craft

# build fractal -> twig pathmap
yarn build:components

Getting an existing project running

git clone <project-git-url> <path>
cd <path>
# create .env
cp .env.example .env

# install deps and basic setup
./scripts/project/after-install
# install Craft
yarn project:setup-craft

Accessing the CraftCMS database

By default Craft is set up to use Project Config, so you shouldn't often need to import / export a database from the site, however, if you do, you can get local mysql credentials in your host machine by running

nanobox info local

You can then use the credentials shown under data.db to access mysql via the cli or a GUI as you wish

Dev workflow...

Run the servers:

# run each of these in their own terminal pane
yarn serve
yarn test:watch
yarn serve:craft

Create a new front end component:

# Interactively skeleton a new component
yarn generate:component

Commands

Dev environment

• yarn serve: start the webpack dev server + fractal server (NB this does not start the craft/PHP server, as you will often want this to run in another process)
• yarn serve:assets start the webpack server above but without fractal running
• yarn serve:fractal start the fractal server
• yarn serve:craft start the nanobox container that serves CraftCMS

Generators

Via Hygen, templates in _templates/

• yarn generate:component interactively generate a new front end component

Linting

• lint what you'd expect
• lint:autofix lint and fix automatically where possible (run automatically pre-commit and pre-push)
• lint:config-check check the eslint config for rules that conflict with prettier

Tests

• test:unit run the unit tests (run automatically pre-push)
• test:watch run the tests on code change
• test:coverage calc code coverage stats

Building for production

• yarn build: Production ready build.
  • JavaScript minification with UglifyJS v3
  • Babel compiling
  • CSS across all components extracted into a single file and minified with cssnano
  • Static assets compiled with version hashes for efficient long-term caching
  • Removes unused CSS with Purgecss. Includes whitelister to keep third-party libraries untouched.
  • Bundle size analytics
  • Builds the living tyleguide to static HTML

Configuration (optional)

To edit the vue-cli config via the UI you will require Vue CLI 3 to be installed globally on your machine. You can run vue ui and import your the project to get started customising the configuration with vue-cli plugins of your choice.

NB By default the project uses a randomly allocated ports for webpack dev server and fractal server, which are set by the project:configure command run during project setup, stored project-wide under the kindConfig key in package.json and loaded into your .env file via the project:apply-env command.

In order for the UI to workvue-cli requires you to run the project on it's default port (8080). To use the UI to configure your project you'll therefore need to temporarily change ASSET_SERVER_PORT in your .env file to 8080 and restart your serve process, then change it back to its previous value once you've finished.

Under the hood

WTF is all this dark magic?

This project automates a lot of dull manual tasks. If you want to understand what's going on, here's a quick rundown

1. After composer creates the project, it runs the post-create-project-cmd script, which:

• sets up your .env file
• replaces the project's composer.json with one that's specific for your project
• cleans up some files that aren't needed
• dumps composer's autoloader

• runs scripts/project/after-install which then...

How asset loading works

NOTE: During development, only your assets will be served from localhost:<ASSET_SERVER_PORT> and referenced in the base template. You'll still load your site locally under your normal development domain (mysite.test, etc.). This will also cause a brief unstyled flash on page loads due to JS/CSS assets loading from javascript for development. This flash isn't present after build, on production.

After running yarn build, the easiest way to test your build files locally is to comment the environment variable in your .env file, and refresh the page. This will serve your assets from the build directory, rather than webpack's dev server.

For a detailed explanation on how things work, check out the Vue CLI docs.

Babel Compiling

This boilerplate uses babel-preset-env for configuring babel. You can read more about it here.

Thanks

Forked from chasegiunta/craft-vue-tailwind

craft-vue-tailwind-nanobox's Issues

Nanobox should be replaced with Docker

…given that development seems to have stalled, Docker is faster to get up and running with, and system drivers required by Nanobox throw warnings in MacOS since Catalina.

Project should include common components

Rather than re-inventing the wheel, or scavenging recent projects, this template should ship with a set of correctly marked up components.

Racist or discriminatory terms should be changed

Proposing:

• master -> production
• blacklist -> blocklist
• whitelist -> safelist

Craft set-up script throws an error

Running ./scripts/project/setup-craft in a box-fresh install gives:

Fatal error: Uncaught Error: Call to undefined method Dotenv\Dotenv::create() in /app/craft:16
Stack trace:
#0 {main}
  thrown in /app/craft on line 16

Manually installing Craft also errrors:

Fatal error: Uncaught Error: Call to undefined method Dotenv\Dotenv::create() in /app/web/index.php:15 Stack trace: #0 {main} thrown in /app/web/index.php on line 15 

Tailwind config is outdated and over-opionated

The defaults set in this file will change for almost every project, so there's little point in setting them here.

Config should also be updated to reflect the latest Tailwind version installed with this project, currently 1.1.4, though this should also be updated. Probably to v.1.9.0, the last version with IE support.

Site language should be determined by site settings

…not hardcoded in the application parent layout.