Extension repository structure

For module, theme, and language pack component repositories, we recommend five best practices:

• Flatter hierarchy
• One extension type (module, theme, or language pack) per repository
• Multiple components per repository
• One component per repository
• One functional test suite per module component

Flatter hierarchy#

Your repository structure should no longer include app/code/<Vendor>/ directories.

Before:

<extension_repo_root\>
└── app/code/<Vendor>/
    └── <Module1>
CopyCopied to your clipboard
1<extension_repo_root\>
2└── app/code/<Vendor>/
3    └── <Module1>

After:

<extension_repo_root>/
└── <Module1>
CopyCopied to your clipboard
1<extension_repo_root>/
2└── <Module1>

One extension type per repository#

You cannot mix extension types (modules, themes, and language packs) in the same extension repository. Each component type must have its own repository. For example, you cannot do this:

// This is not supported
<extension_repo_root>
├── <Module1>
├── <theme1>
└── <language1>
CopyCopied to your clipboard
1// This is not supported
2<extension_repo_root>
3├── <Module1>
4├── <theme1>
5└── <language1>

Multiple components per repository#

If your extension is complex and requires several components, you can keep those components in the same repository to make the extension easy to package and maintain:

<extension_repo_root>
├── <Module1>
├── <Module2>
├── <Module1SampleData>
└── <Module2SampleData>
CopyCopied to your clipboard
1<extension_repo_root>
2├── <Module1>
3├── <Module2>
4├── <Module1SampleData>
5└── <Module2SampleData>

You can do the same for theme and language pack extensions:

<extension_repo_root>/
├── <theme1>
└── <theme2>
CopyCopied to your clipboard
1<extension_repo_root>/
2├── <theme1>
3└── <theme2>

<extension_repo_root>/
├── <language1>
└── <language2>
CopyCopied to your clipboard
1<extension_repo_root>/
2├── <language1>
3└── <language2>

One component per repository#

If your extension requires only one component, your <component_root> directory and your <repo_root> directory will be the same to reduce unnecessary hierarchy in the directory structure:

<MyModule_repo_root>
├── Api
├── Block
├── Controller
├── Console
├── etc
├── Helper
├── i18n
├── Model
├── Plugin
├── Test
├── view
├── composer.json
├── LICENSE.txt
└── ...
CopyCopied to your clipboard
1<MyModule_repo_root>
2├── Api
3├── Block
4├── Controller
5├── Console
6├── etc
7├── Helper
8├── i18n
9├── Model
10├── Plugin
11├── Test
12├── view
13├── composer.json
14├── LICENSE.txt
15└── ...

Test Suites#

Function tests can be added to a Test directory within each module of your extension.

Note: Currently, only Unit and MFTF tests can be run from within a <Module> directory.

<extension_repo_root>
├── <Module1>
│   ├── ...
│   ├── Test
│   │   ├── Unit
│   │   ├── Integration
│   │   └── Mftf
│   │       ├── TestSuite
│   │       └── composer.json
│   └── ...
├── <Module2>
├── <Module1SampleData>
└── <Module2SampleData>
CopyCopied to your clipboard
1<extension_repo_root>
2├── <Module1>
3│   ├── ...
4│   ├── Test
5│   │   ├── Unit
6│   │   ├── Integration
7│   │   └── Mftf
8│   │       ├── TestSuite
9│   │       └── composer.json
10│   └── ...
11├── <Module2>
12├── <Module1SampleData>
13└── <Module2SampleData>