mirror of
https://github.com/discordeno/discordeno.git
synced 2026-09-17 16:57:22 +00:00
feat(docs): Add getting-started with installation (#3557)
* Add getting-started with installation * Add minimal example, and helpers and desired proprieties explanation * Add comment on helper example usage * fix small grammar error * Fix GuildMessages being without the Intents. before Co-authored-by: Awesome Stickz <awesome@stickz.dev> * Apply code suggestion Co-authored-by: Awesome Stickz <awesome@stickz.dev> * Apply suggestions from code review Co-authored-by: Awesome Stickz <awesome@stickz.dev> * fix: typo * remove todo * Apply suggestions from code review Co-authored-by: LTS20050703 <lts20050703@gmail.com> * Remove useless parenthesis * Apply code review suggestion --------- Co-authored-by: Awesome Stickz <awesome@stickz.dev> Co-authored-by: LTS20050703 <lts20050703@gmail.com>
This commit is contained in:
Fleny
co-authored by
Awesome Stickz
LTS20050703
Awesome Stickz
LTS20050703
parent
da01c23841
commit
8e011210e2
@@ -1,6 +1,6 @@
|
||||
{
|
||||
"label": "Beginner Tips",
|
||||
"position": 99,
|
||||
"position": 4,
|
||||
"link": {
|
||||
"type": "generated-index",
|
||||
"description": "Guides for basic knowledge to use discordeno."
|
||||
|
||||
@@ -1,8 +1,8 @@
|
||||
{
|
||||
"label": "Big Bot Guide",
|
||||
"position": 3,
|
||||
"position": 5,
|
||||
"link": {
|
||||
"type": "generated-index",
|
||||
"description": "Learn the most important concepts and set up a base template for your bot."
|
||||
"description": "Learn the most important concepts for a scalable bot."
|
||||
}
|
||||
}
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
{
|
||||
"label": "Examples",
|
||||
"position": 98,
|
||||
"position": 6,
|
||||
"link": {
|
||||
"type": "generated-index",
|
||||
"description": "Examples for making bots in discordeno."
|
||||
|
||||
@@ -11,10 +11,10 @@ Discordeno supports Bun by installing the `@discordeno/bot` package
|
||||
|
||||
Before, going forward, please make sure to have finished everything on this list.
|
||||
|
||||
- Create an application and get the bot token. [Create Application Guide](https://discordeno.js.org/docs/beginner/token)
|
||||
- Add your bot to a server you own. [Invite Bot Guide](https://discordeno.js.org/docs/beginner/inviting)
|
||||
- Install Discordeno. [Installation Guide](https://discordeno.js.org)
|
||||
- Setup environment variables. [Environment Variables Guide](https://discordeno.js.org/docs/beginner/env)
|
||||
- Create an application and get the bot token. [Create Application Guide](../beginner/token)
|
||||
- Add your bot to a server you own. [Invite Bot Guide](../beginner/inviting)
|
||||
- Install Discordeno. [Installation Guide](../getting-started.md)
|
||||
- Setup environment variables. [Environment Variables Guide](../beginner/env)
|
||||
|
||||
After you installed the `@discordeno/bot` package with bun you can start using it.
|
||||
|
||||
|
||||
@@ -11,10 +11,10 @@ Discordeno supports Deno by using the npm: specifier for your import.
|
||||
|
||||
Before, going forward, please make sure to have finished everything on this list.
|
||||
|
||||
- Create an application and get the bot token. [Create Application Guide](https://discordeno.js.org/docs/beginner/token)
|
||||
- Add your bot to a server you own. [Invite Bot Guide](https://discordeno.js.org/docs/beginner/inviting)
|
||||
- Install Discordeno. [Installation Guide](https://discordeno.js.org)
|
||||
- Setup environment variables. [Environment Variables Guide](https://discordeno.js.org/docs/beginner/env)
|
||||
- Create an application and get the bot token. [Create Application Guide](../beginner/token)
|
||||
- Add your bot to a server you own. [Invite Bot Guide](../beginner/inviting)
|
||||
- Install Discordeno. [Installation Guide](../getting-started.md)
|
||||
- Setup environment variables. [Environment Variables Guide](../beginner/env)
|
||||
|
||||
This is how you can use it to create a bot that logs into discord:
|
||||
|
||||
|
||||
@@ -11,10 +11,10 @@ Discordeno supports Node.js by installing the `@discordeno/bot` package
|
||||
|
||||
Before, going forward, please make sure to have finished everything on this list.
|
||||
|
||||
- Create an application and get the bot token. [Create Application Guide](https://discordeno.js.org/docs/beginner/token)
|
||||
- Add your bot to a server you own. [Invite Bot Guide](https://discordeno.js.org/docs/beginner/inviting)
|
||||
- Install Discordeno. [Installation Guide](https://discordeno.js.org)
|
||||
- Setup environment variables. [Environment Variables Guide](https://discordeno.js.org/docs/beginner/env)
|
||||
- Create an application and get the bot token. [Create Application Guide](../beginner/token)
|
||||
- Add your bot to a server you own. [Invite Bot Guide](../beginner/inviting)
|
||||
- Install Discordeno. [Installation Guide](../getting-started.md)
|
||||
- Setup environment variables. [Environment Variables Guide](../beginner/env)
|
||||
|
||||
After you installed the `@discordeno/bot` package with npm, yarn, pnpm or bun you can start using it.
|
||||
|
||||
|
||||
@@ -0,0 +1,151 @@
|
||||
---
|
||||
sidebar_position: 3
|
||||
sidebar_label: Getting started
|
||||
---
|
||||
|
||||
# Getting started with Discordeno
|
||||
|
||||
:::info
|
||||
Discordeno is not intended for beginners, however you can still utilize it.
|
||||
:::
|
||||
|
||||
## Installation
|
||||
|
||||
You can install the npm package `@discordeno/bot` and this package will take care of setting up the REST & Gateway for your bot.
|
||||
|
||||
```bash
|
||||
npm install @discordeno/bot # Using npm
|
||||
yarn add @discordeno/bot # Using yarn
|
||||
pnpm add @discordeno/bot # Using pnpm
|
||||
bun add @discordeno/bot # Using bun (as a package manager)
|
||||
```
|
||||
|
||||
If you are using Deno you will need to still use the npm package, so you will need to use the `npm:` prefix in your imports.
|
||||
|
||||
## Minimal bot that logins into Discord
|
||||
|
||||
You can use `@discordeno/bot` as follows:
|
||||
|
||||
```ts
|
||||
import { createBot, Intents } from '@discordeno/bot'
|
||||
|
||||
const bot = createBot({
|
||||
token: 'YOUR BOT TOKEN',
|
||||
intents: Intents.Guilds | Intents.GuildMessages, // Or other intents that you might needs.
|
||||
events: {
|
||||
ready: data => {
|
||||
console.log(`The shard ${data.shardId} is ready!`)
|
||||
},
|
||||
},
|
||||
})
|
||||
|
||||
// You can add events after the createBot call if you prefer
|
||||
|
||||
bot.events.messageCreate = message => {
|
||||
// Do stuff with the message object ...
|
||||
}
|
||||
|
||||
await bot.start()
|
||||
```
|
||||
|
||||
This code will create a bot object with a specified token and [Gateway Intents](https://discord.com/developers/docs/topics/gateway#gateway-intents), in this case the ones for getting Guilds and Guilds messages.
|
||||
|
||||
You can check some other minimal examples with [Node.JS](./examples/node.md), [Deno](./examples/deno.md) or [Bun](./examples/bun.md) if you want to know more on how to [create](./beginner/token.md) and [invite](./beginner/inviting.md) a Discord application or how to setup the use of [environment variables](./beginner/env.md) instead of putting your token in your code.
|
||||
|
||||
:::danger[Environment Variables]
|
||||
It is highly encouraged to use an environment variable instead of using a string in your code. You can check out different ways to do it in [this guide](./beginner/env.md)
|
||||
|
||||
That way it makes it much harder to leak sensitive information and it easier to share with other people. Sensitive information are, but not limited to, your bot token
|
||||
:::
|
||||
|
||||
:::warning[Excessive Intents]
|
||||
Adding intents that you don't use in the `intent` value on your bot configuration will result in performance degradation. Only use the intents that you need for your bot, especially when dealing with privileged intents. You can read more about [intents](https://discord.com/developers/docs/topics/gateway#gateway-intents) and [privileged intents](https://discord.com/developers/docs/topics/gateway#privileged-intents) on Discord documentation.
|
||||
:::
|
||||
|
||||
## Send a message in a channel from Discordeno
|
||||
|
||||
As well as managing your connection to the Discord gateway, Discordeno also manage HTTP/REST requests and rate limits (such as [Invalid Request Limit aka Cloudflare ban](https://discord.com/developers/docs/topics/rate-limits#invalid-request-limit-aka-cloudflare-bans)) for you.
|
||||
|
||||
In Discordeno, you can call methods in the `bot.helpers` object to perform some actions on Discord. These methods will return objects that are different from the one returned by Discord, a notable example are the IDs. For IDs, Discord return a string with a number inside to avoid rounding errors in most languages, including JavaScript. However, in JavaScript, this issue can be avoided using [`BigInt`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/BigInt). Therefore, before returning objects, Discordeno will transform most (if not every) IDs from a string to a `BigInt`. As for methods with parameters that accept an ID, most methods in the `bot.helpers` object will accept both a `BigInt` and a normal string.
|
||||
|
||||
For example, to send a message to a channel, you can call the `bot.helpers.sendMessage` method with the 2 required parameters:
|
||||
|
||||
- The ID of the channel that you want to sent the message to
|
||||
- The options of your message
|
||||
|
||||
```ts
|
||||
// Change the id below with one of the channels of one of the server your bot is in
|
||||
const message = await bot.helpers.sendMessage(123123123123123123n, {
|
||||
content: 'Hello world. This is test message from Discordeno.',
|
||||
})
|
||||
```
|
||||
|
||||
:::tip[Naming of functions in Discordeno]
|
||||
Most of the functions in Discordeno are explicit in what they do and named similar to what Discord calls the endpoint in the documentation.
|
||||
|
||||
Discordeno's methods always perform one action only. A method will never call multiple Discord endpoints.
|
||||
:::
|
||||
|
||||
## Understanding Desired Properties in Discordeno
|
||||
|
||||
If we ran the code above (for example, by putting the code inside the ready event), the bot will send a message in the channel you specified (as long as it has the permissions to do so) with the content "Hello world. This is test message from Discordeno.". However, if we log to the console the message object that Discordeno return, we won't see many, if any, values on it. This is also the case for other events such as `MessageCreate`. But why is that? Well, this is because of a Discordeno feature called `Desired properties`.
|
||||
|
||||
Desired properties is a feature that reduce the memory usage of your application by removing properties that you don't use. For example, you might not be interested in knowing the topic of a channel, but Discord will always return it, therefore consuming more memory. This is why Discordeno requires you to explicitly set the properties that you want to keep and use.
|
||||
|
||||
You can set which property you want to keep in the `bot.transformers.desiredProperties` object. Discordeno will default everything to false and you can set the values you want to keep to true manually like this:
|
||||
|
||||
```ts
|
||||
bot.transformers.desiredProperties.message.id = true
|
||||
bot.transformers.desiredProperties.message.content = true
|
||||
bot.transformers.desiredProperties.message.channelId = true
|
||||
```
|
||||
|
||||
With the above 3 lines of code, we will be able to get the message ID, the channel ID and the message content\* of a specific message. The same thing can be said for the return object of `sendMessage` method and the `messageCreate` event
|
||||
|
||||
We can also set the properties we want to keep with `{ id: true, content: true, channelId: true }`, but that would require us to specify all others keys in the object, and doing that would get extremely annoying.
|
||||
|
||||
\*: As long as the required privileged intent is enabled.
|
||||
|
||||
:::danger[Changing the default for Desired Properties]
|
||||
THIS IS NOT RECOMMENDED IF YOU PLAN TO SHIP YOUR BOT TO PRODUCTION.
|
||||
|
||||
While not recommended, you can add `defaultDesiredPropertiesValue: true` to the first parameter object of the `createBot` function. This will set every desired property to true by default (you can still disable some if you want to). The reason why this is not recommended and considered deprecated is because while Desired Properties DO slow you down during development (needing to make sure you aren't using something that you won't have at runtime), they have a significant performance impact on both CPU and memory usage.
|
||||
:::
|
||||
|
||||
:::warning[Typescript and Desired Properties]
|
||||
We are aware that TypeScript has no idea which properties will be missing. We are working on fixing this issue.
|
||||
:::
|
||||
|
||||
## Additional information on Discordeno
|
||||
|
||||
Here are some nice to know things about Discordeno that you might be interested, though some may be for more advanced use-cases.
|
||||
|
||||
### Gateway methods
|
||||
|
||||
If you want to edit some state such as your bot status, you will need to use the methods in `bot.gateway`. These methods will not return transformed objects so if you want to get transformed objects you will need to call the transformers yourself (the transformers are in `bot.transformers`).
|
||||
|
||||
### OAuth2
|
||||
|
||||
Some methods in `bot.helpers` will accept a `Bearer` token, or a `Client ID` and `Client Secret`. These OAuth2 methods will require you to setup the OAuth2 authorization flow. One example is the `bot.helpers.getCurrentUser(bearerToken)` method. This is a method that can not be called with a usual Bot token and require a OAuth2 token.
|
||||
|
||||
Discordeno includes some utilities (such as `createOAuth2Link` to create a OAuth2 authorization link) and methods to exchange your token as well as refresh your exiting token.
|
||||
|
||||
<!-- TODO: Add a link to the page on how to use OAuth2 in Discordeno. -->
|
||||
|
||||
You can read more about OAuth2 in Discord on the [documentation](https://discord.com/developers/docs/topics/oauth2).
|
||||
|
||||
### Use individual features from Discordeno separably
|
||||
|
||||
While we do provide a `@discordeno/bot` package on npm with all features included, you might just need some of them. For this reason, Discordeno is split across multiple packages, which are the following:
|
||||
|
||||
- `@discordeno/bot`: Groups all other packages as well as adding transformers and other functionalities on top.
|
||||
- `@discordeno/rest`: Only provide methods to send requests to Discord REST API as well as handling rate limits. This will provide the same object as [`bot.rest`](#raw-rest-methods) when you create a `RestManager`.
|
||||
- `@discordeno/gateway`: Only provide methods to establish and manage gateway connections to Discord. This will provide the same object as `bot.gateway` when you create a `GatewayManager`
|
||||
- `@discordeno/utils`: Only provide some utilities that are independent from other Discordeno features.
|
||||
- `@discordeno/types`: Only provide the Discord & Discordeno types used in all other packages.
|
||||
|
||||
It might make more sense to simply use `@discordeno/bot`, as the separate packages are mostly for advanced use cases.
|
||||
|
||||
### Raw REST methods
|
||||
|
||||
While we recommend using `bot.helpers`, you might find yourself in a situation where avoiding the transformers and desired properties can be beneficial. For this reason, you can use the methods in `bot.rest`. These methods will return the raw response from Discord but with the keys being camelCase instead of snake_case.
|
||||
+11
-28
@@ -24,17 +24,14 @@ Discordeno is actively maintained to guarantee **excellent performance, latest f
|
||||
- Freedom from 1 hour downtimes due to invalid requests
|
||||
- Prevent your bot from being down for an hour, by lowering the maximum downtime to 10 minutes.
|
||||
- Freedom from global rate limit errors
|
||||
- As a bot grows, you need to handle global rate limits better. Shards don't communicate fast enough to truly
|
||||
handle it properly. With one point of contact to discords API, you will never have issues again.
|
||||
- As a bot grows, you need to handle global rate limits better. Shards don't communicate fast enough to truly handle it properly. With one point of contact to Discord API, you will never have issues again.
|
||||
- Numerous instances of your bot on different hosts, all of which can connect to the same REST server.
|
||||
- REST does not rest!
|
||||
- Separate rest guarantees that your queued requests will continue to be processed even if your bot breaks for
|
||||
whatever reason.
|
||||
- Separate rest guarantees that your queued requests will continue to be processed even if your bot breaks for whatever reason.
|
||||
- Seamless updates! When updating/restarting a bot, you'll lose a lot of messages or replies that are queued/processing.
|
||||
- Single point of contact to Discord API
|
||||
- Send requests from any location, even a bot dashboard directly.
|
||||
- Don't send requests from dashboard to bot process to send a request to discord. Your bot process should
|
||||
be freed up to handle bot events!
|
||||
- Don't send requests from dashboard to bot process to send a request to discord. Your bot process should be freed up to handle bot events!
|
||||
- Scalability! Scalability! Scalability!
|
||||
|
||||
### Gateway
|
||||
@@ -43,31 +40,22 @@ Discordeno is actively maintained to guarantee **excellent performance, latest f
|
||||
- Others: With non-proxy bots, it takes about 5s per shard bucket to start up. With 100,000 servers, this would be minimum of 8+ minutes of downtime for bot updates.
|
||||
- Discordeno Proxy Gateway: Resume the bot code almost instantly without worrying about any delays or wasting your identify limits.
|
||||
- **Zero Downtime Resharding:**
|
||||
- Discord stops allowing your bot to be added to new servers when you max out your existing max shards. Consider a bot started with 150 shards
|
||||
operating on 150,000 servers. Your shards support a maximum of 150 \* 2500 = 375,000 servers. Your
|
||||
bot will be unable to join new servers once it reaches this point until it re-shards.
|
||||
- Discord stops allowing your bot to be added to new servers when you max out your existing max shards. Consider a bot started with 150 shards operating on 150,000 servers. Your shards support a maximum of 150 \* 2500 = 375,000 servers. Your bot will be unable to join new servers once it reaches this point until it re-shards.
|
||||
- DD proxy provides 2 types of re-sharding. Automated and manual. You can also have both.
|
||||
- Automated: This system will automatically begin a Zero-downtime resharding process behind the scenes when you
|
||||
reach 80% of your maximum servers allowed by your shards. For example, since 375,000 was the max, at 300,000 we
|
||||
would begin re-sharding behind the scenes with ZERO DOWNTIME.
|
||||
- Automated: This system will automatically begin a Zero-downtime resharding process behind the scenes when you reach 80% of your maximum servers allowed by your shards. For example, since 375,000 was the max, at 300,000 we would begin re-sharding behind the scenes with ZERO DOWNTIME.
|
||||
- 80% of maximum servers reached (The % of 80% is customizable.)
|
||||
- Identify limits have room to allow re-sharding. (Also customizable)
|
||||
- Manual: You can also trigger this manually should you choose.
|
||||
- When discord releases a new API version, updates your gateways to new version with no downtime.
|
||||
- **Horizontal Scaling:**
|
||||
- When your bot grows a lot, you have
|
||||
two options: you can either keep investing money to upgrade your server or you may expand horizontally by purchasing
|
||||
several more affordable servers. The proxy enables WS handling on multiple servers.
|
||||
- When your bot grows a lot, you have two options: you can either keep investing money to upgrade your server or you may expand horizontally by purchasing several more affordable servers. The proxy enables WS handling on multiple servers.
|
||||
- **No Loss Restarts:**
|
||||
- Without the proxy mechanism, you would typically lose a lot of events while restarting. Users could issue
|
||||
instructions or send messages that are not automoderated. As your bot grows, this amount grows sharply.
|
||||
Users who don't receive the automatic roles or any other activities your bot should do.
|
||||
- Without the proxy mechanism, you would typically lose a lot of events while restarting. Users could issue instructions or send messages that are not automoderated. As your bot grows, this amount grows sharply. Users who don't receive the automatic roles or any other activities your bot should do.
|
||||
- While your bot is unavailable, events can be added to a queue, and once the bot is back online, the queue will start processing all of the events.
|
||||
- **Flexibility:**
|
||||
- You have complete control over everything inside the gateway thanks to the controller aspect. Need to customize, the way the manager talks to the workers? Simply, plug in and override the method.
|
||||
- **Clustering With Workers:**
|
||||
- Utilize all of your CPU cores to their greatest potential by distributing the workload across workers. To enhance
|
||||
efficiency, manage how shards per worker.
|
||||
- Utilize all of your CPU cores to their greatest potential by distributing the workload across workers. To enhance efficiency, manage how shards per worker.
|
||||
|
||||
### Custom Cache
|
||||
|
||||
@@ -75,17 +63,12 @@ Have your cache setup in any way you like. Redis, PGSQL or any cache layer you w
|
||||
|
||||
## Getting Started
|
||||
|
||||
Interested? [Check the website](https://discordeno.js.org/) for more details on getting started.
|
||||
|
||||
### Tools
|
||||
|
||||
This library is not intended for beginners, however if you still want to utilise it, check out these excellent official
|
||||
and unofficial templates:
|
||||
Interested? [Check the getting started page](./getting-started.md) for more details on getting started with using Discordeno.
|
||||
|
||||
## Links
|
||||
|
||||
- [Website](https://discordeno.js.org/)
|
||||
- [Documentation](https://doc.deno.land/https/deno.land/x/discordeno/mod.ts)
|
||||
- [Discord](https://discord.com/invite/5vBgXk3UcZ)
|
||||
- [Documentation](../api_reference/category/docs-api-references)
|
||||
- [Discord](https://discord.com/invite/ddeno)
|
||||
|
||||
Discordeno follows [semantic versioning](https://semver.org/)
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
{
|
||||
"label": "Migrating",
|
||||
"position": 98,
|
||||
"position": 7,
|
||||
"link": {
|
||||
"type": "generated-index",
|
||||
"description": "Guides for migrating to discordeno from other libraries."
|
||||
|
||||
@@ -219,6 +219,7 @@ const config: Config = {
|
||||
prism: {
|
||||
theme: themes.github,
|
||||
darkTheme: themes.dracula,
|
||||
additionalLanguages: ['bash'],
|
||||
},
|
||||
} satisfies ThemeConfig,
|
||||
|
||||
|
||||
Reference in New Issue
Block a user