Using Composer to manage dependencies in Drupal 8 and 9

    See more
    • Updated

    Composer usage overview

    Composer should be used to manage Drupal core, all contributed dependencies, and most third party libraries in Drupal 8 and above. The primary exception to this is front-end libraries, which can be managed using a front-end specific dependency manager, such as Bower or NPM.

    Why do we use Composer for dependency management? It is the dependency manager used by Drupal core.

    Be sure to familiarize yourself with Composer’s basic usage, especially how the lock file is used. You should commit both the composer.json and composer.lock files to your project, and every time you update the composer.json file , you must also run the following command to update the composer.lock file:

    composer update

    Never manually edit the composer.lock file.

    Notable Composer concepts

    Recommended tools and configuration

    • Globally install pretissimo for parallelized composer downloads by running the following command:

      composer global require "hirak/prestissimo:^0.3"

    • If you have Xdebug enabled for your PHP CLI binary, to dramatically improve performance it is highly recommended that you disable Xdebug.

    Contributed projects and third-party libraries

    You can find all contributed projects hosted on Drupal.org (including Drupal core, profiles, modules, and themes) on Drupal Packagist, a Drupal.org-hosted packagist server. You must specify this URL in your composer.json file by adding the following code to allow Composer to discover the packages:

    {
   "repositories": {
       "drupal": {
           "type": "composer",
           "url": "https://packages.drupal.org/8"
          }
      }
 }

    Most non-Drupal libraries can be found on Packagist.

    For any required packaged not hosted by the preceding websites, you can define your own array of custom repositories for Composer to search.

    Note: Composer versioning is not identical to Drupal.org versioning.

    Composer resources

    Installing dependencies

    To install a new package to your project, use the composer require command. This command adds the new dependency to your composer.json and composer.lock files, and downloads the package locally. For example, to download a module, run the following command, replacing [module] with the module you want to download:

    composer require drupal/[module]

    After you run the command, be sure to commit your composer.json and composer.lock files.

    Updating dependencies (core, profile, module, theme, libraries)

    To update a single package, run the composer update [vendor/package] command, replacing [module] with the module you want to update:

    composer update drupal/[module] --with-dependencies

    To update all packages, run the following command:

    composer update

    After you run the command, be sure to commit your composer.json and composer.lock files.

    Removing dependencies

    To remove a package from your project, use the composer remove command, replacing [module] with the module you want to remove:

    composer remove drupal/[module]

    After you run the command, be sure to commit your composer.json and composer.lock files.

    Patching a project

    For information about patch naming, patch application, patch ignoring, and patch contribution guidance, see patches.

    Front-end dependencies

    Drupal doesn’t have a definitive solution for downloading front-end dependencies. Acquia suggests you refer to the following solutions:

    • Load the library as an external library. See Adding stylesheets (CSS) and JavaScript (JS) to a Drupal 8 module.
    • Use a front-end package manager (such as NPM) to download your dependencies. Then, use Acquia BLT’s source:build:frontend-assets target-hook to trigger building those dependencies (such as call npm install) in your theme directory using these hooks. For more information, see Front-end development and Acquia BLT.
    • Commit the library to the repository, typically in docroot/librares.
    • Add the library to your composer.json file by using a custom repository. Designate the package as a drupal-library and define an installer-paths path for that package type to ensure that it is installed to docroot/libraries. Ensure that it can be discovered in that location. See example composer.json.

    Contributed projects should provide the ability to download and discover the libraries. If you are using a contributed project, it is suggested that you patch the project to support one of these strategies.

    If you cannot, commit the dependency. You can use a custom .gitignore file for your project.

    Ensure the dependency is copied to the deployment artifact, and supply your own, custom .gitignore file to use in the deployment artifact.

     

    Topics

    Related articles