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
- Why dependencies should not be committed
- The role of composer.lock
- How to use version constraints
- The difference between
require
andrequire-dev
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
- Composer Versions
- Using Composer to Manage Drupal Site Dependencies
- Drupal Composer package naming conventions
- Packagist: Find non-drupal libraries and their current versions.
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 callnpm 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 adrupal-library
and define aninstaller-paths
path for that package type to ensure that it is installed todocroot/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.