The proper way to create custom module in Drupal 8


As the title suggests, we will be exploring the proper way of creating a custom module. But let me set your expectations before we start. This blog post is assuming you already have a broad understanding of PHP and how it works. For those of you coming here not knowing what OOP means, then this article may not be suitable for you. To know more about PHP visit this external link. The focus of this article is not about creating the module itself and its functionality but about having a standard for Drupal developers. Standards make Drupal development clean and easy to delegate and troubleshoot.

Imagine receiving a Drupal maintenance project created by another developer who does not know about Drupal standards. You’ll have to spend days looking for the custom module and much worse, the project has been passed on to 3 different developers before it got to you and your task involves modifying all of the custom modules they created. Don’t be like those developers, follow the standard!

The appropriate directory for your custom module

Before you start creating a directory for your module, you must already have a directory name in mind. Naming is important in Drupal development. The module name you will choose will be used as the machine name or unique identifier for your module so choose wisely. 

To help you choose the appropriate name, below are some rules and considerations you must make.

  • Select a name that is related to the function of the module
  • The module name must be unique on this project [our custom modules usually start with cs_*]
  • The module machine name must start with a letter
  • Space is not accepted in the machine name
  • It should not be any of the reserved terms : src, lib, vendor, assets, css, files, images, js, misc, templates, includes, fixtures, Drupal.
  • And it must be all lowercase letters
  • Underscores are accepted

E.g cs_sword_art_api

Now that we have the name prepared, let’s start by going to the modules directory of your project and create a folder named “custom”. Inside the custom module directory is where we will place our module folder. The path would look like this : /modules/custom/cs_sword_art_api

The actual custom module folder does not have to be the same as the machine name so you can name it the way you want. But it is necessary to use the machine name within the module’s code and file names.

If you are planning to create contributed modules however, the path will contrib instead of custom.


Give Drupal some information about your module

Now that we have our custom module directory created, let’s create the first file that’s essential for our custom module. This is the part where we use the machine name to create an info.yml file. Go ahead and create the file as shown in the example below.


Filename :

Path : /modules/custom/cs_sword_art_api/

Why do we say this file is essential?

This file tells Drupal it’s existence and it’s not limited to custom modules. It’s also used in themes and install profiles. This file also allows Drupal to differentiate between themes and modules. Another use of this file is to provide information for the Drupal Web UI administration pages. This is the file where you provide criteria to control module activation and deactivation and Drupal version compatibility.

Below is the basic content of this file :

name: Sword Art API

description: Creates an API connector for the Sword Art Database Characters.

package: Custom

type: module

core: 8.x

For more information on what you can declare in this file, visit this link :


Having the above is all you need to be able to enable your module without breaking your site but there’s a lot more other files you might need depending on your purpose. Below are some of the files you might need and what they are commonly used for.

  1. your_module_name.module
    1. This is where hooks and theming information are usually stored
    2. For more information about hooks, visit this link
  2. your_module_name.routing.yml
    1. This file serves as a replacement for the hook_menu() call where you can specify different routes for your module
    1. While the routing file creates a page at /admin/config/development/your_route_name, the definitions inside are needed to add the pages to the Administration menu.
  4. your_module_name.libraries.yml
    1. This file is used to record dependencies for CSS and Javascript libraries
    2. For more information about the libraries.yml file, click here
  5. your_module_name.permissions.yml
    1. This is a simpler alternative to hook_permission() where you can declare permissions for your module

The information above only contains the most used parts and there are a lot more files and techniques you can use to build your very own awesome module. To learn more about in-depth module creation, see this article from


Profile picture for user Jeffy Lepatan
Jeffy Lepatan Manager [ Acret PH ]

I grew up in a slum in Cebu and at a young age I already learned that having a comfortable life is not something you get for free, you have to work hard to achieve it. Being the eldest out of seven siblings, I make sure that I share whatever I achieve with my younger brothers and sisters. I think that is the most important trait that I could share with my team, so that nobody gets left behind. I am truly grateful to our CEO for giving me a chance to be part of something big, that is why as a developer, I make my contributions by challenging myself everyday in order to make software solutions that would help the internet space easier to navigate. And as a manager, I encourage my team to always be grateful for an opportunity to create something useful for others while having fun doing it and to help build each other up within the team. I've never been anywhere outside the country and I dream of the day when I can visit other countries just by putting on a VR headgear then seconds later it will feel like you're there. I believe advancements in development technologies can make that possible. Going anywhere in the world within minutes - why not?