From 43d52a6c4301f7330ab05630e236b2f436abf7ff Mon Sep 17 00:00:00 2001 From: Fleny Date: Sun, 25 Feb 2024 02:41:44 +0100 Subject: [PATCH] docs: Add examples for Node.js and Bun, update Deno example (#3385) * Update docusaurus typescript setup for v3 And fix lint-staged and eslint * Enable automatic JSX runtime * Remove babel config and dependencies * update yarn.lock * add typecheck to site workflow * update typedoc config * downgrade docusaurus packages * Update site.yml * Type context and options in webpack-docusaurus-plugin.ts * Update env tips and add minimal examples for node and bun And update the one from deno that was really out of date --------- Co-authored-by: Matt Hatcher <3768988+MatthewSH@users.noreply.github.com> --- website/docs/beginner/_category_.json | 13 ++- website/docs/beginner/env.md | 119 +++++++++++++++++++++----- website/docs/beginner/token.md | 2 +- website/docs/examples/_category_.json | 12 +-- website/docs/examples/bun.md | 40 +++++++++ website/docs/examples/deno.md | 33 +++---- website/docs/examples/node.md | 43 ++++++++++ 7 files changed, 211 insertions(+), 51 deletions(-) create mode 100644 website/docs/examples/bun.md create mode 100644 website/docs/examples/node.md diff --git a/website/docs/beginner/_category_.json b/website/docs/beginner/_category_.json index b8993733a..e8ee347e4 100644 --- a/website/docs/beginner/_category_.json +++ b/website/docs/beginner/_category_.json @@ -1,9 +1,8 @@ { - "label": "Beginner Tips", - "position": 99, - "link": { - "type": "generated-index", - "description": "Guides for basic knowledge to use discordeno." - } + "label": "Beginner Tips", + "position": 99, + "link": { + "type": "generated-index", + "description": "Guides for basic knowledge to use discordeno." } - \ No newline at end of file +} diff --git a/website/docs/beginner/env.md b/website/docs/beginner/env.md index 6bc045a75..9baca4c20 100644 --- a/website/docs/beginner/env.md +++ b/website/docs/beginner/env.md @@ -3,46 +3,65 @@ sidebar_position: 4 sidebar_label: Setup .env --- -# How to Set Up a .env File with TypeScript in Node.js +# How to Set Up a `.env` File with Node.js, Deno or Bun -## Step 1: Install Required Packages +Each runtime has it's own way of handling the `.env` file, we will see how to do it with Node.js, Deno and Bun -Before you can set up a `.env` file with TypeScript in Node.js, you need to install the required packages. Run the following command in your project's directory: +## Setup -`npm install dotenv @types/dotenv --save-dev` - -## Step 2: Create a .env File - -1. Create a new file named `.env` in the root directory of your project. -2. Add your environment variables to the file in the following format: - -VAR_NAME=value +Create a `.env` file we will be loading into our runtime environment and add some variables to it in the following format: `VAR_NAME=value` For example: -```js +```ini DB_HOST = localhost DB_USER = admin DB_PASS = password123 ``` -## Step 3: Load Environment Variables +## Node.js -1. In your TypeScript file, import the `dotenv` package: +### Loading the `.env` file + +Now that we created this file we need to load it into the environment variables of the node process, we have 2 alternative + +1. Use the build-in `--env-file` option (requires Node.js v20.6+) +1. Use the `dotenv` package + +#### --env-file option + +You need to update the command line you use for running node with the following **node** option and passing it the file name for the `.env` file, the file is resolved based on the directory you are running node from + +Here is an example: + +```sh +node --env-file=.env index.js +``` + +You need to add this flag before the file you want to run also if you have multiple `.env` file you want to include you can add multiple `--env-file` + +#### `dotenv` package + +If you don't want or can't use the `--env-file` option you can do it with the `dotenv` package + +First of all you need to install the `dotenv` package along it's type if you are using TypeScript + +`npm install dotenv @types/dotenv --save-dev` +_or using yarn, pnpm or bun_ + +We now need to load the `.env` from our code so let's add the following code to your typescript file: ```ts import dotenv from 'dotenv' -``` -2. Call the config method of the dotenv package to load the environment variables from the .env file: - -```ts dotenv.config() ``` -## Step 4: Access Environment Variables +This will import the dotenv module and add all the variables we declared in our `.env` file into the node environment variables -You can now access your environment variables using the process.env object. For example: +### Use the environment variables + +You can now access your environment variables using the `process.env` object. For example: ```ts const dbHost = process.env.DB_HOST @@ -50,4 +69,62 @@ const dbUser = process.env.DB_USER const dbPass = process.env.DB_PASS ``` -And that's it! You have now set up a .env file with TypeScript in Node.js and can access your environment variables in your code. +And that's it! You have now set up a `.env` file in Node.js and can access your environment variables in your code. + +## Deno + +Deno has a function in the standard library to load the env from a `.env` file so we will use that function to load our `.env` file + +### Loading the `.env` file + +We first need to import the `load` function from the dotenv module of the standard library and then call it, by doing this it will return us with the environment variables that exited inside the `.env` file. + +```ts +import { load } from 'https://deno.land/std@0.212.0/dotenv/mod.ts' + +const env = await load() +``` + +### Use the environment variables + +With the return object returned by `load` we can access the environment variables it just obtained. For example: + +```ts +const dbHost = env.DB_HOST +const dbUser = env.DB_USER +const dbPass = env.DB_PASS +``` + +And that's it! You have now set up a `.env` file in Deno and can access your environment variables in your code. + +## Bun + +Bun automatically detects and load all the `.env` file in the current directory where you run the bun command. Bun actually allows for some configuration of the runtime itself from this `.env` file and some additional options. You can refer to the [Bun documentation](https://bun.sh/docs/runtime/env) to see them + +### Loading the `.env` file + +We just need to have the `.env` in the same directory as the current directory from where we run the `bun` command. + +If you need you can specify one or more `--env-file` options with the path to your .env file if you need it. + +### Using the environment variables + +Since Bun aims to be a Drop-in replacement for Node.js we can use it's own `Bun.env` object to access the environment variables or just use the `process.env` object to do so. + +For example using `Bun.env`: + +```ts +const dbHost = Bun.env.DB_HOST +const dbUser = Bun.env.DB_USER +const dbPass = Bun.env.DB_PASS +``` + +Or using `process.env`: + +```ts +const dbHost = process.env.DB_HOST +const dbUser = process.env.DB_USER +const dbPass = process.env.DB_PASS +``` + +And that's it! You have now set up a `.env` file in Bun and can access your environment variables in your code. diff --git a/website/docs/beginner/token.md b/website/docs/beginner/token.md index 5dd69afdf..180cf028d 100644 --- a/website/docs/beginner/token.md +++ b/website/docs/beginner/token.md @@ -19,6 +19,6 @@ In order to create a bot for your Discord server, you will need to follow these 2. In your bot settings, click on the "Reset" button. Follow any requirements and then click the "Copy" button that appears. 3. Save your bot token in a secure location. -**Your token is your password. Never share your token with anyone. If you do shrae your token, they will have full access to your bot!** +**Your token is your password. Never share your token with anyone. If you do share your token, they will have full access to your bot!** And that's it! You now have a bot token that you can use to create a bot for your Discord server. Happy coding! diff --git a/website/docs/examples/_category_.json b/website/docs/examples/_category_.json index b259758ff..7b5134d92 100644 --- a/website/docs/examples/_category_.json +++ b/website/docs/examples/_category_.json @@ -1,8 +1,8 @@ { - "label": "Examples", - "position": 98, - "link": { - "type": "generated-index", - "description": "Guides for making bots in discordeno." - } + "label": "Examples", + "position": 98, + "link": { + "type": "generated-index", + "description": "Examples for making bots in discordeno." } +} diff --git a/website/docs/examples/bun.md b/website/docs/examples/bun.md new file mode 100644 index 000000000..67831a01d --- /dev/null +++ b/website/docs/examples/bun.md @@ -0,0 +1,40 @@ +--- +sidebar_position: 4 +sidebar_label: Using with Bun +--- + +# Using with Bun + +Discordeno supports Bun by installing the `@discordeno/bot` package + +## Pre-Requirements + +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) + +After you installed the `@discordeno/bot` package with bun you can start using it. + +This is how you can use it to create a bot that logs into discord: + +```ts +import { createBot } from '@discordeno/bot' + +const bot = createBot({ + token: Bun.env.token, + events: { + ready: ({ shardId }) => console.log(`Shard ${shardId} ready`), + }, +}) + +await bot.start() +``` + +:::note +If you want you can use bun with any package manager, so if you want to can use npm to install the `node_modules` and use bun to run the code +::: + +You are free to expand from this point with whatever code you want. Happy coding! diff --git a/website/docs/examples/deno.md b/website/docs/examples/deno.md index 97bde18e5..909473bc9 100644 --- a/website/docs/examples/deno.md +++ b/website/docs/examples/deno.md @@ -1,36 +1,37 @@ --- -sidebar_position: 2 +sidebar_position: 3 sidebar_label: Using with Deno --- # Using with Deno -To be able to use Discordeno with Deno there is one workaround needed if you are using the gateway package. -We need to make Deno use the websocket from Deno instead of the one which is used in node, because the npm support in Deno cannot use our websocket correctly. +Discordeno supports Deno by using the npm: specifier for your import. -To do it you can use a workaround provided here: https://nest.land/package/katsura/files/src/discordenoFixes/gatewaySocket.ts +## Pre-Requirements -You would use it like this. +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) + +This is how you can use it to create a bot that logs into discord: ```ts -import { load } from 'https://x.nest.land/Yenv@1.0.0/mod.ts' -// Import it like this. There might be a newer version of this fix later, but I would not expect much changes. -import { fixGatewayWebsocket } from 'https://x.nest.land/katsura@1.3.9/src/discordenoFixes/gatewaySocket.ts' -import { createBot } from 'npm:@discordeno/bot@19.0.0-next.5c42bdd' +import { load } from 'https://deno.land/std@0.212.0/dotenv/mod.ts' +import { createBot } from 'npm:@discordeno/bot@19.0.0-next.d81b28a' -const env = await load({ - token: /[M-Z][A-Za-z\d]{23}\.[\w-]{6}\.[\w-]{27}/, -}) +const env = await load() const bot = createBot({ token: env.token, events: { - ready: data => console.log(`Shard ${data.shardId} ready`), + ready: ({ shardId }) => console.log(`Shard ${shardId} ready`), }, }) -// Use this function with the gateway managerr -fixGatewayWebsocket(bot.gateway) - await bot.start() ``` + +You are free to expand from this point with whatever code you want. Happy coding! diff --git a/website/docs/examples/node.md b/website/docs/examples/node.md new file mode 100644 index 000000000..279a9683b --- /dev/null +++ b/website/docs/examples/node.md @@ -0,0 +1,43 @@ +--- +sidebar_position: 2 +sidebar_label: Using with Node.js +--- + +# Using with Node.js + +Discordeno supports Node.js by installing the `@discordeno/bot` package + +## Pre-Requirements + +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) + +After you installed the `@discordeno/bot` package with npm, yarn, pnpm or bun you can start using it. + +This is how you can use it to create a bot that logs into discord: + +```ts +import dotenv from 'dotenv' +import { createBot } from '@discordeno/bot' + +dotenv.config() + +const bot = createBot({ + token: process.env.token, + events: { + ready: ({ shardId }) => console.log(`Shard ${shardId} ready`), + }, +}) + +await bot.start() +``` + +:::note +For this example we will be using the env setup with `dotenv` +::: + +You are free to expand from this point with whatever code you want. Happy coding!