DRUPAL BUILDS

Admin Theme & Theme Development

Our current choice for an admin theme is Gin. It is listed as part of the default modules above.

For theme development, we do not use a specific base theme. We strongly recommend to use the folder structure of Drupal core themes such as Olivero, Stable or the starter_kit (see /web/core/themes). Custom themes should be placed in /web/themes/custom.

In order to build CSS and JS bundles the preffered approach is to use our most recent compiler setup. Franois would be the main contact if you do not find a recent one.

Core Build Tools:

Laravel Mix - The primary build tool that provides a clean API wrapper around Webpack 5, simplifying asset compilation and management

Webpack - The underlying module bundler that handles JavaScript transpilation and dependency resolution

Node.js- Specified in .nvmrc for consistent development environments

CSS/Styling Stack:

Sass/SCSS - CSS preprocessor with glob imports via node-sass-glob-importer for wildcard includes

TailwindCSS - Utility-first CSS framework configured with custom design tokens imported from Figma

PostCSS - Post-processing pipeline with autoprefixer and cssnano for optimization

Figma Design Tokens - Design system tokens automatically converted to Tailwind variables via figma-tokens-to-tailwind-variables

JavaScript Tools:

Babel - JavaScript transpiler configured with @babel/preset-env targeting ES modules

Alpine.js 3 - Lightweight JavaScript framework for component interactivity

Component Development:

Storybook 8 - Component development environment for building and testing Single Directory Components (SDC) in isolation

Drupal SDC (Single Directory Components) - Drupal's component architecture for reusable, encapsulated UI components

Build Process:

The webpack.mix.js configuration compiles:

Main theme SCSS (templates/main.scss) into css/main.css

SDC component SCSS from components/**/[^_]*.scss into their respective component directories

Standalone library SCSS from templates/*/**/[^_]*.scss into flat CSS files

Main theme JavaScript and component-specific JS files with source maps

Available Commands:

yarn install        # Install dependencies

yarn dev           # Watch for changes and run Storybook

yarn watch         # Watch and compile assets (with polling)

yarn production    # Build optimized production assets

yarn storybook     # Run Storybook development server on port 6006

yarn build-storybook # Build static Storybook for deployment

If you are working on older projects, there could be a different setup. There are two approaches we usually used in the past: Using Gulp or Laravel Mix. Examples of build setups can be found in existing projects: 

• Gulp Example

• Mix Example

Reminders: 

• Wherever possible, make use of Drupal's libraries feature that allows CSS/JS to be added more targeted.

• Avoid adding excessive logic into TWIG templates. Keep business logic in the THEME.template file via preprocess functions or add it via a custom module

• Readability over extensibility! Avoid deep nesting and complex inheritance/extension of TWIG files.

Custom Module Development

Custom modules should be placed in /web/modules/custom. We recommend using the drush generate CLI in order to create module scaffolding as well as Plugins, Forms and Controllers. 

When creating a custom module, ensure that all its functionality is encapsulated within it. Code produced by the module should not have to rely on CSS or JS that is part of the sites theme and vice versa. Ensure that configuration is properly removed upon uninstalling the module.

We encourage giving back to the Drupal community. So if you feel the module you are developing could be beneficial to the wider community, speak to Andrew about the possibility to turn your work into a contributed module.

Images best practices

Every image displayed on the website should be configured with an image style for performance purpose.

Recommendations:

• Use responsive image styles

• Use the convert Webp

• Limit the sizes of the images using scale & crop

• For images in headers, set the formatter to use loading="eager"

For images that are displayed at the top of the page in headers/hero blocks, also apply this code:

/**

* Implements hook_preprocess_responsive_image().

*

* Add fetchpriority="high" to responsive images in the hero block.

*/

function yourtheme_preprocess_responsive_image(array &$variables) {

 // Make it fetchpriority="high" for performance reasons.

 if (!empty($variables['responsive_image_style_id']) &&

     $variables['responsive_image_style_id'] === 'your_image_style') {

   // Add fetchpriority="high" to the img element.

   if (isset($variables['img_element']['#attributes'])) {

     $variables['img_element']['#attributes']['fetchpriority'] = 'high';

   }

 }

}

Improvements

Potential areas where we need to do some research to improve our workflows and development. 

• Create custom Mellenger recipes for our sites - so we can configure / setup the base of the sites faster. We could potentially create some for features as well.

• Watch Drupal Canvas, test to see when it is ready for us to switch and move away from the layout builder experience.