Skip to content

docs: guide quick start app creation using the slack cli - #2535

Merged
zimeg merged 34 commits into
mainfrom
zimeg-docs-quick-start-cli
Jun 10, 2025
Merged

zimeg merged 34 commits into
mainfrom
zimeg-docs-quick-start-cli

Conversation

@zimeg

@zimeg zimeg commented May 15, 2025

Copy link
Copy Markdown
Member

Summary

This PR contains a WIP guide for a quick start getting started experience that leverages the Slack CLI.

Reviewers

Inspect these elements in a web browser and this branch: http://localhost:3000/bolt-js/getting-started

Notes

  • Some features proposed are in progress so actual commands and updates to the app might not be reflected as expected for now.
  • The diff is not kind to the reviewer but the Quick start replaces the current Getting started guide, which was moved to be Building an app. No updates were made to the existing guide at this time.

Requirements

@zimeg zimeg self-assigned this May 15, 2025
@zimeg zimeg added the docs M-T: Documentation work only label May 15, 2025
@codecov

codecov Bot commented May 15, 2025 •

Copy link
Copy Markdown

Codecov Report

All modified and coverable lines are covered by tests βœ…

Project coverage is 93.35%. Comparing base (d6051f6) to head (eba3c84).
Report is 1 commits behind head on main.

Additional details and impacted files
@@           Coverage Diff           @@
##             main    #2535   +/-   ##
=======================================
  Coverage   93.35%   93.35%           
=======================================
  Files          37       37           
  Lines        7575     7575           
  Branches      664      664           
=======================================
  Hits         7072     7072           
  Misses        498      498           
  Partials        5        5           

β˜” View full report in Codecov by Sentry.
πŸ“’ Have feedback on the report? Share it here.

πŸš€ New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • πŸ“¦ JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

@technically-tracy technically-tracy left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Wonderful - I think there is a clear separation of learning paths here, and this will be most helpful to developers! ✨

Comment thread docs/content/getting-started.mdx Resolved
Comment thread docs/content/getting-started.mdx Resolved
Comment thread docs/content/getting-started.mdx Resolved
Comment thread docs/content/getting-started.mdx Outdated
@@ -1,493 +1,256 @@
---

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

you're going to hate this lol, but we name these .md files! docusaurus treats .md files as .mdx files but with more forgiving syntax. i can't find the docs on this but this page has interesting side thoughts

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🫑 No! In fact quite the opposite. .mdx is not a familiar extension to me so I am glad to make this change.

FWIW the linked page is confusing to me and I don't know which markdown format is used in practice but I am hoping most for what's forgiving πŸ™

By default, Docusaurus v3 uses the MDX format for all files (including .md files) for historical reasons.

.md files will use the CommonMark format

Comment thread docs/content/getting-started.mdx Resolved
Comment thread docs/content/getting-started.mdx Resolved
Comment thread docs/content/getting-started.mdx Resolved
Comment thread docs/content/getting-started.mdx Outdated
```

Change your Bolt initialization code and restart the app.
After the app has started, celebrate, then interrupt the process with `^C` to stop it for now.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

<3

Comment thread docs/content/getting-started.mdx Resolved
Comment thread docs/content/getting-started.mdx Outdated

app.logger.info('⚑️ Bolt app is running!');
})();
```sh

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

sh isn't default in docusaurus i believe. if you'd be so kind, add this to the docusaurus.config.js

  themeConfig: // already exists
  ...
      prism: { // already exists
        darkTheme: prismThemes.dracula, // already exists
        additionalLanguages: ['bash'] // put this here pls
      },

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"sh" is an alias for bash syntax so you dont need to change that

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@lukegalbraithrussell Nice catch! I'm surprised bash is not a default language but it was no problem adding this in b61e880 πŸ“š

Comment thread docs/content/getting-started.mdx Resolved
Comment thread docs/content/getting-started.mdx Resolved
Comment thread docs/content/getting-started.mdx Outdated
At this point, you're running the getting started Bolt for JavaScript [app](https://github.com/slackapi/bolt-js-getting-started-app)!

Let's add a handler to send a followup message when someone clicks the button:
The defaults included leave opportunities abound, so to personalize this app let's now update the app name then respond with a kind farewell.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

this reads like taylor's docs voice and makes me nostalgic <3

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Imitation is the highest form of learning - or something somewhat similar I think - from one of the best 🀩

Comment thread docs/content/getting-started.mdx Resolved
Comment thread docs/content/getting-started.mdx Resolved
Comment thread docs/content/getting-started.mdx Resolved
Comment thread docs/content/getting-started.mdx Resolved
Comment thread docs/content/getting-started.mdx Resolved
Comment thread docs/content/getting-started.mdx Resolved
Comment thread docs/sidebars.js Outdated
Comment on lines +16 to +20
{
type: 'category',
label: 'Getting Started',
items: ['getting-started', 'building-an-app'],
},

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

one idea is to match this navbar to the docs sidebar where it's like

Bolt JS
Quickstart

---

Building an app
Slack API Calls
...

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@lukegalbraithrussell 🧠

Moving this to the top of the sidebar is a great idea! I don't mean to be biased, but this makes getting started even faster!

Comment thread docs/content/getting-started.mdx Outdated
A few tools are needed for the following steps. We recommend using the [**Slack CLI**](https://tools.slack.dev/slack-cli/) for the smoothest experience, but other options remain available.

If you don’t already have a project, let’s create a new one. Create an empty directory and initialize a new project:
<Tabs groupId="cli-or-terminal">

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

i'm tripping ove this a bit because the cli is in the terminal. is there another delineator to use?

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@lukegalbraithrussell This is so confusing to me too. I don't have a better suggestion at the moment since:

  • cli is for the Slack CLI
  • terminal is for both direct commands and the browser

IMO this difference can be understood alright in the tab titles, but that doesn't make it less confusing... πŸ€”

Comment thread docs/content/building-an-app.mdx Resolved
Comment thread docs/content/building-an-app.mdx Resolved
Comment thread docs/content/building-an-app.mdx Resolved

@mwbrooks mwbrooks left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks so much for the updates @zimeg! It's continuing to read smoother. 😎 Below are a few more suggestions after a 2nd read through. Feel free to accept, change, or reject any of the suggestions!

Comment thread docs/content/getting-started.md Resolved
Comment thread docs/content/getting-started.md Resolved
Comment thread docs/content/getting-started.md Resolved
Comment thread docs/content/getting-started.md Resolved
Comment thread docs/content/getting-started.md Outdated
});
```

Once the file is saved, restart your app to make sure the latest changes are being used, then go back to channel and say "goodbye".

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

suggestion: Since this is a Getting Started guide, I think it's best to hold the developer's hand all the way. I'd suggest that we show the command to run your app rather than having the developer figure out how to "restart your app". This would require a <TabItem> for the CLI / Terminal to show the slack run and npm start commands again and explain to open a DM with their bot and send the "goodbye" text.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@mwbrooks Once more a great call that found ef6937f! I might be wanting to avoid repetition when writing, but that doesn't translate so well to the guide πŸ˜‰

Comment thread docs/content/getting-started.md Resolved
Comment thread docs/content/getting-started.md Resolved
@zimeg
zimeg marked this pull request as ready for review June 6, 2025 00:50
@zimeg

zimeg commented Jun 6, 2025

Copy link
Copy Markdown
Member Author

@mwbrooks @lukegalbraithrussell @technically-tracy After all of these incredible reviews and suggestions and even a release of the latest Slack CLI v3.3.0 I'm feeling excited for these changes.

Following the steps of both the "Slack CLI" and "Terminal" guides have proven alright in testing, but all feedback on this or organization otherwise remains so appreciated πŸ™ ✨

Depending on how following reviews go I am hoping we can release this soon and perhaps follow up with enhancement as seen best. Hopes of a similar guide for Bolt Python and reworks of the "Building an app" page await with excitement πŸ‘Ύ

@technically-tracy

Copy link
Copy Markdown
Contributor

Hopes of a similar guide for Bolt Python and reworks of the "Building an app" page await with excitement πŸ‘Ύ

Yes definitely - I've already put this on our road map for when these changes are finalized! πŸ“

@mwbrooks mwbrooks left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

βœ… Looking good @zimeg πŸ‘πŸ» Thank you for writing the Quickstart Guide!

πŸ§ͺ I've manually tried both the Slack CLI and Terminal steps. Things work and flow well together.

πŸ‘₯ I'd suggest we wait until @lukegalbraithrussell or @technically-tracy throws an approval on this PR as well. Personally, I think this is a good first pass and the docs team can come in later to give it the consistent voice that we have on our other docs. But, I'll let them decide when the first edition is ready to ship! πŸ“š

Comment thread docs/content/building-an-app.md Resolved
Comment thread docs/content/building-an-app.md Resolved
Co-authored-by: Michael Brooks <mbrooks@slack-corp.com>
@zimeg

zimeg commented Jun 6, 2025

Copy link
Copy Markdown
Member Author

@technically-tracy Love to hear it! As always, please feel free to loop me in if you'd like πŸ“š ✨

@mwbrooks Great catches more! Thanks for testing and sharing how you read in a review πŸ‘οΈβ€πŸ—¨οΈ

I'd suggest we wait until @lukegalbraithrussell or @technically-tracy throws an approval on this PR as well.

This sounds good to me and I agree that some of word choices here might be off putting πŸ˜‰

@zimeg

zimeg commented Jun 9, 2025

Copy link
Copy Markdown
Member Author

@technically-tracy @haleychaas Apologies for this I hope polite bump, but before we merge this I was wondering if another review is possible or if other happenings related to all things documentation might be needed in shipping this?

@technically-tracy

Copy link
Copy Markdown
Contributor

@technically-tracy @haleychaas Apologies for this I hope polite bump, but before we merge this I was wondering if another review is possible or if other happenings related to all things documentation might be needed in shipping this?

Sure thing, I'll take another look today! πŸ‘€

@technically-tracy technically-tracy left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think this is looking great - thank you so much for all your hard work on this! πŸ’» ✨

@zimeg

zimeg commented Jun 10, 2025

Copy link
Copy Markdown
Member Author

@technically-tracy Such kind words! I'm glad we've brought the quickstart to this point and I think now is a good time to release it 🚒 πŸ’¨

@technically-tracy @lukegalbraithrussell @mwbrooks Thank y'all all for the thorough reviews and suggestions once more. These were incredible perspectives and I feel to be a much better writer now πŸ“š ✨

@zimeg
zimeg merged commit 73484c2 into main Jun 10, 2025
@zimeg
zimeg deleted the zimeg-docs-quick-start-cli branch June 10, 2025 19:03
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

docs M-T: Documentation work only

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants