How-to create a Magento 2 Composer Module

MAgento 2If you are a developer new to Magento 2, you are probably wondering how to create a Magento 2 Composer Module. Hopefully the below steps will be useful to you. This is how I managed to do it, eventually.

First of all, you should familiarise yourself with composer, and it’s basic usage.

This guide asumes you’ve already installed and configured a vanilla Magento 2 project. If you haven’t done that yet, I’d advise you to check this out and follow the official guide. Feel free to drop me a line if you have any issues.

I’ve found quite a few sites that show how to create a Magento 2 module “the old way”, by copying the module contents inside app/code folder (note that in Magento 1.x it used to be app/code/codePool, but that doesn’t exist anymore in Magento 2).

However, as I’ve recently been working on Symfony 2 projects, I’m quite used to composer, and it’s usage to easily integrate third party components/packages. So, once I saw the file “composer.json” on the root directory of Magento 2, I knew that it should be the way forward in order to develop Magento 2 extensions.

Let’s get started. I’m assuming you’ve developed already your Magento 2 extension, as the purpose of this guide is to show how to package the extension within a composer (sub) module, and the creation of an extension would go beyond the scope of this post. Check this guide to find out how to create a Magento 2 extension, or just clone it’s source code from github.

  • To begin with, you should create a new (github/bitbucket…) repository, and place your source code inside.
  • In the root folder, create a new file named composer.json. This fille will describe the details of your package. This is how mine looks like:
        "name": "lumbrales-software/magento2-first-module",
        "description": "Hello world Magento 2 Composer Module!",
        "require": {
            "magento/project-community-edition": "*"
        "type": "magento2-module",
        "version": "0.1.0",
        "extra": {
            "map": [
        "authors": [
                "name": "Javi Lumbrales",
                "homepage": "",
                "role": "Developer"

    The most important parts described below:

    • The name of the package: This will serve as identifier of your package, and will be used later on.
    • Requirements: We’ve added “magento/project-community-edition” as a requirement, as this module requires Magento 2 in order to work.
    • Type: We specify “magento2-module” so that it’s contents are copied to app/local once the package is installed (more about this later).
    • Version: Not important, as we’ll use git tagging to handle the composer module updates.
    • Extra: – Map: This tells composer to copy all (*) contents into app/code/LumbralesSoftware/HelloWorld, so the root of your extension should be structured already. This means that you don’t need to keep your files under app/code/YourCompany/YourModule in your repository. Instead, they should be in the root straightly. This is how it your repository should look like:

Repository Root:

  • Push all your code to the master branch (I’ll explain the tagging on a separated post later on)
  • Go to the root folder of your Magento 2 installation, and type the following commands in your terminal:
composer require magento/magento-composer-installer

This is a submodule required to properly install third party Magento 2 extensions as composer submodules (Remember the type:magento2-module mentioned at the beginning).

  • Then, as your module is still not in a packages repository such as, or, you need to specify your own VCS repository so that composer can find it. In the repositories section of the composer.json file of the Magento 2 project (if the repositories section doesn’t exist, create it, else, add your repository at the end) add the following:
 "repositories": [
      "type": "vcs",
      "url": ""
  • Since your package is in a development stage, you will need to add the minimum-stability as well to the composer.json file:
"minimum-stability": "dev",

Note that this could be removed later on, once we have properly tagged/released a stable version of our package/extension.

  • After that, you should be able to install your module as follows (remember how you named it):
composer require your-package/name #In our example the name was lumbrales-software/magento2-first-module

The above command should download your module and copy it’s content to app/code/YourCompany/YourModule

  • Last, but not least, you will need to enable your module and clear Magento cache. Add a new entry in app/etc/config.php, under the ‘modules’ section (Magento 2 project):
    'Yourcompany_YourModule' => 1,

Note that this name should match with the name that you’ve put on the composer.json, section extra -> map.

That’s it, after that your module should be ready to go.

You can download the source code of my Magento 2 Composer Module sample here.

I hope it helps, and let me know if you have any issues!

In my next post I’ll show a basic usage of git tagging and composer to be able to easily release your module updates.



11 thoughts on “How-to create a Magento 2 Composer Module

  1. Pingback: Magento 2 : You can test the version under development | My Magento Blog

  2. Pingback: Magento 2 : You can test the version under development | My Magento Blog

  3. Pingback: Magento 2 Composer Module Update • The Developer World Is Yours

  4. HI,

    how can i rid from the full path and upload only the module code to github, without app/code/Yourcompany/YourModule/?


Leave a Reply

Your email address will not be published. Required fields are marked *