Starting a Site Using Drupal Composer Project Templates

As of Drupal 8.8.0, Composer project templates (similar to drupal-composer/drupal-project) are now available as part of Drupal core. These project templates serve as a starting point for creating a Composer-managed Drupal site. Once you have selected a template project and created your own site, you will take ownership of your new project files. Thereafter, future updates will be done with Composer.

Templates

There are two project templates to choose from.

drupal/recommended-project

The drupal/recommended-project creates a new Drupal site with a "relocated document root". This means that the files "index.php" and the "core" directory and so on are placed inside a subfolder named "web" rather than being placed next to "composer.json" and the "vendor" directory at the project root. This layout is recommended because it allows you to configure your webserver to only provide access to files inside the "web" directory. Keeping the vendor directory outside of the web server's document root is better for security.

drupal/legacy-project

The drupal/legacy-project creates a new Drupal site that has the same layout used in Drupal 8.7.x and earlier. The files "index.php", the "core" directory and so on are placed directly at the project root next to "composer.json" and the "vendor" directory. The Vendor Hardening plugin is used to ensure the security of this configuration for the Apache and Microsoft IIS web servers.

Note: #3294241: Remove drupal/legacy-project as a starting point for Drupal 12.

How do I set it up?

Use Composer to create a new project using the desired starter template, with the latest version:

composer create-project drupal/recommended-project my-project

For a specific version, use drupal/recommended-project:8.8.0. See Packagist for all available versions, or use the shell with composer show drupal/recommended-project --all.

cd my-project

Add new modules and themes with composer require:

composer require drupal/pathauto

Add a development module such as Devel, see Drupal 8 Composer Best Practices for info about the --dev flag, composer install --no-dev on production server omits dev-modules:

composer require --dev drupal/devel

Check for available Drupal core and module updates (also, see Zsh note below):

composer outdated 'drupal/*'

All of your modules and themes can be updated along with Drupal core via:

composer update

To update only Drupal core without any modules or themes, use:

composer update drupal/core-recommended --with-dependencies

To update Drupal core and all dependencies, use:

composer update drupal/core 'drupal/core-*' --with-all-dependencies

Note: Zsh handles asterisks differently, so asterisk package wildcards need to be quoted.

Drush

As opposed to drupal-composer/drupal-project, Drush is not included, but here is how to add it:

composer require drush/drush

Adding drupal/core-dev

In order to be able to run Drupal core's PHPUnit test suite, you will have to install an additional metapackage, drupal/core-dev.

composer require --dev drupal/core-dev

Note that until #3163114: Match the version of drupal/core-* metapackages is resolved, if you are using a non-default branch of Drupal core in your project, you have to specify a version of drupal/core-dev that matches the one you're currently using.  For example:

composer create-project 'drupal/recommended-project:^8.9' my-project
cd my-project
composer require --dev drupal/core-dev # This will fail.
composer require --dev 'drupal/core-dev:^8' # This will work.

Note: For older versions of Drupal core (before D10), you may need to remove drush/drush, install drupal/core-dev, and then reinstall drush/drush. Try this if Composer displays an error that requirements could not be resolved.

drupal/core-composer-scaffold

These template projects use drupal/core-composer-scaffold to place the scaffold files. This plugin allows the top-level composer.json file for a Drupal site to transform the scaffold files in different ways, e.g. to append new entries to the end of robots.txt and so on. For documentation on how scaffolding works, see the Composer Scaffold plugin README and the development documentation: Using Drupal's Composer Scaffold

Troubleshooting: Permission issues prevent running Composer

Full error

Installation failed, reverting ./composer.json to its original content.
  [RuntimeException]
  Could not delete /srv/users/serverpilot/apps/sandbox/drupal/web/sites/default/default.services.yml:

Workaround

In Drupal version 8.8.0, the permissions for sites/default are set to unwriteable, but Composer needs to write to it. This will hopefully be fixed in the future, but in the meantime, the issue can be resolved by fixing the permissions manually:

chmod u+w web/sites/default

Additionally, You could also use $settings['skip_permissions_hardening'] = TRUE; in the settings files of environments where upgrades are made. This is extremely helpful when you are performing the upgrade in a local environment and committing the result to git.