Template Module

Zero Development maintains an official starter template at 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:

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:

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:

   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:

   {
       "name": "My Module"
   }

Directory Structure

The starter template includes the following pre-built files:

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.
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.