Drupal and Particle via Composer

If you would like to use Pattern Lab with Drupal, and want an opinionated starter kit with Bootstrap 4 and many other goodies, then check out Particle by Phase2.

Hands-on with Design-System-First Development will walk you through getting started with Particle.

Why this guide?

The Particle > Getting Started > Drupal 8 documentation instructs us to download Particle to the themes directory. But you prefer to use Composer for managing Drupal 8 core and contributed modules. The following guide will walk you through how to do that with Particle.

Note: Using Composer is not necessary for us to get Particle with Drupal 8, and, in fact, has a downside that might deter any but the most determined.

Caveat

Christopher Bloom pointed out in a thread in #support on Drupal Slack that,

"Particle isn't a library that can be safely reinstalled on a system rebuild, but rather a starter-kit that must be committed to the repo."

This means that if you go this route, you'll need to manage customizations to Particle via patches applied via Composer. Why? Because, otherwise, when you composer update you'll overwrite any changes you've made. This might be a deal-breaker for most folks considering managing Particle via Composer.

If you choose not to go with Composer, I understand. I am still on the fence about it myself. But, at the very least, I am sure many Drupalers will benefit from the Node version section below.

First things, Node version

As of this writing, Particle supports Node versions 6, 8, and 10. Node is at version 12. So, if you need to support multiple versions of Node on your machine, I recommend the following:

• Uninstall Node

If node is already installed, uninstall it so that nvm can manage your active version globally or per project.

• Install Node Version Manager.

I successfully used brew install nvm, but there are additional instructions you'll need to follow.

• Install Node 10.

You may list available versions with $ nvm ls-remote. Note that v10.x Latest LTS (long-term support) is named Dubnium.

$ nvm install --lts=dubnium

Get Particle via Composer

We assume you've already got a working Drupal instance based on drupal-composer/drupal-project.

• Get the Components module

Particle is not a typical contributed Drupal theme, and does not list this module dependency. So, you'll have to get it via Composer yourself.

$ composer require drupal/components
$ drush en components

• Add the installer path in composer.json

This tells Composer to download the package to the specified directory.

    "extra": {
        "installer-paths": {
            "web/themes/{$name}": ["phase2/particle"],
            ...
        }
    }

Note: we went with the path suggested in the instructions instead of themes/contrib or themes/custom because this design-system needs to be committed into version control.

• Require the Particle package

$ composer require phase2/particle

Build and Install

• Using nvm, specify a project specific Node version in the web/themes/particle directory.

$ echo "10.15.3" > .nvmrc

• From within {drupal-root}/themes/particle/ run:

$ npm install
$ npm run setup
$ npm run build:drupal

• Install the Particle theme and set as default

$ drush theme:enable particle
$ drush config-set system.theme default particle

Conclusion

You now have a working Particle theme in Drupal. At this point, you can continue following the rapid development mode configuration at the bottom of the Getting Started > Drupal 8 instructions.

Again, be sure you understand the stated caveat above before going with this option.