Dependency Management

Neos uses the defacto PHP standard for dependency management - composer. It allows you to declare the libraries your project depends on and it will manage (install/update) them for you.

Check out the composer documentation for a general understanding.

In Neos each projects consists of one git repository for the root. This project then can include third party packages via composer.

Each Neos project must have at least one site package.

In order to ease integration of Neos within the composer eco-system we wanted to provide a standard solution for typical Neos projects to use a single git repository for developing multiple packages while fully embracing composer. This is what we describe on this page.

The "Path Repository" Setup

To avoid problems with composer we propose a setup where the site package - and other project specific packages - are included in the repository but outside the "Packages" folder. It is then loaded via composer and a "path" repository type.

All packages you want to version together with the project distribution go to the DistributionPackages folder. You then need to tell composer where these packages are in the repositories part of your root composer.json manifest.

Since your distribution packages do not have a version of their own–as they are in the same repository as the distribution–you need to require them as "@dev".

An example repository showing how the configuration should look like can be found here:

    "name": "vendor/your-project-distribution",
    "description": "Describe your project here",
    "config": {
        "vendor-dir": "Packages/Libraries",
        "bin-dir": "bin"
    "require": {
        "test/site": "@dev"
    "repositories": {
        "distribution": {
            "type": "path",
            "url": "./DistributionPackages/*"
    "scripts": {
        "post-update-cmd": "Neos\\Flow\\Composer\\InstallerScripts::postUpdateAndInstall",
        "post-install-cmd": "Neos\\Flow\\Composer\\InstallerScripts::postUpdateAndInstall",
        "post-package-update": "Neos\\Flow\\Composer\\InstallerScripts::postPackageUpdateAndInstall",
        "post-package-install": "Neos\\Flow\\Composer\\InstallerScripts::postPackageUpdateAndInstall"

With this configuration your test/site package is installed via composer despite being in the same repository. Therefore composer picks up all dependencies of your site package.

We like this setup and consider it best practice for Neos projects since a while. That also means we will in turn adapt our distributions as well as tools to make use of such a setup.

If you are interested to read about the actual problems this setup solves, read our blog article Project Repository Best Practice.


Take note that in a future Neos version we might remove support for the old type of setup and only rely on composer for installing packages.
best practice project repository

Best practice project repository