Drupal and Particle via Composer
Tags: drupal, patternlab, atomicdesign
Published: 2019-05-15 21:13:55

---
title: Drupal and Particle via Composer
published: true
description: A Getting Started Guide to Particle for Drupal 8 with Composer. 
tags: Drupal, Pattern lab, Atomic design
---

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](https://phase2.gitbook.io/frontend/) by Phase2.

[Hands-on with Design-System-First Development](https://www.youtube.com/watch?v=uYQjN9Ydgqk) will walk you through getting started with Particle.

## Why this guide?

The [Particle > Getting Started > Drupal 8](https://phase2.gitbook.io/frontend/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](https://medium.com/@isaacjoe/best-way-to-install-and-use-nvm-on-mac-e3a3f6bc494d) 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](https://phase2.gitbook.io/frontend/particle/getting-started/drupal-8) instructions.

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