
Dark is a new language for writing deployless backends. Itās also the editor and infrastructure. That means you can only write Dark in your browser, but you never need to set up a server. You donāt even deploy to a server, the code is live as you write it, with changes hidden behind feature flags to prevent breaking your apps.
Dark is a holistic programming language, editor, and infrastructure. By putting the three together we prevent developers from needing to think about infrastructure and deployment, and give them the ability to work with real data and traces.
ā Engineering Team at Dark
At the time of writing, itās still in private beta, but you can request an invite.
Want to gain access faster? Mention my name: Curtis Blackwell, Senior Application Developer at Highland.
I also want to point out that the people creating Dark seem awesome. Their values align well with Highlandās, and I personally admire their active approach to inclusivityāI would love to see more tech companies put people first.
Anyway, the app Iāll show you how to build is similar to IRCāsĀ /me
Ā command. Yes, Slack already has aĀ /me
Ā command, but all it does is regurgitate what you type in italics as though you said it yourself.

If you type ā/me demonstrates why /me is inferior to the app weāll buildā in Slackā¦

Slack will pop out this yawnfest 2020 equivalent to just wrapping your text in underscores.
Instead, weāll useĀ /act
Ā to have a narrator describe our actions.

After building our app, if we type ā/act demonstrates why /me is inferior to the app weāll buildāā¦

A narrator will prefix the input text with the userās display name and italicize the whole thing, much like IRCās /me action.
To accomplish this, weāll need to do a few things:
Create the app in Slack
Write an OAuth endpoint in Dark
Write an endpoint for theĀ
/act
Ā slash command to hit, andGrab the userās profile from Slackās API
1. Creating the Slack app
First, visit your apps page in your Slack workspace and click Create New App.

Name and choose the workspace for your new app, then click Slash Commands then Create New Command.


Fill out the form using your canvas URL appended with /act for the Request URL, e.g.Ā https://your-username-or-canvas.builtwithdark.com/act
.

We also need to set up an OAuth redirect URL. Under Features, click OAuth & Permissions then, on the next page, click Add New Redirect URL. Enter your canvas URL appended withĀ /oauth-redirect
. Donāt forget to click Add and Save URLs (no auto-save for you [insert Seinfeld soup nazi image]).
This next bit wonāt matter until later, but taking care of it now helps us avoid the messiness of having to re-install the app and generate a new OAuth token.
Right underneath the OAuth Tokens & Redirect URLs card, you should see Scopes. Just add theĀ users.profile:read
Ā scope so that we can display the userās name in the narration later.

A brief intro to trace-driven development
Now that weāre about to venture into the Dark side of things ([insert lame Star Wars pun] no pun intended, loljkjkjk), itās important that you know at least a little bit about trace-driven development. I wonāt pretend to know much about itāand what Iām about to say may be technically wrongābut in the case of Dark, I promise itās practical.
Hereās Darkās guide. I recommend you read it, but Iāll include everything you need to know to get through this tutorial.
First, a trace is basically a log of an event. As far as Iāve seen in Dark, itās specifically a log of a request or function call. Without a trace, the Dark IDE wonāt allow you to write code that attempts to access non-existent values, e.g.Ā request.headers
Ā is inaccessible until you actually send a request. (Dark plans to change this, according to their guide.) When you have a trace available, a small dot will appear to the left of the handler, sort of like a tab/window in a more traditional IDE. As you create more traces, you gain the ability to select a specific one to work with. Simply click the dot representing the desired trace.

In this image, the pink arrow points to the currently-hovered trace (its data appears to the left), the blue arrow points to other available traces, and the green arrow points to the currently selected trace (its data appears in tooltips and suggestions as you type).
2. Writing an OAuth endpoint in Dark
Before we can write our OAuth endpoint, weāll need to create a datastore to persist authorized Slack teamsā IDs and their OAuth access tokens, allowing members of the Slack workspace to use your app.

Add a datastore by clicking the plus sign next toĀ Datastores
Name the datastoreĀ
Tokens
, andAddĀ
String
Ā fields forĀteam_id
Ā andĀaccess_token
Next, we need to send a request to the endpoint before writing it. In the Slack app settings, under Settings, click on Manage Distribution. Copy the Sharable URL, and visit it in your browser.

You should see a message about your Slack app requesting permissions. Allow the app to access your Slack workspaceāyou should see a 404. In Dark under 404s, you should see the result of this 404.

Click on the plus sign to create an endpoint.

Type the following code into the endpoint.
Note: Even if Dark has added the ability to copy and paste code by the time you read this, I highly recommend typing this out. Doing so introduces you to how the editor works. Some things behave a little differently than Iām used to in editors like VS Code, and itās nice to understand those differences.No this isnāt actually JavaScript, but the syntax is similar enough that itās easier to read if we lie to Github like the filthy little animals we are.
ReplaceĀ your_client_id
Ā andĀ your_client_secret
Ā with those values found under theĀ Basic InformationĀ page in your Slack appās settings.

The code just goes through the typical authorization code grant flow, so I wonāt delve into whatās going on here.
After definingĀ response
, click the play button to have Dark execute the code.Ā You must do this before definingĀ workspace
Ā so Dark allows you to access the values inĀ response
.

If you receive an error indicating that the code has expired, just revisit the Sharable URL and click Allow again. Make sure you select the newest trace by clicking the highest white do to the left of the endpoint.
After defining workspace
, click the play button next to it so Dark persists the OAuth token.
3. Writing the slash commandās endpoint
Finally, we get to the most exciting part: writing a slash command! We already created the command in the Slack app settings earlier; now we just need to send a request to Dark so that we have a trace to work with.

Just enterĀ /act whatever text you want
Ā in Slack. Donāt worry when you get the error message; we expect that until we actually write the code to handle the request Slack sends to Dark.
Go back to your 404s in your Dark canvas and create a new endpoint from the newĀ /act
Ā 404.
For now, letās keep it simple and just throw italicized text back at Slack. After we have that working, we can add the more complex feature of displaying the userās name. In the newĀ /act
Ā endpoint, add the following code:
This code simply sends a POST request back to Slack using the URL Slack provided in the request,Ā request.body.response_url
.Ā Then we pass the text we want to send (italicizing text is as simple as wrapping the text in underscores, just like when typing messages in Slack) along with the type of response. Without specifying the latter, the message would be visible only to the user who used the slash command. For more info, see Slackās API docs.
Once you have this done, click the play button in the Dark endpoint to have it respond to Slack again. This time, you should see your text displayed. Huzzah!

4. Grabbing the userās profile
Now for some more fun, weāll use Slackās API to grab the userās name for some proper narration. Letās update ourĀ /act
Ā endpoint in Dark to look like this:
First, to query the Slack API, we have to snag our access token from theĀ Tokens
Ā datastore using theĀ team_id
Ā from the request. Then we can pass the token andĀ user_id
Ā (also from the request) to Slackās API and pull the display name out of that.
For more info, see the docs on the API endpoint.
š Phew
We now have a working Slack app to narrate our every move š! For some finishing touches, you can head over to the Slack app settingsā Basic Information page and fill out the Display Information card.
Slackās Display Information form showing the values I used to get my desired style.

To get more practice working with Dark, I suggest ārefactoringā (no tests š±) theĀ /act
Ā endpoint to use functions to fetch the Slack user profile and to italicize text.
If thereās interest in a follow-up post, I can share how I did that and added aĀ /narrate
Ā slash command for non-action-oriented narration purposes. I use it in Highlandās #d20-break channel where I DM some light D&D using the Narrator app and D&D Dice Roller
