DEV Community: Estee Tey

Expenses made easier with Cloudflare AI

Estee Tey — Thu, 11 Apr 2024 14:50:45 +0000

This is a submission for the Cloudflare AI Challenge.

What I Built

This project is a Cloudflare serverless worker with an AI service binding deployed for processing either audio, image or text submitted by users into semantic useful information, especially in the context for submitting expenses.

For users that prefer having a UI to interact with, a simple NextJS web app is created to demonstrate how to upload files and utilizes API routes to make a POST request to the Cloudflare worker endpoint.

How it works

The diagram below looks a bit blurry on this platform, please refer to the raw image here

User can pass any of the following types of content - audio, image or text. Based on the input type given, we will process them eventually to form JSON like this that can be used by any app to display useful expense information for them.

const SAMPLE_RECORD: Expense = {
    date: "2024-04-11",
    time: "14:00",
    type: "product",
    item: "Rubber Ducky",
    expenditure: 100.0,
};

Models used in this project:

Image-to-text: @cf/unum/uform-gen2-qwen-500m
Automatic Speech Recognition: @cf/openai/whisper
Text Generation: @hf/thebloke/mistral-7b-instruct-v0.1-awq

Demo

Try out the worker!

The worker is deployed at https://cf-journal.senchatea.workers.dev.

Text input

curl --location 'https://cf-journal.senchatea.workers.dev?type=text' \
--header 'Content-Type: text/plain' \
--data '2 weeks ago, I went to eat a buffet at Swensens Unlimited at the T2 airport, it'\''s really nice but it costs like $36 per person after GST, and there were 2 of us.'

Audio input

curl --location 'https://cf-journal.senchatea.workers.dev?type=audio' \
--header 'Content-Type: application/octet-stream' \
--header 'Authorization: Bearer pYrzMvsyURxsCUeaQDsa3lSO_tBDQEuiPB3iLEQt' \
--data '@postman-cloud:///1eef4b5b-a64c-4c10-ad4b-5f22c528880b'

Image input

curl --location 'https://cf-journal.senchatea.workers.dev?type=image' \
--header 'Content-Type: application/octet-stream' \
--header 'Authorization: Bearer pYrzMvsyURxsCUeaQDsa3lSO_tBDQEuiPB3iLEQt' \
--data '@postman-cloud:///1eef4b68-e5d7-49e0-a28d-f60b3bd7d70e'

Try it in the web app!

https://cf-journal.vercel.app/

My Code

The project has 2 folders:

serverless: Code that is deployed to a Cloudflare worker. You can find the text generation prompt & code to use the AI models at utils.ts. The Cloudflare worker request handler is found at main.ts
app: Nextjs app code that is deployed to Vercel

lyqht / cloudflare-journal

Introduction

For users that prefer a UI, a simple NextJS web app is created to demonstrate how to upload files and utilizes API routes to make a POST request to the Cloudflare worker endpoint.

How it works

Models used

From Cloudflare AI Models:

Image-to-text: @cf/unum/uform-gen2-qwen-500m
Automatic Speech Recognition: @cf/openai/whisper
Text Generation: @hf/thebloke/mistral-7b-instruct-v0.1-awq

Try out the worker!

The worker is deployed at https://cf-journal.senchatea.workers.dev.

Text input

curl --location 'https://cf-journal.senchatea.workers.dev?type=text' \
--header 'Content-Type: text/plain' \
--data '2 weeks ago, I went to eat a buffet at Swensens Unlimited at the T2 airport, it'\''s really nice but it costs like $36 per person after GST, and there were

…

View on GitHub

Journey

How the idea came about

Before OpenAI introduced ChatGPT and revitalized the AI scene, I once created Billy, a cute a little expense tracker app to help my mom to track her expenses easier. It actually received good reception with my friends both online & offline because of the clean and straight forward UI.

However, the user retention wasn't very good because the act of logging expenses is very tedious because of the multitude of fields to fill. It was very difficult to encourage the habit of logging expenses for the users.

For many users, it is much direct and easier to talk or take a picture with a phone as compared to typing. But it was rather difficult to interpret information from the data of these input types back then, so I dropped that project eventually.

Now, by utilizing different AI models, we can interpret and organize important information for them more easily, simplifying the expense submission process.

This project is meant to be a MVP to demonstrate that.

Room for improvements

I'm very new to AI so there will definitely a lot of things to improve on!

The webapp in this submission is a very early MVP of what I envision the actual expense tracker app to be.

For now, it only create expenses based on the information in the file input (audio/mp3/text).
Ideally after submission, you can still modify the individual fields of the expense form. The AI portion is just there to assist the auto-filling process.

I'm also not very familiar with prompt engineering, but I would also like to improve the text generation prompt in the future.

Resources

These are some helpful resources from Cloudflare that I have used to work on this project since I wasn't familiar with the AI models available for text generation/inference.

My project is eligible for the Triple Task type category.

DeepL Translate Github Action

Estee Tey — Mon, 22 May 2023 16:32:28 +0000

What I built

I created a github action that translates text documents into target languages that DeepL supports. DeepL supports 32 languages at the moment.

DeepL is a AI translation service that uses deep learning techniques to translate entire sentences from one language to another, rather than translating words individually. It offers a rather generous free API for small translation volumes, so hobbyists like me and you 😉 or pretty much any open source project maintainer can try it out!

The GitHub action main script has been tested on simple text documents, as well as relatively complex text documents such as Supabase's README.md which contains many different symbols and html elements.

Category Submission

Maintainer Must-Haves

App Link

https://github.com/lyqht/deepl-translate-github-action

Screenshots

PR for screenshot can be found here

I updated original.md here, and you can see the GitHub action generating a commit for the translated ja.md with very accurate translation.

Description

This action uses the DeepL Translate API to translate text files in your repository to your target languages. The output will follow the file extension of the given input file.

Link to Source Code

https://github.com/lyqht/deepl-translate-github-action

Permissive License

MIT

Background (What made you decide to build this particular app? What inspired you?)

I've been thinking about accessibility, and they say pictures speak a thousand words, but sometimes we really should express ourselves through words. That makes alt text and semantic html structure important as focal points of accessibility for the general public. We can also include language in there, by making sure that text in a native language can easily be offered to the user that is viewing the content so they can enjoy it too.

While there are many plugins for i18n nowadays, the task of translating the text itself isn't trivial. Hence, I built this to allow easy translation of files in GitHub repositories using the DeepL API.

How I built it (How did you utilize GitHub Actions or GitHub Codespaces? Did you learn something new along the way? Pick up a new skill?)

I have built 2 other GitHub actions before:

So the little experience I have does help me to build this project easier, but I still got to learn new stuff about the DeepL API stuff (both how cool/convenient it is and its limitations) and how to pass secret environment variables and inputs to the GitHub Action runner properly so that the file paths are parsed correctly.

I also tried GitHub Codespaces to create the project, it's pretty cool and easy to use.

The generated codespace was named after a birdie, how cute!

Additional Resources/Info

For a demo, refer to this repository deepl-demo

My Hacktoberfest Experience For The Third Time: 2022 Edition

Estee Tey — Thu, 03 Nov 2022 04:25:18 +0000

It is my 3rd time joining Hacktoberfest. This time, I chose to join the event as both a maintainer and a contributor.

Being a contributor

Last year, I was quite active as a contributor. However, this year, I went on a 3-week holiday and couldn’t access the computer as much.

Since I didn’t have too much time to code, I picked up some simpler issues to work on that still give me some room for learning - since I’ve not implemented the features to be worked on are stuff that before.

My contributions

This year, discounting the 1 PR counted to my own project, I have merged 6 PRs to other open source projects. These are the open source projects that I've contributed to:

Fig Autocomplete: A tool that adds autocomplete to your terminal
- Autogenerated Supabase Fig autocomplete specs using Fig's integration with golang CLI framework, Cobra.
supabase: An awesome open source alternative to Firebase, where it provides you with a Postgres database, Authentication, instant APIs, Edge Functions, Realtime subscriptions, and Storage.
- Updated docs for Supabase Fig autocomplete specs
nodejs.dev: Nodejs.org website
- Added a simple GitHub action to sync auto-generated docs daily, and added prettier formatting for .yml files
octo: A minimal knowledge system app like Obsidian
- Added import and export markdown documents functionality

It was nice to learn how to do different things as a developer by being a contributor 😊 However, being a maintainer is another story.

Being a maintainer

While I do not fully understand the concept of open source in its totality, I really like the idea of building, collaborating and learning together with other developers to write better quality code that also translates into features. In my free time after work, I have created a few open source apps using tech stacks that I was keen to learn about and these apps usually also help to serve a specific use case for myself. I have usually worked on these projects by myself, so I thought it will be a nice idea to leverage on Hacktoberfest this year to work together with the GitHub community on these projects.

Projects participating in Hacktoberfest

For Hacktoberfest, I have chosen to open up 4 of my open source side projects for contributions.

Billy: a mobile expense tracker application made with React Native, with a simple Docsaurus documentation website
Octokit-lite: a web app to perform GitHub operations on multiple repositories easily, made with Next.js. Inspired by GitHub's Octokit and Hacktoberfest's hacktoberfest-repo-topic-apply
generate-supabase-db-types-action: a GitHub action to create PRs for creating/updating Supabase type definitions file in the project
awesome-supabase: an awesome-list of official+community starters & resources. This project is created during Hacktoberfest itself as a way to encourage non-code contributions!

How I decide the issues to be created

To make my project easier for contributing for newcomers, I tried to restrict the scope of most issues I create to simpler frontend issues.

In every issue, I also give a simple suggested solution, where they can propose suitable alternatives. I also try to provide relevant code e.g. which method or files to modify, but not to give them too much details on how to implement the logic so that they get the chance to practice problem solving themselves.

Getting contributions

Octokit-lite is my most active project for Hacktoberfest in terms of contributions received and the time/effort that I’ve invested in collaboration.

5 people picked up issues within the 1st day of sharing this project on Hacktoberfest Discord
3 PRs are merged over the 1st weekend
Total of 10 PRs merged to Octokit-lite during the entire event

Contributions to Octokit-lite vary in size and below are some examples of how I gauge the size

XXS: adding a Code of Conduct file (Sumit Bisht)
XS: Input reset after deleting repos at Unfork (najeebkp)
S: Improve History Logs Page layout (LoftyBrambles)
M: Sort repos by last push date at Unfork (ilikepizza2)
L: Add Unlabel to Octokit-lite: functionality of removing label(s) from selected repositories (Dolir)

I usually create L size issues for my own personal tracking of what to work on next, so it was a pleasant surprise for me to see that there would be developers from the community who would volunteer to pick up issues of this scale! ✨

Aside from Octokit-lite, I also merged 1 PR to fix styling on bullet points & video rendering for Billy’s docsaurus website, 1 PR for updating generate-supabase-db-types-action to use the latest supabase CLI to generate types, and 4 awesome-supabase PRs merged that added online courses, starters & update links for Supabase resources.

An unexpected collaboration

While sharing my project on Twitter, I got to know of Gregor Martynus, the maintainer of the JavaScript Octokit – GitHub's official JavaScript SDK and his project Octoherd. He tweeted a reply that it will be nice to have a GUI like Octokit-lite for Octoherd, and that sparked an inspiration for me ✨

I thought that having an Octoherd integration will be really promising and useful since Octokit-lite was intended to be a compilation of microapps to help users perform handy GitHub operations on repositiories in bulk, and this meant achieving a similar goal as Octoherd. In fact, Octokit-lite’s name is inspired by Octokit, so it is no surprise that the two have similar goals 😊

Then, I tried to think about how technically feasible this integration is and wrote down some tasks down in an issue. There, I also seeked Gregor’s advice on how we can go about adding Octoherd functionality.

While I was worried that the implementation plan isn’t perfect before executing it, he said something that felt really assuring.

I'd say go whatever path works for you right now. Make it work, then make it great, and let the community help. - Gregor Martynus

Being a creator of an open source project has made me feel very obliged to be the expert who can answer every question about how to go about doing anything, but that didn’t necessarily have to be the way. While I’m already standing on the shoulders of giants who provided cool open source libraries to use in my project, I can still continue to tap on many other sources of knowledge — and that’s the beauty of open source.

This also brings me to talk about my Hacktoberfest experience as a whole.

Overall Experience

It turned out better than expected

Despite the 3-week holiday, Hacktoberfest was still a refreshing experience for me. Being a contributor this year was much more relaxed since I wasn’t as ambitious as last year.

On the other hand, it is my very first time being a maintainer so I was pretty afraid I would screw up a lot, but the experience turned out better than expected 😊. To be honest, I thought no one would even volunteer to help out on my side projects but I'm glad that I was proven otherwise 😄!

As I learn to work with my contributors, I understand better how to write better setup instructions (big thanks to my first contributor LoftyBrambles for pointing out problems and helping other contributors!) and learn how to give clearer review comments to work together with my contributors on pull requests.

However, some things didn’t go as well as I wanted as a maintainer during Hacktoberfest.

Confusion with the event rules

The rules for Hacktoberfest was slightly different this year, which has caused some confusion for me as well as the contributors that helped out with my project.

Last year, it was required for the issues/PRs has the label hacktoberfest, to be counted. This year, as long as the project has the topic hacktoberfest, any PR merged for that project will count for users that have signed up for Hacktoberfest. This has led to me/other contributors asking for project maintainers to add the label to the issue & PR. 😂

On the other hand, the hacktoberfest-accepted label on PRs is only meant for keeping track of PRs merged for maintainers. However as a maintainer, I don’t really see the website helping me to keep track of this even though I signed up as both a contributor and a maintainer - so honestly I don’t know how well I’m doing as a maintainer. Even though I have over 10 merged hacktoberfest-accepted PRs, I don’t know if that is good or not.

It is difficult to be a maintainer

Although my project can be considered as a relatively small scale project, however, I do experience some troubles as follows:

Ghosting by contributors: This is a quite common thing that happens for open source projects. However, this is not ideal during the Hacktoberfest period because hoarding these issues and not working on them meant that other contributors who were keen to contribute to the project would be turned away due to the lack of open issues to be worked on. I had quite a few issues that got ghosted by my assignees and had to be reassigned. This could also happen multiple times for the same issue.
Getting spammed by contributors to merge PRs: I wish that I didn't have to manually point out that I was on holiday, but there was an instance where a contributor pinged me quite frequently to review the PR. I hope the open source community understands that maintainers are also normal people living out their lives and often have other priorities on hand.
Getting questions on non-project-specific problems: I had contributors asking me for help on very basic problems such as having a outdated node version causing package prroblems, not knowing how to use .env file to set environment variables. While I’m not sure how to ensure that the contributors have a basic understanding of these things before jumping into the issues, it’s a little frustrating when I get these sort of questions because it shows a significant lack of effort on the contributors’ side in troubleshooting problems and it also wastes my time.
Contributions start to decline after the 2nd week: Probably because many contributors have already completed Hacktoberfest by then, there’s a significant drop in activity on my projects thereafter.
Lack of discord community: I took the time to look up on how to create an ok-ish discord server with project specific channels, however aside from my friend, no one else joined it 😂This is also attributed to the fact that I created this discord only after the 2nd week of Hacktoberfest where contributors have become less active.

That’s a wrap!

Thank you for reading, hope you enjoyed the article!

Did you joined Hacktoberfest too? Share your experience below in the comments, I would love to hear it!

If you find the article awesome, hit the reactions 🧡 and share it 🐦~

To stay updated whenever I post new stuff, follow me on Twitter.

To support me on content creation, you can buy a cup of tea for me ✨

How to create and test a GitHub Action that generates Supabase database types

Estee Tey — Sat, 07 May 2022 09:32:58 +0000

How to generate types from a Supabase database

On the Supabase documentation, there is a page on generating types. Following the instructions, the script to run looks something like this.

Note the additional --version=2 parameter. This probably became a mandatory prop after some update to the openapi-typescript tool.

npx openapi-typescript https://{projectId}.supabase.co/rest/v1/?apikey={specialApiKey} --output=types/supabase.ts --version=2

The values for the anon key and URL can be found in the Supabase dashboard.

Running the script generates a file like this. With the definitions that are generated there, I could create a type for Bill with just the code block below.

import {definitions} from '../types/supabase';

export type Bill = definitions['Bill'];

Most of my project source code still works fine after changing the type. The only code I had to refactor is related to the deadline field which is Date type. The definitions has the field declared as a string, even though they do acknowledge it is a Date format.

Bill: {
    /** Format: date */
    deadline?: string;
}

Personally I think this is ok, since this forces you to convert date objects to appropriate ISO strings, so there is less ambiguity about passing the Date object that you have constructed in JS to Supabase. If you don’t like this you could override it in your self-declared type.

In the same documentation, they also included a section on how to update types automatically with GitHub Actions. This ensures that whenever you update the database, your GitHub action will automatically update the types that you have in your DB. Then, the next time you pull your source code, you would know what are the new changes and how to accommodate them.

In the docs, there’s a script to be added to the package.json as such.

"update-types": "npx openapi-typescript https://your-project.supabase.co/rest/v1/?apikey=your-anon-key --output types/database/index.ts"

However, I wasn’t too sure how to replace the values in the package.json script safely with environmental variables when I push the source code. I’m not very familiar with bash syntax, but I assume the script should look something like this for my project.

"update-types": : "npx openapi-typescript https://${SUPABASE_URL}/rest/v1/?apikey=${ANON_KEY} --version=2 --output types/database/index.ts"

To double confirm the syntax, I decided to use the Sourcegraph Visual Studio Code plugin to look for projects that have implemented this GitHub action.

Cross-reference code with Sourcegraph Visual Studio Code plugin

The Sourcegraph Visual Studio Code plugin can be installed through the Extensions panel.

Once you have it installed, you can find the Sourcegraph icon at the side bar. When you click it, you will see the usual UI to do a universal code search. To find other projects that also generate types, we can pass in a query npx openapi-typescript.

We see quite a few results, and luckily, in the 3rd project called tone-row/flowchart-fun, I see that they have package.json script that looks like a promising candidate. They have variables such as SB_URL and SB_ANON_KEY which resemble Supabase stuff ✨

"generate:types": "export $(cat .env.local | xargs) && npx openapi-typescript \"${SB_URL}/rest/v1/?apikey=${SB_ANON_KEY}\" --output types/database/index.ts",

With this cross-reference and knowledge, we know that we are missing out on wrapping the whole API endpoint in a string with escape characters. Then, we can modify our previous script to match this script.

"update-types": "npx openapi-typescript \"${SUPABASE_URL}/rest/v1/?apikey=${SUPABASE_ANON_KEY}\" --version=2 --output types/database/index.ts"

If we run this script locally via npm run update-types , we can see it generates the same output that we have done previously ✨

Out of curiosity, I also want to know if their GitHub workflow follows the same structure that was given in the example given in Supabase docs. The cool thing is with the Sourcegraph plugin, I can explore the repository in the editor itself.

Sadly, this project is not using the generate:types script that they have written in a GitHub workflow. They’re probably only running the npm script locally. Thankfully with the help of the Supabase documentation folks, at least we don’t have to write the action from scratch.

How to create the GitHub workflow

This section has been merged to Supabase documentation here after publication of this article.

To add GitHub action workflows to your project, you need a new folder .github/workflows to store the workflows. For the workflow.yml that consist the steps for the GitHub action workflow, we will be using the sample GitHub action workflow on the Supabase documentation as a base. I have modified it a little to insert some GitHub secrets as environment variables, you can refer to the comments below.

name: Update database types

on:
  schedule:
    # sets the action to run daily. You can modify this to run the action more or less frequently
    - cron: '0 0 * * *'
    # for the workflow to be dispatched manually via GitHub actions dashboards.
  workflow_dispatch:

jobs:
  update:
    runs-on: ubuntu-latest
    env:
        SUPABASE_URL: ${{secrets.SUPABASE_URL}}
        SUPABASE_ANON_KEY: ${{secrets.SUPABASE_URL}}
    steps:
      - uses: actions/checkout@v2
        with:
          persist-credentials: false
          fetch-depth: 0
      - uses: actions/setup-node@v2.1.5
        with:
          node-version: 14
      # -- add echo -- #
      - run: |
          npm run update-types 
          echo "$(cat types/database/index.ts)"
      - name: check for file changes
        id: git_status
        run: |
          echo "::set-output name=status::$(git status -s)"
      - name: Commit files
        if: ${{contains(steps.git_status.outputs.status, ' ')}}
        # -- change git stage filename -- #
        run: |
          git add types/database/index.ts
          git config --local user.email "41898282+github-actions[bot]@users.noreply.github.com"
          git config --local user.name "billy-github-actions[bot]"
          git commit -m "Update database types" -a
      - name: Push changes
        if: ${{contains(steps.git_status.outputs.status, ' ')}}
        uses: ad-m/github-push-action@master
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          branch: ${{ github.ref }}

The changes include:

Addition of a trigger workflow_dispatch so that the workflow can be dispatched manually via GitHub actions dashboards if necessary.
Addition of an echo statement to see the content of the result file from running update-types script
Pass GitHub action secrets into environment variables.
Change the filename to be staged

If you are not familiar with GitHub action secrets, think of it as separate environment variables solely for GitHub actions. This is a screenshot of where you can add them at the settings of your GitHub project.

To deploy the workflow, simply push the .github/workflows folder.

Then you will see the new workflow available in the Actions tab of your GitHub project. When you click on the additional options button, you can manually dispatch the workflow.

You can also view the logs of each workflow run if you encounter any issues. For example, here in the succeeded job, I can see the src/types/supabase.ts file content that is retrieved since we logged it out as part of the steps of the workflow.

In the next section, I’ll introduce you to a handy tool that I learnt while building a custom composite GitHub action to test GitHub actions locally.

How to test GitHub Actions locally with act

act is a tool that lets you test GitHub actions locally. The benefit of this is that you get faster feedback without clogging up the GitHub Action Runner history on your project.

Refer to the GitHub repository README.md to see how to install act. You would need Docker installed too. The first time you start up act, you will be asked to choose the image that you want to create. For this GitHub Action, to test the functionality of updating the database types, the Micro image should be sufficient.

After this config is completed, you can navigate to ~/.actrc to see the config for your docker image.

-P ubuntu-latest=node:16-buster-slim
-P ubuntu-20.04=node:16-buster-slim
-P ubuntu-18.04=node:16-buster-slim

Note that the Micro image does not have the full capability of a GitHub Action runner, so you will see errors related to git commands. I don’t want to explode my computer’s memory with the Large image (~20GB), but you can try if you like.

To run this workflow locally with act, we can run this bash command.

act -j update --secret-file .env

we can pass in the following parameters:

Explanation of parameters

-j ${jobName}
- we only have 1 job declared in this workflow, so we can pass the update job
--secret-file ${filePath}
- for the project, I am already using .env for all the environment variables, so I can pass this same file for secrets.
```
SUPABASE_URL=your_url
SUPABASE_ANON_KEY=hehe
```
- If you rather not have .env files locally for some reason, you can also pass variables manually with the parameter -s SUPBASE_URL=your_url -s SUPABASE_ANON_KEY=hehe

After running the bash command, here’s a simplified extract of the terminal output

[Update database types/update]   ✅  Success - actions/setup-node@v2.1.5
[Update database types/update] ⭐  Run npm run update-types
echo "$(cat src/types/supabase.ts)"
[Update database types/update]   🐳  docker exec cmd=[bash --noprofile --norc -e -o pipefail /var/run/act/workflow/2] user= workdir=
| 
| > billy@0.0.1 update-types /Users/lyqht/self-study/Billy
| > npx openapi-typescript "${SUPABASE_URL}/rest/v1/?apikey=${SUPABASE_ANON_KEY}" --version=2 --output src/types/supabase.ts
| 
| npx: installed 10 in 3.328s
| ✨ openapi-typescript 5.2.0
🚀 ***/rest/v1/?apikey=*** -> /Users/lyqht/self-study/Billy/src/types/supabase.ts [28ms]
| /**
|  * This file was auto-generated by openapi-typescript.
|  * Do not make direct changes to the file.
|  */
| 
| export interface paths {
|   "/": {
|     get: {
|       responses: {
|         /** OK */
|         200: unknown;
|       };
|     };
|   };
|   "/Bill": {
|     get: {
|     .... } // i won't show you all of it, but you will be able to see all these
[Update database types/update]   ✅  Success - npm run update-types
echo "$(cat src/types/supabase.ts)"
[Update database types/update] ⭐  Run check for file changes
[Update database types/update]   🐳  docker exec cmd=[bash --noprofile --norc -e -o pipefail /var/run/act/workflow/git_status] user= workdir=
| /var/run/act/workflow/git_status: line 2: git: command not found
[Update database types/update]   ⚙  ::set-output:: status=
[Update database types/update]   ✅  Success - check for file changes

If you run this, you can can see the output contains the paths portion for '/Bill' as a result of running the update-types script. This meant that it worked correctly 🎉

⚠️ Remember that these changes happen on the docker instance itself, you will not see any changes on your local folder.

Bonus: In Action

On 7 Apr 2022, I added 2 new tables, and my bot was a good boi.

Since publishing the original article, I also created a GitHub action that does what is listed above. Check it out here!

That's a wrap folks! 🎉

Thank you for reading, hope you enjoyed the article!

If you find the article awesome, hit the reactions 🧡 and share it 🐦~

To stay updated whenever I post new stuff, follow me on Twitter.

A Strange Moment.js — 3 Gotchas for Working & Testing with Datetimes

Estee Tey — Fri, 25 Mar 2022 16:57:43 +0000

Introduction to Moment.js

Moment.js is the most commonly used JavaScript library to deal with datetimes, however for many use cases today, it may not be the best library to use given the issues of mutability, file size bundles and that it was designed for the previous era of the JavaScript ecosystem. Even the library maintainers themselves discourage you to use Moment.js in new projects going forward.

Nonetheless, there are many developers who still have to work with this library because many existing production projects use it heavily, and it take significant effort to do a code revamp to migrate to use another immutable datetime library. Hence, this article is meant to highlight some strange gotchas for anyone who still has to deal with Moment.js. And for those who don’t have to, this article also serves as an interesting read for those who are curious about problems that can come from Moment.js & working with DateTime.

Some examples given here are inspired based on what I have done at work. There will also be Jest tests in the article to illustrate that the functionalities work as intended.

If you are not familiar with Jest or find it a bother to set it up, you can also simply console.log the relevant variables to check the values manually. Otherwise you can refer to the source code found here at this GitHub repository on how Jest can be setup for a simple Node.js project.

Gotcha 1: Mutability of DateTime objects

In many DateTime manipulation test cases, we would want to create DateTime objects in a chronological order. Instead of constantly writing hard coded values like “2022-03-21”, “2022-03-22”, I could create relative moment objects for testing.

const today = moment()
const oneWeekLater = today.add(1, "week")
const twoWeeksLater = today.add(2, "week")

However, when we log the 3 values, it turns out that they all have the same date.

today.format() // "2022-03-17T15:16:52.538Z"
oneWeekLater.format() // "2022-03-17T15:16:52.538Z"
twoWeeksLater.format() // "2022-03-17T15:16:52.538Z"

This is because it turns out that all 3 constants refer to the same moment object, with the same datetime value. When we perform .add, moment mutates the original object rather than mutating a copy of that object.

Solution: Clone the moment object

Hence, the solution to this problem is rather straight forward — we simply have to clone the moment object before performing arithmetic operations.

const today = moment()
const oneWeekLater = today.clone().add(1, "week")
const twoWeeksLater = today.clone().add(2, "week")

today.format() // "2022-03-17T15:16:52.538Z"
oneWeekLater.format() // "2022-03-24T15:16:52.538Z"
twoWeeksLater.format() // "2022-03-31T15:16:52.538Z"

That way, we will get 3 unique moment objects and their respective datetime values.

Gotcha 2: moment().isValid()

For backend applications, it is pretty common to validate that the properties found in the request body are the specified type that we expect them to be. For validating that the requestBody has a property of the DateTime string format, this is a simple way of how we can create a function to check it.

const isDateTimeValid = (requestBody) => {
    return moment(requestBody.dateTime).isValid()
}

This function does work as intended for the happy paths.

describe("isDateTimeValid", () => {
    it("YYYY-MM-DD", () => {
        const requestWithDate = {
            dateTime: "2020-11-12"
        }
        expect(isDateTimeValid(requestWithDate)).toBe(true)

    })

    it("YYYY-MM-DDThh:mm:ss", () => {
        const requestWithDateTime = {
            dateTime: "2022-03-17T10:00:00"
        }
        expect(isDateTimeValid(requestWithDateTime)).toBe(true)
    })

    it("ISO string", () => {
        const requestWithISOString = {
            dateTime: "2022-03-17T15:16:52.538Z"
        }
        expect(isDateTimeValid(requestWithISOString)).toBe(true)
    })
})

Running Jest, I get the following expected results.

PASS  ./momentjs.test.js
  isDateTimeValid
    ✓ should return true for YYYY-MM-DD (1 ms)
    ✓ should return true for YYYY-MM-DDThh:mm:ss (1 ms)
    ✓ should return true for ISO string (1 ms)

Now let’s write some sad paths. I will throw in null and some random values that don’t make sense as DateTime.

describe("isDateTimeValid", () => {
    it.each([
              null,
        1,
        -1,
        12312312,
        "hehe"
    ])("should return false for %p", (dateTime) => {
        const request = { dateTime }
        expect(isDateTimeValid(request)).toBe(false)
    })
}

Running Jest, I get the following results. It returned false for null and invalid string values, but not for numbers.

FAIL  ./momentjs.test.js
  isDateTimeValid
    ✓ should return true for YYYY-MM-DD (2 ms)
    ✓ should return true for YYYY-MM-DDThh:mm:ss (1 ms)
    ✓ should return true for ISO string
    ✓ should return false for null
    ✕ should return false for 1 (2 ms)
    ✕ should return false for -1
    ✕ should return false for 12312312
    ✓ should return false for "hehe" (7 ms)

This happens because if we try to create a moment with a generic number, we do get a datetime.

moment(1).format() // 1970-01-01T07:30:00+07:30
moment(-1).format() // 1970-01-01T07:29:59+07:30
moment(12312312).format() // 1970-01-01T10:55:12+07:30

Notice that all of these correspond to the same date, but with a different time.

This happens because Moment interprets number values that we pass to the constructor as the number of seconds since the Unix Epoch. Therefore, we will need to tweak our datetime validity method to make it work as intended for valid datetime strings.

Solution: Enable `strictMode`

A common solution to address these edge cases is to enforce strict mode. How it works is that we have to pass in a format that we are parsing the datetime, and set strict mode boolean as true.

moment(dateTime, "YYYY-MM-DD", true)

If you just change the validity function to use the above, then all the test cases that should be failing will fail correctly, and only the happy case of YYYY-MM-DD will pass.

FAIL  ./momentjs.test.js
  isDateTimeValid
    ✓ should return true for YYYY-MM-DD
    ✕ should return true for YYYY-MM-DDThh:mm:ss (1 ms)
    ✕ should return true for ISO string (1 ms)
    ✓ should return false for null (1 ms)
    ✓ should return false for 1
    ✓ should return false for -1
    ✓ should return false for 12312312 (1 ms)
    ✓ should return false for "hehe"

If we want the other 2 happy cases to continue passing, the solution is to use the ISO 8601 format, which allows for partial timestamps.

export const isDateTimeValid = (requestBody) => {
    return moment(requestBody.dateTime, moment.ISO_8601, true).isValid()
}

Now, all our tests pass correctly 🎉

PASS  ./momentjs.test.js
  isDateTimeValid
    ✓ should return true for YYYY-MM-DD
    ✓ should return true for YYYY-MM-DDThh:mm:ss
    ✓ should return true for ISO string
    ✓ should return false for null
    ✓ should return false for 1
    ✓ should return false for -1
    ✓ should return false for 12312312
    ✓ should return false for "hehe"

However, if we think about the problem we are trying to solve further — to validate the request body containing the datetime format — we should be standardizing the datetime format that we want to accept from our request body rather than allowing a loose list of datetime formats. This depends on the type of consumer that’s calling your API, but generally, the ISO string format in UTC is the safest to handle, since most databases & servers run on UTC by default.

Gotcha 3: Parsing DateTime strings

Many times, developers tend to use open source libraries without fully reading the documentation, and they spend hours fixing problems caused by lack of understanding of the fundamental concepts that the library is built upon. The DateTime string format parsed by Moment.js is one of such fundamental concepts which I’m guilty of just skimming over.

There was a time where I had to retrieve the weekday of a specific date. To do this in Moment.js, all we have to do is call the moment object’s .isoWeekday() function.

moment("2022-03-14").isoWeekday(); // 1 -> Monday
moment("2022-03-17").isoWeekday(); // 4 -> Thursday
moment("2022-03-20").isoWeekday(); // 7 -> Sunday

However, it is rather common for many databases to store some properties as DateTime even though the Date type could be sufficient. When we retrieve these date properties from the DB they would usually return in the format of “YYYY-MM-DDThh:m:ss.SSSZ”.

When we try to find the weekday of DateTime strings, you will notice a strange behavior.

// normal date
moment("2022-03-17").isoWeekday(); // 4 -> Thursday

// datetime retrieved from DB
moment("2022-03-17T22:16:52.538Z").isoWeekday(); // 5 -> Friday

// failed attempts to get the right date
moment("2022-03-17T22:16:52.538Z").startOf("day").format("YYYY-MM-DD"); // 2022-03-18
moment("2022-03-17T22:16:52.538Z").startOf("day").isoWeekday(); // 5 -> Friday

In the examples above, the date portion of the strings are all the same, but the weekday returned is different from expected. For me, the moment parses the DateTime as a day later than expected. For you, you may end up getting a different DateTime that what I’ve written there 😆 If it is indeed different, it is because of timezone differences.

World time buddy is a nice website to go to if you want to compare DateTime between different countries and regions.

If you are not familiar with timezone offsets, meeting this problem can be very frustrating. Here’s an illustration of the string format is parsed by Moment.js.

Having a ‘Z’ in the DateTime string meant that this DateTime string is given in UTC. This meant that if I am residing in Singapore, a GMT+8 timezone, when I use moment to parse this UTC DateTime string, I will get a local DateTime which is 8 hours ahead.

moment("2022-03-17T22:16:52.538Z").format() // 2022-03-18T06:16:52+08:00
moment("2022-03-17T22:16:52.538").format() // 2022-03-17T22:16:52+08:00

If somehow you are saving "2022-03-17T22:16:52.538Z" in your DB and this refers to DateTime in your local timezone rather than a DateTime in UTC (yes this happens 😂), there are 2 ways you can parse this correctly.

Solution 1

The first method is to simply chop off the ‘Z’ part, since it is what causes the timezone offset.

const dateTime = "2022-03-17T22:16:52.538Z"
moment(dateTime.splice(dateTime.length - 1, 1)).format() // 2022-03-17T22:16:52+08:00

Solution 2

The second method is more readable, which is to tell Moment.js explicitly that this DateTime string is actually not in UTC.

moment("2022-03-17T22:16:52.538Z").utc(false).format() // 2022-03-17T22:16:52+08:00

Now that we have a better understanding of how Moment.js parses DateTime strings and why this gotcha happens, remember how I was trying to find out the weekday of a given date?

Let me introduce you to a fun context for that! The problem will be presented in just dates rather than DateTime for simplicity, but you can certainly replace the dates below with DateTime strings and what you have learnt so far ✨

Use case: Find the most recent instance of a given weekday

Imagine that you are a backend developer who has to implement a special weekly check-in reward event for a game. Some requirements are:

Admins are able to configure a specific day of the week for players to check-in to this event e.g. Wednesday
The game has to call the API that you have created to get the most recent instance of Wednesday that the players can check in to the event, to determine whether to show them the most recent checkpoint that they have missed or show them that they can check in today.

Now let’s visualize the scenarios we have to address with some actual dates. Let’s start off with just dates.

Case 1: Get the given weekday from last week

For example, if today is Tuesday 15 March 2022, the most recent instance of Wednesday from this date will be Wednesday 9 March 2022.

This scenario can be translated into a test as such.

describe("getRecentInstanceOfWeekday", () => {
    it("should get last wednesday if today is tuesday", () => {
        expect(getRecentInstanceOfWeekday("2022-03-15", 3)).toBe("2022-03-09");
    })
})

Unfortunately, there isn’t such a utility function available in Moment.js. There are many use cases like this where we would have to write our own. However, that being said, Moment.js does provide arithmetic operations that could aid us in writing the solution.

To address the first test case, we can get the Wednesday of the previous week.

export const getRecentInstanceOfWeekday = (currentDate, dayOfTheWeek) => {
    return moment(currentDate).subtract(1, "weeks").day(dayOfTheWeek).format("YYYY-MM-DD")
}

Running Jest, the test case will pass as intended.

getRecentInstanceOfWeekday
    ✓ should get last wednesday if today is tuesday (5 ms)

Now let’s move to another scenario, where we should be getting the given weekday from current week instead.

Case 2: Get the given weekday from current week

If today is Thursday 17 March 2022, we should be getting Wednesday 16 March 2022.
Likewise if today is Wednesday 16 March 2022 itself, we should be getting Wednesday 16 March 2022.

This translates to the 2 new test cases below.

describe("getRecentInstanceOfWeekday", () => {
    it("should get last wednesday if today is tuesday", () => {
        expect(getRecentInstanceOfWeekday("2022-03-15", 3)).toBe("2022-03-09");
    })

    it("should return this week's wednesday if today is thursday", () => {
        expect(getRecentInstanceOfWeekday("2022-03-17", 3)).toBe("2022-03-16");
    })

    it("should return today if today is wednesday", () => {
        expect(getRecentInstanceOfWeekday("2022-03-16", 3)).toBe("2022-03-16");
    })
})

However, with our previous implementation, when we run this test with Jest, we will see the following test failure results.

● getRecentInstanceOfWeekday › should return this week's wednesday if today is thursday

    expect(received).toBe(expected) // Object.is equality

    Expected: "2022-03-16"
    Received: "2022-03-09"

      42 |
      43 |     it("should return this week's wednesday if today is thursday", () => {
    > 44 |         expect(getRecentInstanceOfWeekday("2022-03-17", 3)).toBe("2022-03-16");
         |                                                             ^
      45 |     })

● getRecentInstanceOfWeekday › should return today if today is wednesday

    expect(received).toBe(expected) // Object.is equality

    Expected: "2022-03-16"
    Received: "2022-03-09"

      46 |
      47 |     it("should return today if today is wednesday", () => {
    > 48 |         expect(getRecentInstanceOfWeekday("2022-03-16", 3)).toBe("2022-03-16");
         |                                                             ^
      49 |     })
      50 | })

Solution

With the test cases we have written, we notice a pattern:

if today is on a weekday < Wednesday, we return the Wednesday of the previous week
if today is on a weekday ≥ Wednesday, we return the Wednesday of the current week

Knowing this pattern and how isoWeekday() works, we can write a solution.

export const getRecentInstanceOfWeekday = (currentDate, dayOfTheWeek) => {
    if (moment(currentDate).isoWeekday() < dayOfTheWeek) {
        return moment(currentDate).subtract(1, "weeks").isoWeekday(dayOfTheWeek).format("YYYY-MM-DD")
    }

    return moment(currentDate).isoWeekday(dayOfTheWeek).format("YYYY-MM-DD");
}

Now, the previous tests will pass.

PASS  ./momentjs.test.js
  getRecentInstanceOfWeekday
    ✓ should get last wednesday if today is tuesday (1 ms)
    ✓ should return this week's wednesday if today is thursday
    ✓ should return today if today is wednesday (1 ms)

We can also write more test cases and generalize them as such in Jest.

describe("getRecentInstanceOfWeekday", () => {
    it.each([
        ["given day is Wed, when today is Tue", "2022-03-15", 3, "2022-03-09"],
        ["given day is Wed, when today is Mon", "2022-03-14", 3, "2022-03-09"],
    ])
    ("should return given weekday from last week - %s", 
    (testCase, today, givenWeekday, expectedDate) => {
        expect(getRecentInstanceOfWeekday(today, givenWeekday)).toBe(expectedDate);
    })

    it.each([
        ["given day is Wed, when today is Wed (same day)", "2022-03-16", 3, "2022-03-16"],
        ["given day is Wed, when today is Thu", "2022-03-17", 3, "2022-03-16"],
        ["given day is Wed, when today is Sun", "2022-03-20", 3, "2022-03-16"],
    ])
    ("should return given weekday from current week - %s", 
    (testCase, today, givenWeekday, expectedDate) => {
        expect(getRecentInstanceOfWeekday(today, givenWeekday)).toBe(expectedDate);
    })
})

And these too will continue to pass 🎉

PASS  ./momentjs.test.js
  getRecentInstanceOfWeekday
    ✓ should return given weekday from last week - given day is Wed, when today is Tue
    ✓ should return given weekday from last week - given day is Wed, when today is Mon
    ✓ should return given weekday from current week - given day is Wed, when today is Wed (same day)
    ✓ should return given weekday from current week - given day is Wed, when today is Thu
    ✓ should return given weekday from current week - given day is Wed, when today is Sat

Conclusion

Working with Date and DateTime objects is a pain in the ass even with libraries that help you to deal with them — but it gets better! Once you know that certain gotchas exist and you have more experience with interesting use cases, you will know the edge cases to look out for. Translating requirements into tests will also help you build more confidence in the functionalities that you are delivering ✨

Below are some additional resources if you are keen to explore further.

Resources

For a deeper dive into datetime manipulation before you even consider using a datetime library, Punit Jajodia wrote The Definitive Guide to DateTime Manipulation.
Why Moment.js library maintainers recommend you not to use Moment.js for newer projects on their landing page.
For those of you who are starting out on new projects and have a choice to use a different datetime library, give Day.js a try! It mimics moment.js API, but better in many ways. This article by Sabesan Sathananthan covers on why you should choose day.js instead of moment.js.
Special Considerations for months and years by Moment.js documentation

That's a wrap folks! 🎉

Thank you for reading, hope you enjoyed the article!

✨ Special thanks to Shaun Chiang & Kah Yee Kwa for pairing with me to work on interesting DateTime scenarios.

If you find the article awesome, hit the reactions 🧡 and share it 🐦~

To stay updated whenever I post new stuff, follow me on Twitter.

Nevertheless, Estee Coded

Estee Tey — Mon, 07 Mar 2022 19:07:20 +0000

Hi, I'm Estee and you can call me ST. My pronouns are She/He, because I don't really feel strongly about my gender in either ways. If I'm playing games, my friends know that I could be very manly in my playing style and if I see cockroaches, you will see me shrieking like a girl. Yes, you can dispute that either gender can be reacting in the same way, and that's a point that I hope more people are aware about when they meet people. It was only by chance, I was born as a girl.

I gave a brief glimpse of my coding background in an interview with the CodeNewbie Community previously, but here's a more complete digest of my background in tech & tech career.

Background in Tech

First experience with coding at age 21, nearing the end of 1st year of university due to freshmore curriculum.
In university, I tried to cover ground in various parts of the tech industry because I didn't know what I really wanted to do in tech, even though I didn't mind the idea of coding for a living.
- In the 2.5 years of school curriculum under the Infosystems major, I learnt introductory concepts on android app development in Java, algorithms, machine learning, data science, game development with Unity.
- Outside of school, I signed up for courses by myself to learn about Internet of Things (IOT), mixed reality app development for HoloLens 2, Blockchain Development.
- Out of all of these, I only enjoyed the app & game development courses 😆
- I also had 1 internship in IT project management, and 1 internship as a Software Engineer.
Eventually, I graduated in a bad time when COVID hit pretty hard, September 2020.
- Because of that, a full-time job offer I attained in March 2020 got pushed back to an indefinite date.
- Nevertheless, life goes on, and bills had to be paid. So I just applied for another job during my finals and I became a Software Engineer trainee for another company in the mean time.
- The former offer did eventually got back for me to start working in Jan 2021.
I've worked in a global tech consultancy company as a Software Developer since then, and I've gotten to work on 5 different projects since my time there.

Working in tech

I've made a twitter thread previously on my WFH experience based on the 1st 4 projects that I worked on in my current job.

// Detect dark theme var iframe = document.getElementById('tweet-1476213935908868097-477'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1476213935908868097&theme=dark" }

For my current project (5th project) that I'm in now, it is very technically challenging compared to all the previous projects for me. The tough part is not the tech stack, but rather understanding the complexity of the system design of microservices, and also to perform technical solutioning with a lot of ambiguity under high pressure from the client.

Nevertheless, I'm excited to learn more in-depth about all of these including the tech stack which comprises of React, React Native, Typescript, Express, Kubernetes, Azure Platform.

I would also be looking forward to building more side projects to learn stuff that I don't get to do at work, and teaching developers like you on various concepts through the technical articles that I write.

Some concluding thoughts

I'm lucky enough to be born in Singapore, a place where women are less discriminated albeit the fact that there is still a very low gender ratio for the tech industry. Honestly, if it is a fact that girls are just not as interested in tech, then so be it. But if they are interested and they are denied opportunities just because of being a "She", then that's another story.

I hope that people will look at individuals via traits more rather than just using the gender label as a convenient way to group people into boxes to be shoved into areas outside their comfort zone.

People are like onions, with many layers deep. Some when you cut it, it will make you cry. But some when you fry it, it's pretty tasty.

How to create a CSS Playground for styling Pseudo-elements with Vanilla JavaScript

Estee Tey — Mon, 07 Feb 2022 04:18:16 +0000

In this article, I will show you how to implement 3 features that I thought to be valuable of a CSS playground (here's the why section if you want to learn why before how) using CSS and Vanilla JavaScript.

Live Preview
Export CSS Functionality
CSS Validation

The steps for implementation will be based on the previous playground that I personally made.

💡 There will be checkpoints across the article where I'll embed a codepen for the progress thus far, so feel free to fork those to continue if you ever get lost. If you ever just want to see the completed product, you can refer to the source code at the GitHub repository.

The CSS Playground

Scrollbar playground is a project that I made previously for users to learn to create a custom scrollbar.

The project structure is very small and mimics the usual structure of a CodePen (1 file each for HTML, CSS & JavaScript).
The challenge of creating this particular playground is that the scrollbar can only be styled using pseudo-elements, which are style selectors that you cannot set directly say using element.style.position= 'absolute'. There's no such thing as element.style.scrollbarProperty. In this article, you will learn later how to indirectly manipulate the value of the pseudo-element properties.

These are the features that have been implemented in the playground:

Live preview → Users have multiple configuration settings such as sizes & colors, and are able to see changes on a live preview. Users can also play with the live preview by resizing the div and scrolling up & down at the div.
Export Button → Users can obtain the styles they want on their clipboard and paste it easily over to their own project. They could even paste over to a new CodePen to test and see it work immediately with a very tall div.

Now let’s dive into an implementation of the most essential feature of playgrounds - live preview.

1. Live Preview

CSS Custom Properties (also known as CSS Variables) is a concept that I used for implementing the live preview. Here, we will go through 2 types of properties that are available for configuration which you can observe from the previous screenshot - sizes & colors.

Here’s the HTML for the preview area.

<div id='preview'>
    <p class='inner-content'>
        Text generated by Cat Ipsum. 
    </p>
</div>

Most live previews exist as a 2 column layout, so let's do that too.

2 column layout On HTML.

Remember to add some lorem ipsum text into the inner content so that the scrollbars will show up. Scrollbars only show up if the content exceeds the height/width of a container.

<body>
    <div id='preview'>
        <p class='inner-content'>
            Text generated by Cat Ipsum. 
            <!-- add more text here -->
        </p>
    </div>
    <div id='form-container'>
       <div id='form'>
       <!-- for user config settings later -->
       </div>
    </div>
</body

2 column layout via CSS

body {
    display: flex;
    flex-direction: row;
    margin: auto;
    padding: 24px;
    color: white;
    background-color: #000000;
    height: 100%;
}

#form-container {
  width: 50%;
  min-width: 30%;
  display: flex;
  align-items: center;
  justify-items: center;
}

#form {
  display: flex;
  justify-items: center;
  flex-direction: column;
}

Then we can style the preview with CSS. The only important CSS for a scrollbar live preview are:

resize: both -> this allows users to resize however they want to see the effect of the scrollbar extending/shrinking
overflow: auto -> this allows user to see the scrollbar on both horizontal & vertical sides of the div.

#preview {
    margin: auto;
    width: 300px;
    height: 400px;
    resize: both; 
    overflow: auto; 
    display: grid;
    place-items: center;
    border-radius: 6px;
    border: 1px solid white;
    color: black;
    background: rgba(255, 255, 255, 0.8);
}

When you're working on your own playground on another topic, be creative on how you want to the structure the layout and style the preview 🎵

Now that we got the basic layout of the live preview done, let's begin to create the playground!

Size Properties

Let’s start with just 1 size configuration, say the scrollbar’s width.

Create a HTML text input for the user to input the scrollbar’s width.

<div>
    <label for="scrollbar-width">Scrollbar Width (px)</label>
    <input id="scrollbar-width" name="scrollbar-width" type="number" min="0" step="10" value="20" />
</div>

Add a CSS pseudo-element value that is set by a CSS variable with fallback default value in the main stylesheet.
```
#preview::-webkit-scrollbar {
    width: var(--scrollbar-width, 20px);
}
```
Once you add this pseudo-element style, you can no longer see the scrollbar 👀 This is an interesting finding I came across while learning about the scrollbar as well. Somehow, by adding 1 scrollbar pseudo-element, you are nullifying the rest of the default scrollbar pseudo-elements as well. I don't know why this CSS is designed this way, but we just have to work around it. For now, to see the scrollbar, we can add basic colors to the scrollbar thumb and track.
```
#preview::-webkit-scrollbar-track {
   background: #A1A1AA;
}

#preview::-webkit-scrollbar-thumb {
   background: #3B82F6;
}
```
Add JavaScript code to get the user’s input for the scrollbar width setting and set it as the live preview container’s scrollbar width. Notice here that we are not setting the pseudo-element directly; we are updating the pseudo-element indirectly by updating the CSS variable that it is tied to.
```
const scrollbarDiv = document.getElementById("preview")
const widthInput = document.getElementById("scrollbar-width")

widthInput.onchange = () => { 
  scrollbarDiv.style.setProperty("--scrollbar-width", `${widthInput.value}px`) 
}
```

And there we have 1 size property that can be be configured by the user and you can see the preview rendering the changes live! ✨

You can imagine the flow to be pretty similar for the scrollbar height & border radius as well. With more size properties that can be configured, the code can get a little messy. This is a way you can choose to refactor the JavaScript code so that it’s more readable and obvious how to add new inputs.

Refactoring size property configuration

Declare a size property array that consists of objects that maps the element & the CSS property that they are intended to update. e.g.
```
{
    el: heightInput,
    property: "--scrollbar-height"
}
```

Create a common update function that takes an input element & property to set the style appropriately for the live preview.

const setSizeFieldOnChange = (el, property) => {
    el.onchange = () => { scrollbarDiv.style.setProperty(property, `${el.value}px`) }
}

Then for each size property, set the onChange function to the common update function.

sizePropertyArray.forEach(({ el, property }) => setSizeFieldOnChange(el, property))

With the addition of 2 other size properties, this leads to the final size property configuration JavaScript code being

const scrollbarDiv = document.getElementById("preview")
const heightInput = document.getElementById("scrollbar-height")
const widthInput = document.getElementById("scrollbar-width")
const borderRadiusInput = document.getElementById("scrollbar-border-radius")

const sizePropertyArray = [
    {
        el: heightInput,
        property: "--scrollbar-height"
    },
    {
        el: widthInput,
        property: "--scrollbar-width"
    },
    {
        el: borderRadiusInput,
        property: "--scrollbar-border-radius"
    }
]

const setSizeFieldOnChange = (el, property) => {
    el.onchange = () => { scrollbarDiv.style.setProperty(property, `${el.value}px`) }
}

sizePropertyArray.forEach(({ el, property }) => setSizeFieldOnChange(el, property))

Now let’s move on to color properties.

Color Properties

For the color picker component, we will be using an external library because it isn’t really worth the effort to write one from scratch when it’s not the focus of the playground. For this article, I’m using Pickr, and it has a CDN link for the library & styles which we can import by including the following script in the head element. Since we are adding importing external scripts now, I'll also add a Google font for styling.

<head>
    <script src="https://cdn.jsdelivr.net/npm/@simonwep/pickr/dist/pickr.min.js"> </script>
    <link href="https://fonts.googleapis.com/css2?family=PT+Mono&display=swap" rel="stylesheet">
    <link rel="stylesheet" href="index.css">
    <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@simonwep/pickr/dist/themes/nano.min.css"></head>

To use the font in your project, just set the font-family wherever you want.

body {
  font-family: "PT Mono", monospace;
}

Now, let’s begin with just 1 color configuration, say the scrollbar’s thumb.

Create a HTML button for the user to bring up the color picker.

<div>
    <label for="scrollbar-thumb-color">Thumb</label>
    <button id="thumb-color-picker" title="thumb-color-picker" />
</div>

Add a CSS pseudo-element value that is set by a CSS variable with fallback default value in the main stylesheet.
```
#preview::-webkit-scrollbar-thumb {
    background: var(--scrollbar-thumb-color, #3B82F6);
}
```

Add JavaScript to create a color picker and bind it to an element. The Pickr creation code looks a little long, but the API is rather intuitive.

const thumbColorElement = document.querySelector("#thumb-color-picker")
const pickr = Pickr.create({
        el: thumbColorElement,
        default: '#3B82F6',
        theme: 'nano',
        swatches: [
            'rgba(244, 67, 54, 1)',
            'rgba(233, 30, 99, 0.95)',
            'rgba(156, 39, 176, 0.9)',
            'rgba(103, 58, 183, 0.85)',
            'rgba(63, 81, 181, 0.8)',
            'rgba(33, 150, 243, 0.75)',
            'rgba(3, 169, 244, 0.7)',
            'rgba(0, 188, 212, 0.7)',
            'rgba(0, 150, 136, 0.75)',
            'rgba(76, 175, 80, 0.8)',
            'rgba(139, 195, 74, 0.85)',
            'rgba(205, 220, 57, 0.9)',
            'rgba(255, 235, 59, 0.95)',
            'rgba(255, 193, 7, 1)'
        ],
        comparison: false,
        components: {
            preview: true,
            opacity: true,
            hue: true,
            interaction: {
                hex: true,
                rgba: true,
                hsla: true,
                hsva: true,
                cmyk: true,
                input: true,
                clear: true,
                save: true
            }
        }
    });

If you are keen to configure more settings at the Pickr component, you can refer to the official Pickr docs.

Then, we also need to add a function to update the the live preview container’s scrollbar thumb color when the user selects a color from the color picker. This is again done by updating the CSS variable.
```
pickr.on('change', (color, instance) => {
        scrollbarDiv.style.setProperty("--scrollbar-thumb-color", color.toHEXA()) 
}
```

With that, you will be able to see the thumb color being changed when the user selects a new color ✨ Likewise, for other colors, we can perform a similar procedure. However, for the color properties, this introduces a lot more bulk code than the size properties due to how long the Pickr creation & binding code is. Hence, it becomes quite important for us to refactor the code.

Refactoring color configuration

Create a common method which does the common pickr creation & binding logic. The overlapping parameters are the input element, the CSS variable to be updated and the default color we want the color pickr to display.

const bindColorPickr = (el, property, defaultColor) => {
    const pickr = Pickr.create({
        el,
        default: defaultColor,
                // the rest of the creation parameters is the same
  })
    pickr.on('change', (color, instance) => {
        scrollbarDiv.style.setProperty(property, color.toHEXA())
}

Declare an array of objects which resembles the size property array that we had earlier on for the color properties that can be configured.

const colorsPropertyArray = [
    {
        el: "#thumb-color-picker",
        property: "--scrollbar-thumb-color",
        defaultColor: "#3B82F6"
    },
    {
        el: "#track-color-picker",
        property: "--scrollbar-track-color",
        defaultColor: "#A1A1AA"
    },
    {
        el: "#button-color-picker",
        property: "--scrollbar-button-color",
        defaultColor: "#3F3F46"
    },
    {
        el: "#corner-color-picker",
        property: "--scrollbar-corner-color",
        defaultColor: "#FFFFFF"
    },
    {
        el: "#border-color-picker",
        property: "--scrollbar-border-color",
        defaultColor: "#FFFFFF"
    },
]

Then for each color property, we will bind the common function.

colorsPropertyArray.forEach(({ el, property, defaultColor }) => bindColorPicker(el, property, defaultColor))

This leads to the overall color configuration code being

const bindColorPicker = (el, property, defaultColor) => {
    const pickr = Pickr.create({
        el,
        default: defaultColor,
        theme: 'nano',
        swatches: [
            'rgba(244, 67, 54, 1)',
            'rgba(233, 30, 99, 0.95)',
            'rgba(156, 39, 176, 0.9)',
            'rgba(103, 58, 183, 0.85)',
            'rgba(63, 81, 181, 0.8)',
            'rgba(33, 150, 243, 0.75)',
            'rgba(3, 169, 244, 0.7)',
            'rgba(0, 188, 212, 0.7)',
            'rgba(0, 150, 136, 0.75)',
            'rgba(76, 175, 80, 0.8)',
            'rgba(139, 195, 74, 0.85)',
            'rgba(205, 220, 57, 0.9)',
            'rgba(255, 235, 59, 0.95)',
            'rgba(255, 193, 7, 1)'
        ],
        comparison: false,
        components: {
            preview: true,
            opacity: true,
            hue: true,
            interaction: {
                hex: true,
                rgba: true,
                hsla: true,
                hsva: true,
                cmyk: true,
                input: true,
                clear: true,
                save: true
            }
        }
    });

    pickr.on('change', (color, instance) => {
        scrollbarDiv.style.setProperty(property, color.toHEXA())
    }).on('save', () => { })
}

const colorsPropertyArray = [
    {
        el: "#thumb-color-picker",
        property: "--scrollbar-thumb-color",
        defaultColor: "#3B82F6"
    },
    {
        el: "#track-color-picker",
        property: "--scrollbar-track-color",
        defaultColor: "#A1A1AA"
    },
    {
        el: "#corner-color-picker",
        property: "--scrollbar-corner-color",
        defaultColor: "#FFFFFF"
    },
]

colorsPropertyArray.forEach(({ el, property, defaultColor }) => bindColorPicker(el, property, defaultColor))

We can also structure the layout of how the color inputs are presented to the user since having all of them in a column looks funny too.

#color-inputs {
    padding: 16px;o
    display: grid;
    grid-template-columns: 1fr 1fr 1fr;
}

#color-inputs>div {
    display: grid;
    place-items: center;
    margin-block-end: 16px;
}

And finally, the live preview our scrollbar playground is completed!

🎉 Good job, you have learnt how to create a simple CSS playground with vanilla JS using CSS variables for size and color properties! The same concepts and thinking process can be applied to other types of properties that you would like your users to play with in the playground - be it pseudo-elements or other CSS selectors 😊

The actual scrollbar playground has a few more config settings, they are excluded intentionally since the principles to implement them are the same as what you just learnt.

The next section will be on adding an export CSS button to your app - a good to have feature for playgrounds.

2. Export CSS Functionality

This section will be covering the export css functionality. I'll leave it to you to design the export CSS button however you want 🌻

For us to export CSS, we need a way to access the existing CSS rules in our app. For that, we can use document.styleSheets to access the array of stylesheets that are used by a website. The order of the stylesheets depends on how you declare the sequence of imports in your app.

Try it out in your browser console on any website ✨

For my project, these are 3 stylesheets used by the HTML document by order:

imported stylesheet for google fonts in index.css
index.css
imported stylesheet for pickr styling

Hence, for us to access the css rules that are declared locally in index.css, we can access the cssRules property in the stylesheet object as such

document.styleSheets[1].cssRules

If you are trying to develop a playground website locally, on Google Chrome, you may notice the following error when you try to access the css rules.

This happens because accessing css rules violates a CORS policy implemented by Google Chrome, and is further discussed in this StackOverflow thread.

Basically, in order to read these rules from the website on your local machine, you have to set up a local testing server. I followed the MDN docs on setting up a local testing server, which just requires to run the below command in bash.

python3 -m http.server

Now, we will be able to access our local website at http:localhost:8000, where we can access stylesheet.cssRules. However, the index.css has other playground layout styles aside from just the scrollbar styles. This meant that we have to perform the following actions:

We will need to filter them out and get only the scrollbar styles to be exported for the user. Let this be exportedStyle
We can also help the user to replace the selector #preview to something more generic like body so that they can test it easily on an empty CodePen. So our exported style will look something like

  let exportedStyle = 'body { ... }'

This leads to the overall code being

const scrollbarDiv = document.getElementById("preview")
const customProperties = scrollbarDiv.style.cssText
const defaultElementForStyling = "body"

let exportedStyle = `${defaultElementForStyling} { ${customProperties} } `

const cssRules = Object.values(document.styleSheets[1].cssRules)
const scrollbarRules = cssRules.filter(rule => rule.cssText.includes('::-webkit-scrollbar'))
    scrollbarRules.forEach(rule => {
        const modifiedRule = rule.cssText.replace("#preview", defaultElementForStyling)
        exportedStyle += modifiedRule

After we get the exported styles as a string, we want to put them at the user's clipboard so they can paste them to their own project. To do so, we can use the Navigator clipboard Web API.

navigator.clipboard.writeText(exportedStyle)

The clipboard API does not work through an iframe usually, but here's a handy monkey-patch by Thai Pangsakulyanont if you really want it to work on a clipboard. You can refer to the codepen to see how this is added in the .js file.
import('https://cdn.skypack.dev/copy-to-clipboard').then(a => navigator.clipboard.writeText = a.default)

In addition to copying to the user's clipboard, we should also show some indicator to tell the user that they did copy the text. For my playground, I added the following text element next to the export button in HTML.

<div id="export-button-container">
    <button id='export-css'>Export CSS</button>
    <p id='export-css-hint'></p>
</div>

Add an initial style to not show this text element


#export-button-container {
    position: relative;
    display: grid;
    place-items: center;
    margin: 16px;
}

#export-button-container>button {
    padding: 12px;
    border-radius: 8px;
}

#export-css-hint {
    opacity: 0;
    color: skyblue;
    left: 60%;
    position: absolute;
    transition: 0.3s;
}

Then after we put the exported styles on the user's clipboard, we can show this text element to fade in, and then fade out after a short while.

const exportCSSHint = document.getElementById('export-css-hint')
navigator.clipboard.writeText(exportedStyle)
exportCSSHint.textContent = 'Copied'
exportCSSHint.style.opacity = 1;
setTimeout(() => {
    exportCSSHint.style.opacity = 0;
}, 1500)

This leads to the final overall code for the export CSS functionality.

const exportCSSButton = document.getElementById('export-css')

exportCSSButton.onclick = async () => {
    let customProperties = scrollbarDiv.style.cssText.length > 0 ? scrollbarDiv.style.cssText : defaultCSSProperties
    let exportedStyle = `${defaultElementForStyling} { ${customProperties} } `
    const cssRules = Object.values(document.styleSheets[1].cssRules) // Google font styles were loaded first before index.css
    const scrollbarRules = cssRules.filter(rule => rule.cssText.includes('::-webkit-scrollbar'))
    scrollbarRules.forEach(rule => {
        const modifiedRule = rule.cssText.replace("#preview", defaultElementForStyling)
        exportedStyle += modifiedRule
    });

    navigator.clipboard.writeText(exportedStyle)
    exportCSSHint.textContent = 'Copied'
    exportCSSHint.style.opacity = 1;
    setTimeout(() => {
        exportCSSHint.style.opacity = 0;
    }, 1500)
}

Great! Now your playground also has the quintessential feature of a generator app ✨ What else is left? Well, the next part will be crucial if you want to work on a playground that allows for raw user input for styling 🚨

3. Validate CSS

This is the third feature which I didn’t include previously in the table of features for playgrounds and generators, it is not commonly thought up of & actually implemented. I couldn't find any guides out there that teaches you how to even do this.

Ideally, when it comes to exporting content for users to use, for a better user experience, we try to make sure that our users don’t even get invalid data e.g. unopenable files, wrong syntax etc. This is because we would be causing trouble for our users who have to spend time to troubleshoot whether it's because they used the exported results wrongly or the exported results are actually invalid.

Hence, it will be great if we could validate our CSS before we give it to the user. For CSS, invalid styles may be exported in a few ways.

Missing edge case handling due to browser support differences.
If the user is allowed to pass in raw CSS input through a text input, sometimes the users may be unfamiliar with CSS and give an invalid CSS. Some users may even intentionally give trash input just to test the system.
The CSS variables could even be updated incorrectly by the developer > e.g. there was once I accidentally removed an additional semicolon in creating the string of exported styles 😆 of course it never made it to production.

Won’t it be great if there’s a CSS validation service? Well, the official W3C does offer a CSS validation service.

The service works great! However, there are a few problems.

The website doesn’t make the API documentation very obvious.
1. If you look at developer resources, the page for Web Service API only states a single example that follow the SOAP (Simple Object Access Protocol) format.
2. To be honest... I haven’t worked with SOAP before despite coding for a few years. I don’t plan to learn it unless I really have to in legacy projects, and I think most of the newer devs wouldn’t know of this format too 😅
The actual generic API documentation is found under the “Experts only” section of the User Manual. Come on, I don’t need to be an expert to use an API 😂
The actual output by the API is very verbose. Here’s an example when I tried to call the API via Postman with the default output format of html. Regardless which output format you choose, be it html/xhtml/soap12/text, all of them will give you similar results.

Luckily, I got some tips from the maintainer of css-validation, Todd Wolfson on how to parse that verbose result. He introduced me to the DOMParser, a Web API.

With this API, we can parse the HTML document we received from the W3C validation service like a normal HTML.
Inspecting the HTML, we can also see that there will be td.error elements if there are errors.

With these knowledge, we can write a validate CSS function which makes an API call and parse the result for validation errors.

const validateCSS = async (cssStylesInText) => {
    const encodedStyles = encodeURI(cssStylesInText)
    const cssValidationResponse = await fetch(`https://jigsaw.w3.org/css-validator/validator?profile=css3&text=${encodedStyles}`);
    const cssValidationResponseText = await cssValidationResponse.text();
    const parser = new DOMParser();
    const validationDoc = parser.parseFromString(cssValidationResponseText, "text/html")
    const validationErrors = validationDoc.getElementsByClassName("error");
    return validationErrors;
}

Then we can simply check whether there are any validation errors before we give the exported results to the user 🔍 You can throw a toast or whatever to let the user know of the validation errors. For my project, this is unlikely to happen since all of my inputs are controlled so I didn't do that part.

This leads to the overall code for the export CSS functionality + CSS validation.

const validateCSS = async (cssStylesInText) => {
    const encodedStyles = encodeURI(cssStylesInText)
    const cssValidationResponse = await fetch(`https://jigsaw.w3.org/css-validator/validator?profile=css3&text=${encodedStyles}`);
    const cssValidationResponseText = await cssValidationResponse.text();
    const parser = new DOMParser();
    const validationDoc = parser.parseFromString(cssValidationResponseText, "text/html")
    const validationErrors = validationDoc.getElementsByClassName("error");
    return validationErrors;
}

exportCSSButton.onclick = async () => {
    let customProperties = scrollbarDiv.style.cssText
    let exportedStyle = `${defaultElementForStyling} { ${customProperties} } `
    const cssRules = Object.values(document.styleSheets[1].cssRules)
    const scrollbarRules = cssRules.filter(rule => rule.cssText.includes('::-webkit-scrollbar'))
    scrollbarRules.forEach(rule => {
        const modifiedRule = rule.cssText.replace("#preview", defaultElementForStyling)
        exportedStyle += modifiedRule
    });

    const cssValidationErrorsCollection = await validateCSS(exportedStyle)
    if (Object.keys(cssValidationErrorsCollection).length === 0) {
        console.log("No CSS validation errors found by W3C")
        navigator.clipboard.writeText(exportedStyle)
        exportCSSHint.textContent = 'Copied'
        exportCSSHint.style.opacity = 1;
        setTimeout(() => {
            exportCSSHint.style.opacity = 0;
        }, 1500)
    } else {
        console.log({cssValidationErrorsCollection})
        // add your own logic to parse the errors into readable text for your users
    }
}

🎉 We finished the 3rd feature and now, we are done for realz!

If you are keen in CSS validation for testing in web apps that are not pure Vanilla JavaScript, here are 2 libraries you can try out.

css-validation - a simple library that uses W3C's validation service like what is shown above, and intended to run on NodeJS.
css-tree/validator - a more advanced library that performs validation via CSSTree parsing, and offers more customization on validation.

Generating playgrounds

After all of that, if you don't want to do so much work in the configuration logic & styling of the playground itself, there are a few solutions below.

CSS Playground

CSS Playground is a website that helps you to generate your own CSS playground. Here's an example playground on Clipping Paths with clip-path created by the website maintainer. The theme is heavily Material Design, with designated layouts for configs, documentation, etc.

Storybook

Storybook is a library that offers many features to help you showcase UI components, particularly that of design systems, which can be implemented on different frontend frameworks e.g. React, Vue, etc. Check out the list of storybook examples.

Now that you know how to create your own CSS playground from vanilla JavaScript and also possible ways to generate a CSS playground, below is an optional overview on the concept of playgrounds.

The concept of Playgrounds

This section is a short opinionated lore on how playgrounds are helpful and how it is different from a generator. Feel free to skip this if you are not particularly keen in semantics.

The first website that I learnt CSS 5 years ago from was W3C, since it has always been the first search result that shows up in Google. I didn’t know of other resources at that time, but I really liked that for every concept, there is always a “Try it Yourself” button so that I could experiment with what I learnt, however I want. Today, there are more established platforms like CodePen, CodeSandbox, StackBlitz, Expo Snack etc where you get to write code on a browser editor on multiple files and seeing your changes get compiled and rendered on the fly.

With such technology, playgrounds became a norm to help developers learn technical concepts and frameworks better, as they often help to complement information that is difficult to captured by plain text documentation through user interactions. "Playground" is a term often used interchangeably with a "generator" since they could be quite similar in terms of the features they offer, but in the macro perspective, their objective is different.

The two have a different value proposition, as such

There will be a difference in the way the user interface is designed between a playground and a generator app.
The priority of feature implementation by the developer will also be different.

The value of a generator seem to match more with that of no-code tools, software where users can create their own software products without knowing how to code, as a compared to a playground where the value is to have fun. This is also a reason why I named my project as a playground rather than a generator - the export feature was more of an after-thought rather than planned from the start of the project.

Anyways, now that you understand better the semantic of a playground vs a generator. Below are some references which may help to inspire you to create your own playground or no-code tool. ✨

Idea inspirations

Exploring specific CSS concepts

Free & Macro CSS generators

Productised Generators

That's a wrap folks! 🎉

Thank you for reading, hope you enjoyed the article! Scrollbar playground is open to feature requests btw. Feel free to create issues and star the project if you find it cool 😊

If you find the article awesome, hit the reactions 🧡 and share it 🐦~

To stay updated whenever I post new stuff, follow me on Twitter.

Introduction to Enterprise Backend Development: Service Design Considerations

Estee Tey — Thu, 13 Jan 2022 16:54:08 +0000

In enterprise projects, you would often be thrown to work on a random spot of a very big system rather than building services one by one from ground up like start-ups. Hence, it could be much more difficult to grasp and piece together the different backend concepts when you are not even sure where or what is the head and tail of the architecture. This article aims to help you to get a better footing of the things to look out for in an enterprise backend development project.

Introduction to enterprise backend development

At a high level, Enterprise backend development can be described in terms of 3 concepts - Domain, Framework and Service Types.

Domain:
- Payments is an often cited domain because transaction-related issues such as concurrency & performance become more salient to be addressed.
- Other domains include health data, vehicles etc. Literally anything can be a domain.
Framework:
- Spring Boot is a popular choice of Java-based opinionated framework for creating backend applications.
- Frameworks from other languages include Flask, Django, Express, Ruby on Rails, CakePHP.
Types of Backend Services commonly built:
1. Domain Service: this service that is responsible for most business logic related features
2. Scheduler Job Service: this could be a midnight job running to send out emails or to update database records to invalidate memberships that have reached their expiration date
3. File Ingestion Service: this is a service often found in enterprise projects to support internal operations, such as parsing the excel sheet files generated by the admin department and then helping to save those data into the database.

For an enterprise backend development project that is starting from scratch, even before deciding the framework and types of backend services to build, it is important to evaluate the team compositions available and come up with a proper technical vision for the project. If you're joining an existing enterprise backend development project, then the technical vision would already be determined, but it will still be helpful for you to learn about the process of designing backend services, as it might be your job to enhance existing services or create new services to add to the system.

Service Design

Service Design is a phrase usually used in the field of User Experience (UX), but it is also very applicable for backend services. In the article Service Design 101 by Nielson Norman Group, this is the definition that they give Service Design.

Service design is the activity of planning and organizing a business’s resources (people, props, and processes) in order to (1) directly improve the employee’s experience, and (2) indirectly, the customer’s experience.

In the UX field, we identify and gather such business resources to improve the internal company's operations, which thus improve the experience that we deliver to end users. Likewise in enterprise backend, we perform a similar process of identifying components of the system:

Data entities
Relationships and associations between entities
Features that are required to perform business logic and deliver value
Features & responsibilities to be delegated to specific services
A "code of conduct" to be established between the producer and consumer
Models required to derive the entities
Validations required on the entities and models

Here's a diagram to visualize the steps and the type of design pattern/process involved for each step.

For the difference between entity and model, you can refer to this short article

The list of steps above may not be performed in the exact sequence as listed above when you are work in enterprise backend development.

If you work in an Agile enterprise project, it is more common for your business analysts (BA) to introduce the requirements of the system starting from step 3, and then they will leave it to the technical people (us) to determine how the rest of the service design process are done. In such a scenario, it is no wonder why the microservices architecture approach has become so popular for delivering enterprise backend projects.

The microservices approach:

Services are designed to be loosely coupled. Examples of loosely coupled architecture include Hexagonal Architecture, Onion Architecture.
Services are designed to be backward compatible for services that depend on them to continue using them without a need to upgrade. This can be done with a proper versioning strategy and use of feature toggles.
This approach hence allows different services to be be designed and worked on independently by different teams in parallel.

At the same time, services do not need to know how their respective producers/consumers are implemented internally in code. For example, a Python Django BFF should be able to consume data from a Java Spring Boot domain service without knowing the tech stack of the upstream service that it is calling. But if the tech stack and code implementation is unknown, how does one requests another service to perform necessary computations? That is where the APIs comes in.

API contract

Application programming interfaces (API) allow microservices to interact with one another, and an API contract written by a service dictates the specifications and format of API requests that they accept from the applications that are consuming this API. In some enterprise projects, Contract-first API development is a practiced concept. In my previous projects, we also perform Contract Testing using SwaggerHub and Pact.

With an API contract, it helps to distinguish which services are the producer and the consumer. It also declares that these services interact synchronously. For asynchronous interaction, Kafka stream processing is an option and you could also enforce a data contract with a schema registry (I'll include a resource link later for this, Kafka concepts are beyond the scope of the article)

There are alternative and commonly used phrases to describe the dependency relationship between services aside from consumer & producer - upstream & downstream services.

Upstream and Downstream Services

Architectures are generally easier to comprehend after understanding the flow of data across different parts of the system. However, in a data flow architecture context, the meaning of the terms "upstream" and "downstream" are not as explicit. If you simply treat data flows as streams of water, you would think that the source of the stream is considered "upstream" while the destination of the stream would be considered "downstream". However in a microservices context, services could be both a producer and consumer of data. In that case, how do we distinguish which is the upstream or downstream service?

On a Reflectoring article, the author deducted 2 rules for determining determine which service is the upstream and downstream service.

Dependency Rule: each item depends on all the items upstream from its viewpoint
Value Rule: moving downstream, each step adds more value to the product

In a microservices context, the value here refers to the value to the end users.

In an example enterprise project architecture as shown above, with the knowledge of the 2 rules, it is much easier to deduce that the BFF is considered a downstream service of the domain service, and the Kafka ingestion service is an upstream service of the domain service.

So why does knowing the upstream and downstream services matter? As much as we try to make services loosely coupled, when we improve on an existing functionality of a service, there is still a chance that we would accidentally break other services that are dependent on that service. Hence knowing this dependency and value relationship will help us to look out for such potential problems and actively address them before they even happen.

Exploring further

With this article, you should be more prepared to face the challenges of enterprise backend development regardless of the tech stack. At the minimum, you now know of some considerations that you should be making when you are working to improve or create a new backend service.

If you are interested to learn more, these are some topics that I have explicitly excluded because of their complexity and variation from project to project.

Authentication
Infrastructure e.g. Gateways, Routing
Stream Processing with Kafka

Here are some resources for topics briefly discussed in this article

That's a wrap folks! 🎉

Thank you for reading, hope you enjoyed the article!

If you find the article awesome, hit the reactions 🧡 and share it 🐦~

I'll also be working on a follow up to this article which will include a Spring Boot project example ✨

To stay updated whenever I post new stuff, follow me on Twitter.

Be a dev detective with Sourcegraph 🔍

Estee Tey — Mon, 13 Dec 2021 05:22:53 +0000

In this article, I will show you a simple scenario where you can learn how to utilize Sourcegraph to:

Figure out the library of an unfamiliar UI component & use it in a project
Find other projects that use this UI component
Monitor for new projects & revisit searches

Figuring out an unfamiliar UI component

This component is something that I have not seen in any of the design system libraries that I've used. I first found it on Dremio.

There is an interactive slider in the centre of the container, and 2 very well designed images are presented in stark contrast next to each other. Notice the light/dark color scheme, and the use of same shapes in both images. This is a really smart way of using this component to showcase the different aspects & features of the services that they offer!

Putting the images aside, I didn't know of the name of the component so I didn't know how to exactly Google this thing.

🔍 To get some clues, let's once again use the Browser Inspector.

Inspecting the element

There's a funny repeated class name called twentytwenty 🤔. Normally developers who make their own custom UI would use Semantic Class Naming rather than a vague name like this. This gives us grounds to deduce that...

👉 this classname is provided for a library implementation.

Now let's use Sourcegraph, a universal code search tool to look for this library, since we don't know whether the library is available on GitHub/ GitLab or etc.

Search for the library with Sourcegraph

Sourcegraph can be accessed here.

🔍 Let's try to find the library using the query repo: twentytwenty

Bingo! We got a few repositories with the description of "image comparison" which tallies to what the component does. From a glance, we can also see that this component is compatible with the following libraries:

jquery (1.2k ⭐)
Vue (197 ⭐)
React (40 ⭐)

Once we click on one of the repositories, we can see that we can navigate the whole project within Sourcegraph itself ✨ There's also a handy icon for us to go the original GitHub repository if we wish to watch/star the repository.

Using the library

Following the setup instructions in the README for the Vue version of the component, I was able to spurn up the component very easily on codepen, using a neko 🐱 and doggo 🐶 image, similar to what we saw on Dremio.

And that is how you can add this image slider UI to your own project too! If you're using React or jquery, you can check out the other 2 repositories instead. Although Dremio already shows a very good use case of the TwentyTwenty component, it will be cool for us to find out other creative ways of using this component too.

Search for other projects that used the component

🔍 To search for other projects that use this component, we can construct a different search query that comprise of 3 filters

select:repo
- by default, Sourcegraph gives us search results in terms of the files where they find relevant content. however, we only want to know the projects, in other words the repositories that uses the component
-repo:^github\.com/.*/.*twentytwenty
- the repo search filter takes in a regex pattern
- we want to exclude the repositories that provide the UI component such as react-twentytwenty, vue-twentytwenty and so on, so the search filter becomes -repo
content:"twentytwenty-container"
- we want the projects to include usage of the twentytwenty-container classname like how Dremio did it.
- you could try with just twentytwenty, but you will get search results irrelevant to this component as well, because there is a widely used official Wordpress theme called TwentyTwenty too.

Combining all three, we get this search query.

select:repo -repo:^github\.com/.*/.*twentytwenty content:"twentytwenty-container"

If you copy and paste it into Sourcegraph, you will get the following search results.

These repositories are all using the the TwentyTwenty component! However, we can't tell at a glance about the framework of each project that are listed in the search results. Most of these results would be using the jQuery plugin version of the component, since the component was first created as that plugin. But what if your project doesn't use jQuery?

Finding a specific framework project

For example, say you are working on a Vue project, it would be more relevant to find projects of the same framework that use this component and check out how they implement it in code.

🔍 To do this, you can add an extra search filter lang: Vue, which creates the combined query below.

select:repo -repo:^github\.com/.*/.*twentytwenty content:"twentytwenty-container" lang:Vue

When you run this search query, as of this post, there is only 1 project out of the 72 that we found just now that is Vue.

In this open source font project Victor Mono, they created a Vue website app that uses the TwentyTwenty component to showcase the difference between the font they offer and the other common programming fonts. It's a pretty cool use case 😎!

Won't it be nice if you could get notified in the future when there are new open source projects that are using creative usages of Vue projects using this component?

Well, Sourcegraph comes with this functionality! ✨

Code Monitoring

To save your searches and monitor code, you would need to create an account with Sourcegraph. You can sign up easily using the GitHub authentication feature.

To create a code monitor, you can click on "Monitoring" at the NavBar.

First, you have to create a new trigger based on a search query. We can copy paste the query we had before, and then add a new filter type:diff.

select:repo -repo:^github\.com/.*/.*twentytwenty content:"twentytwenty-container" lang:Vue type:diff patternType:literal

This new filter is required to tell the code monitor when to notify you.
type:diff represents you

Then we have to choose an action to run. For now, there's only "Send email notifications", so choose that option and continue. You can also click on "Send test email" to see how the notification will be like.

This is the test email that I got.

After filling all the necessary inputs, the "Create code monitor" button will be clickable.

Save a search

To save a search and revisit it manually later, there are 2 ways you can reach the Saved Searches page.

First way: Click on your profile and then on "Saved Searches"
Second way: Click on the "Save Search" button after you run a query at the search page.

Then you will be brought to this page, where you can add a description for the query that you are saving.

For a more exhaustive list of search query syntax to craft more detailed queries, check out the Sourcegraph documentation for Search Query Syntax.

That's a wrap folks! 🎉

Thank you for reading, hope you enjoyed the article to become a better dev detective with Sourcegraph! This is just a very simple use case of how you can utilize Sourcegraph to learn of new libraries like TwentyTwenty and how other projects have used them. Imagine other possibilities you could do with this powerful search tool! ✨

If you find the article awesome, hit the reactions 🧡 and share it 🐦~

To stay updated whenever I post new stuff, follow me on Twitter.

Article Badge Counter (ABC) Workflow

Estee Tey — Fri, 03 Dec 2021 10:01:38 +0000

Submission Category: Wacky Wildcards

Link to Code

Main repository

lyqht / article-badge-counter-workflow

GitHub Action Workflow that complements blog-post-workflow to generate a Shields.io badge. Intended to be easy like ABC

article-count-workflow

This GitHub action workflow aims to help you to create an article badge counter like this to showcase on your profile that you are more than just a developer 😉 Users can click it and be redirected to a website of your choice.

The default badge looks something like this.

What it does

This workflow is a composite action:

The number of articles is retrieved using the blog-post-workflow action.
The badge is generated using Shields.io, which are not clickable by default.
This action has a script to take in your inputs to create a customized clickable badge.
The commit and push github actions to your repo are performed by the git-auto-commit workflow

How to use

If you are new to GitHub Actions, refer to this section. Otherwise, you can get started by referring to to the example given and the input options available.

Example

This is an example…

View on GitHub

Also tried out doing a pre-release on the GitHub Action Marketplace here

About the workflow

This workflow is a composite action:

The number of articles is retrieved using the blog-post-workflow action.
The badge is generated with Shields.io, which is not clickable by default.
This action has a script to take in your inputs to create a customized clickable badge.
The commit and push github actions to your repo are performed by the git-auto-commit workflow

Using the GitHub Action

An example for the action yaml, instructions for those who are unfamiliar with GitHub Actions, and the input options available to be used to customize the badge are included in the repository's README.md.

Users can display their generated badge on their GitHub profile README.md in any way they like. This is a layout example from my profile.

Additional Resources / Info

Special thanks to Gautam Krishnar for helping to fix the bug that I discovered while working on this action 🧡 He also submitted the blog-post-workflow action for the hackathon, and the article can be found here.

Room for improvements

There were a lot of troubleshooting along the way, but it was fun to learn about composite action concepts and create this action 😄 Ideally, I would also want to include some form of E2E test on the README as part of the composite action to make sure that the badge does render correctly before the action pushes the commit.

Make your website stand out with a custom scrollbar 🌟

Estee Tey — Thu, 25 Nov 2021 16:36:56 +0000

The scrollbar is easily one of the most neglected UI components out there that are not leveraged by many websites to enhance their users' experience. By default, on all HTML, when the content of the website exceeds the viewport height, a scrollbar will automatically appear on the right, just like the one you're seeing as you read this article now.

The default scrollbar looks decent, but it can be better. Let's take a reference from the experts. Here's an example of a unique scrollbar found on CSSTricks.com. Put your eyes to the right of the GIF! 👀

This scrollbar fits in with the dark theme of the website much more than the default scrollbar. It also has a little bevel feel to it.

How to re-create the CSS Tricks Scrollbar

As I've taught my previous readers before, you can navigate the frontend simply by using the Browser Inspector. So let's do that!

Here are the steps for inspecting the scrollbar:

Inspect the <html /> element directly. This is because there's no <scrollbar /> tag. The scrollbar is not a specific HTML element.
To find how the scrollbar is styled, filter for 'scrollbar' in the styles tab.
You will see a few pseudo-elements that are used to style the scrollbar.

Here's a preview of how your inspector will look like.

In the style tab, these are the relevant rules that you can find for styling the scrollbar.

html::-webkit-scrollbar {
    width: 16px;
    height: 16px;
}

html::-webkit-scrollbar-thumb {
    background: #434343;
    border-radius: 16px;
    box-shadow: inset 2px 2px 2px hsla(0,0%,100%,.25),inset -2px -2px 2px rgba(0,0,0,.25);
}

html::-webkit-scrollbar-track {
    background: linear-gradient(90deg,#434343,#434343 1px,#111 0,#111);
}

If I simply copy these styles over and use it for a very long HTML page, the scrollbar will look as it is in CSSTricks!

Now that we know the pseudo-elements do work, let's understand how they work.

How to style a scrollbar

For the CSS Tricks Scrollbar, there were 3 pseudo-elements used:

::-webkit-scrollbar
::-webkit-scrollbar-thumb
::-webkit-scrollbar-track

Here's a simple diagram to depict those 3 parts of the scrollbar.

In addition to these 3 pseudo-elements, there are 4 other parts of the scrollbar that you can consider styling. According to MDN Web Docs , these are the 7 pseudo-elements that you can utilize to style your scrollbar.

::-webkit-scrollbar — the entire scrollbar.
::-webkit-scrollbar-thumb — the draggable scrolling handle.
::-webkit-scrollbar-track — the track (progress bar) of the scrollbar, where there is a gray bar on top of a white bar.
::-webkit-scrollbar-button — the buttons on the scrollbar (arrows pointing upwards and downwards that scroll one line at a time).
::-webkit-scrollbar-track-piece — the part of the track (progress bar) not covered by the handle.
::-webkit-scrollbar-corner — the bottom corner of the scrollbar, where both horizontal and vertical scrollbars meet This is often the bottom-right corner of the browser window.
::-webkit-resizer — the draggable resizing handle that appears at the bottom corner of some elements.

Some of these descriptions may be a little hard to visualize. So here's a diagram to help you with that.

For a gentle introduction to how some of these pseudo-elements can be used, I have created a scrollbar playground for you to create a simple custom scrollbar and export its CSS. Take some time to play around with the settings to deduce how the pseudo-elements work✨

👉 Visit the playground in full page view here!

💡 Important Tip in using Scrollbar Playground

Clicking the export to CSS button will copy the element's styles to your clipboard. Afterwards, you can open up an empty codepen and just paste the styles directly to the CSS tab to see the magic. Remember to set the height of the body element to a very big value like height: 3000px; so that there is content overflow for a scrollbar to appear.

Observations

1. Width of the scrollbar

When you change...

Scrollbar Height -> the width of the vertical scrollbar changes.
Scrollbar Width -> the width of the horizontal scrollbar changes.

The style is applied at the following pseudo-element selector.

#fake-window::-webkit-scrollbar {
    width: 16px;
    height: 16px;
}

2. Scrollbar Buttons

In the playground, you can choose to hide or show them. If you show them, you can choose to show 1 or 2 buttons.

Although it is much more common to see scrollbar with just the single arrow buttons on both ends of the scrollbar since that's the native behavior, if you apply styles to just the ::--webkit-scrollbar-button element itself, you will see 2 buttons on each side.

This behavior may differ depending on the Chromium version of your browser, and also the element you apply the style to. For example, if you apply the same style on codepen, you don't see the double button, but if you apply it to a simple html page and open it up on your local machine, you will see the double button, like what you see on the playground when you choose the 2 button option.

To enforce that the scrollbar only shows one button on each side, the following style needs to be applied.

::-webkit-scrollbar-button:vertical:start:increment,
::-webkit-scrollbar-button:vertical:end:decrement,
::-webkit-scrollbar-button:horizontal:start:increment,
::-webkit-scrollbar-button:horizontal:end:decrement {
    display: none;
}

3. Coloring parts of the scrollbar

Most of the scrollbar parts can be colored individually.

#fake-window::-webkit-scrollbar-thumb {
    background: var(--scrollbar-thumb-color, #3B82F6);
}

#fake-window::-webkit-scrollbar-track {
    background: var(--scrollbar-track-color, #A1A1AA);
}

#fake-window::-webkit-scrollbar-button {
    background: var(--scrollbar-button-color, #3F3F46);
}

#fake-window::-webkit-scrollbar-corner {
    background: var(--scrollbar-corner-color, #FFFFFF);
}

Exploring further

Now that you have some basics of setting css properties in terms of sizes and colors for the scrollbar pseudo-elements, consider special scrollbars like this too! ✨

Examples

Here's a very simple example that I made which only has a horizontal scrollbar, but the thumb is an animating cat! 😸 The icon is taken from Gowee's nyan cat SVG on Github.

Another note-worthy scrollbar to be mentioned is the scrollbar on Shawn's portfolio. Eyes to the right 👀 It is a candy stick moving on a heart palette track and it feels super delightful to look at it! Literal eye candy😋

Resources

The original Webkit's article on styling scrollbars
- This article talks about even more selectors that you can utilize to style your scrollbar, although they are rarely used
CSS Tricks' article on styling scrollbars
- Great tons of modern looking examples here!

Libraries for adding a Custom Scrollbar

Of course, if you're lazy and prefer a fast and pre-made solution, here are 3 public packages that I've found which you can choose to add into your project. The way they implemented them is different, so do check out their docs to see which you prefer.

Smooth Scrollbar
- A simple customizable, performant Javascript plugin solution
Overlay Scrollbars
- comes with themes and framework wrappers for Angular, React and Vue
Perfect Scrollbar
- made by the Material Bootstrap team

Bonus: Hiding the scrollbar UI

Although this article is about making your website stand out with a custom scrollbar, if for any reason you hate having to see a scrollbar UI take up visual space on your website, or you want your website to be look alike on both desktop and mobile (websites do not show scrollbars by default on mobile browsers), you can simply set the display: none to the pseudo-element::-webkit-scrollbar.

html::-webkit-scrollbar {
  display: none;
}

You will still be able to scroll on a webpage, just that you can't see the scrollbar UI. For most use cases, I do not recommend you to disable the scrolling entirely 😆

That's a wrap folks! 🎉

Thank you for reading, hope you enjoyed the article! If you have tried out the Scrollbar Playground and created a scrollbar that you like, do share a screenshot below! 😊

If you find the article awesome, hit the reactions 🧡 and share it 🐦~

To stay updated whenever I post new stuff, follow me on Twitter.

Introduction to Scalable Vector Graphics (SVG)

Estee Tey — Tue, 16 Nov 2021 14:56:12 +0000

This article is an enhanced version of the lunch & learn session that I presented recently on Introduction to Scalable Vector Graphics. The slides can be found here, where you can choose to download a PDF version.

There are some iframes which have been excluded in this article e.g. the embedded presentation slides, because the Forem platform does not support them. But if you're keen to see them, check out the original article on my tech blog.

What is SVG?

SVG refers to Scalable Vector Graphics, and it is a type of image format that is widely available on websites. Before we describe further on SVG, let's understand the importance of images and other image format types.

🖼 Images

On a very high level, we can split images into 2 generic types: Raster and Vector.

Raster images are drawn pixel by pixel, and may look different depending on the resolution/ pixel density of the device. Vector images look good and crisp regardless of the resolution. Here's a Codepen to illustrate the difference between the two, try resizing the different images! ✨

The raster art was drawn by my boyfriend using Microsoft Paint (what a madlad! 😍), while the vectorized version are traced and coloured by me using Adobe Illustrator. It was a joint project for creating a couple tee design 😉

I'm sure you're curious about this question - if vector images always look good, then why would we ever consider raster images? Well that's because of 2 practical factors. The first being the fact that the technology to support the creation & usage of raster images is much more accessible compared to SVG.

On the designers' side, there is generally more familiarity to work with tools to create raster art (Photoshop) than vector art (Illustrator).
On the developer's side, most file uploaders e.g. for uploading avatar images, background banners etc, are implemented to be restricted to raster image formats only.

The second reason for preferring raster images over SVG is the file size. Different image formats of the same visual will result in different file sizes, and thus different pages sizes. According to Google Developers Page on Image Compression,

Images comprise up to 60%-65% of bytes on most web pages and page size is a major factor in total rendering time. Page size is especially important for mobile devices, where smaller size images will help to save both bandwidth and battery life.

For different use cases, we should be using different image file types. In the context of online images,

For Raster Image File Types, there's 4 types - GIF, PNG, JPG and WEBP.
For Vector Image File Types, there's only SVG!

Here's a table for the description of the name of the file extensions.

And here's a brief context behind how each raster file type came about.

GIF
- GIF was one of the first two graphics formats supported by HTML, along with XBM.
PNG
- PNG was created to improve upon and replace GIF (Graphics Interchange Format) as an image-file format.
- It supports a better compression algorithm and also transparency in an image.
JPG
- The original file extension for the Joint Photographic Expert Group File Format was .jpeg. On Mac, this was supported but on Windows, all files required a 3-letter file extension. So, the file extension was shortened to .jpg.
- Eventually, with upgrades Windows also began to accept .jpeg. However, many users were already used to ‘.jpg’, so both the 3-letter file extension and the 4-letter were commonly used, and still are.
- Today, the most commonly accepted and used form is the .jpg, as many users were Windows users.
WEBP
- WEBP is an image format type developed by Google to create files that are smaller for the same quality of JPEG, PNG, and GIF image formats.

Now that we know what image formats are commonly used for web images, now we can talk about what the different file types are intended for. Here's a table to illustrate the colour modes, compression algorithm supported, and thus the intended usage for different image file types.

To add on to the table, here are reasons why you should use SVG.

Why use SVG?

SVG is scalable
1. You can stretch it however much, you still won't lose quality because of resolution issues.
2. Responsive design is easier to be achieved!
SVG can be coded inline
- this reduces the HTTP requests required to retrieve media.
- this also meant that the FOUC (Flash of Unstyled Content) problem is less likely to happen from media not being retrieved and styled before rendering in the page.
Developers can work with the individual nodes in the SVG to:
1. animate
2. optimize for performance
3. optimize for accessibility

Animation and optimization are considered a little more advanced so they are not covered in this introductory article. I may conduct more talks/ write articles on these concepts in the future. 😊

Now that we have a clearer picture of image file types and why we should use SVG, we can move on to more hands-on stuff! 🙌

How to create SVG?

In this article, I will show you 2 different ways of creating SVG. The first would be using code to create SVG XML and the other would be to use Figma, a design tool to create SVG.

Create SVG with Code

For learning to create SVG with code, we will create 4 simple country flags from SEA (Southeast Asia) - Japan, Thailand, Vietnam and Singapore.

Country	JP	TH	VN	SG
Image
What you will learn	Rectangle & Circle	Positioning	Polygon, Polyline, Nesting of SVG	Reusing SVG elements

⛳ 1st Flag: Japan

The flag has 2 colors and 2 shapes. The color of SVG elements are indicated by the fill property. The shapes are created by the following HTML tags.

<rect />
<circle />

For the rectangle, the width and height properties are pretty self-explanatory.

For the circle,

(cx, cy) are x,y coordinates of the centre point of the circle
r represents the radius of the circle
Hence to make the circle positioned in the center, we set (cx, cy) to be both a relative 50%. If you prefer absolute units, you could set the rect's width=300 and circle's cx=150 instead.

<svg>
    <rect width="100%" height="100%" fill="white" />
    <circle cx="50%" cy="50%" r="60" fill="#BC002D" />
</svg>

⛳ 2nd Flag: Thailand

This simple example has only 5 rectangles, and is meant to introduce you to positioning. Previously we have the circle centered in the middle of the rectangle by setting the (cx, cy) coordinates. For other elements, usually you can set the (x, y) coordinates directly. These (x, y) coordinates always refer to the top left coordinate of the element

<svg>
    <rect width="100%" height="20%" y="0" fill="red" />
    <rect width="100%" height="20%" y="20%" fill="white" />
    <rect width="100%" height="20%" y="40%" fill="blue" />
    <rect width="100%" height="20%" y="60%" fill="white" />
    <rect width="100%" height="20%" y="80%" fill="red" />
</svg>

⛳ 3rd Flag: Vietnam

There are 2 shapes here - a rectangle and a star. There isn't a <star /> element unfortunately, but there is a generic <polygon /> element that we can use to create a star. W3C provides many examples of shapes, so I will take their star example and use it here.

Example of creating a star with the polygon element

<svg>
  <polygon id="star" fill="yellow"
      points="100,10 40,198 190,78 10,78 160,198" />
</svg>

However, if we try to preview the svg with this star, it will get cut off.

This is because the star is bigger than the SVG's default width & height of 300×150.

To fix this, we could adjust the coordinates one by one but that's painful so let's not do that 😅. Instead, let's change the viewbox property.

⚠ The viewbox property is the most important thing you have to know about SVG.

The viewbox can be declared by giving it a min-x, min-y, width and height. For us to see the star entirely, the height needs to ≥198, since the biggest y-coordinate we have in the SVG is 198. Let's also give the star a little padding, so we will increase both the width and height of the SVG viewbox.

<svg viewbox='0 0 300 300'>
  <polygon fill="yellow" points="100,10 40,198 190,78 10,78 160,198" />
</svg>

Now we can see the star

For a more in-depth explanation on scaling SVG, you can refer to this nifty article by CSS-Tricks.

Let's move on to create the actual VN flag.

In the flag, the star actually looks a lot smaller than what we have created just now with the padding. We can modify the viewbox of this star so that it looks smaller, but at the same time, we want the flag to still look like its original shape of a small rectangle that follows the default viewbox of 300x150.

There're different ways of to implement the flag, but here, I will introduce you to a new concept - Nesting of SVG elements. We can enclose the SVG element for the star within another SVG element tag. That way, we can achieve the scaling down of the star element while keeping the flag's size. We will also add some (x, y) offsets so that the star looks centered.

<svg>
  <rect width="100%" height="100%" fill="red" />
  <svg viewBox="100 0 600 600" x="25%" y="25%">
    <polygon fill="yellow"
      points="100,10 40,198 190,78 10,78 160,198" />
  </svg>
</svg>

Now that you understand how the <polygon /> element works, you can also learn about the <polyline /> element.

The only difference polygon and polyline is that the polygon is a closed path while the polyline is an open path - that's why if you draw the 2 shapes in SVG and give them stroke colors, you can tell the difference.

In <polyline />, the last point is not connected to the first point
In <polygon />, the last point is connected to the first point

⛳ 4th Flag: SG

For the 4th country flag, we are creating my home nation, Singapore! 😊

The flag comprises of 2 rectangles, 5 stars and 1 moon. To create this flag, it requires the combination of concepts that we have learnt from the previous flags.

But how do we draw a moon? Well, when it comes to art, we don't always have to follow the semantic way of creating things. We can just create 2 overlapping circles where the top circle is red and the bottom circle is white, so that the result looks like a moon 🌘

Since we have already created a star before, let's reuse it and just change the fill to white. To reuse an element, we can declare definitions in a <defs> tag and use them using a <use> tag. You can see that this becomes helpful as we reuse the same element multiple times.

<svg>
    <defs>
        <polygon 
            id="white-star" 
            points="100,10 40,198 190,78 10,78 160,198" 
            fill="white" />
    </defs>
    <rect width="100%" height="50%" fill="red" />
    <rect width="100%" height="50%" y="50%" fill="white" />
    <circle cx='15%' cy='25%' r='30' fill='white' />
    <circle cx='20%' cy='25%' r='30' fill='red' />
    <svg viewBox="600 -100 1000 1800">
        <use href="#white-star" />
        <use href="#white-star" x="-20%" y="10%" />
        <use href="#white-star" x="20%" y="10%" />
        <use href="#white-star" x="-12.5%" y="22%" />
        <use href="#white-star" x="12.5%" y="22%" />
    </svg>
</svg>

🎉 Good job reaching here thus far!

🥳 We managed to create SVGs of 4 different SEA country flags using code!

👉 You can find all the .svg files covered here.

For the rest of the article, I promise you the content would be much lighter! 😊 Now, let's move on to creating SVG graphics using Design Tools.

🎨 Create SVG with Design Tools

Common Design Tools used to create SVG include

Out of the 3 options, Figma is free and also accessible on any platform, so I will share with you a very short intro on Figma on creating graphics using Paths, and exporting them as SVG.

👉 Duplicate the Figma demo file here.

⭐ Pro tip: To edit any path, click on a path and press the 'Enter' key.
Try playing around with the paths that are in the file!

Straight Paths

Using the Pen Tool (P key) 🖊, you can easily create straight paths and form polygons, polylines and shapes like the low-poly bear!

Curved Paths

After creating straight paths with the Pen Tool, you can use the Bend Tool (Ctrl Key) to create a Bezier Curve.

Handles will appear, connected to the start and end coordinate of the path that you have selected. This is how shapes like the bunny's round head & ears are created!

Another type of curved Path would be the Arc. After creating an Ellipse, you can hover over the ellipse path to use the Arc Tool to create an Arc.

Exporting the SVG

Once you're done creating your fancy shapes and graphics, you can choose to export them easily as a SVG file.

That sums up how you can create SVG from scratch either using Code or Design Tools! Personally I would recommend you to create graphics using Design Tools because having GUI just makes it so much easier to visualize what you're actually doing. The downside of it is that you have less control over the result SVG element nodes inside your graphic. This may pose a problem if you try to do animation or optimization later on, but if you're just doing static SVG, it's much easier to just use a design tool to create SVG.

Of course, if you don't want to create SVG from scratch at all, there are plenty of online tools to generate SVG of common shapes for us!

Generate SVG

🔖 There's an extensive list of SVG generators by Smashing Magazine that you can check out.

During the talk, I have shown a demo for just two generators that were listed there because I found them relevant to what I've been reading recently.

Squicley → provides configuration for you to generate SVG squircles, a shape that is similar to rounded circles but not identical. Thought this was a pretty funny concept of shape to introduce to you all 😄 Apparently, this is what makes Apple hardware more distinct than others.
SVGBackgrounds → provides you many SVG backgrounds you can customize to be used for your next project. I also previously made a Tweet thread on how you can use it and why you should use it.

// Detect dark theme var iframe = document.getElementById('tweet-1444814549341782018-437'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1444814549341782018&theme=dark" }

Aside from generating SVG, we can also extract SVG that we see on websites using the Inspector ✨

Extract SVG from websites

⚠️ Important Note: Please check if you can use the extracted SVG without attribution.

For extracting SVG from websites, we will use our good old Element Inspector to do it! Let's try it out on Hacktoberfest's website since they have really beautiful flowers this year 🌺

Hacktoberfest-Inspector-Demo GIF

Ctrl+F "<svg>" to find the SVG element that you want.
Once the highlighted area matches the SVG that you're targeting, right click the element and choose "Copy Element"
The result will be something like this, which you can paste in a new .svg file.

🌟 Bonus Helpful Tools for SVG

Optimization of SVG file size: SVGOMG
- If you use design tools to create SVG or extract SVG from websites, chances are that most of them are not optimized in file sizes.
- There's a handy tool called SVGOMG which has many features you can toggle to help you optimize your file size, and you don't have to understand how all of them work.
- You can also preview the result and the result file size at the circled area ✨
Visual Studio Code Extension: SVG
- Provides auto-completion, SVG Live Preview and Export PNG
- You can also minify the SVG code and remove unnecessary code
For React Devs: Convert SVG to JSX
- You can paste SVG code here to be converted to either functional or class component syntax.

Frequently asked questions (FAQ)

Q) I see xmlns attributes are commonly used on SVG elements, but you didn't use them in your talk at all, are they actually needed?

<svg xmlns:xlink="http://www.w3.org/1999/xlink" xmlns="http://www.w3.org/2000/svg"></svg>

A) If you are using them as inline SVG, you don't need to include those. You only need those attributes if you are embedding them using the img element. Here's a useful StackOverflow thread that answers this.

Exploring further

As you try to experiment with SVG in code further by using JavaScript and so on, you will start to realize that creating graphics in code requires a lot of math 😂

Here are some nice tutorials for you to try out to create more complex SVG that include good explanations:

That's a wrap folks! 🎉

Thank you for reading, hope you enjoyed the article! If you have any questions or feedback for me, please leave them below, I'll attend to them shortly 😊

If you find the article awesome, hit the reactions 🧡 and share it 🐦~

To stay updated whenever I post new stuff, follow me on Twitter.

DEV Community: Estee Tey

Expenses made easier with Cloudflare AI

What I Built

How it works

Models used in this project:

Demo

Try out the worker!

Try it in the web app!

My Code

lyqht / cloudflare-journal

Introduction

How it works

Models used

Try out the worker!

Journey

How the idea came about

Room for improvements

Resources

DeepL Translate Github Action

What I built

Category Submission

App Link

Screenshots

Description

Link to Source Code

Permissive License

Background (What made you decide to build this particular app? What inspired you?)

How I built it (How did you utilize GitHub Actions or GitHub Codespaces? Did you learn something new along the way? Pick up a new skill?)

Additional Resources/Info

My Hacktoberfest Experience For The Third Time: 2022 Edition

Being a contributor

My contributions

Being a maintainer

Projects participating in Hacktoberfest

How I decide the issues to be created

Getting contributions

An unexpected collaboration

Overall Experience

It turned out better than expected

Confusion with the event rules

It is difficult to be a maintainer

That’s a wrap!

How to create and test a GitHub Action that generates Supabase database types

How to generate types from a Supabase database

Cross-reference code with Sourcegraph Visual Studio Code plugin

How to create the GitHub workflow

How to test GitHub Actions locally with act

Bonus: In Action

That's a wrap folks! 🎉

A Strange Moment.js — 3 Gotchas for Working & Testing with Datetimes

Introduction to Moment.js

Gotcha 1: Mutability of DateTime objects

Solution: Clone the moment object

Gotcha 2: moment().isValid()

Solution: Enable strictMode

Gotcha 3: Parsing DateTime strings

Solution 1

Solution 2

Use case: Find the most recent instance of a given weekday

Case 1: Get the given weekday from last week

Case 2: Get the given weekday from current week

Solution

Conclusion

Resources

That's a wrap folks! 🎉

Nevertheless, Estee Coded

Background in Tech

Working in tech

Some concluding thoughts

How to create a CSS Playground for styling Pseudo-elements with Vanilla JavaScript

The CSS Playground

1. Live Preview

Size Properties

Color Properties

2. Export CSS Functionality

3. Validate CSS

Generating playgrounds

The concept of Playgrounds

Idea inspirations

That's a wrap folks! 🎉

Solution: Enable `strictMode`