Not only Composer tools to build a Monorepo

Do you maintain a monorepo with more packages?

This package has few useful tools, that will make that easier.

Install

composer require symplify/monorepo-builder --dev

Usage

0. Are you New to Monorepo?

The best to lean-in fast is to read basic intro at goMonorepo.com. We also made a simple command to make that easy for you:

vendor/bin/monorepo-builder init

And the basic setup is done!

1. Merge local composer.json to the Root One

Merges configured sections to the root composer.json, so you can only edit composer.json of particular packages and let script to synchronize it.

# monorepo-builder.yml
parameters:
    merge_sections:
        # default values
        - 'require'
        - 'require-dev'
        - 'autoload'
        - 'autoload-dev'
        - 'repositories'

You can configure it and add minimum-stablity for example or remove any of those default values:

# monorepo-builder.yml
parameters:
    merge_sections:
        - 'require'
        - 'require-dev'
        - 'minimum-stability'

To merge just run:

vendor/bin/monorepo-builder merge

Typical location for packages is /packages. But what if you have different naming or extra /projects directory?

# monorepo-builder.yml
parameters:
    package_directories:
        - 'packages'
        - 'projects'

Sections are nicely sorted by saint defaults. Do you want to order them yourself?

parameters:
    section_order:
        - 'name'
        - 'autoload'
        - 'autoload-dev'
        - 'require'
        - 'require-dev'

After Merge Options

Do you need to add or remove some packages only to root composer.json?

# monorepo-builder.yml
parameters:
    data_to_append:
        autoload-dev:
            psr-4:
                'Symplify\Tests\': 'tests'
        require-dev:
            phpstan/phpstan: '^0.9'

    data_to_remove:
        require:
            'phpunit/phpunit': '*'

2. Bump Package Inter-dependencies

Let's say you release symplify/symplify 4.0 and you need package to depend on version ^4.0 for each other.

Just run this:

vendor/bin/monorepo-builder bump-interdependency "^4.0"

3. Keep Synchronized Package Version

In synchronized monorepo, it's common to use same package version to prevent bugs and WTFs. So if one of your package uses symfony/console 3.4 and the other symfony/console 4.1, this will tell you:

vendor/bin/monorepo-builder validate

4. Keep Package Alias Up-To-Date

You can see this

{
    "extra": {
        "branch-alias": {
            "dev-master": "2.0-dev"
        }
    }
}

even if there is already version 3.0 out.

Get rid of this manual work! Add this command to your release workflow:

vendor/bin/monorepo-builder package-alias

This will add alias 3.1-dev to composer.json in each package.

If you prefer 3.1.x-dev over default 3.1-dev, you can configure it:

# monorepo-builder.yml
parameters:
    package_alias_format: '<major>.<minor>.x-dev' # default: "<major>.<minor>-dev"

5. Split Directories to Git Repositories

Classic use case for monorepo is to synchronize last tag and the master branch to allow testing of @dev version.

# monorepo-builder.yml
parameters:
    directories_to_repositories:
        packages/BetterPhpDocParser: '[email protected]:Symplify/BetterPhpDocParser.git'
        packages/PackageBuilder: '[email protected]:Symplify/PackageBuilder.git'

And run by:

vendor/bin/monorepo-builder split

To speed up the process about 50-60 %, all repositories are synchronized in parallel.

Contributing

Open an issue or send a pull-request to main repository.