Search icon
Cart icon
Close icon
You have no products in your basket yet
Arrow left icon
All Products
Best Sellers
New Releases
Learning Hub
Free Learning
Arrow right icon
Modernizing Drupal 10 Theme Development
Modernizing Drupal 10 Theme Development

Modernizing Drupal 10 Theme Development: Build fast, responsive Drupal websites with custom theme design to deliver a rich user experience

By Luca Lusso
$31.99 $21.99
Book Aug 2023 360 pages 1st Edition
$31.99 $21.99
$15.99 Monthly
$31.99 $21.99
$15.99 Monthly

What do you get with eBook?

Product feature icon Instant access to your Digital eBook purchase
Product feature icon Download this book in EPUB and PDF formats
Product feature icon AI Assistant (beta) to help accelerate your learning
Product feature icon Access this title in our online reader with advanced features
Product feature icon DRM FREE - Read whenever, wherever and however you want
Buy Now

Product Details

Publication date : Aug 31, 2023
Length 360 pages
Edition : 1st Edition
Language : English
ISBN-13 : 9781803238098
Category :
Concepts :
Table of content icon View table of contents Preview book icon Preview Book

Modernizing Drupal 10 Theme Development

Setting up a Local Environment

Do you have a Drupal website you need to style? Or maybe it uses a default layout and the result is not what you want?

Drupal splits the management of content and how it is presented on a page in a very precise way. You can have the same content presented with very different layouts.

The layer of Drupal that manages layout and style is called a theme. The aim of this book is to teach you what the theme layer is, how it works, and how to leverage it to style content the way you want.

To get started, you need an environment where you can do your work. You can choose between your local machine or some remote service; in both cases, you will need a way to run a PHP interpreter, a web server, and a database server.

You will also need a code editor that supports working on different kinds of files—such as PHP, CSS, JavaScript, and YAML—and that is advanced enough to help you navigate through the project, write new code, and debug existing code.

In this chapter, we’ll set up that environment.

We will cover the following topics:

  • Installing the required software
  • Installing the demo site
  • Exploring the demo site
  • Disabling production optimization

Technical requirements

Which software to use to run a project locally can be a matter of taste or a best practice enforced by a team (or an organization). In this section, we’re going to install a selection of software that is free (at least for personal use) and, if possible, open source.

The following selection is not mandatory but it will simplify reading the rest of the book because all the screenshots and examples are based on the platforms mentioned.


Git is a distributed version control system that helps developers manage their source code changes over time. It tracks changes in code and allows multiple developers to collaborate on a project simultaneously. Git allows developers to work on their own copy of the code, experiment with different changes, and merge those changes back into the main code base when they're ready. It also allows for backup and recovery of code in case of system crashes or data loss. Git is widely used in software development and other collaborative projects.

The code used in this book is hosted in a Git repository provided by a company called GitHub. From that remote repository, you can obtain (clone) a copy of the code. A Git client is available by default on Linux and macOS systems; on Windows, you must use the WSL 2 subsystem.

You usually interact with Git using the command line, but different tools exist to provide a graphical user interface (one of these is Visual Studio Code, which we’ll install later).


Docker is a technology used to replicate the same software stack everywhere, independently of the host operating system. This is mandatory to keep consistency between all the developers in a team who may individually use different operating systems. Docker is also useful for replicating as much as possible the configuration of the production environment or having multiple stacks on the same local machine, each one with different software versions and configurations. Maybe you’re working on an old Drupal 7 website that requires PHP 7.*, and a shiny new Drupal 10 website that requires PHP 8.1.

Docker can be installed in different ways, but here we’ll use the simplest one: Docker Desktop.

Docker Desktop is a commercial application developed by the Docker team itself and it’s free for use unless you’re in a large enterprise (more than 250 employees or more than 10 million USD in annual revenue) or some government entity.

Detailed instructions on how to install it can be found at In the next examples, we’ll use macOS, but the setup and usage are the same on Windows and Linux.

After the installation, you may need to set up Docker Desktop to match your system. Here’s how to do that:

  1. To run Docker, simply click on its icon in the applications list. Once it's up and running, you'll see the Docker icon appear on the top right of your screen. Clicking on the icon will open a menu where you can easily check if Docker Desktop is running smoothly or if there are any issues to address.
Figure 1.1 – Docker Desktop menu

Figure 1.1 – Docker Desktop menu

  1. Click on the Preferences link to open the Preferences window.
  2. Click on the Resources | Advanced section to tweak how many of your system resources Docker can consume. On the right pane, you can select how many CPUs and how much memory, swap, and disk size Docker can use:
Figure 1.2 – The Advanced section of Docker Desktop

Figure 1.2 – The Advanced section of Docker Desktop

In this case, I’ve set my system to grant Docker up to 4 CPUs and 12 GB of memory. Usually, you’ll want to choose half of the resources of your system.

  1. Click on the Resource | File sharing section to configure which directories can be bind-mounted into Docker containers:
Figure 1.3 – The File sharing section of Docker Desktop

Figure 1.3 – The File sharing section of Docker Desktop

In a production environment, you will have a Docker image that contains both the PHP interpreter and the code of the website, but in a local environment, to speed things up, the code stays on the host (your local machine) and is then mounted (made accessible) to the Docker container using a volume. Docker Desktop allows only for a subset of your computer filesystem to be mounted to a Docker container (for security and performance); you can set which directory to include in the File sharing section of the Preferences pane. The /Users directory is included by default, so you can just clone the demo repository somewhere inside this folder.

To be sure everything is clear, here you can find a list of base Docker concepts as a reference:

  • Docker engine: The core system that allows you to build and run containers.
  • Image: Contains a list of instructions used to build a container.
  • Container: This is the executable image that contains everything needed to run an application.
  • Volume: This is the system used by Docker to persist a container’s data between executions. So, container data stored in a volume will be preserved even if the container itself is stopped or removed. Furthermore, the same volume can be attached to multiple containers.
  • Compose: This is a tool that allows a set of containers to work together in the same network.

To run a Drupal website, we need at least two containers—one with a web server and one with a database server. Other containers can be useful during development, such as one to explore the database data and one to catch sent emails (for debugging purposes).

Of course, you can set up your stack from scratch, choose which images to use (or build some custom ones), configure them, find a way to orchestrate them, and so on. Because this is a book on Drupal and not Docker, we’ll use a tool that does everything we need for free.


DDEV is an open source tool to speed up local PHP development. It uses Docker to configure and run everything that is required to work on a Drupal (or other PHP-based) website. It also provides a lot of commands to interact with the stack.

DDEV configurations can be added to Git and shared with all developers in the team. In this way, whoever clones and spins up the project will have exactly the same environment.

Again, the installation procedure depends on your computer's operating system. You can find all the details on the project website:


Pay attention to the installation procedure—one required step is about installing and configuring mkcert ( mkcert allows you to visit any DDEV-managed website using HTTPS just as it will be in production.

DDEV doesn’t have a graphical interface; everything is managed through the command line. To see a list of all available DDEV commands, you can simply type ddev on your terminal:


The demo code you’ll download in the next section contains a ready-to-use DDEV setup, located in the .ddev folder in the root of the repository.

Visual Studio Code

More than just a code editor, we need a full IDE to support our work with different kinds of files. Here, we have a lot of choices, which are mainly driven by personal taste and budget. One IDE that is free but very powerful is Visual Studio Code.

Visual Studio Code is a free application that runs nearly everywhere, from every operating system through the web (it’s the IDE that powers and, for example).


You can find detailed instructions about how to download and install Visual Studio Code at

Visual Studio Code's features can be enriched by installing extensions; we’ll need some of them to speed up our work, including the following:

  • PHP Intelephense
  • PHP Debug
  • Tailwind CSS IntelliSense
  • Twig Language 2
  • Prettier (a code formatter)

To install an extension, follow these steps:

  1. Open Visual Studio Code.
  2. Click on the View | Extensions menu item to open the extensions view.
  3. Use the search engine to find the extension to add.
  4. Click on the Install button under the extension name in the right pane:
Figure 1.4 – PHP Intelephense is one of the most complete plugins for working on PHP with Visual Studio Code

Figure 1.4 – PHP Intelephense is one of the most complete plugins for working on PHP with Visual Studio Code

Our local stack is ready to be used. In the next section, we’ll use it to set up and run the demo website.

Installing the demo site

Now that the local environment is ready, we can clone the repository of the demo site.

Cloning and building

The repository has two branches, one with the final website (the same one that you will have at the end of this book) and one with just the CMS configured. We’ll start with the latter, but if you want to see the final result you can switch to the first one.

Start by cloning the repository in a local folder. Remember that Docker Desktop limits the folder that can be mounted in a container, so choose one that is included (usually a subfolder of your home directory is the safer choice):

git clone

Then, cd to that folder and start the DDEV stack:

ddev start

This command starts the stack but doesn’t build the website; to do that, you must run this command:

ddev build

build is a custom command, not part of the original DDEV installation, and it’s available because it has been defined in the .ddev/commands/web folder of the repository you’ve cloned. In the .ddev/commands folder, you will find some other custom commands that we have added to DDEV, and you can add your own too. Commands are bash scripts that run on your host shell or in one of the running containers, depending on which folder contains it:

  • .ddev/commands/host: The host computer
  • .ddev/commands/web: The web container (where the web server and the PHP interpreter run)
  • .ddev/commands/db: The container that runs MySQL


The folder that contains the website is mounted into the web container. The files are exactly the same, but they can be accessed from your local computer and from the web container. Bear in mind that the absolute path may be different between the two systems. On your local computer, it will be something such as /Users/lussoluca/Sites/modern_drupal_themes, but on the web container, it will always be /var/www/html. You can connect to a shell that runs in the web container using the ddev ssh command. To close the web container shell and return to the host shell, just type exit and hit Return.

Internally, the build command uses a set of tools to download all the required dependencies and install the website.

Every time you want to reinstall the demo website from scratch, you can execute the build command again.

DDEV provides some other useful commands, as follows:

  • stop: Stop and remove the containers of a project. Does not lose or harm anything.
  • describe: Get a detailed description of a running DDEV project.
  • delete: Remove all project information (including the database) for an existing project.

And there are many more—just type ddev and hit Enter to see them all.


During the start process, DDEV may print a message such as “ssh-agent container is running: If you want to add authentication to the ssh-agent container, run 'ddev auth ssh' to enable your keys.” You can safely ignore this warning in our context.


All the external PHP dependencies needed to run the website (such as contrib modules and development tools) are not versioned in the Git repository. Instead, they’re downloaded from the internet using a tool called Composer. Composer manages packages using a Semantic Versioning approach, where every package has a version in the form of major.minor.patch (more information at The application and its dependencies are described in a file called composer.json, usually located in the root folder of the project. Composer has a lot of commands, but the three most used are shown next.

Here’s the first one:

composer update –prefer-dist

This updates all the packages to the latest version (always respecting the Semantic Versioning rules). This command also updates (or creates) a composer.lock file that stores the exact version that has been installed for each package. The composer.lock file must be added to the Git repository and is mandatory to allow every developer on the team, the CI/CD pipelines, and remote environments to have the same version of every dependency.

The second most used Composer command is this one:

composer install –prefer-dist

This reads from a composer.lock file and downloads the exact version of every package.

Finally, when you need a new package (for example, the WebProfiler contributed module) you can run the following command:

composer require drupal/webprofiler

The ddev build command already executes composer install for you, and you can see the list of required packages in the composer.json file in the root folder of the project.

Configuration management

Starting from Drupal 8, the system exports all the configuration needed to recreate the site into a folder, where each configuration is stored as a YAML file. A complex website can have hundreds of such files. Drupal doesn’t use those files directly; they must be imported into the database (this means that if you change one of those files manually, it needs to be imported again to be seen by Drupal). A way to package configurations is to create an installation profile. Drupal core has some ready-to-use installation profiles, such as Standard, Minimal, and Umami (you can see the full list by installing Drupal using the web interface or by looking in the core/profiles folder). In our demo website, we have defined a new installation profile, called AlpsTrips, in the web/profiles folder.

Just about everything in Drupal has a double name—one for humans (such as the profile name, AlpsTrips) and one for machines (that has more restrictive rules, such as no spaces, only some special characters allowed, and so on). The machine name for the AlpsTrips profile is alps_trips_profile.


One of the packages downloaded by Composer is Drush ( Drush is not a Drupal module and it isn’t used by the website itself; it’s used to automate operations on a Drupal website from the command line. Tasks such as installing Drupal, managing content or users, installing modules, and so on can all be done without even opening a browser instance. To see all the available Drush commands, you can run the following:

ddev drush

DDEV will forward the call to the Drush instance present in the web container.

Default Content

The content of a Drupal website stored in the same database that is used for configurations, but unlike configurations, the core of Drupal doesn’t have any tools for exporting them. To style the website, we need some content to work on (but also for showing the work in progress to the customer, or for writing end-to-end tests). This can be done in a lot of different ways; the community has not yet agreed on the tool to be used by default.

One solution is to use the Default Content contributed module (

On the demo website repository, we've used Default Content to export a set of dummy contents to a custom module (located on the web/modules/custom/demo folder). When this module is enabled, the contents are automatically imported into Drupal.


The latest tool that is used to build our website is Yarn. Yarn is a package manager for Node.js, and we need it for the same reason we need Composer for PHP packages: we don’t want to save the dependencies in our repository. Similar to Composer, Yarn uses two files—package.json and yarn.lock—to describe which packages to download and at which exact version. Yarn can also be used to define and run custom scripts, such as building CSS and JavaScript assets.

All of those tools are used by our build command to go from a set of files in a repository up to a fully functional Drupal website. The tasks that are executed are set out here:

  1. Use Composer to download all the required PHP dependencies: composer install –prefer-dist.
  2. Use Drush to install Drupal from a set of configurations.
  3. Use the Default Content module to import dummy content.
  4. Use Yarn to download all the required JavaScript dependencies and to build the theme assets.

After the build command ends, you can open a browser and start navigating. The website URL is printed at the end of the ddev start command. At any time, you can use the ddev describe command to print a list of details about the project. The URL you’re looking for is the one for the web service:

Figure 1.5 – Using ddev describe to list all the available services for a project

Figure 1.5 – Using ddev describe to list all the available services for a project

In this case (and probably also for you), the URL is, and the website should look like this:

Figure 1.6 – The home page of the AlpsTrips website

Figure 1.6 – The home page of the AlpsTrips website

You’re navigating as an anonymous user; if you want to administer the site, you must log in as a user with some administrative privileges. During the build, one such user has been created for you, with admin as username and admin as password. To log in, you can do the following:

After submitting the credentials, you should see some more elements, such as a dark toolbar at the top of every page. From there, you can access every configuration page of Drupal.


The admin user created during the installation phase of Drupal has too much power. The permissions enforcement and the access checks don’t run for that user. In a real project, we suggest you create a new user, with only the permissions required.

The demo website is packed with everything you will encounter in a standard Drupal website, so let’s explore it and review all the concepts we’ll need to style it.

Exploring the demo site

Frontend development in Drupal usually starts very late in a project life cycle.

The typical steps are reproduced here:

  1. The design team has to create mockups, style guides, and the design system.
  2. The backend team has to set up the stack, initialize the project, and build the content structure.
  3. Some content needs to be created (manually or with some automatic process).
  4. Finally, the frontend team works on the frontend.

The main focus of this book is on the last step.

We could try to teach you how the theme layer of Drupal works in an abstract way, without implementing any real theme, or we could start from the first step in the list and make you do a lot of stuff even before you start to understand what a theme is.

We don't think this is the best thing we can do. Instead, we’ll take a little bit of an opinionated approach.

By simulating what happens in a typical project, we have already followed the first three steps for you.

We have implemented a fully configured Drupal 10 website, with a content structure and some example content. We’ve added some other modules that are quite standard in a modern Drupal website, such as Paragraphs (

We have created a design system ( and a style guide (

We’ve also defined how the project should run on your local machine. We’ve chosen for you where the code is hosted, the rules to enforce code quality, and the tools to use.

The demo website has enough features to let us talk about every aspect of the theme layer of Drupal 10, but it’s simple enough to avoid wasting time doing the same thing twice. We have a home page, some listing pages, a detail page, and some forms.

We’ve made a lot of assumptions to allow you to concentrate on the frontend layer only. But don’t worry—we’ll explain every decision we’ve made.

Because of this, the code in the book is not enough to replicate the demo website, so you have to start by cloning the Git repository from GitHub ( We suggest you follow along with the explanations by trying them on your local computer—we’ll guide you step by step.

Let’s start by reviewing how editorial data is managed by Drupal and which concepts we’ll use during the rest of the book.


All information an editor writes in content using the Drupal admin interface is stored in fields. A field can have different properties, widgets, and formatters. Let’s look at these in a bit more detail:

  • Property: Represents the data stored in the database—for example, a text area field has three properties: value, summary, and text format; a geographical field that represents a point on a map probably will have two properties: the latitude and the longitude.
  • Widget: An element used by an editor to insert data into the field—for example, a <textarea> HTML element for a text area, or two text fields for a geographical point (to input the latitude and the longitude).
  • Formatter: The markup used to show the field value on the frontend so that a user can read it—for example, a formatter for a text area can simply render the text, maybe truncated, whereas a geographical field can be rendered like a marker on a map.


A single field type can have more than one supported widget and more than one supported formatter.

Paragraph types

A paragraph is not a concept that comes from the core of Drupal; it’s contributed by an external module called Paragraphs (

Modern layouts are built by aggregating components, and one possible way to manage such components in Drupal is by using the Paragraphs module.

Paragraphs are a collection of fields that together build a component. For example, a hero paragraph can be made of a background image, a claim, and a CTA button (composed of a label and a URL). A slider paragraph can contain a media field where the editor can insert a list of images to show in a carousel…. and so on.

You can define as many paragraph types as you need to allow editors to compose complex pages.

Content types

Fields and paragraphs are then aggregated into content types. A content type is a collection of fields, such as a paragraph, but with some added features. For example, all content built from a content type has a canonical URL so that it can be added to a menu and navigated by the end user.

Content types are used to represent the different structures an editor can insert into a website, such as a blog post, a landing page, a news page, and so on.

An instance of a content type is called a node.


Often, it is useful to tag or categorize content, to add information to the end user or for it to be aggregated in some way.

For example, on the demo website, the Trip content type can be tagged by difficulty or by trip duration. To manage this kind of functionality, Drupal provides a taxonomy system, which allows you to manage the vocabulary of terms.


Content types (and paragraphs) are not the only way to add editorial content to a website; the block system allows you to put contextual information around the main content—for example, on the header, the footer, or in a sidebar. Blocks are useful because they aren’t related to a specific URL, but they’re shown on a page based on a set of visibility rules. For example, you can place a block on the sidebar of every node of a particular content type, or for every user in a role.


Content is usually aggregated in lists—for example, the latest blog posts or the trips available in a specific season. On a Drupal website, every time you mention a list of something, you’re talking about a view. A view is a collection of elements, extracted from the database using a set of conditions. A view’s output can then be shown at a specific URL or in a block.


In the end, a website is made of pages that can be navigated by the final user. Pages in Drupal are a mix of nodes, views, and blocks, and the navigation is managed by the menu system. A menu in Drupal is a hierarchical structure that stores a navigation tree. Every element in the tree has a label and a URL, which can be internal or external. A website can have more than one menu—maybe one for the main navigation, one with the user links, one for the footer, and so on.

Before starting to work on the design, we need to do just one more step: disable all the performance optimization that Drupal has out of the box.

Disabling production optimization

Starting from version 8, Drupal is optimized for production out of the box. This means that all cache layers are enabled, and a change in the code is probably not visible until the cache is cleared. Obviously, this can slow down development a lot. In the earlier phases of development, all those optimizations can be turned off, but it is mandatory to turn them all back on before production because running a Drupal site without the cache enabled can hide some very difficult-to-catch bugs. How many times have you heard of data breaches where a legit logged-in user had access to data about some other user? This is probably a cache issue, where a page has been built for a user and then cached and served as is to every other user. If that page contains some personal data, that is leaked to everyone.


Drupal is a complex system; to build a single page, it needs to do a lot of things, and most of them involve some sort of interaction with an external (and usually slow) system (the database for the data, the filesystem for the code, and others). If the markup that Drupal is building can be used as is for multiple requests, it’s a waste of resources to build it over and over again. Cache systems exist precisely to store the intermediate steps of a complex calculation to avoid doing the same thing twice. This text is not part of the note. It must be moved outside, just before the next sentence (At the end...)

At the end of the web/sites/default/settings.php file, we’ve added these lines:

if (
  file_exists($app_root . '/' . $site_path . '/settings.local.php')
  && getenv('IS_DDEV_PROJECT') == 'true'
  include $app_root . '/' . $site_path . '/settings.local.php';

This basically means that if some conditions are true, the system should include a configuration file with local settings. The conditions are set out here:

  • Check whether the $app_root . '/' . $site_path . '/settings.local.php' file exists. app_root resolves to the /var/www/html/web folder, and site_path resolves to the sites/default folder
  • Check whether the value of the IS_DDEV_PROJECT environment variable is true

Both conditions are true on our local stack; the file it’s located at /var/www/html/web/sites/default/settings.local.php and its content has been copied from /var/www/html/web/sites/example.settings.local.php, with a couple of lines uncommented. Let’s see the most important ones:

$settings['container_yamls'][] = DRUPAL_ROOT . '/sites/';

Drupal organizes all the business logic into services, discrete PHP classes that perform a specific task (such as sending an email, rendering a template, writing to logs, and so on). All those services are managed by a service container ( When some code needs a service to perform a task, it asks the service container to provide one, along with all its dependencies. The service container also manages parameters, which are scalar values that can be used to configure the application.

One of the services defined in the service container manages the integration with a cache backend.

A cache backend is used to store data that is slow to be computed. Instead of executing the same slow code on every request, Drupal can store the results in a cache. This speeds up the building and delivery of pages.

By default, the cache backend is the same database that Drupal uses for content (managed by a service called cache.backend.database). Every time Drupal needs to save some intermediate computation, it passes the data to the cache system, which in turn uses the cache backend to persist it somewhere.

We can use the file to add or change services and parameters in the service container. Let’s break down the file to see what it does:

  http.response.debug_cacheability_headers: true

This parameter forces Drupal to add a couple of HTTP headers to the response. This will be useful later when we talk about cache tags.

  debug: true
  cache: false

Those two lines configure Twig (Twig is the render engine that turns templates and data into HTML), by enabling debug and disabling the cache.

  class: Drupal\Core\Cache\NullBackendFactory

Lastly, here we define a new cache backend service, cache.backend.null, which uses the NullBackendFactory class to manage the cache. NullBackendFactory doesn’t persist the cache anywhere, basically forcing Drupal to rebuild its data structures on every request.

Continuing with the settings.local.php file, we find the following:

$config['system.performance']['css']['preprocess'] = FALSE;
$config['system.performance']['js']['preprocess'] = FALSE;

Those two lines disable the CSS and JavaScript preprocessing and minification system of Drupal. When preprocessing is TRUE, if you look at the source of any Drupal page, you will see something like this:

<link rel="stylesheet" media="all" href="/sites/default/files/css/css_4X4pNrCAbSu81rOnCPB9UMoipKt5NIfi5kpoa86bdG8.css" />
<link rel="stylesheet" media="all" href="/sites/default/files/css/css__4bA7B8aKHQdv-woFVLAGpXcUrTGif-jwiZJPj5yZ1s.css" />
<script src="/sites/default/files/js/js_Y151moVVESM9BeoCt8M3cSJ2_x_o14H43dXy6nGL6JM.js"></script>

This is difficult to understand because isn’t clear where a CSS rule or a JavaScript function comes from (also because the CSS in those files are minified). When preprocessing is FALSE, the output is way more readable:

<link rel="stylesheet" media="all" href="/core/themes/stable9/css/system/components/ajax-progress.module.css?rmstqh" />
<link rel="stylesheet" media="all" href="/core/themes/stable9/css/system/components/align.module.css?rmstqh" />
<link rel="stylesheet" media="all" href="/core/themes/stable9/css/system/components/autocomplete-loading.module.css?rmstqh" />

In the preprocessed version, the filename changes every time the cache is cleared, and this forces the browser to download the file again. When preprocessing is turned off, Drupal emits the original name of the file. To force the browser to download the file again, a token is appended at the end.

Three more lines deserve attention in settings.local.php:

$settings['cache']['bins']['render'] = 'cache.backend.null';
$settings['cache']['bins']['page'] = 'cache.backend.null';
$settings['cache']['bins']['dynamic_page_cache'] = 'cache.backend.null';

Those lines are commented in the original example.settings.local.php file. By removing the comments, we force the cache bins that deal with HTML generation to use the cache.backend.null service that we added in the file.


Starting from Drupal 10.1 there is an easier way to manage development settings. A new Configuration | Development settings page has been added that allows you to turn on Twig development mode and to turn off render cache, dynamic page cache, and page cache. You can find more information on the related change record here:

Enabling Twig debug and disabling caches slow down the website but will allow us to see a change in template as soon as we reload a page, without the need to clear the cache. As we mentioned before, the functionalities of the website must be tested with those caches enabled, as they will be in production, to avoid possible data leaks.


In this chapter, we learned an easy way to set up a local machine to work on a Drupal 10 website. Using Docker and DDEV, we installed the website we’ll work on for the rest of the book. We also installed and set up an IDE, Visual Studio Code, which will allow us to inspect and work on the code in a powerful way. We dissected the demo website to recap how a Drupal website is made and which concepts we need to understand it. Finally, we disabled all the performance optimization to speed up the development of the new custom theme.

It's time to start building our theme. In Chapter 2, Setting a New Theme and Build Process, we'll create a new theme from scratch and set up a build process to automate some useful tasks.

Left arrow icon Right arrow icon
Download code icon Download Code

Key benefits

  • Explore real-world examples with proven methodologies to gain a deeper insight into the Drupal theme layer
  • Learn how to translate a graphic design into a maintainable and robust Drupal theme
  • Improve performance and accessibility with a decoupled frontend to consume data exposed by Drupal’s APIs
  • Purchase of the print or Kindle book includes a free PDF eBook


Working with themes in Drupal can be challenging, given the number of layers and APIs involved. Modernizing Drupal 10 Theme Development helps you explore the new Drupal 10’s theme layer in depth. With a fully implemented Drupal website on the one hand and a set of Storybook components on the other, you’ll begin by learning to create a theme from scratch to match the desired final layout. Once you’ve set up a local environment, you’ll get familiarized with design systems and learn how to map them to the structures of a Drupal website. Next, you’ll bootstrap your new theme and optimize Drupal’s productivity using tools such as webpack, Tailwind CSS, and Browsersync. As you advance, you’ll delve into all the theme layers in a step-by-step way, starting from how Drupal builds an HTML page to where the template files are and how to add custom CSS and JavaScript. You’ll also discover how to leverage all the Drupal APIs to implement robust and maintainable themes without reinventing the wheel, but by following best practices and methodologies. Toward the end, you’ll find out how to build a fully decoupled website using json:api and Next.js. By the end of this book, you’ll be able to confidently build custom Drupal themes to deliver state-of-the-art websites and keep ahead of the competition in the modern frontend world.

What you will learn

Map design systems made by Storybook components to Drupal structures Understand and use render arrays and Twig templates Get familiarized with the new Single Directory Component feature introduced in Drupal 10.1 Define, import, and use CSS and JavaScript libraries Discover how to style content created with fields and paragraphs Define, place, customize, and style blocks Explore advanced topics like extending Twig, making a theme configurable, and boosting performance and accessibility Find out how to build a decoupled website using json:api and Next.js

What do you get with eBook?

Product feature icon Instant access to your Digital eBook purchase
Product feature icon Download this book in EPUB and PDF formats
Product feature icon AI Assistant (beta) to help accelerate your learning
Product feature icon Access this title in our online reader with advanced features
Product feature icon DRM FREE - Read whenever, wherever and however you want
Buy Now

Product Details

Publication date : Aug 31, 2023
Length 360 pages
Edition : 1st Edition
Language : English
ISBN-13 : 9781803238098
Category :
Concepts :

Table of Contents

21 Chapters
Preface Chevron down icon Chevron up icon
1. Part 1 – Styling Drupal Chevron down icon Chevron up icon
2. Chapter 1: Setting up a Local Environment Chevron down icon Chevron up icon
3. Chapter 2: Setting a New Theme and Build Process Chevron down icon Chevron up icon
4. Chapter 3: How Drupal Renders an HTML Page Chevron down icon Chevron up icon
5. Chapter 4: Mapping the Design to Drupal Components Chevron down icon Chevron up icon
6. Chapter 5: Styling the Header and the Footer Chevron down icon Chevron up icon
7. Chapter 6: Styling the Content Chevron down icon Chevron up icon
8. Chapter 7: Styling Forms Chevron down icon Chevron up icon
9. Chapter 8: Styling Views Chevron down icon Chevron up icon
10. Chapter 9: Styling Blocks Chevron down icon Chevron up icon
11. Chapter 10: Styling the Maintenance, Taxonomy, Search Results, and 403/404 Pages Chevron down icon Chevron up icon
12. Part 2 – Advanced Topics Chevron down icon Chevron up icon
13. Chapter 11: Single Directory Components Chevron down icon Chevron up icon
14. Chapter 12: Creating Custom Twig Functions and Filters Chevron down icon Chevron up icon
15. Chapter 13: Making a Theme Configurable Chevron down icon Chevron up icon
16. Chapter 14: Improving Performance and Accessibility Chevron down icon Chevron up icon
17. Part 3 – Decoupled Architectures Chevron down icon Chevron up icon
18. Chapter 15: Building a Decoupled Frontend Chevron down icon Chevron up icon
19. Index Chevron down icon Chevron up icon
20. Other Books You May Enjoy Chevron down icon Chevron up icon

Customer reviews

Filter icon Filter
Top Reviews
Rating distribution
Empty star icon Empty star icon Empty star icon Empty star icon Empty star icon 0
(0 Ratings)
5 star 0%
4 star 0%
3 star 0%
2 star 0%
1 star 0%

Filter reviews by

No reviews found
Get free access to Packt library with over 7500+ books and video courses for 7 days!
Start Free Trial


How do I buy and download an eBook? Chevron down icon Chevron up icon

Where there is an eBook version of a title available, you can buy it from the book details for that title. Add either the standalone eBook or the eBook and print book bundle to your shopping cart. Your eBook will show in your cart as a product on its own. After completing checkout and payment in the normal way, you will receive your receipt on the screen containing a link to a personalised PDF download file. This link will remain active for 30 days. You can download backup copies of the file by logging in to your account at any time.

If you already have Adobe reader installed, then clicking on the link will download and open the PDF file directly. If you don't, then save the PDF file on your machine and download the Reader to view it.

Please Note: Packt eBooks are non-returnable and non-refundable.

Packt eBook and Licensing When you buy an eBook from Packt Publishing, completing your purchase means you accept the terms of our licence agreement. Please read the full text of the agreement. In it we have tried to balance the need for the ebook to be usable for you the reader with our needs to protect the rights of us as Publishers and of our authors. In summary, the agreement says:

  • You may make copies of your eBook for your own use onto any machine
  • You may not pass copies of the eBook on to anyone else
How can I make a purchase on your website? Chevron down icon Chevron up icon

If you want to purchase a video course, eBook or Bundle (Print+eBook) please follow below steps:

  1. Register on our website using your email address and the password.
  2. Search for the title by name or ISBN using the search option.
  3. Select the title you want to purchase.
  4. Choose the format you wish to purchase the title in; if you order the Print Book, you get a free eBook copy of the same title. 
  5. Proceed with the checkout process (payment to be made using Credit Card, Debit Cart, or PayPal)
Where can I access support around an eBook? Chevron down icon Chevron up icon
  • If you experience a problem with using or installing Adobe Reader, the contact Adobe directly.
  • To view the errata for the book, see and view the pages for the title you have.
  • To view your account details or to download a new copy of the book go to
  • To contact us directly if a problem is not resolved, use
What eBook formats do Packt support? Chevron down icon Chevron up icon

Our eBooks are currently available in a variety of formats such as PDF and ePubs. In the future, this may well change with trends and development in technology, but please note that our PDFs are not Adobe eBook Reader format, which has greater restrictions on security.

You will need to use Adobe Reader v9 or later in order to read Packt's PDF eBooks.

What are the benefits of eBooks? Chevron down icon Chevron up icon
  • You can get the information you need immediately
  • You can easily take them with you on a laptop
  • You can download them an unlimited number of times
  • You can print them out
  • They are copy-paste enabled
  • They are searchable
  • There is no password protection
  • They are lower price than print
  • They save resources and space
What is an eBook? Chevron down icon Chevron up icon

Packt eBooks are a complete electronic version of the print edition, available in PDF and ePub formats. Every piece of content down to the page numbering is the same. Because we save the costs of printing and shipping the book to you, we are able to offer eBooks at a lower cost than print editions.

When you have purchased an eBook, simply login to your account and click on the link in Your Download Area. We recommend you saving the file to your hard drive before opening it.

For optimal viewing of our eBooks, we recommend you download and install the free Adobe Reader version 9.