Forem: Evertvdw

Part 6: Styling the chat widget

Evertvdw — Thu, 02 Jun 2022 18:32:17 +0000

The code for this part can be found here

In this part of the series I am going to focus on adding some styling to our chat widget, so that we can differentiate between send and received messages and that it will scroll down the chat when receiving a new message.

Add Quasar

As I'm a fan of Quasar and I want to be able to use those components familiar to me inside the chat-widget, I am first going to focus on adding Quasar to the widget.

For this perticular use case it will probably be overkill and leaner/cleaner to design the needed components from scratch, I want to be able to create larger embeddable application later on, and then it will be of more use.

There is a section in the Quasar docs that is a good starting point here.

Let's add the dependencies first:



yarn workspace widget add quasar @quasar/extras
yarn workspace widget add -D @quasar/vite-plugin

Then inside packages/widget/vite.config.ts:



// Add at the top
import { quasar, transformAssetUrls } from '@quasar/vite-plugin';

// Inside defineConfig, change plugins to
plugins: [
  vue({ customElement: true, template: { transformAssetUrls } }),
  quasar(),
],

Then the tricky part, we have to call app.use in order to install Quasar in a vite project. However, we are using defineCustomElement inside packages/widget/src/main.ts, which does not normally come with an app instance, so any installed plugins will not work as expected.

Quasar provides $q which can be accessed in the template as well as through a useQuasar composable. When just adding app.use(Quasar, { plugins: {} }) to our file, and leaving the rest as is, $q will not be provided to the app. So to make this work I had to come up with a workaround. Here is the new full packages/widget/src/main.ts:



import App from './App.vue';
import { createPinia } from 'pinia';
import { createApp, defineCustomElement, h, getCurrentInstance } from 'vue';
import { Quasar } from 'quasar';
import io from 'socket.io-client';
import { useSocketStore } from './stores/socket';

const app = createApp(App);

app.use(createPinia());
app.use(Quasar, { plugins: {} });

const URL = import.meta.env.VITE_SOCKET_URL;
const socketStore = useSocketStore();
const socket = io(URL, {
  auth: {
    clientID: socketStore.id,
  },
});

app.provide('socket', socket);

const chatWidget = defineCustomElement({
  render: () => h(App),
  styles: App.styles,
  props: {},
  setup() {
    const instance = getCurrentInstance();
    Object.assign(instance?.appContext, app._context);
    // eslint-disable-next-line @typescript-eslint/ban-ts-comment
    // @ts-expect-error
    Object.assign(instance?.provides, app._context.provides);
  },
});

customElements.define('chat-widget', chatWidget);

As you can see, instead of doing defineCustomElement(App) we now define an intermediate component to which we set the proper appContext and provides so that our installed plugins work as expected.

I also moved the initialization of the socket from packages/widget/src/App.vue into this file, and providing that to the app as well. That means we can do const socket = inject('socket') inside other components to get access to the socket instance everywhere 😀

The App.styles contains the compiled styles from the <style></style> part of App.vue. We need to pass this along for any styling we write in there to work as expected.

One limitation to defining a web component with vue is that only the style blocks from our root component are included. Any child components that have style blocks will be skipped. So we have to resort to using .scss files and importing those inside App.vue for everything to work correctly.

Inside packages/widget/src/App.vue we can update and remove some lines:



// Remove 
import io from 'socket.io-client';

const socket = io(URL, {
  auth: {
    clientID: socketStore.id,
  },
});
const URL = import.meta.env.VITE_SOCKET_URL;

// Add
import { Socket } from 'socket.io-client';
import { inject } from 'vue';

const socket = inject('socket') as Socket;

With that in place we should still have a functioning widget, and be able to use quasar components inside of it.

Using a self defined name

We now generate a random name when using the widget. For my use case I want to pass the name of the widget user as a property to the widget because I am going to place the widget on sites where a logged in user is already present, so I can fetch that username and pass it as a property to the widget.

In order to do that we have to change a few things. Inside packages/widget/index.html I am going to pass my name as a property to the widget: <chat-widget name="Evert" />.

Inside packages/widget/src/App.vue we need to make a few changes as well:



// Define the props we are receiving
const props = defineProps<{
  name: string;
}>();

// Use it inside addClient
const addClient: AddClient = {
  name: props.name,
}

// Remove these lines
if (!socketStore.name) {
  socketStore.setName();
}

Updating the socket store

Inside the socket store we currently generate and store the random name, we can remove this. In packages/widget/src/stores/socket.ts:

Remove the faker import
Remove the name property from the state
Remove the setName action

Moving the chat window to a separate component

To keep things organized I am going to create a file packages/widget/src/components/ChatMessages.vue with the following content:



<template>
  <div class="chat-messages">
    <div class="chat-messages-top"></div>
    <div class="chat-messages-content">
      <div ref="chatContainer" class="chat-messages-container">
        <div
          v-for="(message, index) in socketStore.messages"
          :key="index"
          :class="{
            'message-send': message.type === MessageType.Client,
            'message-received': message.type === MessageType.Admin,
          }"
        >
          <div class="message-content">
            {{ message.message }}
            <span class="message-timestamp">
              {{ date.formatDate(message.time, 'hh:mm') }}
            </span>
          </div>
        </div>
      </div>
    </div>
    <div
      class="chat-messages-bottom row q-px-lg q-py-sm items-start justify-between"
    >
      <q-input
        v-model="text"
        borderless
        dense
        placeholder="Write a reply..."
        autogrow
        class="fit"
        @keydown.enter.prevent.exact="sendMessage"
      />
    </div>
  </div>
</template>

<script setup lang="ts">
import { Socket } from 'socket.io-client';
import { Message, MessageType } from 'types';
import { inject, nextTick, ref, watch } from 'vue';
import { useSocketStore } from '../stores/socket';
import { date } from 'quasar';

const text = ref('');
const socket = inject('socket') as Socket;
const socketStore = useSocketStore();
const chatContainer = ref<HTMLDivElement | null>(null);

function scrollToBottom() {
  nextTick(() => {
    chatContainer.value?.scrollIntoView({ block: 'end' });
  });
}

watch(
  socketStore.messages,
  () => {
    scrollToBottom();
  },
  {
    immediate: true,
  }
);

function sendMessage() {
  const message: Message = {
    time: Date.now(),
    message: text.value,
    type: MessageType.Client,
  };
  socket.emit('client:message', message);
  text.value = '';
}
</script>

Try to see if you can understand what is going on in this component, it should be pretty self explanatory. Feel free to ask questions in the comments if a particular thing is unclear.

We will define the styling for this component inside separate scss files, so lets create that as well.

Create a packages/widget/src/css/messages.scss file with the following scss:



$chat-message-spacing: 12px;
$chat-send-color: rgb(224, 224, 224);
$chat-received-color: rgb(129, 199, 132);

.chat-messages {
  margin-bottom: 16px;
  width: 300px;
  border-radius: 4px;
  overflow: hidden;
  box-shadow: 0px 10px 15px -5px rgba(0, 0, 0, 0.1);
  border: 1px solid rgba(232, 232, 232, 0.653);

  &-top {
    height: 48px;
    background-color: $primary;
    border-bottom: 1px solid rgb(219, 219, 219);
  }

  &-content {
    height: min(70vh, 300px);
    background-color: rgb(247, 247, 247);
    position: relative;
    overflow-y: auto;
    overflow-x: hidden;
  }

  &-container {
    display: flex;
    flex-direction: column;
    position: relative;
    justify-content: flex-end;
    min-height: 100%;
    padding-bottom: $chat-message-spacing;

    .message-send + .message-received,
    .message-received:first-child {
      margin-top: $chat-message-spacing;

      .message-content {
        border-top-left-radius: 0;

        &:after {
          content: '';
          position: absolute;
          top: 0;
          left: -8px;
          width: 0;
          height: 0;
          border-right: none;
          border-left: 8px solid transparent;
          border-top: 8px solid $chat-received-color;
        }
      }
    }

    .message-received + .message-send,
    .message-send:first-child {
      margin-top: $chat-message-spacing;

      .message-content {
        border-top-right-radius: 0;

        &:after {
          content: '';
          position: absolute;
          top: 0;
          right: -8px;
          width: 0;
          height: 0;
          border-left: none;
          border-right: 8px solid transparent;
          border-top: 8px solid $chat-send-color;
        }
      }
    }
  }

  &-bottom {
    border-top: 1px solid rgb(219, 219, 219);
  }
}

.message {
  &-content {
    padding: 8px;
    padding-right: 64px;
    display: inline-block;
    border-radius: 4px;
    position: relative;
    filter: drop-shadow(0px 1px 2px rgba(0, 0, 0, 0.3));
    font-size: 14px;
  }

  &-send {
    margin: 1px 16px 1px 32px;
  }

  &-send &-content {
    background-color: $chat-send-color;
    float: right;
  }

  &-received {
    margin: 1px 32px 1px 16px;
  }

  &-received &-content {
    background-color: $chat-received-color;
  }

  &-timestamp {
    font-size: 11px;
    position: absolute;
    right: 4px;
    bottom: 4px;
    line-height: 14px;
    color: #3f3f3f;
    text-align: end;
  }
}

I am not going to explain how the css works here, fiddle with it if you are curious 😀 Any questions are of course welcome in the comment section.

As we will create more styling files later one we are going to create a packages/widget/src/css/app.scss in which we import this (and any future) file:



@import './messages.scss';

Now all that is left is using everything we have so far inside packages/widget/src/App.vue:
First the new style block:



<style lang="scss">
@import url('quasar/dist/quasar.prod.css');
@import './css/app.scss';

.chat-widget {
  --q-primary: #1976d2;
  --q-secondary: #26a69a;
  --q-accent: #9c27b0;
  --q-positive: #21ba45;
  --q-negative: #c10015;
  --q-info: #31ccec;
  --q-warning: #f2c037;
  --q-dark: #1d1d1d;
  --q-dark-page: #121212;
  --q-transition-duration: 0.3s;
  --animate-duration: 0.3s;
  --animate-delay: 0.3s;
  --animate-repeat: 1;
  --q-size-xs: 0;
  --q-size-sm: 600px;
  --q-size-md: 1024px;
  --q-size-lg: 1440px;
  --q-size-xl: 1920px;

  *,
  :after,
  :before {
    box-sizing: border-box;
  }

  font-family: -apple-system, Helvetica Neue, Helvetica, Arial, sans-serif;

  position: fixed;
  bottom: 16px;
  left: 16px;
}
</style>

In here we have to import the quasar production css and define some css variables quasar uses manually to make everything work correctly inside a web component.

We could also import the quasar css inside packages/widget/src/main.ts however, that would apply those styles to the root document that the web component resides in. Which means that any global styling will effect not only our web component but also the site it is used in. Which we do not want of course 😅

Other changes to packages/widget/src/App.vue:
The template block will become:



<template>
  <div class="chat-widget">
    <ChatMessages v-if="!mainStore.collapsed" />
    <q-btn
      size="lg"
      round
      color="primary"
      :icon="matChat"
      @click="mainStore.toggleCollapsed"
    />
  </div>
</template>

And inside the script block:



// Add
import { matChat } from '@quasar/extras/material-icons';
import { useMainStore } from './stores/main';
import ChatMessages from './components/ChatMessages.vue';

const mainStore = useMainStore();

// Remove
const text = ref('');

The only thing left then is to add the collapsed state inside packages/widget/src/stores/main.ts:



// Add state property

collapsed: true,

// Add action

toggleCollapsed() {

  this.collapsed = !this.collapsed;

},

Wrapping up

Here is the end result in action:

You can view the admin panel of the latest version here (login with admin@admin.nl and password admin.

The chat widget can be seen here

Going further I will add more functionality to this setup, like:

Show when someone is typing
Display admin avatar and name in the widget
Do not start with the chat window right away, but provide an in-between screen so that user can start a chat explicitely
Display info messages when a message is send on a new day

See you then!🙋

Part 5: Getting ready for deployment & deploy

Evertvdw — Wed, 18 May 2022 22:13:54 +0000

The whole code for this part can be found here

Let's get into the exciting stuff this part! I always find that deploying an app you are working on makes it more 'real'. It's also a good check to see if your setup works, as deployment will most likely require some tweaks. (Spoiler alert, it will😅)

Getting ready for deployment

Section git diff (as my commits were a mess 😅) here

Deploying the app means that we need to build every part and get the build files somewhere on a server and run the main process there. In my case the main file that will be run is the packages/server/index.ts file. This means that we have to serve up our portal and widget package from there.

Serving local files

To do this we have to add some code to this file:

// At the top:
import serveStatic from 'serve-static';
import history from 'connect-history-api-fallback';

// After app.use(cookieParser()):
app.use(history());
app.use(serveStatic('./../../dist/widget'));
app.use(serveStatic('./../../dist/portal'));

Also add the dependencies necessary for this:

yarn workspace server add connect-history-api-fallback
yarn workspace server add -D @types/connect-history-api-fallback

The history() function is needed to run our Vue app in history mode, meaning that you can navigate directly to /clients and get served the entry index.html no matter the initial url.

This will be refined later on. Also we're introducing a bug when we add it like this, which we will tackle later. Can you spot what will go wrong? Hint: the order of code is important 😇

Next, finding out your types sharing solution does not work well

Always fun to find out that some solution you chose is not really a solution at all, but hey, that happens! To me at least but I figure to all developers 🙂

Turns out that by specifying the project rootDir in the tsconfig.json will also affect where the files will be placed when building the project. I did some fiddling around with this and eventually came to the conclusion that moving the types to a separate 4th package in the project should work. This however was unknown territory for me, but I managed to get it to work.

So let's get to it! First off we create a packages/types/package.json file:

{
  "name": "types",
  "version": "0.0.0",
  "license": "MIT",
  "scripts": {
    "build": "tsc --build",
    "start": "tsc -w"
  },
  "main": "dist/index.js",
  "types": "dist/index.d.ts",
  "dependencies": {},
  "devDependencies": {
    "typescript": "^4.6.4"
  }
}

and a packages/types/tsconfig.json:

{
  "compilerOptions": {
    /* Basic Options */
    "declaration": true,
    "declarationMap": true,
    "sourceMap": true,
    "composite": true,
    "outDir": "./dist",
    "rootDir": "./src",
    "target": "esnext",
    "module": "esnext"
  },
  "include": ["./src"]
}

And adding { "path": "./packages/types" } to the references in the root tsconfig.json.

The types.ts file that was initially at the root of our project will move to packages/types/src/index.ts. That is basically it.

What we setup now is a separate package that will export some types that we can import in other projects by importing from types where this name is taken from the name key inside the package.json of that package. To make this work we do have to make sure that our types package is build, otherwise our IDE will complain.

To do that we are going to add and change some scripts in our root package.json:

// add
"types": "cd ./packages/types && yarn start && cd ../..",
"types:build": "cd ./packages/types && yarn build && cd ../.."

// change
"dev": "npm-run-all --parallel types portal server widget",
"build": "npm-run-all types:build portal:build widget:build

Updating all types imports

Next we have to update our project everywhere we import from <relative_path>/types, this is needed in the following files:

packages/portal/src/components/ClientChat.vue
packages/portal/src/stores/client.ts
packages/server/types.ts
packages/widget/src/App.vue
packages/widget/src/stores/socket.ts

Also update the tsconfig.json of the other packages to remove the rootDir property and add "references": [{ "path": "../types" }] as a new property after the include array. Finally remove ../../types.ts from the include array in each file.

Checking if we can build

Let's run yarn run build to see what happens when all packages are build. You should see that a dist directory is created with 3 folders and a packages.json. If this is the first time you build the types packages you will see that some files inside a packages/types/dist folder are created. We need to commit those to the repository as well. But we do want to ignore those when linting, so in our .eslintignore we change /dist to dist. To ignore dist folders anywhere, not just at the root level.

We can run our server now by running:

node dist/server/index.js

Which we will add as a script inside the root package.json as well for convenience: "start": "node dist/server/index.js",.

Getting ready for deployment - environment variables

Git diff for this section here

Our build server should run now but going to localhost:5000 will return Cannot GET / as our paths defined inside packages/server/index.ts are only correct for development 🤷. In fact it would make sense to only add this when we are running a build app, so a good use case to add environment variables to make some thing configurable based on development versus production, where with production I mean running the dist/server/index.js file produced by yarn run build.

Setting up environment variables

Two of our projects are Vite projects which will pick up .env files by default as documented here. I found out about this figuring out the best way to add environment variables, so I learned something new this part🎉.

We can create .env.<production|development> files which will be picked up by vite automatically at either build or development.

We will create the variable VITE_SOCKET_URL as that will not be the same during development and production.

Inside packages/portal/src/boot/socket.ts remove the URL declaration and instead do:

const socket = io(import.meta.env.VITE_SOCKET_URL, {
  autoConnect: false,
});

Do the same for packages/widget/src/App.vue.

At this point typescript will complain so we have to inform it that we will supply this variable by adding to packages/widget/src/env.d.ts and packages/portal/src/env.d.ts:

interface ImportMetaEnv {
  readonly VITE_SOCKET_URL: string;
  // more env variables...
}

interface ImportMeta {
  readonly env: ImportMetaEnv;
}

And also add /// <reference types="vite/client" /> at the top of packages/portal/src/env.d.ts.

Providing the variables for widget and portal

Vite will pickup .env.development files when in development mode, so lets create packages/portal/.env.development and packages/widget/.env.development:

VITE_SOCKET_URL=http://localhost:5000

To make VSCode highlight the files a bit better, add to .vscode/settings.json:

"files.associations": {
  "*.env.*": "env"
}

Small improvement to package.json scripts

Along the way trying stuff out I found out that you can pass a cwd argument to yarn commands that will execute them in a specific working directory, eliminating the need to do cd <path> and cd ../.. in every script. So instead of:

cd ./packages/server && yarn start && cd ../..

We can do:

yarn --cwd ./packages/server start

Much better in my opinion so I changed all the scripts to use this pattern. Also I updated every script to call start when in development and build for building. This means changing the scripts inside the package.json of two packages.

In packages/widget/package.json rename the dev script to start, and update packages/portal/package.json scripts to contain:

"start": "quasar dev",
"build": "quasar build"

Environment variables for the server

There is an important distinction between environment variables in the server compared to the widget and portal. The portal and the widget will run client side (in the browser) and any environment variables used there are read when the project is build, so they are compiled to static variables by rollup in our case. The server will run in nodeJS, which means that the variables mentioned there are not compiled at build time. They will need to be present at runtime. So at the place we start our index.js the environment variables have to be present.

For the server we will have three variables:

APP_ENV - to signal to our code if we run in production or development
PORT - the port our server will listen at
JWT_SECRET - the secret that is used to create our jwt tokens

Define them for typescript inside packages/server/env.d.ts:

declare namespace NodeJS {
  interface ProcessEnv {
    PORT: string;
    JWT_SECRET: string;
    APP_ENV: 'development' | 'production';
  }
}

For development we can use defaults (in the code) for these variables, so that means we only will have to define them when we are deploying the app.

Let's set defaults, inside packages/server/index.ts we read and use the PORT variable:

// add these lines
import path from 'path';

const port = process.env.PORT || 5000;

// change
server.listen(port, () => {
  console.log(
    `Server started on port ${port} at ${new Date().toLocaleString()}`
  );
});

We also serve the portal and widget only when APP_ENV is equal to production:

if (process.env.APP_ENV === 'production') {
  app.use(serveStatic(path.join(__dirname, './../../dist/widget')));
  app.use(serveStatic(path.join(__dirname, './../../dist/portal')));
}

Finally we want to prevent that we run in production with the default JWT_SECRET if we somehow fail to provide it, so lets add a check for it, inside the try-catch before we call server.listen:

if (process.env.APP_ENV === 'production' && !process.env.JWT_SECRET) {
  throw new Error('Should provide JWT_SECRET env variable');
}

Next update the packages/server/middleware/socket.ts and packages/server/routes/auth.ts to use the JWT_SECRET if present by inserting process.env.JWT_SECRET || after secret =.

Deploying an Heroku app

If you do not have an account at Heroku, create one here. Also install the Heroku CLI, which we will use to deploy our app.

In your Heroku dashboard create a new app. Go to the Settings tab and to Config vars, in here we will create two variables for now:

JWT_SECRET - set this one to some long string
APP_ENV - set this to production

Doing the deploy

Deploying to Heroku is done by pushing code from a certain branch to a repository that comes with your heroku app. First login with the Heroku CLI if you have not done so yet:

heroku login

After that we need to add our heroku app as an extra remote in git we can push to. We can do that by running:

heroku git:remote -a <name-of-your-app>

Fill in the name of your app that you have chosen upon creating it, in my case that was embeddable-chat-widget-part-5. Once that is run you can check that a remote was added by running git remote -v, and you should see a remote called origin and a remote called heroku.

To push our code to heroku and start the deploy you need to run:

git push heroku main
// or
git push heroku <other-local-branch>:main

and that will start the deploy, which will output in the command line.

Heroku will only deploy stuff you push to it's main branch or master branch. That is why you have to do :main if you want to push a different branch to a certain heroku app.

Fixes and stuff

If you have coded along and pushed the branch so far to heroku you will probably have seen a build error, and if not atleast things don't work as expected when opening the app. There are a couple of fixes needed, which I will highlight in the next sections.

Production .env file

When we were setting up environment variables we skipped defining them for production. We need to create two files packages/portal/.env.production and packages/widget/.env.production with the following content:

VITE_SOCKET_URL=https://<your-app-name>.herokuapp.com

Where the URL should be the url of your heroku app.

Node engine

We currently specify in our root packages.json inside the engines property: "node": ">= 14" and Heroku will look at this to determine which node version to use when building our app. This will cause it to take the latest version available which is a non-lts version, which for some reason did not work for me. So change this to "node": "16.x", which will take the last version of version 16.

Using absolute path when serving portal and widget

Inside packages/server/index.ts we have to update the lines that use serveStatic

// Add at top
import path from 'path';

// Update
app.use(serveStatic(path.join(__dirname, './../../dist/widget')));
app.use(serveStatic(path.join(__dirname, './../../dist/portal')));

Don't hardcode the login URL

Inside packages/portal/src/stores/auth.ts I forgot to update the login urls, which still harcode to localhost:5000, which will not work once deployed of course. We created an environment variable called VITE_SOCKET_URL for this.

// Replace login url to
`${import.meta.env.VITE_SOCKET_URL}/auth/login`

// Replace refresh_token url to
`${import.meta.env.VITE_SOCKET_URL}/auth/refresh_token`

Widget package missing headers

When we get the widget package to use on a different site we have to send some headers along to allow different origins to use this package, so in packages/server/index.ts update:

app.use(serveStatic(path.join(__dirname, './../../dist/widget')));
// becomes
app.use(
  serveStatic(path.join(__dirname, './../../dist/widget'), {
    setHeaders: (res) => {
      res.header('Cross-Origin-Resource-Policy', 'cross-origin');
    },
  })
);

Allow codepen origins

I want to demonstrate our setup later by importing the widget inside a codepen and using it there, to make that work we have to add 'https://cdpn.io' to our allowed cors origins inside packages/server/index.ts. Add it to both origin: [...] arrays in that file.

Fixing the bug mentioned earlier

Before I mentioned that by serving the portal and the widget caused a bug, and it has to do with the order of the code. When setting up express routes like /auth/<something> the order of setup matters. By using history mode and calling app.use(history()) it sets up a catch all listener for GET requests that will serve up the index.html. By placing this before the app.use('/auth') call, the GET routes inside of it will be intercepted by the history catch all listener.

So we have to move our serveStatic lines after the app.use('/auth'), in order to make it work as expected. I also placed the history() call inside the if statement, as that is only necessary when deploying.

// Move this
if (process.env.APP_ENV === 'production') {
  app.use(history());
  app.use(
    serveStatic(path.join(__dirname, './../../dist/widget'), {
      setHeaders: (res) => {
        res.header('Cross-Origin-Resource-Policy', 'cross-origin');
      },
    })
  );

Wrapping up

After these changes you can push the changes to the heroku branch as before and it will redeploy.

Here is a video of it in action:

You can check out my deployed app here. I made a test user account that you can login with:

email: admin@admin.nl
password: admin

There is also a codepen here which loads in the widget and displays it. This is done by including a script on the page with the source https://embeddable-chat-widget-part-5.herokuapp.com/widget.umd.js and then placing a <chat-widget/> element in the HTML, easy peasy👌

See you in the next part!

Part 4: Portal login & authorization of socket connection

Evertvdw — Sun, 15 May 2022 17:52:30 +0000

The code for this part can be found here

Welcome to part four of this series where we are setting up an embeddable chat widget. In this part we are going to add authentication to the portal. I want to:

Login when accessing the portal
Secure the communication between portal <> server

Currently anyone who sends the right events to the server can be added to the admin room and receive all chat communication with all clients. This is what we are going to prevent by adding a login to the portal and creating a JWT (JSON web token) to authenticate ourselves when communicating with the server.

Setting up stuff at the server end

Commit for this section is here

I will be implementing the OAuth 2.0 protocol with refresh and access tokens as described here. An alternative would be to use an existing auth provider, but I wanted to learn more about it by doing it myself. If you can spot any errors in my implementation, please let me know :)

Storing the password in the database

Just kidding, never do that!🤨

But when someone at the portal side will login we have to verify that they provided the correct password. In order to do that we are going to store the hashed version of the password in our database.

We are creating the admins based on a seed file in packages/server/database/admins.ts, in here we need to add that information. In order to make our life a bit easier when adding future admins, I created a little CLI tool that will hash a password for us.

First run:

yarn add -W -D bcrypt yargs

And the create a file hash-password.js at the root of our project:

const yargs = require('yargs');
const bcrypt = require('bcrypt');

const options = yargs
  .usage('Usage: -p <password>')
  .option('p', {
    alias: 'password',
    describe: 'Password to hash',
    type: 'string',
    demandOption: true,
  }).argv;

bcrypt.hash(options.p, 10, function (err, hash) {
  console.log(hash);
});

What this does it take a password and output the hash of it to the console. We can use it like: node ./hash-password.js -p <password_to_hash>.

Before we add a password to our seed we have to update the Admin type interface in types.ts and add:

email: string;
hash: string;

Then hash a password using the tool and the add that hash and an email to the admins array in packages/server/database/admins.ts. In the example code you can see my hash, but you have to use your own that you generated with a password of your choice.

Adding packages to the server package

We will need to install some extra packages to secure our server:

yarn workspace server add bcrypt cookie-parser helmet jsonwebtoken
yarn workspace server add -D @types/bcrypt @types/cookie-parser @types/jsonwebtoken

Refactoring and adding socket middleware

To add authentication to our socket connection we can add another middleware function. As this will be our second one (the first is the creation of a clientID) it is a good time to put them together in a separate file to keep things organized. Create a packages/server/middleware/socket.ts file with the following content:

import { Server } from 'socket.io';
import jwt from 'jsonwebtoken';
import crypto from 'crypto';
import { Database } from '../types';

const secret = 'alksjd;kl3lkrjtokensfklhklkef';

export default function (io: Server, db: Database) {
  // Verify jwt token on socket connection
  io.use((socket, next) => {
    if (
      socket.handshake.query &&
      socket.handshake.query.token &&
      typeof socket.handshake.query.token === 'string'
    ) {
      jwt.verify(
        socket.handshake.query.token,
        secret,
        // eslint-disable-next-line @typescript-eslint/no-explicit-any
        function (err, admin: any) {
          if (err) {
            console.log('[DEBUG] socket middleware jwt error');
            return next(new Error('Authentication error'));
          }
          socket.admin = admin;
        }
      );
    }
    next();
  });

  // Socket middleware to set a clientID
  const randomId = () => crypto.randomBytes(8).toString('hex');
  io.use((socket, next) => {
    const clientID = socket.handshake.auth.clientID;
    if (clientID) {
      const client = db.clients.findOne({ id: clientID });
      if (client) {
        socket.clientID = clientID;
        return next();
      }
    }
    socket.clientID = randomId();
    next();
  });
}

Let's break it down:

We export a function that can be called to register the middleware
To create a JWT we have to provide a secret. The idea of a secret is that it is secret and that you don't commit this into version control. We are going to change this in part 5 when we will use environment variables.
When a socket connection is setup it will do a handshake and you can send some custom information along with that handshake when you initialize the connection at the client side (either portal or widget). In our case from the portal side we are going to pass an access token, which we will verify in this middleware. - If the verification is successful we set the admin object on the socket object and continue. If it is not we call next with an Error that will cause the connection setup to abort.
Notice that in case a token is not provided we just call next(). Our widget users will not use authentication so we have to do this in order for those connections to be setup and not aborted.

As we are adding an extra property on socket typescript will complain, so in packages/server/types.ts add
admin?: { email: Admin['email'] }; to the Socket interface, below the already defined clientID.

Adding auth routes

Our server is a Socket.IO server but also a regular Express app. That means that we can easily add endpoints, and we need to create two endpoints

A /login to accept a email and password and return an accessToken
A /refresh_token to accept a refreshToken (set in a cookie) and return a new accessToken if the refreshToken is still valid.

We create a separate file for this, called packages/server/routes/auth.ts:

import express from 'express';
import { Database } from '../types';
import bcrypt from 'bcrypt';
import jwt from 'jsonwebtoken';

const router = express.Router();
const secret = 'alksjd;kl3lkrjtokensfklhklkef';

export default function (db: Database) {
  router.post('/login', async (req, res) => {
    console.log('POST /login', [req.body.email]);
    if (!req.body.email || !req.body.password) {
      return res.sendStatus(400);
    }

    const admin = db.admins.findOne({ email: req.body.email });
    if (!admin) return res.sendStatus(401);

    const match = await bcrypt.compare(req.body.password, admin.hash);
    if (match) {
      const token = jwt.sign({ email: admin.email }, secret, {
        expiresIn: '1h',
      });
      const refreshToken = jwt.sign({ email: admin.email }, secret, {
        expiresIn: '30d',
      });
      res.cookie('jwt-refresh', refreshToken, {
        httpOnly: true,
        secure: true,
        maxAge: 30 * 24 * 60 * 60 * 1000, // Equivalent of 30 days
      });
      return res.send(token);
    } else {
      return res.sendStatus(401);
    }
  });

  router.get('/refresh_token', async (req, res) => {
    const refreshToken = req.cookies['jwt-refresh'];
    if (!refreshToken) {
      res.sendStatus(401);
    } else {
      jwt.verify(
        refreshToken,
        secret,
        // eslint-disable-next-line @typescript-eslint/no-explicit-any
        function (err: any, admin: any) {
          if (err) {
            console.log('[DEBUG] jwt.verify error', err);
            res.sendStatus(401);
          } else {
            console.log('[DEBUG] jwt verify success: ', [admin.email]);
            const token = jwt.sign({ email: admin.email }, secret, {
              expiresIn: '1h',
            });
            res.send(token);
          }
        }
      );
    }
  });

  return router;
}

Quick breakdown of the two endpoints, first /login:

Return a 400 status (Bad request) if no email or password is provided
Check if an admin with that email exists in the DB, if not return 401 (Unauthorized)
Compare the stored hash with the hashed password, if the do not match return 401
If they do match, create an accessToken and a refreshToken with different expiration times. The accessToken is shortlived, and the refreshToken has a longer lifetime.
The refreshToken is set as a cookie on the response, which will set it in the browser on the client side, which will be passed along when making requests to the /refresh_token endpoint.
The accessToken is returned as text.
The httpOnly flag means that it is a cookie that cannot be accessed or modified by client side javascript.

Second, the /refresh_token endpoint:

This endpoint is used by the client when the accessToken has expired, instead of logging out when that happens the client requests another accessToken by calling this endpoint.
We get the token from the jwt-refresh cookie, if it is not present return 401
If the token is verified return a new accessToken

Put everything together in the server entry

Inside the packages/server/index.ts file we need to use the created endpoints and middleware.

First the imports at the top:

// add:
import authRoutes from './routes/auth';
import socketMiddleware from './middleware/socket';
import cookieParser from 'cookie-parser';
import helmet from 'helmet';

// remove:
import crypto from 'crypto';

Then some express app plugins:

// add:
app.use(helmet());
app.use(
  cors({
    origin: [/http:\/\/localhost:\d*/],
    credentials: true,
  })
);
app.use(express.json());
app.use(cookieParser());

// remove: 
app.use(cors());

Before calling the adminHandler add an if (socket.admin) statement to only add those socket handlers if there is an admin connected. Remember we set that admin property in the jwt socket middleware, so only authenticated admins have that property set.

Remove the clientID middleware in this file, we moved that to our middlewares file.

Lastly, after the db = await initDB(); call, add the following:

socketMiddleware(io, db);
app.use('/auth', authRoutes(db));

Adding the login screen in the portal

Commit for this section can be found here

The last section of this part is to add the login screen. This again will be minimally styled, as we are going to postpone styling everything until a later stage.

Adding an auth store

We start by adding an auth store which will contain login related stuff, create a file called packages/portal/src/stores/auth.ts:

import { defineStore } from 'pinia';
import { socket } from 'src/boot/socket';

export enum AuthStatus {
  init,
  loading,
  success,
  error,
}

export const useAuthStore = defineStore('auth', {
  state: () => ({
    token: localStorage.getItem('jwt') || '',
    status: AuthStatus.init,
    urlAfterLogin: '/clients',
  }),
  getters: {
    isAuthenticated: (state) => state.status === AuthStatus.success,
  },
  actions: {
    async login(payload: { email: string; password: string }) {
      this.status = AuthStatus.loading;
      const response = await fetch('http://localhost:5000/auth/login', {
        method: 'POST',
        credentials: 'include',
        headers: {
          'Content-Type': 'application/json',
        },
        body: JSON.stringify(payload),
      });
      console.log('[DEBUG] login response', response.ok, response.status);
      if (response.ok) {
        this.status = AuthStatus.success;

        const token = await response.text();
        localStorage.setItem('jwt', token);
        this.token = token;
        socket.io.opts.query = { token };

        console.log('[DEBUG]: login response', token);
      } else this.status = AuthStatus.error;
    },
    async refresh_token() {
      const response = await fetch('http://localhost:5000/auth/refresh_token', {
        credentials: 'include',
      });
      if (response.ok) {
        const token = await response.text();
        localStorage.setItem('jwt', token);
        this.token = token;
        socket.io.opts.query = { token };
        console.log('[DEBUG] refresh_token response', token);
        return true;
      } else {
        return false;
      }
    },
    logout() {
      this.status = AuthStatus.init;
      localStorage.removeItem('jwt');
      this.token = '';
    },
  },
});

Quick breakdown of this file:

We define a login status and an accessToken which is stored inside localStorage and retreived from it if present at startup.
The urlAfterLogin will be used if you enter the portal app at a route /something but you need to be authorized to access that route. In that case we can set the url that we redirect to after logging in successfully.
In the login action we call our created /login endpoint. Notice we use credentials: 'include' in the fetch options, this is necessary so the server can send back a cookie. If this is not set the cookie that the server sets does not get set client side. Took me a while to figure that one out 😅
At socket.io.opts.query we set the token that will be read by the jwt socket middleware and which is used to authenticate the socket connection.
In the refresh_token action we return true or false, which we can use elsewhere to know if the refresh was successful.

Adding an auth boot file

Currently we connect to our socket server automatically when we create the socket object by calling io(). Now we first have to login before we setup the connection so instead we are going to disable auto connect inside packages/portal/src/boot/socket.ts:

const socket = io(URL, {
  autoConnect: false,
});

Now we need to handle connecting elsewhere, we are going to create a packages/portal/src/boot/auth.ts file for that:

import { boot } from 'quasar/wrappers';
import { AuthStatus, useAuthStore } from 'src/stores/auth';
import { socket } from 'src/boot/socket';

export default boot(({ store, router }) => {
  const authStore = useAuthStore(store);

  if (authStore.token) {
    authStore.status = AuthStatus.success;
    socket.io.opts.query = { token: authStore.token };
    socket.connect();
  }

  socket.on('connect_error', async (err) => {
    console.log('[DEBUG] connect_error', err);
    if (err.message === 'Authentication error') {
      const refresh = await authStore.refresh_token();
      if (!refresh) {
        authStore.logout();
        router.push('/');
        socket.disconnect();
      } else {
        socket.connect();
      }
    }
  });

  router.beforeEach((to, from, next) => {
    if (to.matched.some((record) => record.meta.auth)) {
      if (!authStore.isAuthenticated) {
        authStore.urlAfterLogin = to.fullPath;
        next({
          path: '/',
        });
      } else {
        next();
      }
    }
    if (to.fullPath === '/' && authStore.isAuthenticated)
      next({ path: '/clients' });
    next();
  });
});

Breakdown of this file:

This file is run when we initialize our app. If a token is present we use that token to connect to the socket server.
We listen for the connect_error event on the socket. If it returns an authentication error, we assume our token has expired and try to refresh it. If that succeeds we connect again, if it does not we logout and disconnect completely from the socket server.
In this file we also register a Vue router beforeEach handler, which will run, as the name suggests, before each router navigation. It will check if we try to access a protected route (signalled by a meta property called auth), and redirect us if we do that unauthenticated.

We have to register this boot file inside packages/portal/quasar.config.js to use it, by adding it to the boot files array: boot: ['socket', 'auth'].

Vue files for the login

The login page will look a bit different from our other pages so I will use a separate layout for that page. Create a packages/portal/src/layouts/LoginLayout.vue file:

<template>
  <q-layout view="lHh Lpr lFf">
    <q-header>
      <q-toolbar>
        <q-toolbar-title> Portal login </q-toolbar-title>
      </q-toolbar>
    </q-header>

    <q-page-container>
      <router-view />
    </q-page-container>
  </q-layout>
</template>

In there we will have a page packages/portal/src/pages/LoginPage.vue, which will be a simple form with two inputs and a submit button:

<template>
  <q-page class="row justify-center items-center">
    <q-form class="q-gutter-md" @submit="onSubmit" @reset="onReset">
      <q-input v-model="email" filled label="Emailadress" />
      <q-input v-model="password" filled type="password" label="Password" />
      <div>
        <q-btn
          label="Login"
          type="submit"
          color="primary"
          :loading="authStore.status === AuthStatus.loading"
        />
      </div>
    </q-form>
  </q-page>
</template>

<script setup lang="ts">
import { ref } from 'vue';
import { useAuthStore, AuthStatus } from 'src/stores/auth';
import { useRouter } from 'vue-router';
import { socket } from 'src/boot/socket';

const email = ref('');
const password = ref('');
const authStore = useAuthStore();
const router = useRouter();

async function onSubmit() {
  await authStore.login({ email: email.value, password: password.value });
  socket.connect();
  if (authStore.isAuthenticated) router.push(authStore.urlAfterLogin);
  onReset();
}

function onReset() {
  email.value = '';
  password.value = '';
}
</script>

Inside our packages/portal/src/router/routes.ts file we have to use these components. Our apps login page will be at / and the clients page will move to /clients. So our two routes will be:

{
  path: '/',
  component: () => import('layouts/LoginLayout.vue'),
  children: [{ path: '', component: () => import('pages/LoginPage.vue') }],
},
{
  path: '/clients',
  meta: {
    auth: true,
  },
  component: () => import('layouts/MainLayout.vue'),
  children: [{ path: '', component: () => import('pages/IndexPage.vue') }],
},

As a final thing we are going to add a logout button to our app, so that we can test logging/logging out a bit easier. Lets add this to the packages/portal/src/layouts/MainLayout.vue file.

In the template section inside the q-toolbar element:

<q-btn outline @click="logout"> Logout </q-btn>

In the script block:

import { useAuthStore } from 'src/stores/auth';
import { socket } from 'src/boot/socket';
import { useRouter } from 'vue-router';

const authStore = useAuthStore();
const router = useRouter();

function logout() {
  authStore.logout();
  socket.disconnect();
  router.push('/');
}

Wrapping up

That is it for this part!🚀 In the next one we are going to see this deployed to Heroku and be able to create an codepen and load in our webcomponent in there, see you then!👋

Part 3: Adding a database

Evertvdw — Thu, 05 May 2022 19:53:22 +0000

The full code for this part is in branch part-3, found here

In the previous parts we setup our project folders and connected everything together. In this part we will focus on the server package mostly, by adding a database to persist data when the server restarts or is updated.

What database to use?

I went back and forth on this one, as the technology you use has to match your goals for the project. I primarily wanted something simple, easy to deploy and with little extra setup necessary for development.

In the end I want to be able to host the whole project (server/portal/widget) in a single VM somewhere, without having to worry about external connections, databases and such. With that in mind I was looking at some sort of in-memory database with persistence to a local file of some sorts which would be loaded back in upon restarts/updates.

I did want something performant so that I would (hopefully) not run into issues when there are around 100-ish clients connected at the same time. I looked at low-db for a while but did not like that it would JSON.stringify my whole database on every change, which could become a problem when it becomes to big.

So instead I went with lokijs even though I find the documentation of it quite horrible, I have used it before and it works without issues and has lots of features. And I thought it would also be good to show how I use it so others don't have to figure that our on their own 😇

Don't agree with me?

That is of course perfectly fine! In the end it does not matter what database technology you use, feel free to implement it using MongoDB or Firebase whatever you are comfortable with. The only thing that you would need to change is the database initialization and how to save/update/fetch something out of there.

Let's code!

The changes in this section are summarized in this commit

To keep things separated I will put all database related stuff inside the /packages/server/database folder. As the /packages/server/admins.ts we use seed into our database logically belong there, I moved that file into that folder, changing the top line to: import { Admin } from './../types';.

Installing lokijs

To install lokijs run the following commands:

yarn workspace server add lokijs
yarn workspace server add -D @types/lokijs

Initializing the database

I create a packages/server/database/database.ts file with the following:

import { join } from 'path';
import adminSeed from './admins';
import loki from 'lokijs';
import { Admin, Client, Database } from '../types';
const lsfa = require('lokijs/src/loki-fs-structured-adapter');

export default function initDB() {
  return new Promise<Database>((resolve) => {
    const adapter = new lsfa();
    const db = new loki(join(__dirname, './server.db'), {
      adapter,
      autoload: true,
      autosave: true,
      autosaveInterval: 4000,
      autoloadCallback: () => {
        db.removeCollection('admins');
        const admins = db.addCollection<Admin>('admins', {
          autoupdate: true,
        });
        adminSeed.forEach((admin) => {
          admins.insertOne(admin);
        });
        let clients = db.getCollection<Client>('clients');
        if (clients === null) {
          clients = db.addCollection<Client>('clients', {
            autoupdate: true,
            indices: ['id'],
          });
        }
        resolve({ admins, clients });
      },
    });
  });
}

Quick breakdown of what is happening:

Lokijs uses so called adapters to handle the persistence to files. We use the fastest and most scalable adapter called the fs-structured-adapter. You can read more about it here
We export a initDB function which will setup the database and return a promise, resolving when it is done.
Inside the setup we provide some seed data to our database, we repopulate the admins from our seed file every time. Also we check if a collection for our clients exist, and if not, we create one. Collections are logically separated parts of the database, which also get persisted inside their own file.
On both collections we use the autoupdate setting, that will persist changes made to the collection automatically. By default you would have to call .update() manually to make sure the data in memory is also saved to file.

Inside our .gitignore file we have to add /packages/server/database/*.db* to make sure our created database files are ignored by git.

Updating `packages/server/index.ts`

Now we have to use our just created initDB function inside our main entry file. First remove the current database initialization:

const db: Database ... ❌
import admins from ./admins; ❌

And add import initDB from './database/database'; at the top somewhere.

Replace the server.listen call with:

let db: Database;
(async function () {
  try {
    db = await initDB();
    server.listen(5000, () => {
      console.log(
        `Server started on port ${5000} at ${new Date().toLocaleString()}`
      );
    });
  } catch (err) {
    console.log('Server failed to start.');
    console.error(err);
  }
})();

Which is our new initialize function that will startup the server once the database is setup.

At this point typescript is probably complaining that the Database type is no longer correct. Lets change packages/server/types.ts:

add import { Collection } from 'lokijs'; at the top
update the interface to:

export interface Database {
  clients: Collection<Client>;
  admins: Collection<Admin>;
}

Update handlers

Our code in the packages/server/handlers still expects a plain object as a database, we have to update some code inside adminHandler and clientHandler to use our new database properly:

Instead of .find((admin) => admin.name === name) we can now use .findOne({name})
When we want to send all items of a collection we have to to db.clients.find() instead of just db.clients
When adding a new client we use .insert instead of .push.

There is one gotcha when adding a new message to the clients messages array. As lokijs uses Object.observe on the whole client to determine if something needs updating. This does not work for array mutations (common Vue2 reactivity caveat as well, that got me quite a few times😅). So whenever we add a message we have to update manually by adding db.clients.update(client); afterwards.

Store the client session

Commit found here

When a client connects now it will generate a new random name, and when that client refreshes it's browser window it will create a new client. This is of course not really feasible, we have to store the clients session somewhere, and if that same client reconnects we restore that session.

Generate a random id for clients at the server

Inside packages/server/index.ts we add the following

// Socket middleware to set a clientID
const randomId = () => crypto.randomBytes(8).toString('hex');
io.use((socket, next) => {
  const clientID = socket.handshake.auth.clientID;
  if (clientID) {
    const client = db.clients.findOne({ id: clientID });
    if (client) {
      socket.clientID = clientID;
      return next();
    }
  }
  socket.clientID = randomId();
  next();
});

and add import crypto from 'crypto'; at the top.

This is a piece of middleware that will run for every client that connects to our server. It will check a auth object on the handshake that the socket server does with the client, if the a clientID is present there we set that clientID on the socket object. If not it is a new client and we generate a new random ID.

As we use typescript and we set a clientID property on the socket object it does not know about we have to add that to the type of socket.

To do that we add to packages/server/types.ts:

declare module 'socket.io' {
  interface Socket {
    clientID: string;
  }
}

Using the new clientID inside the clientHandler

Inside the packages/server/handlers/clientHandler.ts we currently define the client and add it to the database. We have to check here if our client already exists and only add a new entry to the database if necessary.

Remove:

const client: Client = ... ❌
db.clients.insert(client); ❌

And add:

socket.join(socket.clientID);

socket.emit('client:id', socket.clientID);

let client: Client;
const DBClient = db.clients.findOne({ id: socket.clientID });
if (DBClient) {
  client = DBClient;
  client.connected = true;
  socket.emit('client:messages', client.messages);
} else {
  client = {
    ...data,
    messages: [],
    id: socket.clientID,
    connected: true,
  };
  db.clients.insert(client);
}

Breakdown:

By default socket.io will create a user id store it a socket.id and join a room with that specific id. We now have to join the socket.cliendID room as we define our clientID manually.
We emit the clientID to the client so that it can store that in localStorage and send it along when reconnecting.
We check if the client exists, and if it does not we create and insert that client into the database.
If a client is already in the database we send the message history to the client.

Inside the same file we also have to update our disconnect event listener as we have to change the logic that determines if a client is connected. In theory we could have one client opening multiple tabs, which will each establish it's own socket connection. If one of them closes we need to check if there aren't any connections left open for that client before we update the connection status.

Change the socket.on('disconnect') handler to:

socket.on('disconnect', async () => {
  const matchingSockets = await io.in(socket.clientID).allSockets();
  const isDisconnected = matchingSockets.size === 0;
  if (isDisconnected) {
    client.connected = false;
    io.to('admins').emit('admin:client_status', {
      id: client.id,
      status: false,
    });
  }
});

Save the clientID at the widget side

In the widget we will store the id and name of the client in the socket store, and generate a new name there if it is the first time connecting.

Inside the packages/widget/src/stores/socket.ts we add to our state:

id: localStorage.getItem('clientID'),
name: localStorage.getItem('clientName') || '',

and to our actions:

SOCKET_messages(payload: Message[]) {
  this.messages = payload;
},
SOCKET_id(payload: string) {
  localStorage.setItem('clientID', payload);
  this.id = payload;
},
setName() {
  const name = faker.name.firstName();
  this.name = name;
  localStorage.setItem('clientName', name);
},

Also add import faker from '@faker-js/faker/locale/en'; at the top of the file, and remove it from packages/widget/src/App.vue;

Now we have to use the name and id from the store when connecting to the socket server, change const socket = io(URL); to:

const socket = io(URL, {
  auth: {
    clientID: socketStore.id,
  },
});
watch(
  () => socketStore.id,
  (val) => {
    socket.auth = {
      clientID: val,
    };
  }
);
if (!socketStore.name) {
  socketStore.setName();
}

The watcher here is needed when for some reason the server disconnects (for a restart for example) and the socket connection is reset. In that case the socket will reconnect with the correct clientID provided.

In the addClient object change name to name: socketStore.name and add watch to the list of imports from 'vue'.

Handle reconnects at the portal side

Commit found here

The last thing we take care of in this part is handling reconnecting the portal to the server when the server is restarted or otherwise loses it's connection. In the portal currently we only call admin:add when we boot up our application. If the socket connection is lost and restored we have to call admin:add again to register the correct handlers on that socket.

Inside packages/portal/src/boot/socket.ts we change the admin:add call to:

// This will be called on the initial connection and also on reconnects
socket.on('connect', () => {
  socket.emit('admin:add', 'Evert');
});

We have to do the same inside our widget inside packages/widget/src/App.vue change client:add to:

// This will be called on the initial connection and also on reconnects
socket.on('connect', () => {
  socket.emit('client:add', addClient);
});

Fix a small bug in the portal

There is a bug in the portal code that happens when the server reboots and the socket is reconnected. Even if we re-emit the admin:add event, if we already have a client selected, we cannot send new messages to that selected client. That is because when we reconnect we resend the whole client list and in the SOCKET_list action inside packages/portal/src/stores/client.ts we replace the clients array in the state with the newly received value.

However, if we already had a client selected, the clientSelected state pointed to an item in the old array we overwrote. So to keep things working we have to reset the clientSelected in there as well:

if (this.clientSelected) {
  const currentSelectedId = this.clientSelected.id;
  this.clientSelected =
    this.clients.find((client) => client.id === currentSelectedId) ||
    null;
}

Wrapping up

That's it for this one! In the next part I will be adding a login page to the portal and generate a token to also secure the connection from the portal to the server. See you next time! 🚀

Part 2: Connecting everything together

Evertvdw — Sat, 23 Apr 2022 19:17:01 +0000

In this series we are going to create an embeddable chat widget that you can insert on any website. in part 1 we setup the basic repository, using yarn workspaces. However, when I got going coding stuff for this part of the series, I quickly noticed I should have added the different parts portal, widget and server as folders under /packages and not in the root folder.

If they are not under /packages adding packages to a workspace will not work as expected, creating extra yarn.lock files and node_modules folders.

Fixing workspaces setup of part 1

Anyways, this can of course be fixed, so lets do that first 🙂

Create a new folder packages in the root directory. Move the server, portal and widget folders in here.
Update workspaces in root package.json to ["packages/*"]
Update all the references in root tsconfig.json to ./packages/portal etc.
Adjust build scripts, for changes check this commit

Setting up a simple socket server

Section commit here

First lets update the packages/server/index.ts file, new contents:

import express from 'express';
import { createServer } from 'http';
import { Server } from 'socket.io';
import cors from 'cors';

const app = express();
app.use(cors());

const server = createServer(app);
const io = new Server(server, {
  cors: {
    origin: [/http:\/\/localhost:\d*/],
  },
});

io.on('connection', (socket) => {
  console.log(
    `Socket ${socket.id} connected from origin: ${socket.handshake.headers.origin}`
  );
  socket.onAny((event, ...args) => {
    console.log(event, args);
  });
});

server.listen(5000, () => {
  console.log(
    `Server started on port ${5000} at ${new Date().toLocaleString()}`
  );
});

We create a Socket.io server which we attach to our existing http server. On here we do some basic logging to log if someone connect and a onAny event handler that will log all events send to the server for debugging purposes.

Connecting the widget to the server

Section commit here

Now lets update the widget project to connect to the socket server. I am going to use Pinia to manage the state of both the widget and the portal. For the Widget we will have to add it as a dependency. You can do that by running:

yarn workspace widget add pinia

in the root directory. This will add the dependency to the package.json inside the corresponding workspace.

Updating `main.ts`

Inside the widget entry let's add Pinia and refactor a bit. The new code will be:

import App from './App.vue';
import { createPinia } from 'pinia';
import { defineCustomElement, createApp } from 'vue';

const app = createApp(App);

app.use(createPinia());

const chatWidget = defineCustomElement(App);

customElements.define('chat-widget', chatWidget);

This will define a custom element that we can use as <chat-widget /> inside regular HTML.

Adding a simple store

Create a file packages/widget/stores/main.ts, which will contain our main Pinia store, with the following content:

import { defineStore } from 'pinia';

export const useMainStore = defineStore('main', {
  state: () => ({
    hello: 'Hi there!',
  }),
  getters: {
    //
  },
  actions: {
    //
  },
});

Creating App.vue

Inside the widget entry we imported App.vue, lets create it at packages/widget/App.vue with the following content:

<template>
  <div class="chat-widget">
    Chat-widget says hi!
    <div>From the store: {{ mainStore.hello }}</div>
  </div>
</template>

<script setup lang="ts">
import io from 'socket.io-client';
import { onUnmounted } from 'vue';
import { useMainStore } from './stores/main';

const URL = 'http://localhost:5000';
const socket = io(URL);
const mainStore = useMainStore();

socket.on('connect_error', (err) => {
  console.log('connection error', err);
});

socket.onAny((event, ...args) => {
  console.log(event, args);
});

onUnmounted(() => {
  socket.off('connect_error');
});
</script>

<style lang="scss">
.chat-widget {
  background-color: red;
  color: white;
}
</style>

Connect the portal to the socket

Section commit here

Connecting the portal to the socket server is quite simple. We can leverage a Quasar feature called boot files for that. In short those are files that will run at application startup. You can initialize external packages in there instead of having one big entry file. Read more here

Create packages/portal/src/boot/socket.ts with the following content:

import { boot } from 'quasar/wrappers';
import io from 'socket.io-client';

export default boot(({}) => {
  const URL = 'http://localhost:5000';
  const socket = io(URL);
  socket.onAny((event, ...args) => {
    console.log(event, args);
  });
});

And add socket to the boot section inside packages/portal/quasar.config.js. That is all!

Creating a simple chat between the portal and the widget

Now that we have everything connected properly, let's focus on some actual functionality. I'm going to highlight changes in here, all changes can be found in this git diff, spanning 4 commits:

Git diff here

Creating common type interfaces

I like to start with the basis, as we are using Typescript it makes sense to define the interfaces we are going to use. Most interfaces will be shared between all three projects, so I'm going to create a types.ts file in the root directory, and import from that inside the projects.

I'm not sure this is best practice, if there are other ideas/ways to do this, please let me know in the comments! We can always refactor 😇

As an admin of the portal I want to see all connected clients and be able to chat with any one of them. Also I want to keep in mind that multiple admins could in theory chat with one client. Based on these requirements we will create the interfaces.

Create a types.ts file in the root directory with the following contents:

export interface AddClient {
  name: string;
}

export interface Client extends AddClient {
  id: string;
  connected: boolean;
  messages: Message[];
}

export interface Admin {
  name: string;
  connected?: boolean;
}

export enum MessageType {
  Admin = 'admin',
  Client = 'client',
  Info = 'info',
}

export interface Message {
  time: number;
  message: string;
  adminName?: Admin['name'];
  type: MessageType;
}

This defines a basic structure of how a Message will look like.

A timestamp (unix time, so a number)
The message content
The type of a message
- Admin if coming from the portal
- Client if coming from the widget
- Info if it is system message, like updated connection status etc.
The name of the admin, if it is a message of type Admin this will be filled

An array of these messages will be stored in an object we define as Client. Once a client connects we will supply some info about that client. For now that will only be a name, but this will be extended as we progress in this project.

Include this file in all the projects

If we want to import from types.ts which is at the root of the project from inside a package, we need to add some configuration to each package's tsconfig.json.

../../types.ts needs to be added to the include array, and "rootDir": "../../" added to the compilerOptions.

Add server code for admins and clients

The server will also have a few type interfaces of its own, not shared with the other packages. So we create packages/server/types.ts and define those types in there, as well as tunnel any types we use from the generic types as well:

import { Admin, Client, Message, AddClient } from '../../types';

export interface Database {
  clients: Client[];
  admins: Admin[];
}

export { Admin, Client, Message, AddClient };

Next we will need to add socket handlers that will listen to events sent from either portal or widget and do something with those. To separate concerns I am going to create separate handlers for events send by admins and clients.

So let's create a file packages/server/handlers/adminHandler.ts:

import { Socket, Server } from 'socket.io';
import { Database, Message } from '../types';

export default function (io: Server, socket: Socket, db: Database) {
  socket.on('admin:add', (name: string) => {
    socket.join('admins');

    const admin = db.admins.find((admin) => admin.name === name);

    if (!admin) return socket.disconnect(true);
    admin.connected = true;

    socket.emit('admin:list', db.clients);

    socket.on(
      'admin:message',
      ({ id, message }: { id: string; message: Message }) => {
        const client = db.clients.find((client) => client.id === id);
        if (client) {
          // Store message in the DB
          client.messages.push(message);
          // Send message to the client
          socket.to(client.id).emit('client:message', message);
          // Send message to all admins
          io.to('admins').emit('admin:message', {
            id: client.id,
            message,
          });
        }
      }
    );

    socket.on('disconnect', () => {
      admin.connected = false;
    });
  });
}

Quick (or not so quick) summary of what is going on here:

This file returns a function which needs to be called with some parameters, including our database, which will just be a in memory javascript object for now.
I will prefix messages between server and admin with admin:, so that I can more easily see what some event is about. This is just a convention I am going to use inside this project, not a requirement, you can name events however you want.
Once an admin connects it will send a admin:add event to the server. Upon that event the server will add that admin to the room admins. > Rooms in Socket.io are used to easily send messages to multiple connected sockets.
The database will contain some predefined admins. If the admin connecting is not among then, disconnect the socket. This is a first step into securing our server, but of course by no means secure yet. We will upgrade this as we go along.
socket.emit('admin:list', db.clients); will emit the list of clients to the just connected admin.
The admin:message event will listen for message send by the admin to a certain client.
- This will contain the id of the client to which the message should go
- It will lookup that client in the DB, and send the message to that client
- After that it will send all admins that same message

Similarly we create a handler for the clients, packages/server/handlers/clientHandler.ts:

import { Socket, Server } from 'socket.io';
import { AddClient, Client, Database, Message } from '../types';

export default function (io: Server, socket: Socket, db: Database) {
  socket.on('client:add', (data: AddClient) => {
    socket.join('clients');
    const client: Client = {
      ...data,
      messages: [],
      id: socket.id,
      connected: true,
    };
    db.clients.push(client);
    io.to('admins').emit('admin:list', db.clients);

    socket.on('client:message', (message: Message) => {
      // Add message to DB
      client.messages.push(message);
      // Send message back to client
      socket.emit('client:message', message);
      // Send message to all admins
      io.to('admins').emit('admin:message', {
        id: client.id,
        message,
      });
    });

    socket.on('disconnect', () => {
      client.connected = false;
      io.to('admins').emit('admin:client_status', {
        id: client.id,
        status: false,
      });
    });
  });
}

Summary of this file:

All messages between client and server will be prefixed with client:
When client sends client:add we join a room with all clients and add that client to the database.
We notify all admins of the newly connected client with io.to('admins').emit('admin:list', db.clients);.
When the client sends a message with the event client:message we:
- Add that message to the database
- Emit the message back to the client. This might seem odd but I want the messages that the client has in memory in the browser to have come from the server, so that we won't get in the situation that a client will see messages displayed that are not properly send over.
- Emit the same message to all admins
Upon disconnect of a client we will update the client status to all admins so that we can display the connection status in our list of clients.

Using these handlers and creating a database inside packages/server/index.ts it will look like this:

This is not all new code but I pasted the whole file for convenience.

import { createServer } from 'http';
import { Server } from 'socket.io';
import cors from 'cors';
import { Database } from './types';
import admins from './admins';
import adminHandler from './handlers/adminHandler';
import clientHandler from './handlers/clientHandler';

const app = express();
app.use(cors());
const server = createServer(app);
const io = new Server(server, {
  cors: {
    origin: [/http:\/\/localhost:\d*/],
  },
});

// Create an in memory 'database'
const db: Database = {
  clients: [],
  admins: admins,
};

io.on('connection', (socket) => {
  console.log(
    `Socket ${socket.id} connected from origin: ${socket.handshake.headers.origin}`
  );
  adminHandler(io, socket, db);
  clientHandler(io, socket, db);

  socket.onAny((event, ...args) => {
    console.log('[DEBUG]', event, args);
  });
});

We import our handlers and call those functions when we receive a incoming connect, initializing all our event handlers. As for our 'database' this will be upgraded later on, for now I am ok with our clients being wiped on every restart of the server.

This file imports one file not yet mentioned, namely packages/server/admins.ts, which will function as our seed of admins:

import { Admin } from './types';

const admins: Admin[] = [
  {
    name: 'Evert',
  },
  {
    name: 'Jane Doe',
  },
];

export default admins;

Defining a simple portal interface

In the portal packages I also delete quite some files, check the git diff to see which files are removed.

Inside the portal project I want to keep the data received from the server inside a separate Pinia store. So lets create packages/portal/src/stores/client.ts:

import { defineStore } from 'pinia';
import { Client, Message } from '../../../../types';

export const useClientStore = defineStore('client', {
  state: () => ({
    clients: [] as Client[],
    clientSelected: null as Client | null,
  }),
  actions: {
    SOCKET_list(payload: Client[]) {
      this.clients = payload;
    },
    SOCKET_message(payload: { id: string; message: Message }) {
      const client = this.clients.find((c) => c.id === payload.id);
      if (client) {
        client.messages.push(payload.message);
      }
    },
    SOCKET_client_status(payload: { id: string; status: boolean }) {
      const client = this.clients.find((c) => c.id === payload.id);
      if (client) {
        client.connected = payload.status;
      }
    },
    setClientSelected(payload: Client) {
      this.clientSelected = payload;
    },
  },
});

Quick summary:

We store a list of clients and one selected client, the messages of the selected client will be displayed in the interface and we can switch between selected clients.
Notice the prefix SOCKET_ for some actions, this signal events coming from the server. How this works I will explain later on.

The interface will consist of two main parts for now, a list to see which clients are connected and so select a client and a chat window, showing the messages of the selected client and an input to send a message to that client.

First the list, create packages/portal/src/components/ClientList.vue:

<template>
  <q-list>
    <q-item-label header> Client list </q-item-label>
    <q-item
      v-for="client in clientStore.clients"
      :key="client.id"
      v-ripple
      class="q-my-sm"
      clickable
      @click="clientStore.setClientSelected(client)"
    >
      <q-item-section avatar>
        <q-avatar color="primary" text-color="white"
          >{{ client.name.charAt(0) }}
        </q-avatar>
      </q-item-section>

      <q-item-section>
        <q-item-label>{{ client.name }}</q-item-label>
        <q-item-label caption lines="1">{{ client.id }}</q-item-label>
      </q-item-section>

      <q-item-section side>
        <q-badge rounded :color="client.connected ? 'green' : 'red'" />
      </q-item-section>
    </q-item>
  </q-list>
</template>

<script setup lang="ts">
import { useClientStore } from 'src/stores/client';
const clientStore = useClientStore();
</script>

<style lang="scss"></style>

Quasar has quite some components to create easy, good looking lists with, with lots of customizations possible, see the documentation for more information. We just loop over the list of clients and display an item for each client. For that client we display the name and connection status using a green or red dot.

For the display of message we create packages/portal/src/components/ClientChat.vue:

<template>
  <div v-if="clientStore.clientSelected" class="fit column">
    <div class="text-h6 q-pa-md">
      Chat with {{ clientStore.clientSelected.name }}
    </div>
    <q-separator></q-separator>
    <div class="col q-pa-md">
      <div
        v-for="(message, index) in clientStore.clientSelected.messages"
        :key="index"
      >
        {{ message.message }}
      </div>
    </div>
    <div class="q-pa-md row items-center">
      <q-input
        v-model="text"
        outlined
        placeholder="Type your message here"
        class="col"
      />
      <div class="q-pl-md">
        <q-btn
          outline
          round
          icon="send"
          :disabled="!text"
          @click="sendMessage"
        />
      </div>
    </div>
  </div>
</template>

<script setup lang="ts">
import { ref } from 'vue';
import { useClientStore } from 'src/stores/client';
import { socket } from 'src/boot/socket';
import { Message, MessageType } from '../../../../types';
const clientStore = useClientStore();
const text = ref('');
function sendMessage() {
  if (clientStore.clientSelected) {
    const message: Message = {
      time: Date.now(),
      message: text.value,
      type: MessageType.Admin,
    };
    socket.emit('admin:message', {
      id: clientStore.clientSelected.id,
      message,
    });
    text.value = '';
  }
}
</script>

<style lang="scss"></style>

Which will just display the messages in plain text, no styling for now. There is also an input along with a button to input some text which we can send to the server upon clicking the button. Again we use some Quasar components for the button and the input.

Now we have to use these components, so we edit packages/portal/src/layouts/MainLayout.vue to:

<template>
  <q-layout view="lHh Lpr lFf">
    <q-header elevated>
      <q-toolbar>
        <q-btn
          flat
          dense
          round
          icon="menu"
          aria-label="Menu"
          @click="toggleLeftDrawer"
        />

        <q-toolbar-title> Quasar App </q-toolbar-title>

        <div>Quasar v{{ $q.version }}</div>
      </q-toolbar>
    </q-header>

    <q-drawer v-model="leftDrawerOpen" show-if-above bordered>
      <ClientList />
    </q-drawer>

    <q-page-container>
      <router-view />
    </q-page-container>
  </q-layout>
</template>

<script setup lang="ts">
import { ref } from 'vue';
import ClientList from 'src/components/ClientList.vue';

const leftDrawerOpen = ref(false);

function toggleLeftDrawer() {
  leftDrawerOpen.value = !leftDrawerOpen.value;
}
</script>

And the packages/portal/src/pages/IndexPage.vue:

<template>
  <q-page :style-fn="fullPage">
    <ClientChat />
  </q-page>
</template>

<script setup lang="ts">
import ClientChat from 'src/components/ClientChat.vue';

function fullPage(offset: number) {
  return { height: offset ? `calc(100vh - ${offset}px)` : '100vh' };
}
</script>

Now that we have that setup we have to make sure that events are send to the socket instance at the portal make it to our store actions, and update the store. To do this, we can make use of the onAny listener that SocketIO provides, we update packages/portal/src/boot/socket.ts:

import { boot } from 'quasar/wrappers';
import io from 'socket.io-client';
import { useClientStore } from 'src/stores/client';

const URL = 'http://localhost:5000';
const socket = io(URL);

export default boot(({ store }) => {
  const clientStore = useClientStore(store);
  socket.emit('admin:add', 'Evert');
  socket.onAny((event: string, ...args) => {
    if (event.startsWith('admin:')) {
      const eventName = event.slice(6);
      if (Object.hasOwn(clientStore, 'SOCKET_' + eventName)) {
        // eslint-disable-next-line @typescript-eslint/ban-ts-comment
        // @ts-expect-error
        clientStore['SOCKET_' + eventName](...args);
      }
    }
    console.log(`[DEBUG] ${event}`, args);
  });
});

export { socket };

What is happening here?

We emit the admin:add event to add ourselves to the admin pool. We have to add authentication here later of course as now anyone can do that.
In the onAny event we parse the event name, and if it starts with admin: we take the part after it and check if there is a store action defined called SOCKET_ + that part after it. If there is we call that action with the arguments passed in by the events. This way we only have to add the specific actions in the store if we want to process more events, no additional socket listening needed, I'm quite happy with that.😄

The last change to the portal package is to set the router mode of vue-router to history instead of the default hash used by Quasar. We do this by setting the vueRouterMode property in the quasar.config.js to history.

Setting up the widget

Now that we have the server and portal done, we can move on to the widget. In here we will have to emit the event client:add and supply client details. Instead of coming up with weird names myself I am going to use a package called faker, to do this for me for the remainder of this series. We have to add that to our widget package:

yarn workspace widget add @faker-js/faker

This command must be run from the root folder, and it will add a dependency to the package.json inside the packages/widget folder.

Inside the widget package we already have 1 store defined, this will hold our UI state, the socket/client data I will put in a separate store, so lets create packages/widget/src/stores/socket.ts:

import { defineStore } from 'pinia';
import { Message } from '../../../../types';

export const useSocketStore = defineStore('socket', {
  state: () => ({
    messages: [] as Message[],
  }),
  actions: {
    SOCKET_message(payload: Message) {
      this.messages.push(payload);
    },
  },
});

As you can see we are going to use the same action prefix as inside the portal package. Only thing left is to update our packages/widget/src/App.vue and add some code to display and send messages in here:

<template>
  <div class="chat-widget">
    Chat-widget
    <div>Name: {{ name }}</div>
    Messages:
    <div class="messages">
      <div v-for="(message, index) in socketStore.messages" :key="index">
        {{ message.message }}
      </div>
    </div>
    <input v-model="text" type="text" />
    <button @click="sendMessage">Send</button>
  </div>
</template>

<script setup lang="ts">
import io from 'socket.io-client';
import { onUnmounted, ref } from 'vue';
import { useSocketStore } from './stores/socket';
import { AddClient, Message, MessageType } from '../../../types';
import faker from '@faker-js/faker/locale/en';

const URL = 'http://localhost:5000';
const socket = io(URL);
const socketStore = useSocketStore();
const name = faker.name.firstName();
const text = ref('');

const addClient: AddClient = {
  name,
};

socket.emit('client:add', addClient);
socket.onAny((event: string, ...args) => {
  if (event.startsWith('client:')) {
    const eventName = event.slice(7);
    if (Object.hasOwn(socketStore, 'SOCKET_' + eventName)) {
      // eslint-disable-next-line @typescript-eslint/ban-ts-comment
      // @ts-expect-error
      socketStore['SOCKET_' + eventName](...args);
    }
  }
  console.log(`[DEBUG] ${event}`, args);
});

function sendMessage() {
  const message: Message = {
    time: Date.now(),
    message: text.value,
    type: MessageType.Client,
  };
  socket.emit('client:message', message);
  text.value = '';
}

onUnmounted(() => {
  socket.off('connect_error');
});
</script>

<style lang="scss">
.chat-widget {
  background-color: #eeeeee;
  color: #111111;
}

.messages {
  padding: 16px;
}
</style>

And thats it! You should have a basic setup functioning now, where you can send/receive messages between a widget and a portal.

Here is a small gif of things in action:

Wrapping up

We have the basics setup up now, but there is still much to do to extend it, what is currently on my list of things to include in this series (not necessarely in that order):

Persist the database between restarts
Add authentication for the portal
Add authentication for admins connecting to the server
Display when a client/admin is typing
Setting up a pipeline for automatic deployment
Add avatars
Group/cluster the chat messages and show timestamps

I will keep off from styling everything in detail for now. In part because I don't have a good design for it yet, and also because everyone will probably want their own design, so I'm just gonna focus on the technical stuff.

Until next time! Thanks for making it so far 👍

Part 1: Setting up the project

Evertvdw — Sat, 09 Apr 2022 20:36:20 +0000

Welcome to my first ever blogpost! This is going to be part 1 of a series in which I will walk you through creating a embeddable chat widget, you know, one of those things that will popup on a site by which you can talk to a sales representative or whatever.

The general idea, what will we make?

I'm doing this as part of my day-to-day job where we host numerous websites and offer support for customers that need help with issues or configuration of their site. Instead of them calling us or creating tickets in Zendesk I wanted to create a way for them to contact us using a chat widget that can be embedded in their website.

It will be a project consisting of three parts:

A socket server
A chat portal
A chat widget

Probably this is still a bit vague, but let me explain in more detail what I mean with each part.

The socket server

This will be the backbone of the project, a socket server that both the portal and widget will talk to. It will use a web technology called WebSockets. Using that we can send messages back and forth between the clients (using the widget) and the portal.

The chat portal

When someone opens up the chat widget and starts typing, a chat will appear in the chat portal (much like Whatsapp for example) and from there you can send messages back.

The chat widget

This will be a small project packed as a WebComponent which can be inserted on every website by just adding a script tag and a custom HTML element. For more information on web components you can start here

Now that we have an idea of what we will make, lets get into it!

Quick summary of tools and technologies

I am going to make this with the technologies I feel comfortable with, so here some of the tools we will be using:

Vue (version 3)
Quasar (Vue framework)
Typescript
Node.js (for the backend)
Socket.io

And as an editor I will use VS Code.

Setting up the project

I first started writing this as a code along section, but a few steps in I came to my senses and asked myself who would enjoy this? I certainly would not, as the setup is basically all boilerplate code and project configuration so we can get cracking later on.

But it is fun (I think so atleast) to walk you around the boilerplate code and show you how I set up the project.

Get the code

The code for this series will be hosted here.

In that project I will create a branch for every part of this series. There is a branch part-1 which contains the end result of this part.

What is in it?

Here is a screenshot of the folder structure:

Let's break it down🚀

Yarn workspaces - monorepo

I make use here of something called workspaces. You can use workspaces to create a monorepo, a repository hosting multiple projects. As our three parts are basically three different projects I decided it would be a good time to try this out. The folders portal, server and widget all contain their own projects, with their own typescript configuration (tsconfig.json) and own package.json. The dependencies however are installed on the root level.

This means that you only have to run yarn at root level once, to install the dependencies of all the projects, nice!🎉

To make this work the root package.json contains these lines:

 "workspaces": [
    "./portal",
    "./server",
    "./widget"
 ],

And to support typescript our root tsconfig.json contains these lines:

"references": [
    { "path": "./portal" },
    { "path": "./widget" },
    { "path": "./server" }
]

This means that every project can have it's own tsconfig.json and therefore it's own configuration.🙂

Editor configuration

One thing crucial to a happy me (and hopefully every developer) is that the project you work in makes your life easier.

There are a lot of VS code extensions that do just that, and luckily you can include which extensions you use and their configuration inside a .vscode folder in every codebase.

When you loaded this project VS code probably asked/recommended you to install the recommended extensions. If you did not do that at that time, go to the extensions tab and filter on @recommended where you can do it manually.

There are a few things setup worth noting:

Code formatting using Prettier (on every save)
Code linting using ESLint (autofix on every save)

This means you don't have to worry about formatting files and VS Code will tell you if you are doing something wrong that can't be fixed automatically. Double yay!🎉

Inside the `portal` folder

Inside the portal folder I created a starter project using Quasar. For those of you that don't know Quasar, check it out! In short, it can do everything! A large component library combined with build configurations for SSR, SPA, PWA and more.

You can create a boilerplate project using the CLI, just run

yarn create quasar

Which will ask you some questions about the sort of project you want to create. For those who are interested, here is what I filled in:

√ What would you like to build? » App with Quasar CLI, let's go!
√ Project folder: ... portal
√ Pick Quasar version: » Quasar v2 (Vue 3 | latest and greatest)
√ Pick script type: » Typescript
√ Pick Quasar App CLI variant: » Quasar App CLI with Vite (BETA stage)
√ Package name: ... portal
√ Project product name: (must start with letter if building mobile apps) ... Chat portal
√ Project description: ... A Quasar Project
√ Author: ... _______________
√ Pick a Vue component style: » Composition API
√ Pick your CSS preprocessor: » Sass with SCSS syntax
√ Check the features needed for your project: » ESLint, State Management (Pinia)
√ Pick an ESLint preset: » Prettier

I moved some ESLint and Prettier configuration from this boilerplate to the root level and did some tsconfig.json changes but other than that the code is as is.

Inside the `server` folder

In here I setup a single index.ts file with the most basic express application, it only tells you that it is running, not much more. But that is not the point for this part :)

Inside the `widget` folder

This one I had to research a bit. I figured there must be someone that has done something like this before, and after stumbling upon vite community templates I quickly found what I was looking for: a webcomponent vite template

I added this template to this folder and did some changes to tsconfig.json and vite.config.ts to make it work for my use case, no sweat!😄

Running and building

The last thing I setup was creating a scripts section inside the root package.json that will build and run the different parts. Either separately or at once, whatever is your preference. Go take a look, I think it is quite self explanatory.

As a quick tip⚡, you can also use the npm scripts section inside the Explorer tab to quickly run the scripts you want. Here:

Wrapping up

That's it for this part! Maybe you are a bit disappointed because we did not get to some real coding yet, but stay tuned for the next part where that certainly will be the case.

Also, feedback and reactions are welcome! As this is my first post, I would like to know what I can improve 😇

See you next time!

Forem: Evertvdw

Part 6: Styling the chat widget

Add Quasar

Using a self defined name

Updating the socket store

Moving the chat window to a separate component

Wrapping up

Part 5: Getting ready for deployment & deploy

Getting ready for deployment

Serving local files

Next, finding out your types sharing solution does not work well

Updating all types imports

Checking if we can build

Getting ready for deployment - environment variables

Setting up environment variables

Providing the variables for widget and portal

Small improvement to package.json scripts

Environment variables for the server

Deploying an Heroku app

Doing the deploy

Fixes and stuff

Production .env file

Node engine

Using absolute path when serving portal and widget

Don't hardcode the login URL

Widget package missing headers

Allow codepen origins

Fixing the bug mentioned earlier

Wrapping up

Part 4: Portal login & authorization of socket connection

Setting up stuff at the server end

Storing the password in the database

Adding packages to the server package

Refactoring and adding socket middleware

Adding auth routes

Put everything together in the server entry

Adding the login screen in the portal

Adding an auth store

Adding an auth boot file

Vue files for the login

Wrapping up

Part 3: Adding a database

What database to use?

Don't agree with me?

Let's code!

Installing lokijs

Initializing the database

Updating packages/server/index.ts

Update handlers

Store the client session

Generate a random id for clients at the server

Using the new clientID inside the clientHandler

Save the clientID at the widget side

Handle reconnects at the portal side

Fix a small bug in the portal

Wrapping up

Part 2: Connecting everything together

Fixing workspaces setup of part 1

Setting up a simple socket server

Connecting the widget to the server

Updating main.ts

Adding a simple store

Creating App.vue

Connect the portal to the socket

Creating a simple chat between the portal and the widget

Creating common type interfaces

Include this file in all the projects

Add server code for admins and clients

Defining a simple portal interface

Setting up the widget

Wrapping up

Part 1: Setting up the project

The general idea, what will we make?

The socket server

The chat portal

The chat widget

Quick summary of tools and technologies

Setting up the project

Get the code

What is in it?

Updating `packages/server/index.ts`

Updating `main.ts`

Inside the `portal` folder

Inside the `server` folder

Inside the `widget` folder