Craft Starter

An Upstatement-flavored starter project for Craft 3

🎁 What's In the Box

• Craft 3 install
• ups-dock configuration
• Webpack bundling & optimization of CSS and JavaScript
• Browsersync
• Upstatement linting configuration for ESLint & Prettier
• Stylelint and PHP linting

🧰 Prerequisites

1. Install Docker for Mac
2. Install Ups Dock
3. Ensure NVM is installed globally

🚀 Getting Started

1. Download or clone this repository, and make sure to remove the .git folder

2. Make sure you're using the correct version of Node

   nvm install

3. Do a case-sensitive find and replace for

   • Craft Starter

   • craftstarter

     and replace those with your desired project name

   NOTE: Whatever you replace craftstarter with should be all lowercase, as it will be part of your Ups Dock URL

4. Run the install script:

   ./bin/install

At this point you should have a fully functioning Craft install available at https://your-project-name.ups.dock

NOTE: To access the CMS you need to use the Ups Dock URL (https://your-project-name.ups.dock/admin) and not localhost:3000/admin.

🐳 Ups Dock Environment

• URL: https://your-project-name.ups.dock
• Craft Admin: https://your-project-name.ups.dock/admin (un: admin, pw: password)

NOTE: your-project-name should be the same name you replaced craftstarter with in the "Making it your own" section above

🛠 Development Workflow

1. Run nvm use to ensure you're using the correct version of Node
2. Run ./bin/start to start the Craft backend / static build server
3. Open the Local URL that appears below [Browsersync] Access URLs: in your browser (https://localhost:3000/)

To modify front-end stuff, you should be working out of the static directory for styles & JavaScript and the templates directory for Twig markup. Read more about using Twig with Craft.

When you're ready to stop, type Control-C to kill the server.

Pro Tips

• If you ever need to backup your database, while the container is up and running you can run

  ./bin/backup

  and a gzipped SQL file will be dumped into the backups directory

• On ./bin/install, if you encounter an error such as

  ERROR: Bind for 0.0.0.0:3306 failed: port is already allocated

  this is happening because you already have something else (most likely a container from a different project) running that is using port 3306. To see your running docker containers, type docker-ps -a. Shut down any containers using port 3306.

💣 Uninstalling

To completely destroy the local Docker environment run:

./bin/uninstall

🖼 Static Assets

This project uses Webpack to compile and process static assets. For the most part you shouldn't have to think about it but here are some highlights:

• JavaScript is transpiled with Babel to support modern ES features.
• Stylesheets are compiled with Node Sass and run through Autoprefixer configured to add prefixes for all supported browsers.
• Fonts and images referenced in your scripts and stylesheets will be processed by Webpack and converted to data URIs or copied to the build directory depending on their file size.

📦 Third Party Libraries

There are two Webpack configurations -- one for project files (webpack/config.js), and one for third party vendor libraries (webpack/config.vendor.js). To cut down on build time these bundles are compiled separately.

If you need to add a third-party library:

1. Add the vendor library as a node dependency with npm (e.g. npm install --save jquery)
2. Add the package name to the vendor entrypoint in webpack/config.vendor.js.
3. Run npm run build:vendor to re-build the vendor bundle.

‍🙅‍ Code Quality

Don't commit messy code!

Here's a list of things already configured to keep you in line:

• EditorConfig
• Stylelint
• Upstatement's ESLint Config
• Upstatement's Prettier Config
• PHP Code Sniffer

All of these tools will be run with the pre-commit hook (configured with Husky) to make sure you're not committing inconsistent code. We highly recommend configuring your editor to use these tools so that you can see (and fix) style violations as you write code.

You can also run the linters from your terminal at any time:

npm run lint:styles
npm run lint:scripts
npm run lint:php

📚 Resources

Official Resources

• Craft 3 Documentation
• Craft 3 Class Reference
• Craft 3 Plugins

Community Resources

• Mijingo – Video courses and other learning resources
• Envato Tuts+ – Video courses
• Straight Up Craft – Articles, tutorials, and more