Our future generation platform is in closed beta. During the beta, expect some rough edges, broken windows overlooking blue sky vistas, and regularly scheduled changes.

Already signed up? Great! You can ignore this.
Need to sign up? Apply to join the beta.
Beginner

Create a basic app with the Slack CLI

Our next-generation platform empowers everyone to take control of their workspace and supercharge their productivity.

In the following guide, we'll get your machine and workspace ready to build on the new platform, then walk through the starter code that comes with every newly scaffolded Slack app. By the end, you'll have created a new app, customized it a bit, and installed it into your workspace. You'll be able to get a Slack app up and running in less time with fewer lines of code.

Before you begin, ensure you have installed the slack CLI and authenticated it into the workspace you'll be developing in. These two steps are outlined in our Quickstart guide:

Step 1Create an app using the Slack CLI

  • Scaffold a new app

    In the following sections, you are going to create a new app that, once installed, will provide you with a Shortcut named Reverse. It will take one argument—a string—and return the same string in reverse.

    At this point, you should have the slack CLI installed, and if you run slack auth list, you should see your workspace listed as ACTIVE.

    Open up a terminal menu and navigate to a directory where you have write access.

    Next, run the CLI's create command. If you run slack create without an argument, the CLI will generate a random app name for you.

    Let's create an app with a name that matches the starter code presented in the next section.

    Go ahead and run the following:

    $ slack create reverse-string
    

    You'll see some output confirming that an app named reverse-string was successfully created in a folder with the same name.

    Let's head into that directory:

    $ cd reverse-string
    

    In the next section, we'll take a look at the file and folder structure of our newly created app to get a feel for where things go and how they all work together.

Step complete!

Step 2Understand the app's file structure

  • The project's parent folder

    This section will introduce you to the file and folder structure of the next-generation Slack platform.

    There are two key learnings in this section:

    1. How to define your function in the manifest.ts file
    2. How to implement and test your function(s) in the functions/ folder

    First, let's start with an overview of your apps directory. You'll find the following files listed below in your new scaffolded app:
    deno.jsonc
    README.md
    LICENSE
    assets/
    functions/
    import_map.json
    manifest.ts
    slack.json
    

    There are two relevant areas within these files to focus on at this point: manifest.ts and the functions folder.

    • functions/: the functions you define in manifest.ts will each be implemented in a separate file in this folder along with their test files.

    • manifest.ts: the app's Manifest where you will specify information about your app, including the specific functions it will use.

     

    The other items in the project include:

    • .slack/: a home for internal configuration files, scripts hooks, and the app SDK. This directory must be checked into your version control.

    • import_map.json: a helper file for Deno that specifies where modules should be imported from.

    • assets/: a place to store assets related with the project. This is a great place to store the icon that your app will display when users interacts with it.

     

    At this point, you created a Slack app on our new platform (horay!) and have been given a fresh perspective on the app's project structure.

    In the next section, we'll look more closely at the reverse-string app and how the different components of it's Manifest fit together.

  • The Manifest file

    In this section, we'll outline the manifest.ts file, what purpose it serves, and how it's correlated to your app.

    Open the manifest.ts. file and you'll find an import statement with three Slack SDK methods DefineFunction, Manifest, and Schema:

    import { DefineFunction, Manifest, Schema } from "deno-slack-sdk/mod.ts";
    
    • DefineFunction: defines a function.

    • Manifest: creates a Slack manifest instance.

    • Schema: defines the acceptable parameter input types.

     

    All three of these methods are called in the ReverseFunction definition below. This is the backbone of your app, where the inputs and outputs of your function will be defined.

    export const ReverseFunction = DefineFunction({
      callback_id: "reverse",
      title: "Reverse",
      description: "Takes a string and reverses it",
      source_file: "functions/reverse.ts",
      input_parameters: {
        properties: {
          stringToReverse: {
            type: Schema.types.string,
            description: "The string to reverse",
          },
        },
        required: ["stringToReverse"],
      },
      output_parameters: {
        properties: {
          reverseString: {
            type: Schema.types.string,
            description: "The string in reverse",
          },
        },
        required: ["reverseString"],
      },
    });
    

    Lastly, declare your Manifest; key information and permissions will be given to your app, allowing your funciton to be implemented elsewhere in the project. You can learn more about exporting your app in our Configuring an App guide.

    export default Manifest({
      name: "my-app",
      description: "Reverse a string",
      icon: "assets/icon.png",
      functions: [ReverseFunction],
      outgoingDomains: [],
      botScopes: ["commands", "chat:write", "chat:write.public"],
    });
    

    Now that you have a solid understanding of how the manifest.ts file works, let's dive into the reverse.ts file.

  • The example function

    In this section we'll overview workings of the functions/ folder and grab some footing within the files inside. For the purpose of this guide we'll only focus on an in depth overview of reverse.ts.

    Open the functions/ folder, you'll find two typescript files:

    • reverse.ts: contains a function implementation.
    • reverse_test.ts: contains (yep, you guessed it!) an example test for said implementation. More on testing to come later!

     

    There are two types, SlackFunctionHandler and ReverseFunction imported at the top of the file:

    import type { SlackFunctionHandler } from "deno-slack-sdk/types.ts";
    import type { ReverseFunction } from "../manifest.ts";
    
    • ReverseFunction: the function definition defined in manifest.ts.
    • SlackFunctionHandler: a function handler that enables your app to perform automatic typing.

     

    Automatic typing
    SlackFunctionHandler will perform automatic typing against the function defintion it is a type of, in this case, the ReverseFunction.

    Let's take a look at the reverseString function implementation.

        const reverseString = inputs.stringToReverse.split("").reverse().join("");
        return await {
          outputs: { reverseString },
        };
    

    reverseString can take input parameters that are described in the properties of the input_parameters field in ReverseFunction; in this case, a single variable named stringToReverse of type Schema.types.string.

    It also defines output_parameters—which is another Schema.types.string named reverseString.

    Notice how it's using the stringToReverse input parameter (inputs.stringToReverse), and that the resultant transformed string stored in reverseString is declared in outputs: { reverseString } as the function's return value.

    Now that you have an understanding of how manifest.ts and reverse.ts work together, in the next section we'll run your app and see how reverseString performs its job (which, of course, is to reverse a string).

Step complete!

Step 3Deploy and run your app

There are two ways to deploy and run your app: Local Development (on your local machine), and Production (on Slack).

  • Local development mode

    When your app is production-ready and you want to deploy it, use slack deploy to get it installed into the workspace of your choice.

    Navigate to your project's root folder at the command prompt, then execute slack deploy.

    Select the workspace you'd like to install your app in once prompted.

    Notice that slack will package up and deploy your app, then put you right back at the command prompt; there's no local development server when deploying this way.

    Jump into Slack and look for your production app. You'll know it's the production version of your app because it does not have (dev) appended to its name.

    At this point, your app has been deployed to your workspace. Now you can make your Shortcut available for use by other users in your workspace by distributing your function. This can only be done after your app has been deployed to production.

  • Production mode

    When your app is production-ready and you want to deploy it, use slack deploy to get it installed into the workspace of your choice.

    Navigate to your project's root folder at the command prompt, then execute slack deploy.

    Select the workspace you'd like to install your app in once prompted.

    Notice that slack will package up and deploy your app, then put you right back at the command prompt; there's no local development server when deploying this way.

    Jump into Slack and look for your production app. You'll know it's the production version of your app because it does not have (dev) appended to its name.

    At this point, your app has been deployed to your workspace. Now you can make your Shortcut available for use by other users in your workspace by distributing your function. This can only be done after your app has been deployed to production.

    You'll be prompted to choose a workspace to install your app. Select the workspace from which you authorized the CLI back in Step 2: Authorize your workspace at the beginning of this guide. Notice that slack will package up and deploy your app, then put you right back at the command prompt; there's no local development server when deploying this way.

    Two different apps in your workspace
    Local and App Hosted modes create different apps on the configured workspace—even though both apps are using the exact same codebase.

    What's the difference?

    When you use slack run, you spin up a local development server and can see your changes propagated to the dev version of your workspace app in real-time; when you use slack deploy, you are packaging that app up for production hosting on our infrastructure.

    Some other important differences between slack run and slack deploy include:

    • Environment variables (with slack env) only works on hosted deployments (e.g., slack deploy)
    • Local environment variables (with slack run) are defined in .env
    • Icons are not supported in Local Development mode
    • After executing slack run, a dev version of your app is installed to the workspace you specify. If you then exit out of the development server, you can still invoke the Shortcut but it will simply timeout; a dev app will only work when the development server is running.

    Where to go from here?

    This marks the end of our Get Started guide, but only the start of your next-generation Slack development journey. Continue onward and keep exploring; we're excited to see what you build!

Step complete!
Next steps