Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/yhatt/jsx-slack

Build JSON object for Slack Block Kit surfaces from JSX
https://github.com/yhatt/jsx-slack

slack slack-block-kit slack-blockkit

Last synced: about 2 months ago
JSON representation

Build JSON object for Slack Block Kit surfaces from JSX

Awesome Lists containing this project

README 

        


  

    


    jsx-slack

  




[![CircleCI](https://img.shields.io/circleci/project/github/yhatt/jsx-slack/main.svg?logo=circleci)][circleci]

[![Codecov](https://img.shields.io/codecov/c/github/yhatt/jsx-slack/main.svg?logo=codecov)](https://codecov.io/gh/yhatt/jsx-slack)

[![npm](https://img.shields.io/npm/v/jsx-slack.svg?logo=npm)][npm]

[![LICENSE](https://img.shields.io/github/license/yhatt/jsx-slack.svg)][license]



[circleci]: https://circleci.com/gh/yhatt/jsx-slack/

[npm]: https://npm.im/jsx-slack

[license]: ./LICENSE



Build JSON object for [Slack][slack] [block kit] surfaces from [JSX].



[slack]: https://slack.com

[jsx]: https://reactjs.org/docs/introducing-jsx.html

[react]: https://reactjs.org/

[block kit]: https://api.slack.com/block-kit

[block kit builder]: https://api.slack.com/tools/block-kit-builder





  

    

  

  


  

    

  




:point_right: **[Try our REPL demo](https://jsx-slack.netlify.app/)** in https://jsx-slack.netlify.app/.



### Features



- **[Block Kit as components](docs/jsx-components-for-block-kit.md)** - Build contents for any surfaces by composing components for Block Kit with JSX.

- **[HTML-like formatting](docs/html-like-formatting.md)** - Keep a readability by using well-known elements.



See **[references](#references)** to dive into jsx-slack deeply.



## Motivation



When developing Slack-integrated app, continuous maintenance of the rich contents is a difficult task. A team member must read and write JSON with deep knowledge about specifications of payload for Slack API.



We believe JSX-based template well-known in front-end development would enhance a developer experience of Slack app.



## Project goal



A project goal is creating an interface to compose contents for Slack with keeping code maintainability by using [JSX].



jsx-slack would allow composing contents with simple and predictable HTML-like markup. It helps in understanding the structure of complex contents and interactions.



## Install



### [Node.js](https://nodejs.org/)



We require Node.js >= 14. If you are using TypeScript, we also require TS >= 3.7.



```bash

# npm

npm install --save jsx-slack

```



```bash

# yarn

yarn add jsx-slack

```



Now you can begin to write the code with [`jsxslack` template literal tag](#quick-start-template-literal). Furthermore, [setting up JSX transpiler](docs/how-to-setup-jsx-transpiler.md) would make the best development experience.



### [Deno](https://deno.land/) ([Slack CLI](https://api.slack.com/future/tools/cli))



We also have Deno support. If you are using Deno v1.28 and later, [you can import jsx-slack through npm directly](https://deno.land/manual/node/npm_specifiers).



```typescript

// `jsxslack` template literal tag

import { jsxslack } from 'npm:jsx-slack@6'

```



```typescript

// JSX transpilation

/** @jsxImportSource npm:jsx-slack@6 */

import { Blocks, Section } from 'npm:jsx-slack@6'

```



> **Note**

> Alternatively [you also can import jsx-slack through esm.sh CDN](https://deno.land/[email protected]/node/cdns#esmsh): [`https://esm.sh/jsx-slack@6`](https://esm.sh/jsx-slack@6)



## Usage



### Quick start: Template literal



Do you hate troublesome setting up for JSX? All right. We provide **`jsxslack`** tagged template literal to build blocks _right out of the box_.



It allows the template syntax almost same as JSX, powered by [HTM (Hyperscript Tagged Markup)](https://github.com/developit/htm). Setting for transpiler and importing built-in components are not required.



This is a simple example of the template function just to say hello to someone.



```javascript

import { jsxslack } from 'jsx-slack'



export const exampleBlock = ({ name }) => jsxslack`

  

    

      Hello, ${name}!

    

  

`

```



### [JSX Transpiler](docs/how-to-setup-jsx-transpiler.md)



When you want to use jsx-slack with JSX transpiler, you have to set up to use our runtime for JSX.



**[▶︎ How to setup JSX transpiler](docs/how-to-setup-jsx-transpiler.md)** (Babel / TypeScript / Deno)



```jsx

/** @jsxImportSource jsx-slack */

import { Blocks, Section } from 'jsx-slack'



export const exampleBlock = ({ name }) => (

  

    

      Hello, {name}!

    

  

)

```



### Use template in Slack API



After than, just use created template in Slack API. We are using the official Node SDK [`@slack/web-api`](https://github.com/slackapi/node-slack-sdk) in this example. [See also Slack guide.](https://slackapi.github.io/node-slack-sdk/web_api)



```javascript

import { WebClient } from '@slack/web-api'

import { exampleBlock } from './example.jsx'



const web = new WebClient(process.env.SLACK_TOKEN)



web.chat

  .postMessage({

    channel: 'C1234567890',

    blocks: exampleBlock({ name: 'Yuki Hattori' }),

  })

  .then((res) => console.log('Message sent: ', res.ts))

  .catch(console.error)

```



It would post a simple Slack message like this:



[][block-kit-builder-example]



[][block-kit-builder-example]



[block-kit-builder-example]: https://jsx-slack.netlify.app/#bkb:jsx:eJyzccrJT84utuNSULAJTk0uyczPA7EVFDxSc3LydRRskuwiS7MzFTwSS0ryizJt9JPsFEFq9eGKbfShRgAAVeQWug==



## Block Kit as components



Slack has recommended to use **[Block Kit]** for building tempting messages and modals.



By using jsx-slack, you can build a template with piling up Block Kit blocks by JSX. It is feeling like using components in React or Vue.



### [For messaging](https://jsx-slack.netlify.app/)



```jsx



  

    
Enjoy building blocks!


    


      

        jsx-slack

      

      


      Build JSON for Slack Block Kit from JSX

    


    yhatt

  

  

    Maintained by Yuki Hattori

    yhatt

  

  

  

    GitHub

    npm

  



```



### [For modal](https://jsx-slack.netlify.app/#modal)



```jsx



  

    


      It's my first modal! :sunglasses:

    


    
jsx-slack also has supported Slack Modals.


  

  



  

  



  



  

  



```



### [For home tab](https://jsx-slack.netlify.app/#home)



```jsx



  

  Welcome back to my home! :house_with_garden:

  

  What's next?

  

    

      

        See assigned tickets :ticket:

        

          Check your tickets to start your work.

        

      

      

        Remind a task later :memo:

        

          I'll remember a task for you.

        

      

      

        Start pomodoro timer :tomato:

        

          Get focused on your time, with tomato!

        

      

    

    

      Start working

    

  



```



### References



- **[How to setup JSX transpiler](docs/how-to-setup-jsx-transpiler.md)**

- **[JSX components for Block Kit](docs/jsx-components-for-block-kit.md)**

  - [Block containers](docs/block-containers.md)

  - [Layout blocks](docs/layout-blocks.md)

  - [Block elements](docs/block-elements.md)

    - [Interactive components](docs/block-elements.md#user-content-interactive-components)

    - [Composition objects](docs/block-elements.md#user-content-composition-objects)

    - [Input components](docs/block-elements.md#user-content-input-components)



* **[HTML-like formatting](docs/html-like-formatting.md)**

* **[About escape and exact mode](docs/about-escape-and-exact-mode.md)**



- **[Highlight of v2](docs/highlight/v2.md)**



### Examples by use cases



Ported from templates for [Block Kit Builder].



#### [Message](https://api.slack.com/tools/block-kit-builder?mode=message&template=1)



- [Approval (New device request)](https://jsx-slack.netlify.app/#messagingApprovalNewDevice)

- [Approval (Time Off request)](https://jsx-slack.netlify.app/#messagingApprovalTimeOff)

- [Notification](https://jsx-slack.netlify.app/#messagingNotification)

- [Onboarding (Taskbot)](https://jsx-slack.netlify.app/#messagingOnboardingTaskbot)

- [Onboarding (Onboarding App)](https://jsx-slack.netlify.app/#messagingOnboardingApp)

- [Poll](https://jsx-slack.netlify.app/#messagingPoll)

- [Search Results (TripAgent)](https://jsx-slack.netlify.app/#messagingSearchResultsTripAgent)

- [Search Results (FileCard Agent)](https://jsx-slack.netlify.app/#messagingSearchResultsFileCard)

- [Newsletter](https://jsx-slack.netlify.app/#messagingNewsletter)



#### [Modal](https://api.slack.com/tools/block-kit-builder?mode=modal&template=1)



- [Poll](https://jsx-slack.netlify.app/#modalPoll)

- [Search Results](https://jsx-slack.netlify.app/#modalSearchResults)

- [Settings (App menu)](https://jsx-slack.netlify.app/#modalSettingsAppMenu)

- [Settings (Notification settings)](https://jsx-slack.netlify.app/#modalSettingsNotification)

- [List of information (Your itinerary)](https://jsx-slack.netlify.app/#modalListOfInformationYourItinerary)

- [List of information (Ticket app)](https://jsx-slack.netlify.app/#modalListOfInformationTicketApp)



#### [App Home](https://api.slack.com/tools/block-kit-builder?mode=appHome&template=1)



- [Project Tracker](https://jsx-slack.netlify.app/#appHomeProjectTracker)

- [Calendar](https://jsx-slack.netlify.app/#appHomeCalendar)

- [Expense App](https://jsx-slack.netlify.app/#appHomeExpenseApp)

- [Todo App](https://jsx-slack.netlify.app/#appHomeTodoApp)



## Fragments



[As like as React](https://reactjs.org/docs/fragments.html), jsx-slack provides `` (``) component for higher-order component (HOC) consited of multiple blocks or elements.



For example, you can define the custom block by grouping some blocks with `` if you were using JSX transpiler.



Let's say about defining `` custom block that is consisted by `` and ``.



```javascript

import { Fragment, Section, Divider } from 'jsx-slack'



const Heading = ({ children }) => (

  

    

      {children}

    

    

  

)

```



Now the defined block can use in `` as like as the other blocks:



```jsx



  

    jsx-slack custom block :sunglasses:

  

  Let's build your block.



```



[][custom-header-block]



[][custom-header-block]



[custom-header-block]: https://jsx-slack.netlify.app/#bkb:jsx:eJxVjrEOgzAQQ3e-4jYmejs6Zag6duMLSIjQlZRIOEHt3xcaBphsD8-23EN0E0xFJJ13SeO8-y3ZoptT88KnQejdRC4jxTfZnRJWQy3yPIYe8GgLyH9S-FQnD1118AvxZejpUw2yWcNA35iXUns7ocLHvx9tITN_



### Short syntax for fragments



Babel transpiler and TypeScript 4 can use [the short syntax `<>>` for fragments](https://reactjs.org/docs/fragments.html#short-syntax). See [how to setup JSX transpiler](docs/how-to-setup-jsx-transpiler.md).



```javascript

import { Section, Divider } from 'jsx-slack'



const Heading = ({ children }) => (

  <>

    

      {children}

    

    

  >

)

```



### In the case of template literal tag



`jsxslack` template literal tag has [built-in fragments support](https://github.com/developit/htm#improvements-over-jsx) so `` does not have to use.



```javascript

// Heading.js

import { jsxslack } from 'jsx-slack'



export const Heading = ({ children }) => jsxslack`

  

    ${children}

  

  

`

```



A defined component may use in `jsxslack` tag as below:



```javascript

import { jsxslack } from 'jsx-slack'

import { Heading } from './Heading'



console.log(jsxslack`

  

    <${Heading}>

      jsx-slack custom block :sunglasses:

    />

    Let's build your block.

  

`)

```



Please notice to a usage of component that has a bit different syntax from JSX.



## Frequently questions



### Is jsx-slack the state of production-ready?



Of course! In our workspace, we are developing Slack custom app for internal with providing great UX powered by jsx-slack. And some apps published in Slack app directory are also using jsx-slack in production.



Do you have an app with jsx-slack in public? Please let us know your great app!



### Can I develop Slack app _only using jsx-slack_?



No. jsx-slack just generates JSON for Slack API. You have to send generated message and control interaction with Slack by yourself.



Don't worry; you can use jsx-slack together with helpful libraries: [Bolt framework for JavaScript](https://slack.dev/bolt) (recommended), [Slack Node SDK](https://slack.dev/node-slack-sdk/), and third-party library (e.g. [BotKit](https://botkit.ai/), [Bottender](https://bottender.js.org/)).



### Is this working based on [React]?



No, jsx-slack has very similar API to React but is not based on React, because our library doesn't need to use some features provided by React: incremental updates, event handling, reference to the rendered JSON, and component class.



Nevertheless, jsx-slack can use React's methodology (composition of components) through JSX and the basic JavaScript function. In addition, we can follow up rapidly-evolving Slack Block Kit by keeping the smallest requirements without depending on React.



FYI there are some projects based on React ([react-reconciler](https://github.com/facebook/react/tree/master/packages/react-reconciler)) to generate or manage Slack interactions: [phelia](https://github.com/maxchehab/phelia) framework, [react-chat-renderer](https://github.com/asynchronous-dev/react-chat-renderer) (< v0.1.0), and [rebot](https://github.com/bradennapier/rebot). You should use them if you want to use React ecosystem.



### How do you spell this library?



"jsx-slack" with all in lowercase. It is neither of "JSX-Slack" nor "JSX Slack".



## Similar projects



- [phelia](https://github.com/maxchehab/phelia) - :zap: A reactive Slack application framework. 

- [react-chat-renderer](https://github.com/asynchronous-dev/react-chat-renderer) - React renderer implementation for building rich Slack messages using JSX 

- [slack-blockx](https://github.com/kevin940726/slack-blockx) - jsx for Slack block-kit 



## Author



- @yhatt Yuki Hattori ([@yhatt](https://github.com/yhatt)) - Maintainer



## License



[MIT License](LICENSE)