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

feat: update CLI docs

Browse Source
This commit is contained in:
DuroCodes
2024-05-09 13:02:03 -04:00
parent 2513e3e233
commit 39f5be584e
5 changed files with 125 additions and 104 deletions
Download Patch File Download Diff File Expand all files Collapse all files

116
src/content/docs/cli/build.mdx
View File

@@ -17,13 +17,19 @@ Options:
## Guiding Principles
When designing the `sern build` command, our aim was to make building bot applications as simple as possible for the majority of developers. The setup process has been streamlined, and most of the configuration details have been handled for you. Here are some key points to keep in mind:
When designing the `sern build` command, our aim was to make building bot applications as simple as possible for the majority of developers. The setup process has been streamlined, and most of the configuration details have been handled for you.
Here are some key points to keep in mind:
import { Steps } from '@astrojs/starlight/components';
<Steps>
1. **Minimal Configuration**: In the vast majority (99%) of use cases, developers do not need to configure the bot application building process. We believe that simplicity is key, so only a few decisions need to be made on the developer's end.
2. **Optimal Defaults**: We've chosen sensible defaults. This means you can get started without getting bogged down by complex, unneeded configurations.
3. **Finetuned for production bots**: Our CLI leverages an opinionated build solution powered by esbuild. This ensures that bots are built without issues and can be shipped easily.
</Steps>
## Experimental Features
@@ -47,16 +53,17 @@ The `sern build` command comes equipped with a range of features designed to enh
## Implicits
- command line arguments take precendence over sern.build configuration file
- default build format is ESM
- defineVersion = true
- **DEV** AND **PROD** constants are configured.
- only a [few tsconfig options](https://esbuild.github.io/content-types/#tsconfig-json) are respected.
- Command line arguments take precendence over `sern.build` configuration file
- Default build format is ESM
- `defineVersion = true`
- `__DEV__` AND `__PROD__` constants are configured.
- Only a [few tsconfig options](https://esbuild.github.io/content-types/#tsconfig-json) are respected.
### sern.build.js
### `sern.build.js`
- For any extra configuration you may need
- the cli was intentionally made to be installed globally, and we can't provide typings at a project level. If you need typings, here they are:
The `sern.build.js` file is for any extra configuration you may need, such as adding esbuild plugins.
The CLI was intentionally made to be installed globally, and we can't provide typings at a project level. If you need typings, here they are:
```ts
type BuildOptions = {
@@ -100,15 +107,15 @@ type BuildOptions = {
## Usage
```
```sh
sern build
```
(that was easy)
## Adapting older projects
## Adapting Older Projects
- Change your tsconfig.json to extend our generated one.
Change your `tsconfig.json` to extend our generated one, `./.sern/tsconfig.json`.
```json {2}
{
@@ -119,12 +126,11 @@ sern build
}
```
## In depth
## In Depth
We use the `define` and `drop labels` api in C style macros to have easy development stage differences.
[Here](https://esbuild.github.io/api/#drop-labels) is the esbuild full API documentation
We use the `define` and `drop labels` API in C style macros to have easy development stage differences. [Here](https://esbuild.github.io/api/#drop-labels) is the esbuild full API documentation
### drop labels
### Drop Labels
```sh
# mode is set to production
@@ -153,63 +159,49 @@ import { Tabs, TabItem } from '@astrojs/starlight/components';
</TabItem>
</Tabs>
### constants
### Constants
sern builds with three default constants. `__DEV__`, `__PROD__`, `__VERSION__`.
sern builds with three default constants. `__DEV__`, `__PROD__`, `__VERSION__`, where `__VERSION__` is the version in your build options, or `package.json` if unspecified.
<Tabs>
<TabItem value="input" label="Preprocess">
```sh
sern build
```
</TabItem>
<TabItem value="sh" label="Constants available and typesafe!">
```ts
if (__PROD__) {
console.log("Bot version: " + __VERSION__);
}
```
</TabItem>
<TabItem value="input" label="Preprocess">
```sh
sern build
```
</TabItem>
<TabItem value="sh" label="Constants available and typesafe!">
```ts
if (__PROD__) {
console.log("Bot version: " + __VERSION__);
}
```
</TabItem>
</Tabs>
Full esbuild documentation [here](https://esbuild.github.io/api/#define)
Add more to the `define` field in build options (only availible with a `sern.build` file at the moment.
Full esbuild documentation [here](https://esbuild.github.io/api/#define). Add more to the `define` field in build options (only availible with a `sern.build` file at the moment)
### process.env
### `process.env`
We generate your process.env with `dotenv` and generate typings for process.env. Less hassle!
<Tabs>
<TabItem value="input" label=".env">
```sh frame="none"
DISCORD_TOKEN=<your token>
```
<TabItem value="input" label=".env">
```ts
process.env.DISCORD_TOKEN; // string | undefined (not typesafe :()
```
</TabItem>
```sh frame="none"
DISCORD_TOKEN=<your token>
```
```ts
process.env.DISCORD_TOKEN; // string | undefined (not typesafe :()
```
</TabItem>
<TabItem value="sh" label="sern build">
```sh
sern build
```
```ts
process.env.DISCORD_TOKEN; // string (typesafe :))
```
</TabItem>
<TabItem value="sh" label="sern build">
```sh
sern build
```
```ts
process.env.DISCORD_TOKEN; // string (typesafe :))
```
</TabItem>
</Tabs>

22
src/content/docs/cli/clear.md
View File

@@ -13,9 +13,13 @@ Options:
-h, --help display help for command
```
## Implicits
## Introduction
- Automatically reads a .env in the working directory. For seamless integration, your .env file should look like this:
The clear command is a utility that resets all of your commands. It's useful if you accidentally publish the wrong command, such as publishing a guild command globally.
The clear command works by sending an empty array via the [`PUT`](https://discord.com/developers/docs/interactions/application-commands#bulk-overwrite-global-application-commands) route to the Discord API, for each guild and globally.
To use this command, ensure you have a proper `.env` file in your root directory:
```sh title=".env"
DISCORD_TOKEN=<YOUR_TOKEN>
@@ -23,13 +27,13 @@ APPLICATION_ID=<YOUR_APPLICATION_ID>
NODE_ENV=<development|production>
```
- Calls the discord API with the [PUT route](https://discord.com/developers/docs/interactions/application-commands#bulk-overwrite-global-application-commands) with an EMPTY array, essentially setting all registered commands to nothing.
## Usage
- Optionally override an .env path as a command line argument as well. **CLI arguments take precedence.**
If you do not know how to obtain either of these credentials, [click here](https://github.com/reactiflux/discord-irc/wiki/Creating-a-discord-bot-&-getting-a-token)
```sh
sern commands clear
```
- Automatically confirm with the **-y** flag.
## Notes
## Features
- Clears all application data and sern-commands-data.json
- The clear command will prompt you to confirm the action. You can bypass this by using the `-y` flag.
- The clear command will automatically read a `.env` file in the working directory. If you need to override this, you can use the `-e` flag to supply a path to a different `.env` file.

14
src/content/docs/cli/extra.md
View File

@@ -11,4 +11,16 @@ Options:
-h, --help display help for command
```
This command is pretty straightfoward. Install utilities into your application. Assumes you have a sern.config.json.
## Introduction
This command is pretty straightfoward. Install utilities into your application, assuming you have a `sern.config.json`.
You can use this command to install things such as a `Dockerfile`
## Usage
```ansi frame
❯ sern extra
# Choose which extra feature from the prompt, such as this:
✔ What extra feature do you want to add? › Dockerfile (TypeScript)
```

75
src/content/docs/cli/publish.md
View File

@@ -17,9 +17,19 @@ Options:
-h, --help display help for command
```
## Implicits
## Introduction
- Automatically reads a .env in the working directory. For seamless integration, your .env file should look like this:
The publish command is a way to publish slash commands to Discord. It uses the [`PUT`](https://discord.com/developers/docs/interactions/application-commands#bulk-overwrite-global-application-commands) route to overwrite existing commands.
Wherever your commands directory is located, publish will override the existing application commands on Discord. Existing commands do not count towards the command limit creation daily.
The publish command automatically reads your `.env` file in the working directory. If you do not have a `.env` file, you can pass in the `--token` and `--appId` flags.
:::caution
CLI arguments, if specified, take precedence over `.env` file.
:::
Your `.env` file should look like this:
```sh title=".env"
DISCORD_TOKEN=<YOUR_TOKEN>
@@ -27,53 +37,49 @@ APPLICATION_ID=<YOUR_APPLICATION_ID>
NODE_ENV=<production|development>
```
- Calls the discord API with the [PUT route](https://discord.com/developers/docs/interactions/application-commands#bulk-overwrite-global-application-commands). Wherever your commands directory is located, publish will override the existing application commands at Discord. Existing commands do not count towards the command limit creation daily.
You may pass these in as command line arguments as well. **CLI arguments take precedence.**
If you do not know how to obtain either of these credentials, [click here](https://github.com/reactiflux/discord-irc/wiki/Creating-a-discord-bot-&-getting-a-token)
## Usage
:::caution
CommonJS and JavaScript users need to compile first, then run `sern publish` on the `dist` output
:::
![usage](~/assets/docs/sern-publish.gif)
## Features
- Automatically syncs api with your command base
- generates JSON file of output (**.sern/command-data-remote.json**)
- supports publishing direct esm typescript files
- commonjs + javascript users need to compile first and then run sern publish on the dist/ output
- prerequire scripts.
- supports a configuration that is the same as the original publish plugin.
Each command file can have an extra config that follows `ValidPublishOptions`:
- Automatically syncs API with your command base
- Generates a JSON file of output (`.sern/command-data-remote.json`)
- Supports publishing direct ESM TypeScript files
- Prerequire scripts are supported
- Supports a configuration that is the same as the original publish plugin
- Each command file can have an extra config that follows `ValidPublishOptions`
- This can be a function or a `PublishConfig` object
## Config
```ts
```ts {13-15}
type ValidMemberPermissions =
| PermissionFlagBits //discord.js enum
| PermissionFlagBits[] //array of discord.js enum
| string //must be a stringified number
| PermissionFlagBits // discord.js enum
| PermissionFlagBits[] // array of discord.js enum
| string // must be a stringified number (such as "8" for ADMINISTRATOR)
| bigint
interface PublishConfig {
guildIds?: string[];
dmPermission?: boolean;
defaultMemberPermissions: ValidMemberPermissions;
dmPermission?: boolean;
defaultMemberPermissions: ValidMemberPermissions;
}
type ValidPublishOptions =
| PublishConfig
| (absPath: string, module: CommandModule) => PublishConfig
```
In other words, you can export a function or object.
## Prerequiring
Is there a [service](../guide/walkthrough/services) that is required at the top level of a command?
Is there a [service](../../guide/walkthrough/services) that is required at the top level of a command?
- Create an ES6 script anywhere:
Create an ES6 script anywhere, such as:
```ts title="scripts/prerequire.mjs"
import { makeDependencies, single, Service } from "@sern/handler";
@@ -87,17 +93,25 @@ await makeDependencies({
await Service("@sern/client").login();
```
This will create a container for publishing. (as of 0.6.0, client is required or this will crash)
This will create a container for publishing.
### Example: command published in guild
:::danger
As of 0.6.0, the `client` is required, or this will crash.
:::
#### Script ran:
## Example
This example will publish a ping command to a specific guild: `889026545715400705`.
### Script
```sh
sern commands publish -i ./scripts/prerequire.mjs
```
```ts title=src/commands/ping.ts
### Command
```ts title=src/commands/ping.ts {5-7}
import { commandModule, Service, CommandType } from '@sern/handler'
const client = Service('@sern/client');
@@ -113,5 +127,4 @@ export default commandModule( {
ctx.reply('pong')
}
})
```

2
src/content/docs/guide/walkthrough/good-to-know.md
View File

@@ -4,7 +4,7 @@ sidebar:
order: 13
---
## sern.config.json
## `sern.config.json`
A `sern.config.json`, although not necessary, allows your project to communicate with our cli.