deploy-interactions is a Node.js module providing a powerful command line interface via Commander.js to deploy Discord Application Commands
- Deploy without connecting to the gateway
- Deploy with a package script
- Deploy using npx
- API for deploying in code
- Highly Configurable
Node.js 16.6.0 or newer is required.
npm install deploy-interactionsThings you will need to get started:
- Application id: find it in the developer portal
- Bot token (Client credentials not supported right now!): find it in the developer portal
- Command definitions in a file, either raw or cooerced into the raw format by
.toJSON(), i.e. generated by @discordjs/builders
If you have these three things and all you want to do is deploy globally, its as simple as running npx --no-install deploy-interactions and the CLI will guide you through entering this information.
Note: It is highly recommended to add a script to your package.json to run this command instead of running it with npx. To do so simply add
"deploy": "deploy-interactions"and then you can use npm run deploy to run the command anywhere in the project.
Different projects can vary wildly in structure depending on need. As such your file structure may be vastly different than another persons. There is no required file structure to use deploy-interactions, but there are some structures that make it easier to configure, so here are some samples.
(Easy) A folder with all commands. Deploy all commands using deploy-interactions -c commands
.
|-- commands
|-- example-command-1.js
|-- example-command-2.js
(Medium) Multiple folders. Deploy all commands using deploy-interactions -c commands/example commands/sample
.
|-- commands
|-- example
| |-- example-command-1.js
| |-- example-command-2.js
|
|-- sample
|-- sample-command-1.js
|-- sample-command-2.js
(Hard) Individual files (typically in folders with other files). Deploy all commands using deploy-interactions -c handlers/example/example-command.js handlers/sample/sample-command.js
.
|-- handlers
|-- example
| |-- example-command.js
| |-- not-a-command.js
|
|-- sample
|-- not-a-command.js
|-- sample-command.js
Note: The file extension is required when deploying a single command, otherwise the cli considers it a folder
Another common use case is exporting the command definition as a named export. This is handled via the --named-export <name> CLI argument or the namedExport config key. All exports must use the same key.
There are a few different ways to configure deployment.
- Command Line Question and Answer
- Configuration Files
- Command Line Arguments
- A combination of any of the above
Any command line arguments will always take precedence over configuration files.
The command line Q and A will only ask for the base additional information required unless there is no config file and no other arguments
The command line Q&A is meant as a first time setup and does not provide all the possible options but also serves as a method to not store your token in the config file when using JSON files.
Configuration Files give you the most flexibility in setting up how you deploy your application commands. There are several different ways to store the configuration that will automatically be checked.
- Javascript - Use
.interactionsrc.jsand export an object containing your configuration. - Javascript (ESM) - Use
.interactionsrc.cjswhen in an ESM environment. - JSON - Use
.interactionsrc.jsonto define the configuration. - package.json - create a
interactionsConfigproperty in yourpackage.jsonthat contains the configuration.
The order specified here is the order in which the files are checked, if one is found, the next will not be used.
You can also use --config <path> when running the command to tell the command line where your configuration file is. If the specified file is not found, the deploy will not continue.
The following table describes the possible configuration options, there are further tables that expand upon the types.
| Configuration Key | Type | Command Line Argument | Description |
|---|---|---|---|
| bulkOverwrite | boolean (default: false) | -b, --bulk-overwrite | Whether to overwrite all commands when deploying, skips equality checks |
| clientId | Snowflake | -i, --client-id | The id of the client / application to deploy commands to |
| commandDefinitions | Array of API Ready Application Commands | N/A | The raw definitions for deploying commands, using this key is not recommended |
| commandDestinations | InteractionsDeployDestinationsConfig | N/A (can be setup in Q&A) | The configured destinations for deploying commands |
| commands | Array of file paths or paths with destinations | -c, --comands <files...> | The paths to load command definitions from, if in configuration, it can contain deployment configs for the entire path |
| debug | boolean (default: false) | --debug | Runs the deployment in debug mode, with much more verbose output |
| developer | boolean | -d, --developer [guildId] | Whether to run deployment in dev mode (deploying all commands to a single guild regardless of other config). Uses the devGuildId in config if present and not provided |
| devGuildId | Snowflake | N/A (Set via --developer) | The id of the guild to deploy to when running in developer mode |
| dryRun | boolean (default: false) | -r, --dry-run | Skips the actual API deployment stage and outputs the full summary of deployment |
| force | boolean (default: false) | -f, --force | Skips the equality checks when deploying commands |
| full | boolean | --full | Outputs the full compiled results list after deployment |
| namedExport | string | -n, --named-export | The name of the export in the command files, if the command definition is not the default export |
| summary | boolean | --no-summary | Enables printing summary view after deployment (for CLI setting the option disables it) |
| token | string | -t, --token | The token to use for deploying to the specified application |
| N/A (CLI only) | N/A | --no-global | Disable global deployment, only deploy to guilds |
| N/A (CLI only) | N/A | --store [filename] | Store the generated configuration (excluding token) to .interactionsrc.json or the specified file |
| N/A (CLI only) | N/A | -h, --help | Outputs help for the CLI command |
A record of configured destinations for where commands are being deployed
| property | type |
|---|---|
| global? | Array of InteractionsDeployCommandConfig |
| [guildId]* | Array of InteractionsDeployCommandConfig |
*Any number of guildIds can be used as a key for the object, each with the same type
The name and type of a command to be deployed, effectively an id before one exists
| property | type |
|---|---|
| name | string |
| type? | number (Application Command Type) (default: 1) |
The path and the destinations that all commands specified in the path will go to
| property | type |
|---|---|
| path | string |
| destinations | PathDestinations |
| property | type |
|---|---|
| global | boolean |
| guildIds? | Array of Snowflakes |
This is a quick overview of the API, for full API reference see TODO TSDOC
This module also provides an API for deploying commands in code using recommended best practices. It uses ESM style exports to be compatible with ESM, but is still compatible with CommonJS.
The default export is deploy, the function used to deploy commands.
In the following examples, config is not actually valid
// CommonJS
const deploy = require('deploy-interactions').default
const config = {}
deploy(config)// ESM
import deploy from 'deploy-interactions'
const config = {};
deploy(config)// TypeScript
import deploy, { DeployConfig } from 'deploy-interactions'
const config: DeployConfig = {};
void deploy(config)There are also a few utility functions exported that are used internally to check equality between a Discord Application Command and a API Ready Application Command but can be useful in your code as well.
// Typescript
import { commandEquals } from 'deploy-interactions'
const receivedCommand = // A received command from discord
const command = // A command ready to be deployed
const upToDate = commandEquals(receivedCommand, command)