Emulsify on the Docksal stack

Not so long ago I wrote a short "How to" for using Emulsify Drupal theme with Docksal development environment (which you can also read in the official Emulsify wiki page).

In my humble opinion, Docksal is an amazing Docker powered environment for web development. It works blazing fast and is highly customizable. Give it a try!

In some other Docker based environments which I tried, I came across the obstacle. That obstacle was the use of the npm and its packages from dockerized environment simply because port 3000 wasn't opened for usage. Because I'm using the Emulsify Drupal theme, port 3000 is very important for me.

Guys behind Docksal fix that gap really fast so I switched all my projects to Docksal development environment.

Ok, let's start shall we.

Position yourself in the project root directory:

cd [project_root_dir]

Install Emulsify theme using Docksal's Composer (Composer instance installed and configured in Docksal image):

fin exec composer require fourkitchens/emulsify

NOTE!!! I recommend using the docksal/cli:2.0 or newer images (e.g. docksal/cli:2.0-php7.1). Docksal now exposes port 3000 for NodeJS apps by default so you can use Browsersync and similar node applications directly from Docksal containers. This means that it is no longer necessary to have node.js, nvm or/and yarn installed on your local OS.

Next, enable Emulsify and its dependencies. Drush 8.x users should use the following command but before that, position yourself in the web root directory ("web" or "docroot" in most cases) or use your drush aliases:

cd [web_root_dir]
fin exec drush en emulsify components unified_twig_ext -y

Drush 9.x users should use the following commands:

cd [web_root_dir]
fin exec drush en components unified_twig_ext -y
fin exec drush theme:enable emulsify

Optionally, create a custom clone of the Emulsify (you need to run the following command from within the Emulsify directory; replace "your_theme_name" with your theme name):

cd themes/contrib/emulsify
php emulsify.php "your_theme_name"

(Run php emulsify.php -h for other available options)

I like to use this clone command with the following arguments (replace Your Theme Name with your theme name):

fin exec php emulsify.php "Your Theme Name" --machine-name your-theme-name --path custom --description "Your Theme Name is a clone of Emulsify theme"

Next, run the following command from your theme directory if you're going to use your custom clone of the Emulsify theme (I always make a "custom" directory for custom themes, e.g. custom/your_theme_name):

cd ../..
cd custom/[your_theme_name]

If you plan on using the Emulsify theme (which is not recommended!), just stay in the contrib/emulsify directory.

If you already don't have your Github auth token globally defined you should do this now with (replace "YOUR_TOKEN" with the token generated on your Github account):

fin exec composer config --global github-oauth.github.com your_token

This step is necessary, otherwise, you'll get this error after executing command in the following step: "Failed to clone the git@github.com:drupal-pattern-lab/patternengine-php-twig.git repository".

Then run npm or yarn install command:

fin exec npm install

fin exec yarn install

After a successful installation you can start your Gulp tasks by running:

fin exec npm start

fin exec yarn start

There are 2 access URLs and you'll use the second one (external URL).

Finally, don't forget to set your theme as a default one. If you created a cloned theme, disable the original Emulsify theme (works on Drush 8.x):

fin exec drush pmu emulsify -y

or with:

fin exec drupal theme:uninstall emulsify

then enable and set to default your new theme in Drupal (you can do that with the Drupal console command or via the Drupal UI):

fin exec drupal theme:install [your_name_theme] --set-default

You're now ready to use your PL theme.