# Template Module

URL: https://zerodev.ca/docs/medusa/developer-documentation/template

> Quickstart template repository for creating custom Medusa modules.



Zero Development maintains an official starter template at [github.com/zerodev-ca/Medusa-Template](https://github.com/zerodev-ca/Medusa-Template). The template includes complete implementations of every Medusa subsystem, preconfigured translation files for all 16 supported languages, audit logging, database models, Discord commands, and custom dashboard pages.

## Cloning the Template

To begin creating a new module, clone the repository directly into your Medusa `modules/` directory or as an isolated git worktree:

```bash
git clone https://github.com/zerodev-ca/Medusa-Template modules/my-module
cd modules/my-module
```

If you manage your module as an isolated git branch in the Medusa workspace:

```bash
git worktree add modules/my-module -b module/my-module
```

## Renaming the Module

Update the module identifier in the following files:

1. **`main.js`**: Update the `name` property to match your folder name in lowercase, and specify a readable `displayName` for the web dashboard:
   ```js title="modules/my-module/main.js"
   super(medusa, {
       name: "my-module",
       displayName: "My Module",
       author: "Your Organization",
       version: "1.0.0.0",
       description: "Custom module built from the Medusa template."
   });
   ```

2. **`resources/lang/en/common.json`** (and other language folders): Update your localized display name:
   ```json
   {
       "name": "My Module"
   }
   ```

## Directory Structure

The starter template includes the following pre-built files:

```text
modules/my-module/
├── main.js
├── README.md
├── resources/
│   ├── config/
│   │   └── settings.js
│   ├── dashboard/
│   │   └── pages/
│   │       └── template/
│   │           ├── page.js
│   │           └── view.tsx
│   ├── lang/
│   │   ├── de/
│   │   ├── en/
│   │   │   ├── common.json
│   │   │   └── messages.js
│   │   ├── es-ES/
│   │   ├── fr/
│   │   ├── it/
│   │   ├── ja/
│   │   ├── ko/
│   │   ├── nl/
│   │   ├── pl/
│   │   ├── pt-BR/
│   │   ├── ru/
│   │   ├── sv-SE/
│   │   ├── tr/
│   │   ├── uk/
│   │   ├── zh-CN/
│   │   ├── zh-TW/
│   │   └── translations.json
│   ├── leaderboards/
│   │   └── activity.js
│   ├── logs/
│   │   └── templateEvents.js
│   └── nodes/
│       └── sendNotification.js
└── src/
    ├── clocks/
    │   └── cleanup.js
    ├── commands/
    │   └── template.js
    ├── events/
    │   ├── messageCreate.js
    │   └── interactionCreate.js
    ├── handlers/
    │   └── Items.js
    ├── models/
    │   └── Item.js
    └── routes/
        └── items/
            └── route.js
```

## Development Workflow

1. **Database Schema**: Define your database columns in `src/models/`. When Medusa boots, it automatically alters database tables to match your schema.
2. **Business Logic**: Write reusable methods in `src/handlers/`. Use `this.fail(statusCode, message)` to bubble errors cleanly up to routes or command responses.
3. **Discord Commands & Components**: Expose user interactions in `src/commands/`. Send interactive buttons, select menus, and modals using Discord.js builders with `medusa:<component>:<module>:<name>:<describer>` custom IDs.
4. **Gateway Interactions**: Handle button clicks, dropdown selections, and modal submissions in `src/events/interactionCreate.js`.
5. **Dashboard Forms**: Declare settings in `resources/config/`. To show a live preview next to a config group, add a component in `resources/dashboard/previews/`, see [Pages](/docs/medusa/developer-documentation/pages).
6. **Custom Dashboard Views**: Provide bespoke management pages in `resources/dashboard/pages/` utilizing built-in shadcn/Tailwind UI components (`Button`, `Select`, `Input`, `Switch`, `Badge`, `Card`, `Modal`).
7. **Localization**: Define keys in `resources/lang/en/messages.js` and provide localized versions in `resources/lang/translations.json`.

Restart Medusa to compile and load your changes.