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.

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

Git

If you plan to use Git to manage your Drupal site, then copy web/example.gitignore to .gitignore (The new .gitignore file should be at your project root or top-level directory. Same level as the vendor directory - outside the web directory). Review the comments in that file and edit it to suit your requirements. In most cases these steps should do it:

1. Enter project folder with cd my-project and copy the web/example.gitignore file to the root of the project:
   cp web/example.gitignore .gitignore
2. Adjust the paths from sites/ to web/sites/:
   sed -i'.bak' -z 's|\nsites|\nweb/sites|g' .gitignore
3. Remove the backup file:
   rm .gitignore.bak

The resulting file structure:
tree -La 1
├── composer.json
├── composer.lock
├── .editorconfig
├── .gitattributes
├── .gitignore
├── vendor
└── web

If you use drupal/legacy-project, then example.gitignore is in the top-level directory.

For a more detailed .gitignore file, see #3082958: Add gitignore(s) to Composer-ready project templates and the file in the MR.

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.

Note that until #3163114: drupal/core-dev should depend on drupal/core so you don't get version mismatches 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: Add development libraries first, then Drush to avoid a failure, see Can only install drupal/core-dev before Drush and #3123013: drupal/core-dev install fails if drush/drush already installed.

Works: Add core-dev first, then Drush

composer create-project drupal/recommended-project d8 && cd d8
composer require --dev drupal/core-dev
composer require drush/drush

Works: Add Drush first, then core-dev with Composer 2

Composer 2 provides the --update-with-all-dependencies option (short form -W):

composer require --dev -W drupal/core-dev

Doesn't work: Add Drush first, then core-dev

composer create-project drupal/recommended-project d8dc && cd d8dc
composer require drush/drush
composer require --dev drupal/core-dev

Resulting error message:

Error: "Your requirements could not be resolved to an installable set of packages."
- Conclusion: don't install drupal/core-dev ...
  - Can only install one of: symfony/filesystem[v3.4.9, v4.4.7].
  - Installation request for symfony/filesystem (locked at v4.4.7) -> satisfiable by symfony/filesystem[v4.4.7]. ...
Installation failed, reverting ./composer.json to its original content.

Check for available versions

To see which versions of Drupal core are available, use this command

composer show drupal/recommended-project --all

Result:

versions : 10.0.x-dev, 10.0.0-alpha3, 10.0.0-alpha2, 10.0.0-alpha1, 9.4.x-dev, 9.3.x-dev, 9.3.11, 9.3.10, 9.3.9, 9.3.8, 9.3.7, 9.3.6, 9.3.5, 9.3.4, 9.3.3, 9.3.2, 9.3.1, 9.3.0, 9.3.0-rc1, 9.3.0-beta3, 9.3.0-beta2, 9.3.0-beta1, 9.3.0-alpha1, 9.2.x-dev, 9.2.17, [...]

Install latest release of Drupal 10

If you want to try the latest Drupal 10 release, this syntax will also get beta and rc-releases when ready, defining alpha as minimum-stability. Replace with @dev for development release:

composer create-project drupal/recommended-project:^10@alpha

See also #3276209: Install latest Drupal 10 release with Composer.

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.