generator-mc-d8-theme

Mediacurrent D8 Theme Generator

Yeoman generator for Drupal Themes - lets you quickly set up a Drupal 8 theme with sensible defaults and best practices.

What's New

Read the ⚡️ Changelog!

Links

• .sass-lint.yml
• .eslintrc.yml

Usage

While the mc-d8-theme generator can be run anywhere, it's happiest when it's run from an empty directory you'd like to become your theme.

I.E.

themes/custom/my_awesome_theme

First a note about using Node.js via NVM

While not a requirement we like to use NVM to manage the version of Node per project. Here's a quick one liner that will create a .nvmrc file and install the latest stable version of Node using NVM.

nvm install stable | grep -ohe 'v[0-9]*\.[0-9]*\.[0-9]*' | head -1 > .nvmrc && nvm use

Getting Started

There are two ways to install and use the theme generator:

1. Use npx

This is the recommended way of running the theme generator.

If you're using npm@5.2.0 or newer you already have npx available on the command line.

npx allows you to run one off commands using the latest version of a package without installing it globally.

npx -p yo -p generator-mc-d8-theme -c 'yo mc-d8-theme'

Tools like this you only run once every so often. By the time you need to run it again it'll be so far out of date you'll have to update it.

2. Install yo and generator-mc-d8-theme globally:

This is NOT the recommended way of running the theme generator.

If you're using an older version of npm or just want to install it globally:

npm install -g yo generator-mc-d8-theme

Run yo mc-d8-theme:

yo mc-d8-theme

To see which generators and subgenerators you have, run yo --help.

Update the generator as needed.

npm update -g generator-mc-d8-theme

Generators

The mc-d8-theme generator makes use of several subgenerators. Each of these can be called individually.

Available generators:

• mc-d8-theme (aka mc-d8-theme:app, the main app)
• mc-d8-theme:component
• mc-d8-theme:js-behavior
• mc-d8-theme:kss-style-guide

App

Main generator

Sets up a new theme, generating all the boilerplate you need to get started. The app generator also adds normalize and sample components.

Example:

npx -p yo -p generator-mc-d8-theme -c 'yo mc-d8-theme'

Or:

yo mc-d8-theme

Component

Generates component boiler plate based on whatever name you pass it. Please delete whatever you don't need. If you haven't modified it, you don't need it.

Example:

npx -p yo -p generator-mc-d8-theme -c 'yo mc-d8-theme:component "Site Logo"'

Or:

yo mc-d8-theme:component 'Site Logo'

This would generate the following files:

• components/site-logo/site-logo.scss
• components/site-logo/site-logo.json
• components/site-logo/site-logo.twig

JS Behavior

Generates a Drupal JS behavior based on whatever component file name you pass it.

Example:

npx -p yo -p generator-mc-d8-theme -c 'yo mc-d8-theme:js-behavior "site-logo"'

Or:

yo mc-d8-theme:js-behavior 'site-logo'

By default this will put the new behavior in the components directory. For example if the component name you passed it was site-logo, it will generate a new behavior within: src/components/site-logo/site-logo.es6.js.

The generated file is ES6 / ES2015 ready and can be compiled by the provided build tools.

KSS Style Guide

Generates a KSS Node style guide. You must pass it a name and a machine name for the theme if run independently of the main app. If run by itself this subgenerator has no way to modify your existing gulpfile.js Instead it will provide code you can copy and paste into your gulpfile.js for it to work correctly.

Example:

npx -p yo -p generator-mc-d8-theme -c 'yo mc-d8-theme:kss-style-guide "Super Sweet Theme" "super_sweet_theme"'

Or:

yo mc-d8-theme:kss-style-guide 'Super Sweet Theme' 'super_sweet_theme'

Use --help to see all usage info.

Example:

npx -p yo -p generator-mc-d8-theme -c 'yo mc-d8-theme:kss-style-guide --help'

Or:

yo mc-d8-theme:kss-style-guide --help

The New Theme

Sass & Gulp

Currently your new theme uses libSass and Gulp. While you can add whichever Gulp plugins you'd like, by default only the basics are provided.

• Gulp Sass
• Gulp Autoprefixer
• Browser Sync
• Source Maps
• Gulp Sass lint
• Gulp Eslint
• Gulp Babel
• Gulp imagemin

If you're not using npm@5.0.0 or later (which generates a lockfile package-lock.json) consider using shrinkwrap.

After you've got the Gulp file modified to your hearts content, shrinkwrap the dependencies so everyone uses the exact same node modules.

npm shrinkwrap --save-dev

Now running npm install will download the node modules specified in the npm-shrinkwrap.json file.

Go Team

Provided by default are seven npm scripts that point to Gulp tasks. We run gulp through npm scripts so the build tools can change without the user ever knowing.

1. Run the default build task (gulp in this instance) and everything in it. This is the equivalent to running gulp on the command line with Gulp installed globally.

npm run build

1. Compile Sass and JS.

npm run compile

1. Watch files and run tasks when they change.

npm run watch

1. Compress png and svg assets.

npm run compress

1. Build the KSS Style guide.

npm run styleguide

1. Lint Sass and JS files.

npm run lint

1. Delete compiled Sass, JS and style guide files from the /dist directory.

npm run clean

Contributing

Would you like to contribute? Want to make a few changes or fix a bug? COME ON OVER!

Clone down this repo:

git clone [e-mail]:mediacurrent/theme_generator_8.git

Remove generator-mc-d8-theme if you have previously installed it:

Tip: use npm ls -g -depth=0 to see what global node modules are installed.

npm uninstall generator-mc-d8-theme -g

From the generator root directory link your local generator files to npm:

npm link

Now whenever you run yo mc-d8-theme it'll use your locally cloned mc-d8-theme generator. Any updates done to the generator can be tested in real time.

Break off a feature branch dive right in. After you've got something you'd like to add, push back to the repo and pull request against master.

Changelog

🕷 1.4.0 (2017-09-01)

Bug Fix

• Back in 1.3.3 I fixed the layout folder but didn't quite get it in the right spot. This is now fixed.

New Feature

• Updated Babel to use env instead of a preset. This means you can simplify browser support a bit by adding browsers needed to the project's package.json.
• Moved Autoprefixer config to the package.json file similar to Babel env. This sets us up for when both Babel env and Autoprefixer use the same config.
• Added in error handling for JS and SCSS compiling. Now the watch task won't fail completely but will show you the error and keep watching files. This is a feature right?

Documentation

• Add best practice about using the generator via npx.
• Added theme documentation that points out Autoprefixer and Babel project config.