sern/website
1
0
Fork 0
mirror of https://github.com/sern-handler/website synced 2026-06-06 01:16:47 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

getting a more cohesive tutorial working

Browse Source
This commit is contained in:
Jacob Nguyen
2024-01-11 12:23:50 -06:00
parent 90b22074df
commit 6b366501f2
11 changed files with 42880 additions and 11575 deletions
Download Patch File Download Diff File Expand all files Collapse all files

BIN
.yarn/install-state.gz
View File

Binary file not shown.

10
docs/tutorial/en/02-preparing/package-manager.md
View File

@@ -12,13 +12,7 @@ The most used ones are:
- [Yarn](https://yarnpkg.com)
- [pnpm](https://pnpm.io/)
For this tutorial, we'll be using **[Yarn](https://yarnpkg.com)**. It's made by Facebook.
**Advantages of Yarn:**
1. **Performance:** Yarn is fast and has efficient dependency management.
2. **Lockfile:** Yarn's `yarn.lock` file ensures deterministic builds, crucial for collaboration.
3. **Offline Mode:** Yarn offers a reliable offline mode, ideal for environments with limited internet access.
5. **Plug-n-play:** Yarn Berry (2) introduces "plug-n-play" (PnP), reducing disk space usage.
For this tutorial, we'll be using **[NPM](https://www.npmjs.com)**, to keep it simple.
---
<GuideFeedback />
<GuideFeedback />

20
docs/tutorial/en/04-setting-up-bot/create-bot.md
View File

@@ -16,28 +16,16 @@ After installing the package, prompts will show up on your terminal. Neat!
## Prompt walkthrough
First, choose a template. In this guide we'll be using the `js-esm` template.
- `js` means Javascript.
- `esm` means ECMAScript Modules. ESM provides a better developer experience than the old CommonJS, so
```js
const { Sern, makeDependencies, single } = require('@sern/handler');
```
would turn to
```js
import { Sern, makeDependencies, single } from '@sern/handler';
```
First, choose a template. In this guide, select the please select the `Javascript with sern cli & ESM` option when prompted.
:::info
We primarily use Typescript but to make the tutorial easier Javascript will be used.
:::
Then, choose a project name. This one should be lowercase with dashes and/or underscores (aka `kebab-case` or `snake_case`).
Then, choose a project. This one should be lowercase with dashes and/or underscores (aka `kebab-case` or `snake_case`).
In the package manager prompt, select [NPM](../preparing/package-manager)
In the package manager prompt, select [Yarn](../preparing/package-manager)
And you're done... with that. See you in the next chapter, where you'll get your discord bot token!
---
Written by [Sr Izan](../intro/who-are-we#ethan)
Get the [source code](https://github.com/sern-handler/tutorial-bot/tree/setting-up-bot/creating-bot)!
<GuideFeedback />
<GuideFeedback />

78
docs/tutorial/en/04-setting-up-bot/create-discord-app.md
View File

@@ -8,61 +8,87 @@ Welcome back!
Before we do anything, we need to edit some code in our bot to make it read the Discord token safely and securely.
# Installing dotenv
The npm package [`dotenv`](https://npm.im/dotenv) lets us use environment variables defined in a `.env` file inside a Node.JS application.
On the newest versions of node.js you can do it without this package, but for the sake of simplicity this will be used.
Alright, enough rambling. Let's open up a terminal (your favorite thing I know...)
```sh
yarn add dotenv
```
This command will add dotenv to the dependencies. Awesome!
And create a blank `.env` file in the root of your project directory (the directory where, for example, your `package.json` file is)
Create a blank `.env` file in the root of your project directory (the directory where your `package.json` file is located)
```
.
├── .env
├── .env.example
├── .sern
├── generated
├── .gitignore
├── .npmignore
├── README.md
├── package.json
├── sern.config.json
├── jsconfig.json
├── src
│ ├── commands
│ │ └── ping.js
│ ├── dependencies.d.ts
│ └── index.js
└── yarn.lock
└── package-lock.json
```
## Setting up your Discord Application
Notice the `.env.example` file? Let's open it.
```sh
DISCORD_TOKEN=YOUR_DISCORD_TOKEN
APPLICATION_ID=YOUR_DISCORD_BOT_USER_ID
NODE_ENV=<production OR development>
```
We need to fill this out, but in another file.
- Create a file `.env` next to `.env.example`
- Copy `.env.example` contents into `.env`, we'll fill this out now.
### Discord Token
You have your bot (almost) ready to go, but first we need a bot token.
First go to Discord Developer's homepage (you can type [discord.dev](https://discord.dev) in your browser and then click on "Applications" on the sidebar)
- Go to Discord Developer's homepage (you can type [discord.dev](https://discord.dev) in your browser and then click on "Applications" on the sidebar)
Click on "New Application" in the top right.
- Click on "New Application" in the top right.
Then, fill in your application's name:
![](https://img.srizan.dev/brave_QYp7LQe5xd.png)
Click on "Bot" in the sidebar, then the "Reset Token" button and copy the token. The token should look something like this:
- Click on "Bot" in the sidebar, then the "Reset Token" button and copy the token. The token should look something like this:
```
MTE1MjM2MDczNzczMDE5OTU2Mg.GUWUsy.dXAoO6NI1Cy3OV7IA-BTGcyzLS28-9tECNcVOg
```
:::danger
Please don't share your discord token (and probably all your other secrets)! Please `gitignore` your `.env` file and keep it safe.
Please don't share your discord token (and probably all your other secrets)!
:::
Also scroll down and enable the `Message Content Intent` and `Server Members Intent` so text commands work and discord.js doesn't error out.
- Scroll down and enable the `Message Content Intent` and `Server Members Intent` so text commands work and discord.js doesn't error out.
Now, go back to your .env file and add this line:
- Replace `YOUR_DISCORD_TOKEN` with your actual discord token:
```
DISCORD_TOKEN=(your discord token)
DISCORD_TOKEN=MTE1MjM2MDczNzczMDE5OTU2Mg.GUWUsy.dXAoO6NI1Cy3OV7IA-BTGcyzLS28-9tECNcVOg
```
### APPLICATION_ID
- Go to "General Information" and find your "APPLICATION ID". Copy That!
- Place it into your .env file.
- In future versions of sern, this may not be needed, but bear with me.
```
APPLICATION_ID=12345632432423987432987
```
### Mode
With sern, there are two stages, development and production. Production is when we ship it to a hosting server and development is
for ...developing. Let's set our NODE_ENV to development. For a more formal explanation, read [this](https://nodejs.org/en/learn/getting-started/nodejs-the-difference-between-development-and-production)
```
NODE_ENV=development
```
### Final
Your `.env` file should looks something like this.
```
DISCORD_TOKEN=MTE1MjM2MDczNzczMDE5OTU2Mg.GUWUsy.dXAoO6NI1Cy3OV7IA-BTGcyzLS28-9tECNcVOg
APPLICATION_ID=12345632432423987432987
NODE_ENV=development
```
What we're essentially doing is defining a new environment variable called `DISCORD_TOKEN` that is set to `(your discord token)`.
## Inviting your bot to a Discord server.
@@ -77,13 +103,19 @@ Then on `Bot permissions` tick `Send Messages` and `Read Message History`. If yo
Finally, scroll down, copy the generated URL, paste it on the address bar and invite your bot as usual.
## Starting the bot
Since we use slash commands, we need to let Discord know we want to use their user interface.
- Run `npm run commands:publish`
There's an npm script that's called `test`, so we're going to be running that.
:::info
This script uses our command line utility, [publish](https://sern.dev/docs/cli/publish).
:::
There's an npm script that's called `start`, so we're going to be running that.
Execute in your terminal:
```
yarn test
npm start
```
And your bot should start up in no time! Congrats!
And your bot should start up in no time! **Congrats!**
---
Written by [Sr Izan](../intro/who-are-we#ethan)

49
docs/tutorial/en/05-overview/commands.md
View File

@@ -1,48 +1,41 @@
---
title: commands
sidebar_position: 2
sidebar_position: 1
---
# Commands
Every sern command is located in the commands directory.
:::caution
Any command outside the specificed directory from `Sern.init` will be ignored!
:::
### Look at ping.js (go into your tutorial rn)
Please soak in all the comments I wrote for what each field will do. We will make a brand new command.
## Example command
- View the command **ping.js** in `src/commands`.
- Make a new file next to **ping.js** called **tictactoe.js**
- Copy **ping.js** contents into **tictactoe.js**.
We base **tictactoe.js** from **ping.js**
:::tip
The name of your command will be the name of your file. This is the ping command.
The name of your command will be the name of your file.
:::
We can activate this command by running `!ping` or `/ping`
Each slash command will follow this similar structure.
In this tutorial, maybe you were smart enough to guess, but we'll be making tictactoe!
Each command will follow this similar structure.
In this tutorial, we'll be making tictactoe!
### New command
- Make a new file
- Call it **tictactoe.js**
- import `CommandType` and `commandModule` from `@sern/handler`
- export this command under the [**default**](https://www.geeksforgeeks.org/what-is-export-default-in-javascript) export
- give it the type `CommandType.Slash`
## New command, tic-tac-toe
- Instead of **CommandType.Both**, `type` property should be **CommandType.Slash**
- This is to keep it simple. You'll see later, but slash commands work well with message components.
- Give it a description.
#### Halfway
This is what your command should look like rn
This is what your command should look like:
```js title=./commands/tictactoe.js
export default commandModule({
type: CommandType.Slash,
description: "I do tictactoe."
description: "I do tictactoe.",
execute: async (ctx, args) => {
await ctx.reply('Pong 🏓');
}
})
```
- Give it a function to execute.
- For now, let's tell the command to execute a reply like "in progress"
- run `sern commands publish`
- run `npm run commands:publish`
- Your command should be usable on discord now!
### Result
@@ -51,8 +44,8 @@ Your command should now look something along the lines of this:
export default commandModule({
type: CommandType.Slash,
description: "I do tictactoe."
execute: (ctx) => {
ctx.reply("Pwease wait. dis command in pwogwess");
execute: async (ctx) => {
await ctx.reply("Pwease wait. dis command in pwogwess"); // 👻
}
})
```

36
docs/tutorial/en/05-overview/events.md
View File

@@ -1,36 +0,0 @@
---
title: events
sidebar_position: 4
---
# Events
Every sern event listener is located in the events directory.
:::caution
Like commands, any event module outside the specificed directory from `Sern.init` will be ignored!
:::
At the moment, all of these events will be turned on at the start of an application. An event is simply an event listener. There are a few events we can listen to: `External`, `Discord`, and `Sern`.
- External events are provided by makeDependencies.
- Discord events are provided by your client, or your channel to the discord API
- Sern events are the events that we provide.
Let's create an event module that'll listen to users joining.
```ts title="events/guildMemberAdd.js
export default discordEvent({
name: 'guildMemberAdd',
execute: (guildMember) => {
console.log("A new member joined!")
//TODO: later
}
})
```
Whenever we restart our bot, every time a user joins, we get a log in the terminal. Good job. If you want to play around with it, go ahead, there are many events you may want to listen to, but for the sake of the tutorial we only need guildMemberAdd.

37
docs/tutorial/en/05-overview/plugins.md
View File

@@ -1,6 +1,6 @@
---
title: plugins
sidebar_position: 3
sidebar_position: 2
---
@@ -11,31 +11,36 @@ sidebar_position: 3
sern has a bunch of premade plugins thanks to our awesome community, which you can install via the cli!
## Forward:
```sh
sern plugins
```
Run this to see all community plugins.
- Run: `sern plugins`, selecting the **channelType** plugin
- Thank the creator(s) of the plugin. (Thank you)
Lets make a command only meant to be run in a *nsfw channel!*
Once you download the `channelType` plugin, You may continue.
## Aside:
### How to use plugins?
Lets take an aside to show how to install plugins.
- Run: `sern plugins`, selecting plugins
- Thank the creator(s) of the plugin. (Thank you)
```js
import { channelType } from '../plugins/channelType.js'
- Install the nsfwOnly plugin.
- Thank the creator of the plugin. (Thank you)
- Read the doucmentation that comes with it.
- Use it!
```ts
export default commandModule({
type: CommandType.Slash,
description: "post very nsfw stuff",
//WE CALL THE PLUGIN IN THE PLUGINS FIELD.
plugins: [nsfwOnly("You cannot use this command here.", true)]
plugins: [channelType([ChannelType.GuildText], 'This cannot be used here')]
})
```
Keep in mind some plugins cannot run for every type of interaction sern handles.
For example, nsfwOnly plugin will probably not work in a modal.
For example, the **channelType** plugin will probably not work in a modal, and if you are using typescript,
the type checker won't allow it. However, there are some more generic plugins, one being **fromCallback**, which can
run in any command / component.
To create custom plugins, view [here](../../../guide/walkthrough/plugins).
### How to contribute plugins?:
- view [here](../../../guide/walkthrough/plugins).
## Moving forward:
Download the `channelType` plugin, because we'll be using that for this tutorial.

23
docs/tutorial/en/05-overview/start.md
View File

@@ -1,23 +0,0 @@
---
title: index
sidebar_position: 1
---
# start
## initiate
We start at the humble index.js. This is where this bot will start. Notice the Sern.init, hmm... I wonder what that does. (it initiates sern)
A few options are availible, which are **conveniently labeled already**. Make sure to glance here.
## dependencies
This requires a little more explaning. In `makeDependencies`, add necessary objects to run your application. you and sern, will use these structures. In the [template](../04-setting-up-bot/create-bot) you have now, we only initiate the client, which is necessary for the handler to run.
```js
await makeDependencies({
build: (root) => root.add({
'@sern/client': single(() => client) // we register our client into sern
})
})
```

20
docs/tutorial/en/05-overview/tictactoe.md Normal file
View File

@@ -0,0 +1,20 @@
---
title: TicTacToe
sidebar_position: 3
---
## Tic Tac Toe
> How hard can this be?
This will probably be the longest chapter in the book. Don't worry though, once we're done, making commands is [**fodder**](https://www.merriam-webster.com/dictionary/fodder).
Here are some inspirational quotes to make you get motivated.
> "If you don't make mistakes, you're not working on hard enough problems." ― Frank Wilczek
> "Dwell on the beauty of life. Watch the stars, and see yourself running with them." ― Marcus Aurelius, Meditations
> "Never let the future disturb you. You will meet it, if you have to, with the same weapons of reason which today arm you against the present." ― Marcus Aurelius, Meditations
If you want to add more, feel free to pull request this, but not too many please

32763
package-lock.json generated Normal file
View File

File diff suppressed because it is too large Load Diff

21419
yarn.lock
View File

File diff suppressed because it is too large Load Diff