A collection of processes, designs, and tools our team has standardized on. en-us https://architecture.lullabot.com/ Eleventy v3.1.5 Mon, 18 May 2026 01:16:22 GMT 2026 Lullabot, Inc. CC-BY 4.0. https://architecture.lullabot.com/adr/20260505-pin-github-actions-to-hash/ GitHub Actions referenced by a mutable tag or branch can be silently replaced with malicious code, exposing CI/CD secrets across every repository that uses them. ci, security Tue, 05 May 2026 00:00:00 GMT https://architecture.lullabot.com/adr/20260505-pin-github-actions-to-hash/ https://architecture.lullabot.com/adr/20260421-use-stylelint/ Using Stylelint helps prevent errors and keeps code in a consistent format. front-end, css Tue, 21 Apr 2026 00:00:00 GMT https://architecture.lullabot.com/adr/20260421-use-stylelint/ https://architecture.lullabot.com/adr/20260414-use-tagify/ Drupal's default entity reference autocomplete widget has limited UX. A modern, well-supported replacement is needed and the Tagify module has been successfully used in several Lullabot projects. drupal, contrib-modules, editorial-experience Tue, 14 Apr 2026 00:00:00 GMT https://architecture.lullabot.com/adr/20260414-use-tagify/ https://architecture.lullabot.com/adr/20260410-composer-audit/ Third-party dependencies can introduce known security vulnerabilities at any time, so projects need an automated mechanism to detect them early. composer, security, ci Fri, 10 Apr 2026 00:00:00 GMT https://architecture.lullabot.com/adr/20260410-composer-audit/ https://architecture.lullabot.com/adr/20260320-use-phpstan/ Static analysis catches type errors, logic bugs, and unsafe code paths without running the application, improving code quality at low cost. php, drupal, ci Fri, 20 Mar 2026 00:00:00 GMT https://architecture.lullabot.com/adr/20260320-use-phpstan/ https://architecture.lullabot.com/adr/20260320-files-listing-access/ Drupal's built-in files listing at `/admin/content/files` is a technical tool that has caused editorial confusion and accidental data loss. drupal, access-control, media, editorial-experience Fri, 20 Mar 2026 00:00:00 GMT https://architecture.lullabot.com/adr/20260320-files-listing-access/ https://architecture.lullabot.com/adr/20260313-use-access-unpublished/ Some pages need to be accessible only to specific groups or individuals using a password or token, without requiring a full user account. drupal, contrib-modules, access-control Fri, 13 Mar 2026 00:00:00 GMT https://architecture.lullabot.com/adr/20260313-use-access-unpublished/ https://architecture.lullabot.com/adr/20260313-microcontent-terminology/ Teams have used inconsistent terminology — including "micro-content", "component", "embeds", and "inline content" — to describe content that is embedded within pages but never exists independently. drupal, content-modeling, editorial-experience Fri, 13 Mar 2026 00:00:00 GMT https://architecture.lullabot.com/adr/20260313-microcontent-terminology/ https://architecture.lullabot.com/adr/20260313-drupal-build-steps/ When updating Drupal code and configuration in a given environment, it's useful to make sure all members of the team and all teams follow a consistent set of steps, in the same order. Having consistent steps across multiple projects will reduce onboarding for new team members. drush, drupal, deployments Fri, 13 Mar 2026 00:00:00 GMT https://architecture.lullabot.com/adr/20260313-drupal-build-steps/ https://architecture.lullabot.com/adr/20251219-self-host-third-party-static-assets/ Third-party hosted assets (e.g. web fonts, icon libraries) can lead to performance, privacy, and reliability issues. These include GDPR violations, extra DNS lookups, and outages outside the organization control. front-end, performance, javascript, css Fri, 19 Dec 2025 00:00:00 GMT https://architecture.lullabot.com/adr/20251219-self-host-third-party-static-assets/ https://architecture.lullabot.com/adr/20251210-create-deliberate-stacking-contexts/ Overlap elements predictably by creating new stacking contexts for `z-index` values. front-end, css Wed, 10 Dec 2025 00:00:00 GMT https://architecture.lullabot.com/adr/20251210-create-deliberate-stacking-contexts/ https://architecture.lullabot.com/adr/20251125-main-deployable/ Even with the best planning, unexpected bugs and security issues can require a fast deployment to production. By ensuring the main branch is always deployable, we minimize additional development work and QA in the case of an unplanned deployment. devops Tue, 25 Nov 2025 00:00:00 GMT https://architecture.lullabot.com/adr/20251125-main-deployable/ https://architecture.lullabot.com/adr/20251120-use-renovate/ Renovate supports automatic updates across a wide variety of ecosystems ensuring our projects are secure and up to date. drupal, devops, security Thu, 20 Nov 2025 00:00:00 GMT https://architecture.lullabot.com/adr/20251120-use-renovate/ https://architecture.lullabot.com/adr/20251008-use-svg-viewbox/ Using viewBox improves maintainability. front-end, performance Wed, 08 Oct 2025 00:00:00 GMT https://architecture.lullabot.com/adr/20251008-use-svg-viewbox/ https://architecture.lullabot.com/adr/20250924-human-readable-views-filters/ drupal, editorial-experience, views Wed, 24 Sep 2025 00:00:00 GMT https://architecture.lullabot.com/adr/20250924-human-readable-views-filters/ https://architecture.lullabot.com/adr/20250922-use-twig-coding-standard/ Linters like twigcs keep code more consistent and readable twig, drupal, front-end Mon, 22 Sep 2025 00:00:00 GMT https://architecture.lullabot.com/adr/20250922-use-twig-coding-standard/ https://architecture.lullabot.com/adr/20250409-use-imagemagick-with-drupal/ Drupal requires the GD PHP extension, but many sites prefer ImageMagick for better performance, flexibility, and reliability. This choice affects image features, speed, and deployment in various hosting environments. drupal, images Thu, 24 Apr 2025 00:00:00 GMT https://architecture.lullabot.com/adr/20250409-use-imagemagick-with-drupal/ https://architecture.lullabot.com/adr/20250416-avoid-using-jquery/ jQuery is an unnecessary dependency for modern browsers. front-end, javascript Wed, 16 Apr 2025 00:00:00 GMT https://architecture.lullabot.com/adr/20250416-avoid-using-jquery/ https://architecture.lullabot.com/adr/20250320-use-relative-units-in-css/ Using relative units improves accessibility by ensuring that text and content does not overlap when zooming web pages or changing the base font size. front-end, css Thu, 20 Mar 2025 00:00:00 GMT https://architecture.lullabot.com/adr/20250320-use-relative-units-in-css/ https://architecture.lullabot.com/adr/20250124-use-one-h1-per-page/ Using one h1 on each page is best practice for accessibility and usability. drupal, accessibility Fri, 24 Jan 2025 00:00:00 GMT https://architecture.lullabot.com/adr/20250124-use-one-h1-per-page/ https://architecture.lullabot.com/adr/20250109-use-issue-template-patches/ When managing patches in a `composer.json` file, clear and consistent descriptions improve maintainability and facilitate tooling. Currently, there is no standard template for describing patches, leading to inconsistent documentation. composer Thu, 09 Jan 2025 00:00:00 GMT https://architecture.lullabot.com/adr/20250109-use-issue-template-patches/ https://architecture.lullabot.com/adr/20240924-11ty-adr/ We need a site generator to publish our ADRs. meta Tue, 24 Sep 2024 00:00:00 GMT https://architecture.lullabot.com/adr/20240924-11ty-adr/ https://architecture.lullabot.com/adr/20240820-project-docs/ Documentation for getting started on a project should always be found in the same place and use the same formatting. documentation Tue, 20 Aug 2024 00:00:00 GMT https://architecture.lullabot.com/adr/20240820-project-docs/ https://architecture.lullabot.com/adr/20240221-use-svg-icons/ Using SVGs for icons has the best display, performance, and accessibility front-end, accessibility, performance Wed, 21 Feb 2024 00:00:00 GMT https://architecture.lullabot.com/adr/20240221-use-svg-icons/ https://architecture.lullabot.com/adr/20240212-do-not-use-placeholders-forms/ Placeholder text introduces significant usability and accessibility issues and should be avoided. drupal, editorial-experience Mon, 12 Feb 2024 00:00:00 GMT https://architecture.lullabot.com/adr/20240212-do-not-use-placeholders-forms/ https://architecture.lullabot.com/adr/20231110-field-order-as-in-page/ When content types have dedicated pages, matching the display order when possible makes edit forms easier to understand. drupal, editorial-experience Fri, 10 Nov 2023 00:00:00 GMT https://architecture.lullabot.com/adr/20231110-field-order-as-in-page/ https://architecture.lullabot.com/adr/20231027-javascript-loading-defaults/ Loading JavaScript as deferred has the best default performance javascript, front-end, performance Fri, 27 Oct 2023 00:00:00 GMT https://architecture.lullabot.com/adr/20231027-javascript-loading-defaults/ https://architecture.lullabot.com/adr/20230929-drupal-build-steps/ When updating Drupal code and configuration in a given environment, it's useful to make sure all members of the team and all teams follow a consistent set of steps, in the same order. Having consistent steps across multiple projects will reduce onboarding for new team members. drush, drupal, deployments Wed, 04 Oct 2023 00:00:00 GMT https://architecture.lullabot.com/adr/20230929-drupal-build-steps/ https://architecture.lullabot.com/adr/20230804-javascript-loading-defaults/ Loading JavaScript as async & deferred has the best default performance javascript, front-end, performance Fri, 04 Aug 2023 00:00:00 GMT https://architecture.lullabot.com/adr/20230804-javascript-loading-defaults/ https://architecture.lullabot.com/adr/20230309-use-typed-entity/ Wrapping the business logic for an entity using Typed Entity produces code that is easier to read, maintain, test, and discover. drupal, code quality Thu, 09 Mar 2023 00:00:00 GMT https://architecture.lullabot.com/adr/20230309-use-typed-entity/ https://architecture.lullabot.com/adr/20221205-render-entities-with-view-modes/ Rendering entities using view modes have multiple benefits. These include better maintainability, faster initial development time, better performance, and hardened security. drupal Wed, 14 Dec 2022 00:00:00 GMT https://architecture.lullabot.com/adr/20221205-render-entities-with-view-modes/ https://architecture.lullabot.com/adr/20220920-git-branch-naming/ Omitting key information in branch names can cause confusion over the purpose of a branch. git Tue, 20 Sep 2022 00:00:00 GMT https://architecture.lullabot.com/adr/20220920-git-branch-naming/ https://architecture.lullabot.com/adr/20220906-identical-cache-backends/ Using memory caches like Memcached or Redis in production but not in development environments can lead to bugs and confusion. drupal, devops Tue, 06 Sep 2022 00:00:00 GMT https://architecture.lullabot.com/adr/20220906-identical-cache-backends/ https://architecture.lullabot.com/adr/20220816-use-js-strict-mode/ Opt in to settings that raise errors for problematic code. front-end, javascript Tue, 16 Aug 2022 00:00:00 GMT https://architecture.lullabot.com/adr/20220816-use-js-strict-mode/ https://architecture.lullabot.com/adr/20220721-organize-stylesheets-using-smacss/ Organizing CSS within projects the same way Drupal organizes its CSS establishes a consistent pattern. front-end, css Thu, 21 Jul 2022 00:00:00 GMT https://architecture.lullabot.com/adr/20220721-organize-stylesheets-using-smacss/ https://architecture.lullabot.com/adr/20220705-use-typescript/ Strictly typed languages like TypeScript avoid unexpected behavior, prevent bugs, and improve code maintainability. javascript, front-end, back-end, developer-experience Tue, 05 Jul 2022 00:00:00 GMT https://architecture.lullabot.com/adr/20220705-use-typescript/ https://architecture.lullabot.com/adr/20220622-use-css-logical-properties/ Decoupling styles from a language's writing direction makes them easier to maintain across translations. front-end, css, multilingual Wed, 22 Jun 2022 00:00:00 GMT https://architecture.lullabot.com/adr/20220622-use-css-logical-properties/ https://architecture.lullabot.com/adr/20220622-1-do-not-add-metatags-to-node-form/ The metatag field makes the node form slow and overly complex for editorial users. drupal, node-form, editorial-experience, performance, seo Wed, 22 Jun 2022 00:00:00 GMT https://architecture.lullabot.com/adr/20220622-1-do-not-add-metatags-to-node-form/ https://architecture.lullabot.com/adr/20220621-gatsby-theme-adr/ We need a site generator to publish our ADRs. meta Tue, 21 Jun 2022 00:00:00 GMT https://architecture.lullabot.com/adr/20220621-gatsby-theme-adr/ https://architecture.lullabot.com/adr/20220519-use-claro-as-admin-theme/ Claro offers a modern, responsive, and accessible interface that showcases Drupal's capabilities from the outset. drupal, editorial-experience Thu, 19 May 2022 00:00:00 GMT https://architecture.lullabot.com/adr/20220519-use-claro-as-admin-theme/ https://architecture.lullabot.com/adr/20220511-use-inclusive-language/ Inclusive language can make technical subjects more inviting and understandable. Wed, 11 May 2022 00:00:00 GMT https://architecture.lullabot.com/adr/20220511-use-inclusive-language/ https://architecture.lullabot.com/adr/20220504-use-simple-add-more/ Drupal core by default outputs the maximum number of values (cardinality) as empty elements on entity forms, which usually represents a poor user-experience. drupal, contrib-modules, editorial-experience Fri, 06 May 2022 00:00:00 GMT https://architecture.lullabot.com/adr/20220504-use-simple-add-more/ https://architecture.lullabot.com/adr/20220503-use-type-tray/ Drupal's editorial experience in the "Add Content" page is confusing out of the box, especially when the content model's complexity increases. drupal, contrib-modules, editorial-experience Fri, 06 May 2022 00:00:00 GMT https://architecture.lullabot.com/adr/20220503-use-type-tray/ https://architecture.lullabot.com/adr/20220429-composer-patchlevel/ Drupal's git repository has a different directory structure than projects built on Drupal. Default Composer Patches settings can cause Drupal patches to be silently misapplied. drupal, php, composer Fri, 29 Apr 2022 00:00:00 GMT https://architecture.lullabot.com/adr/20220429-composer-patchlevel/ https://architecture.lullabot.com/adr/20220429-composer-patches-inline/ Validating a complete Composer configuration is important to ensuring build issues are caught early. drupal, php, composer Fri, 29 Apr 2022 00:00:00 GMT https://architecture.lullabot.com/adr/20220429-composer-patches-inline/ https://architecture.lullabot.com/adr/20220429-composer-patch-files/ When using [cweagans/composer-patches](https://github.com/cweagans/composer-patches), it is important that patch sources are consistent and do not change between builds. drupal, php, composer Fri, 29 Apr 2022 00:00:00 GMT https://architecture.lullabot.com/adr/20220429-composer-patch-files/ https://architecture.lullabot.com/adr/20220429-composer-exit-failure/ Allowing builds to succeed with failed patches can lead to malformed code or hidden errors. drupal, composer, php Fri, 29 Apr 2022 00:00:00 GMT https://architecture.lullabot.com/adr/20220429-composer-exit-failure/ https://architecture.lullabot.com/adr/20220426-use-dedicated-accounts-service-integrations/ Service integrations that use personal accounts tie the function of the service with the person's engagement with the project. devops Tue, 26 Apr 2022 00:00:00 GMT https://architecture.lullabot.com/adr/20220426-use-dedicated-accounts-service-integrations/ https://architecture.lullabot.com/adr/20220425-hide-untranslatable-fields/ When content translation is enabled, it's possible to decide which fields can be translated. drupal Mon, 25 Apr 2022 00:00:00 GMT https://architecture.lullabot.com/adr/20220425-hide-untranslatable-fields/ https://architecture.lullabot.com/adr/20220320-prevent-language-change/ Editors new to Drupal often try to translate content by changing the language on existing content, causing confusion for site visitors. drupal Sun, 20 Mar 2022 00:00:00 GMT https://architecture.lullabot.com/adr/20220320-prevent-language-change/ https://architecture.lullabot.com/adr/20220208-naming-fields/ Adopting a consistent set of rules when naming entities in Drupal can reduce errors and improve maintainability. drupal Tue, 08 Feb 2022 00:00:00 GMT https://architecture.lullabot.com/adr/20220208-naming-fields/ https://architecture.lullabot.com/adr/20220207-php-unit-tests/ drupal, php, coding, testing Mon, 07 Feb 2022 00:00:00 GMT https://architecture.lullabot.com/adr/20220207-php-unit-tests/ https://architecture.lullabot.com/adr/20220119-composer-patches/ Default `composer-patches` settings can lead to misapplied patches or hidden errors. Using a consistent configuration across projects will reduce errors and save time. drupal, php, composer Mon, 07 Feb 2022 00:00:00 GMT https://architecture.lullabot.com/adr/20220119-composer-patches/ https://architecture.lullabot.com/adr/20220112-type-hints/ Following stricter typing where available can significantly reduce bugs, and simplify maintainability. This has been proven by several studies across different disciplines. drupal, php, coding Wed, 12 Jan 2022 00:00:00 GMT https://architecture.lullabot.com/adr/20220112-type-hints/ https://architecture.lullabot.com/adr/20211026-one-time-login-first-drupal-user-account/ The first user account in a Drupal site (often referred to as "administrator" or "user 1") is [granted every permission automatically](https://www.drupal.org/docs/user_guide/en/user-admin-account.html). If the account credentials are compromised, an attacker can easily inject JavaScript to attack site visitors and can likely execute arbitrary PHP code. drupal, security Wed, 12 Jan 2022 00:00:00 GMT https://architecture.lullabot.com/adr/20211026-one-time-login-first-drupal-user-account/ https://architecture.lullabot.com/adr/20211212-config-status-check/ Configuration should never be in an overridden state after configuration import(s) have been completed. drupal, deployment, automation, devops Sun, 12 Dec 2021 00:00:00 GMT https://architecture.lullabot.com/adr/20211212-config-status-check/ https://architecture.lullabot.com/adr/20211207-ddev-locals/ The software development industry is continuing to move to containers both for production and local environments. It's clear that the bulk of new investment in local tooling is going towards container-focused solutions. While containers themselves add some complexity to local environments, they also reduce variance in development environments for teams with multiple developers. dev-tools, drupal, devops Tue, 07 Dec 2021 00:00:00 GMT https://architecture.lullabot.com/adr/20211207-ddev-locals/ https://architecture.lullabot.com/adr/20211201-use-strict-types-in-php-code/ PHP's type coercion can cause logical errors within a program. For example, when a float is cast to an int, the decimal portion is lost. We aim to reduce these errors in our code, but they can easily slip through manual code review. Following stricter typing where available can significantly reduce bugs, as shown by [Python's urllib3 type hinting case study](https://sethmlarson.dev/blog/2021-10-18/tests-arent-enough-case-study-after-adding-types-to-urllib3). php, drupal Wed, 01 Dec 2021 00:00:00 GMT https://architecture.lullabot.com/adr/20211201-use-strict-types-in-php-code/ https://architecture.lullabot.com/adr/20211026-use-settings-not-splits/ When developing a Drupal website, additional modules and configuration are useful for local and development environments. dev-tools, drupal Tue, 26 Oct 2021 00:00:00 GMT https://architecture.lullabot.com/adr/20211026-use-settings-not-splits/ https://architecture.lullabot.com/adr/20210729-stage-file-proxy/ Lullabot often works on projects that have large numbers of static file assets in production, such as images or PDFs. Keeping a complete copy of those files for each environment is wasteful, since developers tend to only look at a small portion of a site locally. A solution is needed to reduce disk use and the time it takes to update an environment. devops, locals, drupal, contrib-modules Tue, 26 Oct 2021 00:00:00 GMT https://architecture.lullabot.com/adr/20210729-stage-file-proxy/ https://architecture.lullabot.com/adr/20211006-avoid-command-aliases/ When writing scripts for CI tasks or local procedures, it is helpful to have the full command spelled out. Having the long options and avoiding command aliases will reduce chances of misinterpretation and mistakes. This will also reduce the need for checking the documentation while reading or reviewing a script. scripting Wed, 06 Oct 2021 00:00:00 GMT https://architecture.lullabot.com/adr/20211006-avoid-command-aliases/ https://architecture.lullabot.com/adr/20210924-drupal-build-steps/ When updating Drupal code and configuration in a given environment, it's useful to make sure all members of the team and all teams follow a consistent set of steps, in the same order. Having consistent steps across multiple projects will reduce onboarding for new team members. drush, deployments Fri, 24 Sep 2021 00:00:00 GMT https://architecture.lullabot.com/adr/20210924-drupal-build-steps/ https://architecture.lullabot.com/adr/20210609-environment-indicator/ All Drupal websites our team works on have one or more environments. At a minimum, there will be a production and a local development environment. Most projects will have production, staging, development preview, and local environments. Developers and QA often access different environments at the same time. Since making content or configuration changes on the wrong environment can have unintended consequences, it is important to be able to distinguish environments easily. contrib-modules, editorial-experience Fri, 23 Jul 2021 00:00:00 GMT https://architecture.lullabot.com/adr/20210609-environment-indicator/ https://architecture.lullabot.com/adr/20210705-use-log4brains-to-manage-the-adrs/ dev-tools, doc, meta Sun, 04 Jul 2021 00:00:00 GMT https://architecture.lullabot.com/adr/20210705-use-log4brains-to-manage-the-adrs/ https://architecture.lullabot.com/adr/20210608-record-architecture-decisions/ We need to record the architectural decisions made on this project. meta Tue, 08 Jun 2021 00:00:00 GMT https://architecture.lullabot.com/adr/20210608-record-architecture-decisions/