How to set up multiple Compony themes in your project

Introduction #

The Compony theme is a theme like any other theme you can download from Drupal.org. The only exception is that this theme doesn't actually do any theming by default. By default it is just a skeleton for your components.

Compony themes can be subthemes of any other (Compony or non-Compony) theme. (see instructions on how subtheming works on Drupal.org)

Next to subtheming with Compony, it is also possible to have multiple Compony themes in the themes directory.

If you have multiple Compony themes, you will want one Gulp-setup for all of your themes. This means you will only need to run the gulp command once, and only need to download the NPM-packages once.

These instructions assume you are starting from a setup with just one Compony theme.

Move the Gulp setup #

1. Install the Gulp setup inside your first Compony-theme

Firstly, please follow the instructions on how to install the Gulp-setup for a Compony-theme

2. Move the Gulp-specific files to the root of your project

Once you have successfully installed Gulp, it's time to move the Gulp-specific files to outside of your theme-directory, So multiple themes can use it.  

We can do this by opening up the theme-directory:

Terminal Created with Sketch.
Command line
cd themes/custom/compony

Next, we need to move these folders/files to the root of your project (commonly besides the web folder):

  • The gulpfile.js folder
  • The node_modules folder
  • The package.json file
  • The package-lock.json file
  • The yarn.lock file
  • The .nvmrc hidden file
compony
_sass-essentials
components
gulpfile.js <---
.nvmrc <---
YAML Created with Sketch.
compony.info.yml
YAML Created with Sketch.
compony.libraries.yml
compony.theme
package.json <---
package-lock.json <---
yarn.lock <---

An extra advantage of this is that your theme-folder looks way cleaner too.

3. Tell your Gulp-setup where your Compony-theme is located

After having moved the files to the root of your project, open up gulpfile.js/project.config.js and have a look at the gulpthemes-variable in there:

gulpfile.js
core
js-badge Created with Sketch.
config.js
js-badge Created with Sketch.
local.config.js
js-badge Created with Sketch.
project.config.js
module.exports = {
  gulpthemes: [
    {
      path: '',
      with_styleguide: false
    },
    // uncomment the following to enable it in multiple themes
    // {
    //   path: 'web/themes/custom/compony',
    //   with_styleguide: true
    // },
  ],
  features: {...}
};

By default the path-variable is set to an empty string '' because be default the Gulp-setup is directly in the Compony-theme. 

Having moved our Gulp-setup, this is no longer the case. So we need to tell our Gulp where our theme lives. We do this by filling in the path-variable so it becomes the path to our theme:

js-badge Created with Sketch.
project.config.js

module.exports = {
  gulpthemes: [
    {
      path: 'web/themes/custom/compony',
      with_styleguide: false
    },
    // uncomment the following to enable it in multiple themes
    // {
    //   path: 'web/themes/custom/compony',
    //   with_styleguide: true
    // },
  ],
  features: {...}
};

4. Test if it's working

You can now run the gulp-command, to check if everything is still working:

Terminal Created with Sketch.
Command line
gulp

An added advantage for having Gulp in the root of your project is that you can now run the gulp command from anywhere in your project. Your backend-colleague doesn't need to go find the right theme to compile either!

5. Commit your changes

You can now commit your changes, but first have a look at what files actually changed, as .gitignore files are different in every project. The only changes that you should have to commit is the moving of the files. Don't all of a sudden commit your node_modules-folder, if it wasn't committed before.

These changes are backwards compatible, so if your live-server is executing the gulp-command, that command won't break.

Add a second Compony theme #

Having followed the steps to move the Gulp-setup to be in the root of your project, it is now time to add a new Compony-theme.

1. Download a Compony-theme

Go to compony.io and download the latest version of the Compony-theme. Unzip the downloaded folder.

2. Rename the folder 

We can't have 2 themes with the same name in one project. Therefor we need to name the new theme to be something else of what we already have.

Therefor, let's name the folder comhorsy instead of compony. (replace comhorsy by a name relevant to your project). And then place it in your themes under web/themes/custom.

3. Remove the Gulp-setup from comhorsy

Because we already have a Gulp-setup outside of the themes-directory, we don't need the Gulp-setup that comes with the newly downloaded theme.

Therefor, we should remove the Gulp-setup by removing the following:

  • The comhorsy/gulpfile.js folder
  • The comhorsy/node_modules folder
  • The comhorsy/package.json file
  • The comhorsy/package-lock.json file
  • The comhorsy/yarn.lock file
  • The comhorsy/.nvmrc hidden file

4. Rename the internal files

In order for Drupal to recognise that we renamed a theme, we also need to rename 3 files inside our new theme:

  • rename compony.info.yml to comhorsy.info.yml
  • rename compony.libraries.yml to comhorsy.libraries.yml
  • rename compony.theme to comhorsy.theme

5. Change comhorsy.info.yml 

If you open up comhorsy.info.yml, you should change the name, description and libraries variables from this:

YAML Created with Sketch.
comhorsy.info.yml

name: Compony
type: theme
description: Compony, the component-only theme.
base theme: classy
core: 8.x
libraries:
  - compony/global

to this:

YAML Created with Sketch.
comhorsy.info.yml

name: Comhorsy
type: theme
description: Comhorsy, the component-only theme.
base theme: classy
core: 8.x
libraries:
  - comhorsy/global

6. Change comhorsy.theme

Function names in this file should start with comhorsy_ instead of compony_

7. Change your project.config.js

Now that you have added a new theme to your project, you need to go back to the root of your project, and change gulpfile.js/project.config.js to point to multiple themes.You need to change the gulpthemes-variable to something like this:

js-badge Created with Sketch.
project.config.js

module.exports = {
  gulpthemes: [
    {
      path: 'web/themes/custom/compony',
      with_styleguide: false
    },
    {
      path: 'web/themes/custom/comhorsy',
      with_styleguide: false
    }
  ],
  features: {...}
};

8. Restart Gulp

You can now rerun the gulp-command from anywhere in your project.

9. Test that both themes compile

You can now save a Sass-file of any component in both the compony-theme, and in the comhorsy-theme. If you check the output in your terminal, or check the dist-folder of both components, you can verify that everything works as expected.

10. Enable the theme in the backend

You can now enable the theme, in the Drupal backend, just as if you would do for any other Drupal-theme.

Go to "Appearance" (/admin/appearance) on the main Administration menu of your site. Click "Install" to install the theme, and you are done!

Common pitfalls #

If you have a Compony-theme installed on your site, but it's no longer named compony, you should be aware off a few things when:

Downloading components

Components on Compony.io, assume they will be used in a theme with the name of compony. So when you download components and place them in a theme that is not called compony, you need to find and replace the string compony by the name of your theme.

For example: if my-component is attaching the my-component-library to the my-component.html.twig-file it will do so like this:

my-component
dist
YAML Created with Sketch.
libraries.yml
Twig Created with Sketch.
my-component.html.twig

...

{{ attach_library('compony/my-component') }}

...

But if there is no theme called compony that defines a my-component-library, Drupal won't be able to attach this library. Therefor the Twig-code should change to:
 

Twig Created with Sketch.
my-component.html.twig

...

{{ attach_library('comhorsy/my-component') }}

...

Another example would be if the component uses a my-component.theme-file. As that would mean it will define function-names, that will start with compony_ instead of the name of your theme.

Contributing components

When you contribute your components, please be aware that every component should assume the theme-name is compony. This convention will make all of our work easier to share.

Updating 

If you plan to update your customly-named theme to a newer version by downloading the latest version from Compony.io, Please be aware that you will need to take in to account, that the updated code will assume that your theme is called compony.