deno-slack-hooks

This library is intended to be used in applications running on Slack's next-generation application platform, focused on remixable units of functionality encapsulated as ephemeral functions. It implements the communication contract between the Slack CLI and any Slack app development SDKs.

Overview

This library enables inter-process communication between the Slack CLI tool and apps authored for Slack's next-generation platform. The CLI delegates various tasks to the application SDK by means of invoking a process and expecting specific kinds of responses in the process' resultant stdout. For a full list of these tasks, check out the Supported Scripts section.

Requirements

This library requires a recent (at least 1.22) version of deno.

Any invocations of this library require additional deno permissions, depending on which of the Supported Scripts is being invoked.

Supported Scripts

The hooks currently provided by this repo are build, check-update, doctor, get-hooks, get-manifest, get-trigger, install-update, and start.

Hook Name	CLI Command	Description
`build`	`slack deploy`	Bundles any functions with Deno into an output directory that's compatible with the Run on Slack runtime. Implemented in `build.ts`.
`check-update`	`slack upgrade`	Checks the App's SDK dependencies to determine whether or not any of your libraries need to be updated. Implemented in `check_update.ts`.
`doctor`	`slack doctor`	Returns runtime versions and other system dependencies required by the application. Implemented in `doctor.ts`.
`get-hooks`	All	Fetches the list of available hooks for the CLI from this repository. Implemented in `mod.ts`.
`get-manifest`	`slack manifest`	Converts a `manifest.json`, `manifest.js`, or `manifest.ts` file into a valid manifest JSON payload. Implemented in `get_manifest.ts`.
`get-trigger`	`slack trigger create`	Converts a specified `json`, `js`, or `ts` file into a valid trigger JSON payload to be uploaded by the CLI to the `workflows.triggers.create` Slack API endpoint. Implemented in `get_trigger.ts`.
`install-update`	`slack upgrade`	Prompts the user to automatically update any dependencies that need to be updated based on the result of the `check-update` hook. Implemented in `install_update.ts`.
`start`	`slack run`	While developing and locally running a deno-slack-based application, the CLI manages a socket connection with Slack's backend and delegates to this hook for invoking the correct application function for relevant events incoming via this connection. For more information, see the deno-slack-runtime repository's details on `local-run`.

Check Update Script Usage

The check_update.ts file is executed as a Deno program and takes no arguments.

Example

deno run -q --config=deno.jsonc --allow-read --allow-net https://deno.land/x/deno_slack_hooks/check_update.ts

Get Hooks Script Usage

The mod.ts file is executed as a Deno program and takes no arguments.

Example

deno run -q --config=deno.jsonc --allow-read --allow-net https://deno.land/x/deno_slack_hooks/mod.ts

Get Trigger Script Usage

The get_trigger.ts file is executed as a Deno program and takes one required argument:

Arguments	Description
`--source`	Absolute or relative path to your target trigger file. The trigger object must be exported as default from this file.

Example

deno run -q --config=deno.jsonc --allow-read --allow-net https://deno.land/x/deno_slack_hooks/get_trigger.ts --source="./trigger.ts"

Install Update Script Usage

The install_update.ts file is executed as a Deno program and takes no arguments.

Example

deno run -q --config=deno.jsonc --allow-run --allow-read --allow-write --allow-net https://deno.land/x/deno_slack_hooks/install_update.ts

Script Overrides Usage

If you find yourself needing to override a hook script specified by this library, you can do so in your Slack app's /slack.json file! Just specify a new script for the hook in question. All supported hooks can be overwritten.

Below is an example /slack.json file that overrides the build script to point to your local repo for development purposes. It's using an implicit "latest" version of the https://deno.land/x/deno_slack_hooks/mod.ts script, but we suggest pinning it to whatever the latest version is.

{
  "hooks": {
    "get-hooks": "deno run -q --allow-read --allow-net https://deno.land/x/deno_slack_hooks/mod.ts",
    "build": "deno run -q --config=deno.jsonc --allow-read --allow-write --allow-net --allow-run file:///<path-to-your-local-repo>/mod.ts"
  }
}

The Slack CLI will automatically know to pick up your local hook definition and use that instead of what's defined by this library.

This can also be used to change the flags sent to the deno run command if you decide to change the location of your config file, or switch to an import map instead.

Getting Help

We welcome contributions from everyone! Please check out our Contributor's Guide for how to contribute in a helpful and collaborative way.