15 May 2020

As announced, started from Drupal 8.8.0 release there is a composer template that is available as part of Drupal core. So you can use the Drupal composer template to start a new Drupal project, it’s called drupal/recommended-project. Please use the following link to dive deeper into this information. Drupal.org prepared guidance on how to start a Site Using Drupal Composer Project Templates. There is a lot of information on how to set up the drupal/recommended-project smoothly and carefully. 

What is the drupal-recommended project for? 

Traditionally, Composer-managed Drupal sites have utilized third-party template projects such as drupal-composer/drupal-project to build and update Drupal dependencies with Composer. Since Drupal 8.0 was released (November 2015), the Drupal Composer/Drupal Project template has been the “best practice”. As we already knew Drupal 8.8 was released with the drupal/recommended-project template. The difference between these templates is that the drupal-recommended project template is a bit simpler, it doesn’t include things like Drupal Console and Drush. 

There were announced two: drupal/recommended-project and drupal/legacy-project.

drupal/recommended-project - in this template, the site root is moved one level lower to the web /default folder. This template is recommended for all new projects on Drupal 8.
Here is an example of the project structure: 
  ├─ web/
  │  ├─ core/
  │  ├─ libraries/
  │  ├─ modules/
  │  ├─ profiles/
  │  ├─ themes/
  │  └─ index.php
  ├─ vendor/
  └─ composer.json
If you are familiar with the drupal-composer/drupal-project it’s obvious - that new drupal/recommended-project template is its counterpart. The Drupal management through Composer is the main goal, as well as taking the site core to the lower level. 

    Fortunately, drupal-composer/drupal-project is still being actual, moreover, it has also been updated to use official packages (but this will only apply to the new projects). But what if you want to switch to the official version? Then this material is for you. This is a fairly simple, step-by-step operation, where you only need to make a few decisions and everything will work further!

What is the difference between drupal/recommended-project and drupal-composer/drupal-project?

  • First - drupal/recommended-project is an official template. Thanks to this any issues will be fixed much faster because it being supported by the community. 
  • drupal/recommended-project created several of other official Composer projects that solve problems that the drupal-composer/drupal-project tried to solve on their own and, possibly, crutches. Now everything is automatically prepared in the Drupal ecosystem.
  • drupal/recommended-project has almost no dependencies by default. That’s more beneficial, as its structure and the initial project do not have “garbage” (except for the welcome package). For example, there is neither Drush, nor Drupal Console, nor other similar noticeable dependencies, and this is good! They do not impose anything on you and decide nothing for you.
  • drupal/recommended-project is preferable suited as the basis for creating personal composer templates. Again, since it is “cleaner”.
  • drupal/recommended-project cannot be used for projects under Drupal 8.8.0. Passing to it, you should already be updated, or do it in the process. 

Otherwise, they are not very different and there’s no point to hurry up with the changing.
Our team would recommend performing this migration only if there are a desire and opportunities, in the process of updating the project to Drupal 8.8.0+ or when the time comes to upgrade to Drupal 9. 


Composer templates are just preparation with default files, as well as predefined dependencies that will be loaded during the installation process. Further, it passes completely under your control and no longer has any connection with the template. It  means that migration comes down to replacing packages that were previously used and installed by drupal-composer / drupal-project with those used by drupal / recommended-project.

    Thus, the migration is optional so you decide yourself what should be migrated, what to replace, and what to leave as it was.

    Last, but not least - the new template better regulates the dependencies of Drupal Core, which minimizes compatibility issues and improves the experience of updating a project (support).

    Let’s become better together, your Golems