deploy-interactions

About

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

Install

Node.js 16.6.0 or newer is required.

npm install deploy-interactions

Usage

Things 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.

Commands

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.

Output Formats

Summary View (Default)

Limited View (--no-summary)

Full View (--full) also gives more detailed errors for single command deploy errors.

Configuration

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

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.js and export an object containing your configuration.
• Javascript (ESM) - Use .interactionsrc.cjs when in an ESM environment.
• JSON - Use .interactionsrc.json to define the configuration.
• package.json - create a interactionsConfig property in your package.json that 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.

Options

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

InteractionsDeployDestinationConfig

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

InteractionsDeployCommandConfig

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)

Paths with Destinations

The path and the destinations that all commands specified in the path will go to

property	type
path	string
destinations	PathDestinations

PathDestinations

property	type
global	boolean
guildIds?	Array of Snowflakes

API

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)