DEV Community: Yan Ivan Evdokimov

Building Telegram Mini App with Drayman Framework

Yan Ivan Evdokimov — Thu, 02 Nov 2023 10:35:39 +0000

In this tutorial, we'll create a Telegram mini app that will allow users to match with movies. We'll use Drayman framework to create this app and go trough some major features of Telegram mini apps.

You can find the final code of this app here: tg-movie-matcher-app.

If you want to check final result, share t.me/movie_matcher_bot/app link to your friend in Telegram, launch mini app and start movie matching!

Initialization with Drayman Framework

Drayman Framework was chosen for the Telegram Mini App development because of its fast setup and unified full-stack development - combining server and client side inside components. It is also very easy to use and has a lot of features that are useful for Telegram Mini Apps.

Let's start by initializing and starting new Drayman project:



npx @drayman/framework-init@latest tg-movie-matcher-app
cd tg-movie-matcher-app
npm start

"Drayman started at http://localhost:3033" text will be printed in the console. Open this URL in your browser and you'll see Drayman welcome page:

Installing Necessary Packages

Let's install all packages we'll need for this app:

telegraf - Telegram bot API wrapper, we'll use it to work with Telegram API.
@lottiefiles/lottie-player - Lottie animation player, we'll use it to play animated stickers.
chroma-js - color manipulation library, we'll use it to generate correct color for movie rating badge.
drayman-swipi-cards - Drayman component for swiping cards.
js-confetti - confetti animation library, we'll use it to show confetti animation when user matches with a movie.
nanoid - library to generate unique IDs, we'll use it to generate unique IDs for user connections.
node-themoviedb - library to work with The Movie Database API, we'll use it to get movies data.



npm install telegraf@4.14.0 @lottiefiles/lottie-player@2.0.2 chroma-js@2.4.2 drayman-swipi-cards@2.0.9 js-confetti@0.11.0 nanoid@3.3.4 node-themoviedb@0.2.8 --save-exact

Modifying index.html, adding styles.css and assets

Some packages we've installed require scripts to be added to index.html file. Also you'll need to add telegram-web-app.js script to enable Telegram mini app mode. Here is the final index.html file:



<head>
  <meta charset="utf-8" />
  <meta http-equiv="X-UA-Compatible" content="IE=edge" />
  <title>Movie Matcher Telegram Mini App</title>
  <meta name="viewport" content="width=device-width, initial-scale=1" />
  <script src="https://telegram.org/js/telegram-web-app.js"></script>
  <script src="/drayman-framework-client.js"></script>
  <script src="/node_modules/drayman-swipi-cards/dist/swipi-cards/swipi-cards.js"></script>
  <script src="/node_modules/js-confetti/dist/js-confetti.browser.js"></script>
  <script src="/node_modules/@lottiefiles/lottie-player/dist/lottie-player.js"></script>
  <link rel="stylesheet" href="styles.css" />
</head>

As you can see, we've also added styles.css file to index.html. Don't forget to create this file in public folder next to index.html file. Copy the code from this link: styles.css and paste it to your styles.css file.

Create stickers folder in public folder and copy all stickers from this link: stickers.

Retrieving API Tokens

Now let's retrieve required tokens for our app.

Telegram token - BOT_TOKEN - create a new bot using /newbot command in BotFather and copy the token.
The Movie Database API key - MOVIE_DB_API_KEY - create a new account on The Movie Database and copy the API key from API page.

Setting up ngrok for HTTPS Tunneling

One of the Telegram requirements is that web app must be hosted on HTTPS, so we'll use ngrok to create a tunnel to our local server. Install it and after that, I suggest you to create a ngrok account to create a static domain. This way you'll be able to use the same link to your app every time you start it. Here are official instructions on how to do it: free static domain for all ngrok users.

After retrieving your domain, start ngrok tunnel:



ngrok http --domain=[static-domain] 3033

In result, you'll see something like this:

Integrating with Telegram

Copy this HTTPS link and using BotFather create a new app with /newapp command. When asked for a link to the app, paste the link you've copied from ngrok. As the short app name, you can simply type app. In result, you'll get a link to your app, something like this: t.me/movie_matcher_test_bot/app.

We can also add menu button to our bot to launch our app. To do this, go to BotFather and select your bot. Then select Bot Settings and then Menu Button, Configure menu button. Send him a link you got from ngrok. After that, you'll be able to launch your app by clicking on the menu button in your bot. However, we haven't added Telegram bot API support to our app yet, so it won't work. Let's do it now.

Adding Telegram Bot API Support

Let's integrate Telegram bot API support to our app now. Create a new Server index.ts file in src folder and add the following code to it:



import { Telegraf } from "telegraf";
import { message } from "telegraf/filters";
import express from "express";
import MovieDB from "node-themoviedb";

export const Server: DraymanServer = async ({ EventHub, app }) => {
  app.use("/node_modules", (req, res, next) =>
    express.static("node_modules")(req, res, next)
  );
  const mdb = new MovieDB(process.env.MOVIE_DB_API_KEY);
  const tgToken = process.env.BOT_TOKEN;
  const bot = new Telegraf(tgToken);
  bot.launch();
  bot.on(message(), (ctx) => {
    return ctx.replyWithHTML(`🎬 <b>Welcome to Movie Matcher!</b> 🎥

Choose your genres and years, and <b>swipe through</b> our top movie picks. 

To match with <b>friends</b> share the <b>app link</b> - t.me/movie_matcher_test_bot/app.

If you're in the mood for <b>solo</b> discovery, use the <b>menu button</b> 

When everyone <b>swipes right</b> on a movie, it's popcorn time! 

Dive in and elevate your movie nights!
`);
  });
};

In this code we've initialized Telegraf bot API wrapper and The Movie Database client. We've also added a handler for any message that will be sent to our bot and replied with a welcome message. Please make sure that you use your own link to the app in the message.

Start our app, providing required tokens as environment variables:



MOVIE_DB_API_KEY=<your-movie-db-token> BOT_TOKEN=<your-telegram-token> npm start

Now open your bot in Telegram and you'll see the welcome message:

Click "Start Matching" button you've added earlier and mini app will be launched:

We have finished main setup of our app. You can use these instructions and code above as boilerplate for your own Telegram app. But we'll continue and add more features to our Movie Matcher app.

Defining the Movie Matcher app flow

Before we start implementing our app, let's define the flow of it.

User opens the app.
- When user can't be validated, failed validation screen will be shown.
- When matching is in progress, user will see the matching screen.
- When matching is not in progress, user will see the setup screen where he can select genres and years and can see connected users. User can also click "Start" button.
- When user selectes genres or years (genres screen, years screen), "Back" button will appear and user will be able to go back to the setup screen.
- When user clicks "Start" button, and there movies with selected genres and years can be found, matching will start and user will see the matching screen.
- When user clicks "Start" button, and there are no movies with selected genres and years, user will see the no movies screen.
- When user disconnects from setup screen, connected users list will be updated.
User is in the matching screen.
- "Start" button will be hidden and "Back" button will appear.
- User can swipe left movie card to dislike the movie and swipe right to like the movie.
- When all users swipe right on the same movie, confetti animation will be shown, notifcation message will be sent from the bot and users will see the movie selected screen.
- When user made selection and there are no more movies to swipe, user will see the waiting for others screen.
- When all users made selection and haven't matched with any movie, users will see the no movie selected screen.
- When user disconnects from matching screen, likes and dislikes will be recalculated according to the new number of users.
- When user clicks "Back" button, all users will be redirected to the setup screen and matching will be stopped.
Connected users list is created based on chat from which a link to the app was sent. When a user opens the app link within the same chat, he will be added to the list.

Setting up browser commands and events

Inside index.html, change <script> tag to this:



<script>
  const jsConfetti = new JSConfetti();
  initializeDraymanFramework({
    browserCommands: (emit) => ({
      getTelegramData: () => {
        window.Telegram.WebApp.ready();
        return {
          initData: window.Telegram.WebApp.initData,
          initDataUnsafe: window.Telegram.WebApp.initDataUnsafe,
          themeParams: window.Telegram.WebApp.themeParams,
          colorScheme: window.Telegram.WebApp.colorScheme,
          viewportHeight: window.Telegram.WebApp.viewportHeight,
        };
      },
      setMainButtonParams: (params) => {
        window.Telegram.WebApp.MainButton.setParams(params);
      },
      setBackButtonVisibility: ({ visible }) => {
        visible
          ? window.Telegram.WebApp.BackButton.show()
          : window.Telegram.WebApp.BackButton.hide();
      },
      explode: async () => {
        jsConfetti.addConfetti();
      },
      events: async ({
        onMainButtonClick,
        onViewportChanged,
        onBackButtonClick,
      }) => {
        Telegram.WebApp.onEvent("mainButtonClicked", () =>
          emit(onMainButtonClick)
        );
        Telegram.WebApp.onEvent("backButtonClicked", () =>
          emit(onBackButtonClick)
        );
        Telegram.WebApp.onEvent("viewportChanged", () =>
          emit(
            onViewportChanged,
            { viewportHeight: window.Telegram.WebApp.viewportHeight },
            { debounce: 300 }
          )
        );
      },
    }),
  });
</script>

This code will initialize Drayman framework and set up browser commands and events. You can read about browser commands and events in Drayman framework docs here. Let's go through each command and event we've added:

getTelegramData - this command will return neccessary Telegram data that we'll use later to set up main component when it initializes.
setMainButtonParams - this command will set up main button parameters. We'll use it to change main button text and visibility.
setBackButtonVisibility - this command will set up back button visibility. We'll use it to show back button when user performs some actions.
explode - this command will trigger confetti animation. We'll use it to show confetti animation when users match with a movie.
events - this allows to listen for Telegram events and emit Drayman events. We'll use it to listen to main button click, back button click and viewport change events.

Validating user

First thing user will load when connecting to the app is home.tsx component. It is already created in src/components folder when you initialized Drayman framework project. It is a good place where main logic and UI of the app should be placed. Let's begin modifying this component by adding user validation because Telegram requires that user is validated before app can be used.

Create utils.ts file and place it to src folder next to index.ts file. Add the following code to it:



import crypto from "crypto";

export function verifyInitData(telegramInitData: string): boolean {
  const urlParams = new URLSearchParams(telegramInitData);
  const hash = urlParams.get("hash");
  urlParams.delete("hash");
  urlParams.sort();
  let dataCheckString = "";
  for (const [key, value] of urlParams.entries()) {
    dataCheckString += `${key}=${value}\n`;
  }
  dataCheckString = dataCheckString.slice(0, -1);
  const secret = crypto
    .createHmac("sha256", "WebAppData")
    .update(process.env.BOT_TOKEN);
  const calculatedHash = crypto
    .createHmac("sha256", secret.digest())
    .update(dataCheckString)
    .digest("hex");

  return calculatedHash === hash;
}

verifyInitData function will be used to verify user data according to Telegram requirements. Let's use it in home.tsx component. Add the following code to home.tsx file:



import { verifyInitData } from "../utils";

export const component: DraymanComponent = async ({ Browser }) => {
  const data = await Browser.getTelegramData();

  if (!verifyInitData(data.initData)) {
    await Browser.setMainButtonParams({ is_visible: false });

    return () => {
      return <h1>Invalid data</h1>;
    };
  }

  return () => {
    return <h1>Valid data</h1>;
  };
};

In this code we've added verifyInitData function to home.tsx file and used it to validate user data. If user data is invalid, we'll hide main button and show "Invalid data" text. Otherwise, we'll show "Valid data" text. We get initial data by calling Browser.getTelegramData command we defined earlier in "Setting up browser commands and events" section.

We can safely make validations here because in Drayman all components are server-side rendered and communication between browser (Browser object) and server (Server object) is done in a secure way.

Returning textual info seems boring, so let's add some stickers!

Sticker animation component

Create lottieAnimation.tsx file in src/components folder and add the following code to it:



export const component: DraymanComponent<{
  src: string;
  title?: string;
  overview?: string;
}> = async ({ props }) => {
  return async () => {
    return (
      <div class="lottie-animation">
        <lottie-player autoplay loop src={props.src}></lottie-player>
        {!!props.title && <div class="title">{props.title}</div>}
        {!!props.overview && <div class="overview">{props.overview}</div>}
      </div>
    );
  };
};

This component will be used to show Lottie animation. We'll use it to show stickers. Let's modify home.tsx component to use this component:



import { verifyInitData } from "../utils";

export const component: DraymanComponent = async ({ Browser }) => {
  const data = await Browser.getTelegramData();

  if (!verifyInitData(data.initData)) {
    await Browser.setMainButtonParams({ is_visible: false });

    return () => {
      return (
        <lottieAnimation
          src="stickers/not_found.json"
          title="Oops, Something Went Wrong!"
          overview="We couldn't verify your identity."
        />
      );
    };
  }

  return () => {
    return <h1>Valid data</h1>;
  };
};

Let's test it. Open your bot in Telegram and click "Start Matching" button. You'll see the following screen:

To test what happens when user data is invalid, change verifyInitData(data.initData) to verifyInitData(data.initData + 1) and you'll see the following screen (don't forget to return it back to verifyInitData(data.initData) after testing):

Setting up server logic

We will now program logic defined before in "Defining the Movie Matcher app flow" section. Copy this index.ts and replace your index.ts file with it. Modify your utils.ts code with this code.

Let's go through the code we've added to index.ts file. Main logic of this script is around methods a server exposes to all components:

enterStage - will be called when user enters a stage (opens app). If there are no stages with specific chat_instance, new stage will be created. If there are stages with specific chat_instance, user will be added to the stage with the same chat_instance. After this method is called, stageUpdated event will be emitted to all components within the same chat_instance group.
exitStage - will be called when user exits a stage (disconnects from app). If there are no users left in the stage, stage will be deleted. If there are some users left in the stage and they are in movie selection state, movie selection gets recalculated using updateMovieSelectionState function. We will go trough this function later. After this method is called, stageUpdated event will be emitted to all components within the same chat_instance group.
restartStage - will be called when user restarts a stage (clicks "Back" button). It simply resets stage preserving users and movie options. After this method is called, stageUpdated event will be emitted to all components within the same chat_instance group.
changeMovieOption - will be called when user changes movie option (selects genres or years). After this method is called, stageUpdated event will be emitted to all components within the same chat_instance group.
startMovieSelection - will be called when user starts movie selection (clicks "Start" button). It will search for movies using movie API and selected years and genres and switch to movie selection scene. After this method is called,stageUpdated event to all components within the same chat_instance group.
rateMovie - will be called when user rates a movie (swipes left or right). It will call updateMovieSelectionState function which determines whether movieSelected or movieNotSelected. If so, stageUpdated event to all components within the same chat_instance group.

There is also updateMovieSelectionState function which counts likes and dislikes. If it determines that movie is selected (all users matched on one movie), it sends users a notification message and emits movieSelected event. If it determines that movie is not selected (all users made their selection and no movie was matched), it emits movieNotSelected event.

Matching main component to server logic

Now as we have server logic, let's match main component to it. Copy this home.tsx and replace your home.tsx file with it. Let's go through the code we've added to home.tsx file.

We receive stage state from server by using EventHub.on('stageUpdated') event handler. Inside this handler:
- If user is on setup screen, component calls browser to show main button and sets main button text to "Start". It aslo hides back button if user was selecting genres or years.
- If user is on matching screen, component calls browser to hide main button and show back button.
- If user is on movie selected screen, component calls browser to show back button and calls explode browser command to show confetti animation.
- If user is on no movie selected screen, component calls browser to show back button.
When user initializes component (ComponentInstance.onInit), a server call enterStage method is called.
When user destroys component (ComponentInstance.onDestroy), a server call exitStage method is called.
All events from browser are also handled:
- When user clicks main button, startMovieSelection method is called.
- When user clicks back button and user is not in setup screen, restartStage method is called.
- When user changes viewport height, viewportHeight internal variable is updated (we will see how it is used later).

Based on state the component is in, it renders different screens. But now we can't launch our app because we haven't added some necessary components yet. Let's do it now.

Options button component

Add optionsButton.tsx file to src/components folder and add the following code to it:



export const component: DraymanComponent<{
  buttonLabel: string;
  selectedLabel: string;
  onSelect: () => Promise<void>;
}> = async ({ props }) => {
  return async () => {
    return (
      <div
        class="select clickable"
        onclick={async () => await props.onSelect()}
      >
        <div>{props.buttonLabel}</div>
        <div class="separator"></div>
        <div>{props.selectedLabel} ›</div>
      </div>
    );
  };
};

This component will be used to show options button. We'll use it to show genres and years buttons. It is crafted to match Telegram UI style and matches user's theme color:

Options menu component

Add optionsMenu.tsx file to src/components folder and add the following code to it:



export const component: DraymanComponent<{
  header: string;
  options: any[];
  selectedOption: any;
  viewportHeight: number;
  onSelect: (data: { value: any }) => Promise<void>;
}> = async ({ props }) => {
  return async () => {
    return (
      <div
        class="options-menu right-to-left-appear"
        style={{ height: `${props.viewportHeight - 20}px` }}
      >
        <div class="option-header">{props.header}</div>
        <div class="select-wrapper">
          {props.options.map((option) => {
            return (
              <div
                class="select clickable"
                onClick={async () => await props.onSelect({ value: option })}
              >
                <div>{option.name}</div>
                <div class="separator"></div>
                <div>{props.selectedOption.id === option.id && `✓`}</div>
              </div>
            );
          })}
        </div>
      </div>
    );
  };
};

This component will be used to show options menu. It is crafted to match Telegram UI style and matches user's theme color:

Movie card component

Add movieCard.tsx file to src/components folder and add the following code to it:



import chroma from "chroma-js";
import { genres } from "../utils";

export const component: DraymanComponent<{
  movie: any;
  viewportHeight: number;
}> = async ({ props }) => {
  const ratingScale = chroma.scale(["#e64d44", "#32b545"]).domain([0, 10]);

  return async () => {
    return (
      <div class="wrapper">
        <div
          class="fade-image"
          style={{
            "--dynamic-bg-image": `url('https://image.tmdb.org/t/p/w1280/${props.movie.backdrop_path}')`,
          }}
        >
          {!!props.movie.vote_count && (
            <div
              class="rating-circle"
              style={{
                background: ratingScale(props.movie.vote_average).hex(),
              }}
            >
              {props.movie.vote_average}
            </div>
          )}
        </div>
        <div class="title">{props.movie.title}</div>
        <div class="genre">{`${props.movie.genre_ids
          .map((x) => genres.find((xx) => xx.id == x).name)
          .join(", ")} | ${props.movie.release_date.slice(0, 4)}`}</div>
        <div
          class="overview"
          style={{ height: `${props.viewportHeight - 340}px` }}
        >
          {props.viewportHeight - 340 > 100 && (
            <div class="content">{props.movie.overview}</div>
          )}
        </div>
      </div>
    );
  };
};

This component will be used to show movie card. It is crafted to match Telegram UI style and matches user's theme color:

Movie card component has rating badge which is colored using chroma-js library based on movie rating.

Final look at the main component

Now we have everything set up. Let's check how our main component looks like.

Setup screen and year/genre selection screens

Main screen where user can select genres and years and see connected users. It matches Telegram UI style and matches user's theme color. It also has transition animation when user navigates between screens:

Matching screen and movie selected screen

Matching screen is a screen where user can swipe movie cards. If all users swipe right on the same movie, confetti animation will be shown, notifcation message will be sent from the bot and users will see the movie selected screen:

Waiting for others screen

When user made selection and there are no more movies to swipe and other users haven't made their selection yet, user will see the waiting for others screen:

No movie selected screen

When all users made selection and haven't matched with any movie, users will see the no movie selected screen:

No movies screen

When user clicks "Start" button, and there are no movies with selected genres and years, user will see the no movies screen:

Invalid data screen

When user can't be validated, failed validation screen will be shown:

Reacting to viewport height change

Some of components are using viewport height which is received from Telegram API. You can see method which returns viewport height in index.html file:



Telegram.WebApp.onEvent("viewportChanged", () =>
  emit(
    onViewportChanged,
    { viewportHeight: window.Telegram.WebApp.viewportHeight },
    { debounce: 300 }
  )
);

It is then received in home.tsx file:



onViewportChanged: async (data) => {
  viewportHeight = data.viewportHeight;
  await forceUpdate();
};

Then, it is passed to some components as a prop and height of elements is calculated based on it. This way we can make our app responsive to viewport height change and also hide or show some elements based on viewport height:

Reacting to theme change

Because all component styles are built aroun Telegram CSS variables, our app will automatically change its style when user changes theme:

Multiplayer usage

If a link to the app (in our case it is t.me/movie_matcher_test_bot/app) is sent to a chat, all users who open this link within the same chat will be added to the same group. This way, users can match with each other. If a user opens the app link in a different chat, he will be added to a different group. This way, users can match with different people in different chats:

Publishing the app

The easiest way to publish you app is to use render. While they offer a free plan, it's not ideal for Telegram apps since it suspends them after periods of inactivity. However, their first paid plan is just $7/month, which is suitable for hosting small Telegram apps without significant traffic.

Some tips of publishing your app on render:

Don't forget to add BOT_TOKEN and MOVIE_DB_API_KEY environment variables. Also you'll need to add PORT environment variable and set it to 3033:

You'll also need to use npm install as build command and npm run start as start command:

Building a real-time Todo app with Drayman, MongoDB and Tailwind CSS

Yan Ivan Evdokimov — Mon, 30 Aug 2021 19:52:12 +0000

In this guide we will build a real-time Todo app with Drayman, MongoDB and Tailwind CSS.

If you are using regular tools, you would need to create a server with endpoints, a client app using some modern framework or just vanilla JavaScript. With Drayman, however, it will be just a single script with 100 lines of code.

If you are new to Drayman, you can go to our official docs to check out how it works or to read other guides.

Prerequisites

This guide assumes that you:

have installed Drayman project locally or you are using it through new.drayman.io;
have MongoDB installed with Change Stream functionality enabled. For this guide you can create a free cloud MongoDB database here. This way you get Change Stream functionality enabled by default.

When Drayman project is ready and you have MongoDB up and running, we can start developing our Todo app by adding Tailwind CSS.

Setting up Tailwind CSS

First, you'll need to install autoprefixer and tailwindcss:

npm install -D tailwindcss@latest autoprefixer@latest

Next, generate tailwind.config.js and postcss.config.js files with this command:

npx tailwindcss init -p

Now modify tailwind.config.js file to exclude non-used CSS classes on compile:

module.exports = {
  purge: [
    "./src/**/*.tsx",
  ],
  darkMode: false,
  theme: {
    extend: {},
  },
  variants: {
    extend: {},
  },
  plugins: [],
};

Create your main CSS file at src/styles.css and append this code:

@tailwind base;
@tailwind components;
@tailwind utilities;

The final step is to modify public/index.html file to include the generated CSS file. Drayman will generate it to the public/styles.css file:

<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8" />
    <meta http-equiv="X-UA-Compatible" content="IE=edge" />
    <title>Drayman Framework</title>
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <script src="/drayman-framework-client.js"></script>
    <link rel="stylesheet" href="styles.css" />
  </head>

  <body>
    <drayman-element component="home"></drayman-element>

    <script>
      initializeDraymanFramework();
    </script>
  </body>
</html>

Creating a Todo app

We will start by adding basic UI using Tailwind CSS classes and then improve our solution to include real-time functionality and MongoDB support.

Adding basic UI

Paste this code inside src/components.home.tsx:

export const component: DraymanComponent = async () => {
  return async () => {
    return (
      <div class="flex justify-center items-center">
        <div class="flex flex-col pt-8 lg:w-2/5 sm:w-3/5 w-11/12 gap-4">
          <div class="flex gap-2">
            <input
              placeholder="New Todo"
              class="shadow appearance-none border rounded w-full py-2 px-3 text-gray-700 leading-tight focus:outline-none focus:shadow-outline"
            />
            <button
              class={`bg-blue-500 text-white font-bold py-2 px-4 rounded`}
            >
              Save
            </button>
          </div>
          <div class="flex items-center gap-2">
            <div
              class={`flex flex-grow items-center gap-2 bg-gray-200 p-2 rounded cursor-pointer`}
            >
              <input class="flex-none" type="checkbox" />
              <div class="flex-grow">Grab a coffee</div>
            </div>
            <button class="flex-none bg-red-500 hover:bg-red-700 text-white font-bold py-2 px-4 rounded">
              Delete
            </button>
          </div>
        </div>
      </div>
    );
  };
};

If Tailwind CSS was successfully initialized, you should see this result in your browser:

Adding MongoDB support

For this guide we will use Change Stream functionality of MongoDB to make our Todo list work in real-time. This way if something gets changed in the database, our application will reflect these changes. Let's modify our src/components/home.tsx component and see in detail what is happening inside our script:

import { MongoClient, ObjectId } from "mongodb";

interface Todo {
  _id: ObjectId;
  text: string;
  done: boolean;
}

export const component: DraymanComponent = async ({
  forceUpdate,
  ComponentInstance,
}) => {
  const uri = "YOUR_MONGODB_CONNECTION_STRING";
  const client = new MongoClient(uri);
  await client.connect();
  const db = client.db("todo");
  const todoListCollection = db.collection<Todo>("list");

  let todos = await todoListCollection.find().toArray();

  todoListCollection.watch().on("change", async (x) => {
    if (x.operationType === "insert") {
      todos.push(x.fullDocument as Todo);
    } else if (x.operationType === "update") {
      todos = todos.map((todo) => {
        if (todo._id.equals(x.documentKey._id)) {
          return { ...todo, ...x.updateDescription.updatedFields };
        }
        return todo;
      });
    } else if (x.operationType === "delete") {
      todos = todos.filter((todo) => !todo._id.equals(x.documentKey._id));
    }
    await forceUpdate();
  });

  ComponentInstance.onDestroy = async () => {
    await client.close();
  };

  return async () => {
    return (
      <div class="flex justify-center items-center">
        <div class="flex flex-col pt-8 lg:w-2/5 sm:w-3/5 w-11/12 gap-4">
          <div class="flex gap-2">
            <input
              placeholder="New Todo"
              class="shadow appearance-none border rounded w-full py-2 px-3 text-gray-700 leading-tight focus:outline-none focus:shadow-outline"
            />
            <button class="bg-blue-500 text-white font-bold py-2 px-4 rounded">
              Save
            </button>
          </div>
          {todos.map((x) => (
            <div class="flex items-center gap-2">
              <div
                class={`flex flex-grow items-center gap-2 ${
                  x.done ? `bg-green-200 line-through` : `bg-gray-200`
                } p-2 rounded cursor-pointer`}
              >
                <input class="flex-none" checked={x.done} type="checkbox" />
                <div class="flex-grow">{x.text}</div>
              </div>
              <button class="flex-none bg-red-500 hover:bg-red-700 text-white font-bold py-2 px-4 rounded">
                Delete
              </button>
            </div>
          ))}
        </div>
      </div>
    );
  };
};

First, we have added a connection to our database (don't forget to change YOUR_MONGODB_CONNECTION_STRING to your actual connection string). Then we made the initial fetch of our Todo list by converting it to an array - let todos = await todoListCollection.find().toArray();.

Then we added real-time functionality by watching for changes to database todoListCollection.watch():

on insert a Todo will be pushed to todos array;
on update a specific Todo from todos array will be updated;
on delete a specific Todo from todos array will be deleted.

The component will reflect all these changes because we also call the forceUpdate function - if any change gets caught, the component will re-render itself.

Finally, we are using the onDestroy lifecycle method to close the connection to the database when a component instance gets destroyed.

We also have made changes to our UI by mapping through todos array and rendering each Todo and changing CSS classes dynamically when a Todo is done.

As a result, any change made inside the database (I am using TablePlus for this), gets reflected inside our component:

Our final step will be to make the input field and buttons work as expected.

Adding functionality to UI elements

We will start by modifying the <input> element:

// ...
let newTodo: string;
// ...

return async () => {
  return (
    // ...
    <input
      placeholder="New Todo"
      class="shadow appearance-none border rounded w-full py-2 px-3 text-gray-700 leading-tight focus:outline-none focus:shadow-outline"
      value={newTodo}
      oninput={async ({ value }) => {
        newTodo = value;
        await forceUpdate();
      }}
    />
    // ...
  );
};

The variable newTodo was introduced. When the user types in something, the oninput event gets triggered that saves the input value to the newTodo variable thus providing a single source of truth - the input's value will always be inside newTodo.

Let's now modify the <button>Save</button> element:

<button
  class={`bg-blue-500 text-white font-bold py-2 px-4 rounded ${
    newTodo ? `hover:bg-blue-700` : `opacity-50 cursor-not-allowed`
  }`}
  disabled={!newTodo}
  onclick={async () => {
    await todoListCollection.insertOne({ text: newTodo, done: false });
    newTodo = null;
  }}
>
  Save
</button>

We have modified class and disabled attributes to appear disabled when there is no input by the user (newTodo is empty). When the user clicks a button, onclick gets triggered and a new Todo gets inserted into the database. We also don't need to call forceUpdate here because it already was managed before when watching for database changes. Now we can input something, click the button and the result will appear in the browser:

Our final step will be to modify todos list mapping:

todos.map((x) => (
  <div class="flex items-center gap-2">
    <div
      onclick={async () => {
        await todoListCollection.updateOne(
          { _id: x._id },
          { $set: { done: !x.done } }
        );
      }}
      class={`flex flex-grow items-center gap-2 ${
        x.done ? `bg-green-200 line-through` : `bg-gray-200`
      } p-2 rounded cursor-pointer`}
    >
      <input class="flex-none" checked={x.done} type="checkbox" />
      <div class="flex-grow">{x.text}</div>
    </div>
    <button
      class="flex-none bg-red-500 hover:bg-red-700 text-white font-bold py-2 px-4 rounded"
      onclick={async () => {
        await todoListCollection.deleteOne({ _id: x._id });
      }}
    >
      Delete
    </button>
  </div>
));

Here we have added the onclick event handler for <div> to mark a Todo done or undone and the onclick event handler for <button>Delete</button> to delete a Todo from the database when it is clicked.

Our component is now complete and you can open a page with this component in multiple tabs to check real-time functionality:

Final component script

import { MongoClient, ObjectId } from "mongodb";

interface Todo {
  _id: ObjectId;
  text: string;
  done: boolean;
}

export const component: DraymanComponent = async ({
  forceUpdate,
  ComponentInstance,
}) => {
  const uri = "YOUR_MONGODB_CONNECTION_STRING";
  const client = new MongoClient(uri);
  await client.connect();
  const db = client.db("todo");
  const todoListCollection = db.collection<Todo>("list");

  let todos = await todoListCollection.find().toArray();
  let newTodo: string;

  todoListCollection.watch().on("change", async (x) => {
    if (x.operationType === "insert") {
      todos.push(x.fullDocument as Todo);
    } else if (x.operationType === "update") {
      todos = todos.map((todo) => {
        if (todo._id.equals(x.documentKey._id)) {
          return { ...todo, ...x.updateDescription.updatedFields };
        }
        return todo;
      });
    } else if (x.operationType === "delete") {
      todos = todos.filter((todo) => !todo._id.equals(x.documentKey._id));
    }
    await forceUpdate();
  });

  ComponentInstance.onDestroy = async () => {
    await client.close();
  };

  return async () => {
    return (
      <div class="flex justify-center items-center">
        <div class="flex flex-col pt-8 lg:w-2/5 sm:w-3/5 w-11/12 gap-4">
          <div class="flex gap-2">
            <input
              placeholder="New Todo"
              class="shadow appearance-none border rounded w-full py-2 px-3 text-gray-700 leading-tight focus:outline-none focus:shadow-outline"
              value={newTodo}
              oninput={async ({ value }) => {
                newTodo = value;
                await forceUpdate();
              }}
            />
            <button
              class={`bg-blue-500 text-white font-bold py-2 px-4 rounded ${
                newTodo ? `hover:bg-blue-700` : `opacity-50 cursor-not-allowed`
              }`}
              disabled={!newTodo}
              onclick={async () => {
                await todoListCollection.insertOne({
                  text: newTodo,
                  done: false,
                });
                newTodo = null;
              }}
            >
              Save
            </button>
          </div>
          {todos.map((x) => (
            <div class="flex items-center gap-2">
              <div
                onclick={async () => {
                  await todoListCollection.updateOne(
                    { _id: x._id },
                    { $set: { done: !x.done } }
                  );
                }}
                class={`flex flex-grow items-center gap-2 ${
                  x.done ? `bg-green-200 line-through` : `bg-gray-200`
                } p-2 rounded cursor-pointer`}
              >
                <input class="flex-none" checked={x.done} type="checkbox" />
                <div class="flex-grow">{x.text}</div>
              </div>
              <button
                class="flex-none bg-red-500 hover:bg-red-700 text-white font-bold py-2 px-4 rounded"
                onclick={async () => {
                  await todoListCollection.deleteOne({ _id: x._id });
                }}
              >
                Delete
              </button>
            </div>
          ))}
        </div>
      </div>
    );
  };
};

Conclusion

We have created a real-time Todo app with Drayman, MongoDB and Tailwind CSS in just 100 lines of code, inside a single script.

If this felt interesting to you, visit the official docs to deep-dive into Drayman framework!

Getting started with Drayman

Yan Ivan Evdokimov — Tue, 17 Aug 2021 15:54:56 +0000

Drayman is a server-side component framework that allows you to use any available HTML element, web component or custom Drayman third-party component together with server-side code in a single script.

With Drayman, the browser only renders what the user should see - all logic and calculations happen server-side and UI is written using JSX syntax.

The best way to show Drayman capabilities is to create something with it. So let's get started.

File viewer component

Let's build a component that allows the user to select a file from the file system and view it's contents.

First, you need to install Drayman. It can be done by running these commands:

npx @drayman/framework-init@latest my-app
cd my-app
npm start

The website will be available at http://localhost:3033.

If you don't want install anything, you can always try Drayman inside CodeSandbox by visiting new.drayman.io.

Initial component template

Go to src/components/home.tsx and replace its contents with this code:

export const component: DraymanComponent = async () => {
  return async () => {
    return (
      <>
        <p>Select a file to view it directly from file system</p>
        <select></select>
        <br />
        <pre></pre>
      </>
    );
  };
};

You will see an initial skeleton of our component. Further <select> will be used to show available files and <pre> will show contents of the selected file.

Filling select with options

Because Drayman runs a component server-side, we can use any Node.js library. In our case we will use the fs module.

Let's read file names from the project root directory and fill <select> options with them:

import { promises as fs } from "fs";

export const component: DraymanComponent = async () => {
  const files = (await fs.readdir("./")).filter((x) => x.includes("."));

  return async () => {
    return (
      <>
        <p>Select a file to view it directly from file system</p>
        <select>
          {files.map((fileName) => (
            <option>{fileName}</option>
          ))}
        </select>
        <br />
        <pre></pre>
      </>
    );
  };
};

Right now our component is only showing some elements without any interactivity. Our next step will be to add it.

Reacting to user actions

We need to remember which file the user has selected to show its contents. It can be done by using the onchange event attribute and attaching a function that will be executed server-side. We also need to add the value attribute to each option so that select would know which option was selected.

Let's also add the fs.readFile function inside the <pre> tag so that Drayman would read file contents during re-render. We won't show the pre until a file is actually selected:

import { promises as fs } from "fs";

export const component: DraymanComponent = async () => {
  const files = (await fs.readdir("./")).filter((x) => x.includes("."));
  let selectedFile;

  return async () => {
    return (
      <>
        <p>Select a file to view it directly from file system</p>
        <select
          onchange={async ({ value }) => {
            selectedFile = value;
          }}
        >
          {files.map((fileName) => (
            <option value={fileName}>{fileName}</option>
          ))}
        </select>
        <br />
        {selectedFile && <pre>{await fs.readFile(selectedFile, "utf-8")}</pre>}
      </>
    );
  };
};

If you make a selection from the dropdown, you will see that nothing happens on the page - file contents don't appear. That is because with Drayman you must strictly tell when a component needs to be re-rendered. It can be done by using a special helper function forceUpdate.

Import it and add to the onchange event after the selected file was saved:

import { promises as fs } from "fs";

export const component: DraymanComponent = async ({ forceUpdate, }) => {
  const files = (await fs.readdir("./")).filter((x) => x.includes("."));
  let selectedFile;

  return async () => {
    return (
      <>
        <p>Select a file to view it directly from file system</p>
        <select
          onchange={async ({ value }) => {
            selectedFile = value;
            await forceUpdate();
          }}
        >
          {files.map((fileName) => (
            <option value={fileName}>{fileName}</option>
          ))}
        </select>
        <br />
        {selectedFile && <pre>{await fs.readFile(selectedFile, "utf-8")}</pre>}
      </>
    );
  };
};

Now our component is complete and file contents are shown on select:

Conclusion

We have built a component that combines server-side logic and client-side view in a single script.

If this felt interesting to you, visit the official docs to deep-dive into Drayman framework!