extensions/extending-sudobot-with-extensions/page.mdx

---
title: Extending SudoBot with Extensions
short_name: Extending SudoBot with Extensions
---

import Callout from "@/components/Alerts/Callout";

# Extending SudoBot with Extensions

SudoBot has support for extensions, and it was introduced in version 6.17. Extensions can extend the bot's feature, by adding commands, event listeners, services and a lot more stuff. You can install/uninstall/disable extensions, or create your own to make the bot behave exactly how you want. Extensions can be written using JavaScript and TypeScript.

In this article, you'll learn how SudoBot's extension system works.

## The `extensions` directory

The `extensions` is a special directory in the project root. Every installed extension stays inside this directory. If you want to install extensions, you have to create a directory named `extensions/` in the project root.

Each installed extension has a directory associated with it inside the `extensions/` directory. Inside of that inner directory, there is a special file `extension.json` which contains meta information about the extension, and how to build it.

The `extension.json` file looks something like this:

```json5
{
    "main": "./build/index.js" /* The entry point. */,
    "commands": "./build/commands" /* Commands directory. The bot will load commands from this directory. */,
    "events": "./build/events" /* Event handlers directory. The bot will load event handlers from this directory. */,
    "language": "typescript" /* The language being used for this extension. Can be either "javascript" or "typescript". */,
    "main_directory": "./build" /* The main directory where the entry point is located. */,
    "build_command": "npm run build" /* Command to build the extension. In this case `npm run build` invokes `tsc`. */,
}
```

## Creating your first SudoBot extension

To get started, first create a directory named `extensions` inside the project root. In that directory, create another directory for your extension. The name of this directory usually should be your extension's name. In this example, we'll name the extension "hello".

Then inside your extension's directory, create the `extension.json` file, and the `src/` directory. Inside `src`, create `events` and `commands` directories. The final directory tree should look something like this:

```
+ sudobot/ [project root]
  + extensions/
    + hello/
      + src/
        + commands/
        + events/
      - extension.json
```

Now add the following to your `extension.json` file:

```json
{
    "main": "./build/index.js",
    "commands": "./build/commands",
    "events": "./build/events",
    "language": "typescript",
    "main_directory": "./build",
    "build_command": "npm run build"
}
```

We'll be using TypeScript to write the extension in this example. If you'd like to use JavaScript instead, you can set `language` to `javascript` and you don't need to specify a build command, and your main directory will be the directory where you put your JavaScript files (usually `src/`). You should also adjust the paths to point to that directory (rather than `build/` which is used in this example).

#### Setting up TypeScript and Dependencies

First, run `npm init` to initialize your extension project. This will ask you a few questions and create a `package.json` file. Then run:

```bash
npm link --save ../.. # Path to the sudobot project root
```

<Callout type="info">
    Remember **this is a really important step** to make sure your extension can
    access SudoBot's core utilities to initialize itself. If you don't link
    SudoBot with your extension, it will fail to import the necessary files.
</Callout>

Then we can go ahead and install the dependencies and also set up TypeScript.

```shell
npm install module-alias
npm install -D typescript
npx tsc --init
```

This will add `typescript` as a dev dependency and also create the `tsconfig.json` file which contains the configuration for the TypeScript compiler.

Now open up `tsconfig.json` file, and add the following to the `compilerOptions` object:

```json
"paths": {
    "@sudobot/*": "node_modules/sudobot/build/*"
},
"target": "ES2021",
"experimentalDecorators": true,
"module": "commonjs",
"rootDir": "./src",
"outDir": "./build",
"resolveJsonModule": true,
```

This sets up the `@sudobot` import alias for TypeScript, specifies the source root and build directory, and a few other things that are needed.

<Callout type="info">
    Remember to build the bot beforehand! As you can see, this alias points to
    the `build` directory which is created when you build the bot.
</Callout>

Then open up `package.json` file and add the following inside the root object:

```json
"_moduleAliases": {
    "@sudobot": "node_modules/sudobot/build"
},
"scripts": {
    "build": "tsc"
}
```

You might be thinking, why do we need to add the module aliases twice? It's because TypeScript doesn't actually deal with these module aliases, it just checks the types and imports. In runtime, we need another way to resolve these imports. We use `module-alias` for that.

#### The entry point

We need to create the entry point now! Make a file `src/index.ts` and put the following code inside of that file:

```typescript
import "module-alias/register";
import { Extension } from "@sudobot/core/Extension";

export default class HelloExtension extends Extension {
    // ...
}
```

That's actually all we need inside this file.

#### Adding commands to the extension

Alright, let's add a command to the extension! Create a file `src/commands/HelloCommand.ts` and inside of that file, put the following code:

```typescript
import BaseCommand, {
    BasicCommandContext,
    CommandMessage,
    CommandReturn,
} from "@sudobot/core/Command";

export default class HelloCommand extends BaseCommand {
    public readonly name = "hello";
    public readonly description = "A simple hello-world command.";

    async execute(message: CommandMessage, context: BasicCommandContext) {
        await message.reply("Hello world, from the hello extension!");
    }
}
```

This command just responds to the user with "Hello world, from the hello extension!".

#### Adding event listeners to the extension

Now, let's add an event listener to the extension! Create a file `src/events/MessageCreateEvent.ts` and inside of that file, put the following code:

```typescript
import EventListener from "@sudobot/core/EventListener";
import { Message } from "discord.js";

export default class MessageCreateEvent extends EventListener<"messageCreate"> {
    public readonly name = "messageCreate";

    async execute(message: Message) {
        if (message.author.bot) {
            return;
        }

        if (message.content === "ping") {
            await message.reply("Pong, from the hello extension!");
        }
    }
}
```

This event listener listens to `messageCreate` event, and whenever someone sends a message with content "ping", it will reply to them.

#### Building the extension

Go to the project root, and run the `extensions.js` script to build all the installed extensions:

```bash
node scripts/extensions.js --build
```

This will take a little bit time. After that, you're ready to go. You can now start the bot (assuming you've build it already):

```bash
npm start
```

And then if everything was configured correctly, the `hello` command will be loaded and can be executed on any server.

Congratulations, you've just built an extension for SudoBot!

### Help and Support

If you need help with anything, feel free to create a discussion topic at the [GitHub repo](https://github.com/onesoft-sudo/sudobot). You can also contact via email at [[email protected]](mailto:[email protected]), or join our [Discord Server](https://discord.gg/892GWhTzgs).
1	rakinar2	577	---
2			title: Extending SudoBot with Extensions
3			short_name: Extending SudoBot with Extensions
4			---
5
6			import Callout from "@/components/Alerts/Callout";
7
8			# Extending SudoBot with Extensions
9
10			SudoBot has support for extensions, and it was introduced in version 6.17. Extensions can extend the bot's feature, by adding commands, event listeners, services and a lot more stuff. You can install/uninstall/disable extensions, or create your own to make the bot behave exactly how you want. Extensions can be written using JavaScript and TypeScript.
11
12			In this article, you'll learn how SudoBot's extension system works.
13
14			## The `extensions` directory
15
16			The `extensions` is a special directory in the project root. Every installed extension stays inside this directory. If you want to install extensions, you have to create a directory named `extensions/` in the project root.
17
18			Each installed extension has a directory associated with it inside the `extensions/` directory. Inside of that inner directory, there is a special file `extension.json` which contains meta information about the extension, and how to build it.
19
20			The `extension.json` file looks something like this:
21
22			```json5
23			{
24			"main": "./build/index.js" /* The entry point. */,
25			"commands": "./build/commands" /* Commands directory. The bot will load commands from this directory. */,
26			"events": "./build/events" /* Event handlers directory. The bot will load event handlers from this directory. */,
27			"language": "typescript" /* The language being used for this extension. Can be either "javascript" or "typescript". */,
28			"main_directory": "./build" /* The main directory where the entry point is located. */,
29			"build_command": "npm run build" /* Command to build the extension. In this case `npm run build` invokes `tsc`. */,
30			}
31			```
32
33			## Creating your first SudoBot extension
34
35			To get started, first create a directory named `extensions` inside the project root. In that directory, create another directory for your extension. The name of this directory usually should be your extension's name. In this example, we'll name the extension "hello".
36
37			Then inside your extension's directory, create the `extension.json` file, and the `src/` directory. Inside `src`, create `events` and `commands` directories. The final directory tree should look something like this:
38
39			```
40			+ sudobot/ [project root]
41			+ extensions/
42			+ hello/
43			+ src/
44			+ commands/
45			+ events/
46			- extension.json
47			```
48
49			Now add the following to your `extension.json` file:
50
51			```json
52			{
53			"main": "./build/index.js",
54			"commands": "./build/commands",
55			"events": "./build/events",
56			"language": "typescript",
57			"main_directory": "./build",
58			"build_command": "npm run build"
59			}
60			```
61
62			We'll be using TypeScript to write the extension in this example. If you'd like to use JavaScript instead, you can set `language` to `javascript` and you don't need to specify a build command, and your main directory will be the directory where you put your JavaScript files (usually `src/`). You should also adjust the paths to point to that directory (rather than `build/` which is used in this example).
63
64			#### Setting up TypeScript and Dependencies
65
66			First, run `npm init` to initialize your extension project. This will ask you a few questions and create a `package.json` file. Then run:
67
68			```bash
69			npm link --save ../.. # Path to the sudobot project root
70			```
71
72			<Callout type="info">
73			Remember this is a really important step to make sure your extension can
74			access SudoBot's core utilities to initialize itself. If you don't link
75			SudoBot with your extension, it will fail to import the necessary files.
76			</Callout>
77
78			Then we can go ahead and install the dependencies and also set up TypeScript.
79
80			```shell
81			npm install module-alias
82			npm install -D typescript
83			npx tsc --init
84			```
85
86			This will add `typescript` as a dev dependency and also create the `tsconfig.json` file which contains the configuration for the TypeScript compiler.
87
88			Now open up `tsconfig.json` file, and add the following to the `compilerOptions` object:
89
90			```json
91			"paths": {
92			"@sudobot/": "node_modules/sudobot/build/"
93			},
94			"target": "ES2021",
95			"experimentalDecorators": true,
96			"module": "commonjs",
97			"rootDir": "./src",
98			"outDir": "./build",
99			"resolveJsonModule": true,
100			```
101
102			This sets up the `@sudobot` import alias for TypeScript, specifies the source root and build directory, and a few other things that are needed.
103
104			<Callout type="info">
105			Remember to build the bot beforehand! As you can see, this alias points to
106			the `build` directory which is created when you build the bot.
107			</Callout>
108
109			Then open up `package.json` file and add the following inside the root object:
110
111			```json
112			"_moduleAliases": {
113			"@sudobot": "node_modules/sudobot/build"
114			},
115			"scripts": {
116			"build": "tsc"
117			}
118			```
119
120			You might be thinking, why do we need to add the module aliases twice? It's because TypeScript doesn't actually deal with these module aliases, it just checks the types and imports. In runtime, we need another way to resolve these imports. We use `module-alias` for that.
121
122			#### The entry point
123
124			We need to create the entry point now! Make a file `src/index.ts` and put the following code inside of that file:
125
126			```typescript
127			import "module-alias/register";
128			import { Extension } from "@sudobot/core/Extension";
129
130			export default class HelloExtension extends Extension {
131			// ...
132			}
133			```
134
135			That's actually all we need inside this file.
136
137			#### Adding commands to the extension
138
139			Alright, let's add a command to the extension! Create a file `src/commands/HelloCommand.ts` and inside of that file, put the following code:
140
141			```typescript
142			import BaseCommand, {
143			BasicCommandContext,
144			CommandMessage,
145			CommandReturn,
146			} from "@sudobot/core/Command";
147
148			export default class HelloCommand extends BaseCommand {
149			public readonly name = "hello";
150			public readonly description = "A simple hello-world command.";
151
152			async execute(message: CommandMessage, context: BasicCommandContext) {
153			await message.reply("Hello world, from the hello extension!");
154			}
155			}
156			```
157
158			This command just responds to the user with "Hello world, from the hello extension!".
159
160			#### Adding event listeners to the extension
161
162			Now, let's add an event listener to the extension! Create a file `src/events/MessageCreateEvent.ts` and inside of that file, put the following code:
163
164			```typescript
165			import EventListener from "@sudobot/core/EventListener";
166			import { Message } from "discord.js";
167
168			export default class MessageCreateEvent extends EventListener<"messageCreate"> {
169			public readonly name = "messageCreate";
170
171			async execute(message: Message) {
172			if (message.author.bot) {
173			return;
174			}
175
176			if (message.content === "ping") {
177			await message.reply("Pong, from the hello extension!");
178			}
179			}
180			}
181			```
182
183			This event listener listens to `messageCreate` event, and whenever someone sends a message with content "ping", it will reply to them.
184
185			#### Building the extension
186
187			Go to the project root, and run the `extensions.js` script to build all the installed extensions:
188
189			```bash
190			node scripts/extensions.js --build
191			```
192
193			This will take a little bit time. After that, you're ready to go. You can now start the bot (assuming you've build it already):
194
195			```bash
196			npm start
197			```
198
199			And then if everything was configured correctly, the `hello` command will be loaded and can be executed on any server.
200
201			Congratulations, you've just built an extension for SudoBot!
202
203			### Help and Support
204
205			If you need help with anything, feel free to create a discussion topic at the [GitHub repo](https://github.com/onesoft-sudo/sudobot). You can also contact via email at [[email protected]](mailto:[email protected]), or join our [Discord Server](https://discord.gg/892GWhTzgs).