DEV Community: Tomasz Buszewski

Design Systems in React – Scaffolding and Setup (Part 0)

Tomasz Buszewski — Wed, 14 Aug 2024 21:36:13 +0000

Creating and maintaining UI library or an entire design system is complex.
Building one from scratch can be a challenge, so let’s prepare the project to
make it easier.

This is taken from my blog. You can also view the video on YouTube.

Before we start, let’s lay some ground rules:

This is part zero of a larger series, in which we will explore the whole topic of developing a design system, from development environment (we are here), through tokens and grouping, to even testing the components.
I picked React, but this architecture is viable for every other library. I am not using any particular features that only React has.
I am using Tailwind due to its great customization options paired with tons of ready-made code, but this is entirely optional. Vanilla CSS or any other framework works perfectly fine.
In the upcoming parts, I will be using Atomic Design methodology by Brad Frost. I find it the most scalable solution as of yet for mid to large systems.
This is not a design tutorial. I won’t go into details on how things should look with each other, but I will dive into how they should work with each other.

All right, let’s start writing some code!

Bootstrapping and Storybook

We start by creating a new project using Vite:

~ npm create vite@latest react-design-system -- --template react-ts

This will create a new directory called react-design-system in which we will
find all the required things to start. After the process is completed, we need
to install the dependencies:

~ cd react-design-system
~ npm i

Just to be sure, let’s run the development command:

~ npm run dev

Works! Great. Now let’s start with the actual environment.

First off, Storybook. It’s the golden standard for developing UI, and supports
many libraries out of the box, including React, Vue, Angular and Svelte. So, in
our main directory:

~ npx storybook@latest init

Historically, Storybook was bundled by Webpack, and it is still supported. But
it also support Vite, both out of the box. As you can see, the installer itself
decided what to use, so that’s all we had to do!

One thing is that Storybook collects some telemetry. If you’re fine with this,
that’s completely fine, but if you want to opt out, go to ./.storybook/main.ts
and add

core: {
  disableTelemetry: true,
},

to the config object.

Installing Storybook today is as seamless as can be. I still remember how
problematic it could be back in the late 2010s, when Webpack came with tons of
config and you had to adjust every bit of it for your app and Storybook’s just
to make it render the same.

Adding Tailwind

The next step is to add Tailwind. Tailwind is pretty seamless to add to the
project, so let’s start.

First, we need to install the library and its dependencies:

~ npm i -D tailwindcss postcss autoprefixer

After this ends, we can initialize it:

~ npx tailwindcss init -p

By adding -p flag, the wizard will also create PostCSS config that will then
utilize autoprefixer.

Right, so let’s configure Tailwind to see our files. In the config file
(tailwind.config.js), set config property to:

content: ["./index.html", "./src/**/*.{ts,tsx}"],

This will make Tailwind scan aforementioned files.

Now create style.css file in ./src and put the basics:

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

And import the file in main.tsx:

// ./src/main.tsx

import { StrictMode } from "react";
import { createRoot } from "react-dom/client";
import App from "./App.tsx";
import "./style.css";

createRoot(document.getElementById("root")!).render(
  <StrictMode>
    <App />
  </StrictMode>,
);

That’s it for the app. We can run the dev mode and see if it works.

But that’s not everything. Storybook doesn’t know we want to use Tailwind and
won’t see it. Luckily, this is an easy fix. Go to ./storybook/preview.ts and
import the CSS file we’ve made earlier:

import "../src/style.css";

That’s it!

Adding linters

One of the most crucial things in development is code style. I know it sounds
funny and you might think I am overreacting, but fighting over spaces, quotes
and line lengths can often balloon and become a real problem. A good way to
solve the issue early is to throw Prettier and ESLint in. Let’s do it now.

~ npm i prettier -D

This will add the prettier package to our project. We need to configure it, so
let’s create the config file:

/**
 * @type {import("prettier").Config}
 */
export default {
  semi: true,
  singleQuote: false,
  tabWidth: 2,
  trailingComma: "all",
};

I like to have this as a standard: always add semicolons, use double quotes, use
two spaces and add trailing commas to all elements.

While Prettier can work as a command line utility, I strongly suggest
configuring your IDE to reformat the file on save. In IntelliJ this is done via
Settings > Languages & Frameworks > JavaScript > Prettier, and in there, pick
"Automatic Prettier Configuration" and check "Run on Save".

To start fresh and have all the files formatted correctly, go into terminal and
run

~ prettier -w ./*

This will reformat and write (hence the -w flag) all files in the project.

As for ESLint, Vite adds it automatically, and with decent settings to boot. For
the sake of brevity, I will leave it as-is. You can, obviously, modify it to
your needs and make it as lax or as strict as you want. One thing to remember
here is that, by default, ESLint uses its new “flat” config, and some plugins
aren’t compatible. There’s FlatCompat class exposed by @eslint/eslintrc, but
I had mixed results with it.

Defining our first component

If all is configured, let’s get to work. There’s stories directory created by
Storybook which serves as an example repository. You can keep it, be we won’t be
using it. We’ll create another “space” for the UI, named, well, ui. From
there, we will export all the public components to use across the app.

I like to have a global export file in every space, and with that, a shortcut
defined in tsconfig.json. Something like

@path/* -> ./src/path/*
@path -> ./src/path/index.ts

I won’t dive into Atomic Design today to save time, so let’s just create a basic
component in the UI space to get it going!

// ./ui/Info/Info.tsx

import type { ReactNode, HTMLAttributes } from "react";

interface Props extends HTMLAttributes<HTMLDivElement> {
  variant?: "info" | "warning" | "error";
}

export default function Info({ className, children, variant = "info" }: Props) {
  const cls: string[] = [className || ""];

  switch (variant) {
    case "warning": {
      cls.push("bg-yellow-100 text-yellow-800 border-yellow-500");
      break;
    }

    case "error": {
      cls.push("bg-red-100 text-red-800 border-red-500");
      break;
    }

    default:
    case "info": {
      cls.push("bg-blue-100 text-blue-800 border-blue-500");
      break;
    }
  }

  return (
    <div
      role="alert"
      className={"p-4 mb-4 text-sm text-blue-800 rounded-lg" + cls.join(" ")}
    >
      {children}
    </div>
  );
}

We could (and will, soon) add more to the directory, like styles and tests. But
for now, just this file. And let’s export it.

// ./ui/index.ts
export { default as Info } from "./Info/Info";

And let’s add the TypeScript paths.

"compilerOptions": {
  "paths": {
    "@ui": ["./src/ui/index.ts"],
  }
}

But, this won’t work just yet! We need to install vite-tsconfig-paths to allow
Vite to understand it.

~ npm i -D vite-tsconfig-paths

And add it in the config. I suggest putting it first just to be safe.

// ./vite.config.ts

import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
import tsconfigPaths from "vite-tsconfig-paths";

// https://vitejs.dev/config/
export default defineConfig({
  plugins: [tsconfigPaths(), react()],
});

Great, so we have our component, but how to see how it looks? Well, you might
throw it in the main file, but there’s a better way.

Writing stories

To create a story, first create its file: Info.stories.tsx. The process is
rather straightforward, and mostly consists of configuration.

import type { Meta, StoryObj } from "@storybook/react";
import Info from "./Info";

const meta: Meta<typeof Info> = {
  title: "UI/Info",
  component: Info,
};

export const Primary: StoryObj<typeof Info> = {
  args: {
    children: "Hello from Storybook",
  },
};

export default meta;

Let’s go through the file. First, we import types and the component in question.
Then we define the meta where all the info that Storybook digest resides. Note
the slash in the title – adding each creates a new “directory”, so right now we
have UI → Info, but soon we’ll expand this.

Last, but not least, is the definition of the story, named “Primary” as per
standard. But the naming is unimportant, it can be whatever, as long as it’s a
valid component (so, as long as it starts with a capital letter).

Okay, we got this, so let’s try if it works!

~ npm run storybook

If you see the Storybook page, and in the sidebar there’s an “UI” space, all
works great!

Adding Plop to generate scaffolding

This is all fine and well, but creating such components and stories will surely
prove exhausting, right?

Yes. You can trust me here, it will get old very, very fast.

That’s why we can use a generator that will create empty components for us. Plop
can do this.

~ npm i -D plop

And create the config file in the root, named plopfile.mjs. In there, we can
define what we want to generate. Let’s start by defining a UI component:

// ./plopfile.mjs

function plop(/** @type {import('plop').NodePlopAPI} */ plop) {
  plop.setGenerator("ui", {
    description: "Create a new UI component",
    prompts: [
      {
        type: "input",
        name: "name",
        message: "Component name",
      },
    ],
  });
}

export default plop;

Right now, it does nothing. Simply defines that such generator exists and asks
for the name, but to actually write files, it needs an “action”.

// ./plopfile.mjs

actions: [
  {
    type: "add",
    path: "./src/ui/{{pascalCase name}}/{{pascalCase name}}.tsx",
    templateFile: "./plop-templates/Component.tsx.hbs",
  },
  {
    type: "add",
    path: "./src/ui/{{pascalCase name}}/{{pascalCase name}}.stories.tsx",
    templateFile: "./plop-templates/Story.tsx.hbs",
  },
  {
    type: "append",
    path: "./src/ui/index.ts",
    template: 'export { default as {{pascalCase name}} } from "./{{pascalCase name}}/{{pascalCase name}}";',
  },
],

Let’s go from the top. First, we add a new file, with path being
src/ui/Name/Name name.tsx. If you look into the “prompts”, you’ll see that
there’s name property that is reflected in here. It also uses a template that
we are yet to write.

Second action is the same, it just has the story. And the third one is
appending the export to the main index.ts file.

Right, so let’s create the templates! It’s written in Handlebars and, frankly,
it’s quite straightforward.

// ./plop-templates/Component.tsx.hbs

import type { ReactNode, HTMLAttributes } from "react";

interface Props extends HTMLAttributes<HTMLDivElement> {
  children: ReactNode;
}

export default function {{pascalCase name}}(props: Props) {
  return (
    <div {...props} />
  );
}

As you see, it’s very barebones. That’s by design, because eventually we will
expand component types and have different templates. For now, this will suffice.
Same with the story:

// ./plop-templates/Story.tsx.hbs

import type { Meta, StoryObj } from "@storybook/react";
import {{pascalCase name}} from "./{{pascalCase name}}";

const meta: Meta<typeof {{pascalCase name}}> = {
  title: "UI/{{pascalCase name}}",
  component: {{pascalCase name}},
};

export const Primary: StoryObj<typeof {{pascalCase name}}> = {
  args: {
    children: "Hello from Storybook",
  },
};

export default meta;

Lastly, let’s add the shortcut to npm scripts:

"scripts": {
  ...

  "plop": "plop"
},

There’s one thing I like to do, and it’s to have Prettier run through the files
after we are done. It’s achievable with post-scripts:

"scripts": {
  ...

  "plop": "plop",
  "postplop": "prettier --write 'src/**/*.{ts,tsx}'"
},

Right, so let’s test!

~ npm run plop

If everything worked, we should see a success report. All that’s left is to fire
up Storybook and see if all is fine!

—

UI libraries are complex, and the devil is always in the details. Today we’ve
managed to create a solid ground for development. Join me in the next videos
from the series, where we will dive into tests, visual regressions and atomic
design.

How to Run Technical Interviews

Tomasz Buszewski — Fri, 09 Aug 2024 12:26:15 +0000

Running a good interview is one of the most important skills as a developer. And yet, many of us struggle to get it right.

This is a repost from my blog.

You can also watch the video on YouTube.

Describe the Interview Process

That’s basically the step zero. Take a minute to tell the candidate what will happen during the interview. Tell them what stages are there. This will show them that you came prepared and you know what you are doing.

Bring Someone with You

You are hiring for the team, not for yourself. Dynamic is very important, and seeing how candidate can talk and work with a potential colleague is extremely important. That’s why I always try to bring someone with me.

If I can, I take someone with the opposite seniority. If candidate’s senior, I take a junior, and vice versa. Two seniors will get along quicker than a senior and a junior.

Besides, it’s always a second pair of eyes, so they might notice whatever you’ve missed. Make sure to debrief after the call, when thoughts are still fresh. I suggest doing a quick five minutes sync right after the interview, and then writing it down after an hour or so. That way you’ll get what’s on your mind quickly, and then, after your mind structures it, you’ll write a formal feedback.

Sometimes I left even more time for my mind to wander, and wrote the feedback in the next day. Especially if the interview was the last thing to do in a given day.

Don’t Get Technical at the Beginning

This one I’ve seen way too many times. “Hi, my name is Xyz, let’s start, can you tell me all the array methods in JavaScript?” right off the bat, on a single breath. This is very bad, for both parties, because you lose the opportunity to sink into the meeting. A few minutes of chat won’t ruin your plan, but will give you the opportunity to get to know the person you’ll spend the next hour or so a bit better.

I always start with a bit of a small talk, mostly basing on an interesting part of the CV (like interests, school I know of, side projects, you name it) or on some background detail, like a poster or a figurine (Dark Souls merch = instant hire in my book, btw). I never rush this section, as candidate will take the time to tell a bit about themselves, but also to acclimatize to the situation. Once you find that the topic has run its course and is drying up, proceed onwards.

Make Proper Introduction of Yourself and the Company

When I started going on interviews, the golden rule was to know at least a bit about the company. Now it’s not always the case. Chances are, you’re not hiring for Google, and candidates, especially those who are looking for “a job” rather than “the job in the company”, might not know about you guys. It’s up to you to tell them why it’s a good idea to join. Introduce yourself, tell them what are you doing in here and for how long you’ve been in your position. Describe what the company does, describe the service in more details than the job posting or “about” page.

What’s important here is to underline that if they have questions, they are welcome to ask. Sometimes candidates will want to ask something, but you’ll be talking and talking for ten minutes, and once you’re done, the interviewee will forget what they wanted to know.

It’s also a good thing to describe the project from technical perspective. All the things you think a developer should be aware of. Don’t overdo it though, don’t spend thirty minutes detailing the last test you wrote, just deliver the basics, such as

stack;
high level architecture;
team structure;
project management (methodology, amount of work);
deployment and testing flows.

Remember to tell the truth here. Sugarcoating is a short-term game, and if they join and find out you lied to them, they might lose any trust they have for you and the company. If you don’t have tests – tough luck, admit to that. If you’re deploying via FTP, okay, say it. They should know what they are signing for, even if it’s uncomfortable.

Ask About Real Life Problems

Sometime ago there was a popular term in IT. “Grilling" meant that you take the candidate and throw questions at them to make them sweat, just like you would keep them over a grill. I find this practice extremely poor. Why would you make the person uncomfortable? Why would you stress them?

Instead of asking hundred of small questions nitpicked from the documentation, ask about real life problems. “How do you know when to start optimizing your code? How do you do the optimizations?”, “How and why would you use dependency injection” or “How would you handle a situation when a colleague submits very poor pull request”. These are just a couple of examples. And they will tell you more than “What does clamp() do in CSS” or “What’s the difference between var and let”.

Such questions are also a good opportunity to see what’s the person’s stronger sides. If they dive deep into the answer, consider jumping in and following the thread, ask follow-up questions. With answers that aren’t going according to your expectations, don’t overdo it. If you push the person too hard, they might lock themselves and it will be super hard to get out of that hole.

When asking, make sure to observe what the person is doing, though. Are they reading something? I had a situation when the interviewee asked Chat GPT all the questions, and read the answers. I knew something’s off, because it felt formulaic, like describing a painting you’ve only heard of. And how I know it for sure? Later on we did screen sharing and they forgot to close the chat tab, so we were able to see everything.

And since we’re talking about screen sharing…

Have a Pair Programming Session…

Seeing someone writing their own code is always a good thing. While people might not love it, I’d call it necessary evil. But, instead of asking the candidate to write you a binary tree and then reverse it while you sit muted, have a pair programming session.

I tend to use this part when we talk to a senior, and I have a junior with me. Let them work together, let’s see how fast they will catch on. Senior should lead the pair, so it’s a good way to test how they handle such situations. How they can explain something to someone with less knowledge, how they paint their plans for the solution, how they execute it.

In this section, it’s important to remember that delivering a working solution is not the case. After all, limited time and stress will hinder the interviewee’s skills, and you’re (hopefully) not hiring the fastest typist. What’s important is to see how they proceed, plan and execute the solution, as mentioned before. Ask your junior afterwards, was it all clear from the beginning? Were they able to follow along?

One red flag I always look out for here is when the senior acts superior to the lesser-experienced colleague. Being condescending is something many seasoned developers are struggling with (ask me how I know, I dare you), often without knowing it. While sometimes it’s something you can work on with the said person, you must consider whether you have the time to invest, and will they be willing to make the effort.

…or a System Design Challenge

If you need to hire someone that will be more self-reliant, consider doing a system design challenge. It requires you to play the Product Owner or Manager part for a bit though.

Think of the problem before the interview. I like to go with auth flow, so my main prompt is “we have a public and private areas in our app and we want people to register and log in to see the latter.” It’s vague on purpose, because getting more details is a part of the challenge. If the candidate jumps straights into delivering a solution, that’s a red flag and almost always a poor solve.

Ideally, the candidate should ask tons of questions, from the exact requirements, through stack, finally, to acceptance criteria. After all this, they should have something that is more similar to a user story rather than to one sentence they heard at the start.

Form of the solution is completely up to them, though. If they don’t propose anything, I suggest draw.io, but most of the time, candidates have their own tools. Some will draw you full UML diagrams, some will just throw a couple of rectangles connected by arrows. The form is extremely unimportant. What matters is how the solution works, and how they react to critique and questions.

Asking questions about the solution is super important. It will tell you whether the person can defend their vision and how they react to being challenged. You want to question their decisions, even if they seem fine to you. Try asking questions you know are fundamentally wrong, and see how they react.

Leave Them Time for Questions

I always make sure to highlight the fact that the candidate can ask whenever they feel like. But sometimes they won’t want to, and will keep their doubts and comments until the end. Make sure you give them time to ask. And answer honestly.

I like to say that interviews are a form of dance where both parties try to enchant one another. But that’s something I actively avoid during my meetings. Answering dishonestly, as mentioned early, will hinder their trust, and that’s a short way to quitting.

This section can be lengthy, so make sure to have you have time to spare. If you notice you’re running out of planned time, ask whether they can stay for a few minutes so that you can answer all the questions. If they can’t, offer a follow-up email.

—

That’s it, that’s my recipe for conducting good technical interviews. No grilling, no whiteboard coding, no hoops to jump. Just a good talk with some tech challenges at the end. I hope you’ll find it helpful!

Good luck interviewing!

How to Add OpenAPI to your Express App?

Tomasz Buszewski — Tue, 06 Aug 2024 09:02:27 +0000

Proper documentation is the key for comfortable work with your code. And the
best documentation is the one you generate, not write.

This is a repost from my blog.

You can also watch the video on YouTube.

Structure and Preparations

Let’s say we have a simple Express application written in TypeScript. It
consists of only one area – “chores”. It’s glorified todo app, yes. It has:

main.ts as the app’s entry point;
app.ts for the app initialization;
chore/ as the actual business unit.

For the logic, it’s not really that important. What matters is that we have
controller as classes.

// ./chore/controller.ts

import { ChoreService } from "./service";
import { BaseChore, Chore, ChoreUpdate } from "./types";

export class ChoreController {
  private service: ChoreService;

  constructor(service: typeof ChoreService = ChoreService) {
    this.service = new service();
  }

  public getAllChores(): Chore[] {
    return this.service.getAllChores();
  }

  public createChore(chore: BaseChore): Chore[] {
    return this.service.createChore(chore);
  }

  public updateChore(id: string, chore: ChoreUpdate): Chore[] {
    return this.service.updateChore(id, chore);
  }

  public deleteChore(id: string): Chore[] {
    return this.service.deleteChore(id);
  }
}

It uses a service, but that’s really beyond the point. We could (we shouldn’t,
but we could) dump all the logic in the controller and it wouldn’t matter for
this example.

There’s also routes.ts file that basically takes URLs and payloads and pushes
it further:

// ./chore/routes.ts

import { type Request, type Response, Router } from "express";
import { ChoreController } from "./controller";
import { ChoreService } from "./service";
import { BaseChore, ChoreRequest } from "./types";

export const router = Router();

const controller = new ChoreController(ChoreService);

router.get("/", (_req: Request, res: Response): Response => {
  return res.json(controller.getAllChores());
});

router.post(
  "/",
  (req: Request<undefined, BaseChore>, res: Response): Response => {
    if (!req.body.name || !req.body.description) {
      return res.status(400).send("Invalid chore");
    }

    try {
      return res.status(201).json(controller.createChore(req.body));
    } catch (e) {
      console.log(e);
      return res.status(500).send(JSON.stringify(e));
    }
  },
);

router.put(
  "/:id",
  (req: Request<ChoreRequest, BaseChore>, res: Response): Response => {
    if (!req.params.id) {
      return res.status(400).send("Invalid chore");
    }

    return res.json(controller.updateChore(req.params.id, req.body));
  },
);

router.delete("/:id", (req: Request<ChoreRequest>, res: Response): Response => {
  return res.json(controller.deleteChore(req.params.id));
});

And it is exported and thrown into the express app in app.ts:

// app.ts

import express, { Express } from "express";

import chores from "./chore";

export const app: Express = express();

app.use(express.json());
app.use("/", chores);

…which in return is taken by main.ts:

// main.ts

import express from "express";
import { app } from "./app";

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

app.use(express.json());

app.listen(port, () => console.log(`http://localhost:${port}`));

That’s it for preparations. This is a fully working app that accepts GET, POST,
PUT and DELETE. But to know it, you have to go through the code. This is where
OpenAPI comes in.

Adding TSOA for generating docs

In order to enhance the controller with OpenAPI markers, we will use
TSOA. It’s battle-tested library built
exactly for this purpose. If you’ve worked with NestJS or TsED, you might’ve
seen decorators like Get() or Post() for controllers. That’s TSOA.

Let’s start by adding the library:

~ npm install tsoa

It comes fully typed, so there’s no need to add anything more.

After it is installed, let’s create tsoa.json file in the root of our project.
It’s the config file for the generator, it tells it where to look for
controllers and where to save the docs. It looks like this:

{
  "entryFile": "src/main.ts",
  "controllerPathGlobs": ["./src/**/controller.ts"],
  "spec": {
    "outputDirectory": "./docs",
    "specVersion": 3,
    "spec": {
      "servers": [
        {
          "url": "http://localhost:3000",
          "description": "Local server"
        }
      ]
    }
  }
}

Going from the top,

entryFile is for which file is the main one;
controllerPathGlobs is a glob for where to look for controllers;
spec is the config for documentation that will be generated, with outputDirectory pointing at where we want to have swagger.json. specVersion defined whether we want OpenAPI standard (3) or Swagger (2). I highly recommend the former.

Expanding the Controller

As mentioned earlier, TSOA works with controllers. So we need to enhance what we
currently have to make it readable.

Let’s start with marking the controller as Route, tag it and make it extend
the Controller class from TSOA:

// ./chore/controller.ts
import { Route, Tags, Controller } from "tsoa";

@Route()
@Tags("Chore")
export class ChoreController extends Controller {
  // ...

  constructor(service: typeof ChoreService = ChoreService) {
    super();

    this.service = new service();
  }
  // ...
}

From the top, Route allows the library to detect that it’s actually a
controller that takes care of traffic. Tags serves as the name (otherwise it
defaults to "default") and Controller is a thin class giving us few
additional methods, like setting status codes and headers.

All right, let’s start adding some routes! First, we have getAllChores, which
is the easiest. Just add Get() and you’re golden:

// ./chore/controller.ts

export class ChoreController extends Controller {
  // ...

  @Get()
  public getAllChores(): Chore[] {
    return this.service.getAllChores();
  }
  // ...
}

Okay, we’ve been doing this for a while, but does it even work? Let’s try!

~ tsoa spec

And we have a new directory – ./docs – created, with a swagger.json inside.
Okay, let’s keep the momentum going!

The most complex is definitely the POST verb, because it requires defining the
body. Let’s try:

// ./chore/controller.ts

@Route()
@Tags("Chore")
export class ChoreController extends Controller {
  // ...

  @SuccessResponse("201", "Created")
  @Post()
  public createChore(@Body() chore: BaseChore): Chore[] {
    this.setStatus(201);
    return this.service.createChore(chore);
  }

  // ...
}

Okay, it wasn’t that hard, right? The biggest thing is this.setStatus method,
coming from the TSOA Controller class. Without this, we’d get 200, default
success status. It’s not a mistake, but good status codes just nice and makes
the work easier. What’s left are the PUT and DELETE ones, with path params.
Let’s go:

// ./chore/controller.ts

@Route()
@Tags("Chore")
export class ChoreController extends Controller {
  // ...

  @Put("{id}")
  public updateChore(
    @Path("id") id: string,
    @Body() chore: ChoreUpdate,
  ): Chore[] {
    return this.service.updateChore(id, chore);
  }

  @Delete("{id}")
  public deleteChore(@Path("id") id: string): Chore[] {
    return this.service.deleteChore(id);
  }
}

Important thing is to match the param names, so if we have Put("{id}"), we
want to retain this id everywhere in the method.

Right, so it seems we’re done? Let’s try.

~ tsoa spec

And we’re golden. Docs are generated, so we can now have certainty that
everything we say in the Swagger matches the reality.

Bonus #1: Exposing the Swagger docs

Having docs as the JSON file is the most important, but can we also present it
somehow? Sure we can. Enter Swagger UI! And I am not talking about the
Swagger Editor, but our very own instance!

First, let’s install the dependencies:

~ npm i swagger-ui-express;
~ npm i -D @types/swagger-ui-express;

Now, we need to enable JSON imports in our TypeScript config:

{
  "compilerOptions": {
    "resolveJsonModule": true
  }
}

Having this will allow TS to import JSON files just like any other modules.

Now let’s import the dependencies in our main file:

// main.ts

import express from "express";
import Swagger from "swagger-ui-express";
import { app } from "./app";
import swaggerDocument from "../docs/swagger.json";

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

app.use(express.json());
app.use("/docs", Swagger.serve, Swagger.setup(swaggerDocument));

app.listen(port, () => console.log(`http://localhost:${port}`));

That’s it! Now, after we start out server and access
http://localhost:3000/docs, we should have our
docs ready!

Bonus #2: Generated Routing and Validation

But wait, there’s more!

No, really, there’s a bit more TSOA can do.

As you can see, there’s no validation to be found, and all the routes are made
by hand. That's a bit of a problem, because we define routes in routes.ts
file, and then in TSOA annotations in the controller. And all the validation
requires us to jump in and write it manually. These two issues can be solved in
one fell swoop.

First, let’s go back to the config file and add routes entry:

{
  "entryFile": "src/main.ts",
  "controllerPathGlobs": ["./src/**/controller.ts"],
  "spec": {
    "outputDirectory": "./docs",
    "specVersion": 3,
    "spec": {
      "servers": [
        {
          "url": "http://localhost:3000",
          "description": "Local server"
        }
      ]
    }
  },
  "routes": {
    "routesDir": "./src/api"
  }
}

routesDir defines where the routes should be written. I put it in a general
location, because TSOA will take all controllers and combine them into one file.
Right, so let’s try to generate this.

~ tsoa routes

All right! We have routes.ts file created, which… frankly, looks messy. But
all generated code does, so don’t worry. If we dive a bit deeper, there’s
validation added, basing on our routes as well! For example, app.delete checks
for the id in path:

// ./src/api/routes.ts

const args: Record<string, TsoaRoute.ParameterSchema> = {
  id: {"in":"path","name":"id","required":true,"dataType":"string"},
};

// ...

try {
    validatedArgs = templateService.getValidatedArgs({ args, request, response });

// ...

That’s great, but what if we want to have more strict validation? Like, input
lengths?

No problem!

Let’s say we want to make sure that, when we add a chore, name is at least 3
characters long. To do so, we need to modify our type a bit:

// ./src/chore/types.ts

export interface BaseChore {
  /**
   * @minLength 3
   */
  name: string;
  /**
   * @minLength 3
   */
  description: string;
}

Yes, I know these aren't the most appealing, but adding these comments will
allow the generator to create validation clauses. Let’s try!

~ tsoa routes

And in the routes, we have our models updated:

// ./src/api/routes.ts

const models: TsoaRoute.Models = {
    "Chore": {
        "dataType": "refObject",
        "properties": {
            "name": {"dataType":"string","required":true,"validators":{"minLength":{"value":3}}},
            "description": {"dataType":"string","required":true,"validators":{"minLength":{"value":3}}},
            "id": {"dataType":"string","required":true},
            "done": {"dataType":"boolean","required":true},
        },
        "additionalProperties": false,
    },
// ...

Great!

Now all there’s left is to register these routes.

The generated routes.ts exposes RegisterRoutes function, which accepts the
Express app, so it’s just a formality:

// app.ts

import express, { Express } from "express";

import { RegisterRoutes } from "./api/routes";

export const app: Express = express();

app.use(express.json());
RegisterRoutes(app);

That’s it!

—

We now have a fully working application that generated its documentation and
routes. In the future, I’ll show you how to utilize the Swagger file to generate
a fully typed API client for the frontend.

Happy coding!

5 Things to do First as a Team Leader

Tomasz Buszewski — Thu, 01 Aug 2024 09:06:18 +0000

You've made a team lead, congrats! What now?

In a perfect world, your manager would have a series of meetings with you to guide you into your new role. But that's not always the case. Most of us are thrown in the deep end and expect to perform. So here's five things I always make sure to do when taking over a team as a lead.

This post is cross-published from my blog. You can also view on YouTube.

Meet with your team members

The first you should do is talk to your colleagues. These are the people you will work with on a daily basis. Team makes or breaks the lead, so having good relationships within is crucial.

Before you start sending invitations to your Zooms and Google Meets though, make sure you know what you want to communicate. Going in without preparations sure gives this "laid back" vibe, but it also can raise questions of whether you actually know why you’re here.

So, what should you say? Some must-haves are:

A good introduction with some background. How did you get here, what experience you have under your belt, what makes you the person for the job? Highlight your strengths and try to lean into your interlocutor’s experience to connect with them;
Brief vision of how you envision working together. What you would like to introduce? What worked in your previous companies and why?

This meeting should also help you to know your new team members. It’s a good place to ask some questions, like:

What’s their background, past experiences, hobbies;
What do they think is missing in the team or in the company;
What works and what not.

Don’t expect five hours conversation though – they will most likely be reserved. Don’t take it against you – it’s completely normal. What’s important is not to push anyone. Some open sooner, some later – but it’s on you to see when they are getting pressured. If you see someone’s getting less comfortable, don’t push any further. Remember, you’re for a long ride together, and pressing people will never work out, it will just alienate everyone.

Okay, if you know what to say and what to ask, send invitations. I make it 30 minutes (with 15-20 minutes to spare in my calendar, just in case), as there’s no point to keep people for too long. I like to write them a heads-up on Slack, something like “Hey, I’ve sent an invitation for an intro call, nothing fancy, just a chat to know each other”. I found out it takes a bit of the edge and costs virtually nothing.

Meet with your stakeholders

The next thing you should do is to meet with the stakeholders. Product owners, marketing and design leads, other team leaders. This shouldn’t be that different from meeting your team, after all this is – again – the intro call. When introducing yourself, try to:

Highlight your experiences with working with people in a role similar to theirs (for example, how you improved design/development handover or estimations);
Offer your support, but underline that you’re still onboarding and most likely will require their help.

Also make sure to prepare questions you want to ask, such as:

What are their expectations towards you?
What are their expectations towards your team?
What strong sides they see when working with the team so far?
What weak sides they see?

After having answers to your questions, you will be able to start formulating a game plan for the team. It’s not a job for now, but something you should keep in your mind.

Go Through the Codebase

Once you talked with the devs, you’ve most likely heard at least something about the code. But nothing beats going through it alone. Clone the repo and read the docs attached. Note all the observations, like:

Can it be installed easily? Will newcomers have hard time getting it up?
Does it require any internal knowledge to get it running?
Does the pipeline looks understandable? Can it be modified by someone who isn’t a senior?
Which parts are changed often, which are dormant for months or years?
What are observability options? Which parts of the applications are measured, can you see bottlenecks?

Note these findings and address them with your team. There’s nothing wrong in showing that you don’t know everything. It is certainly better than pretending that you do, and make a laughing stock out of yourself.

Take a Step Back

You’ve analysed all the things your colleagues and co-workers told you. You made some notes, jotted some ideas for what’s to come. You have an idea of what people like and what they don’t in the team. You know how the team is perceived by the other stakeholders. Great, now what?

Now, take a step back. Put these things on the back burner for a few days and just be present in the team. Join meetings, listen how the team works together, just feel the pulse of it. Don’t jump into any conclusions, don’t assume anything. Just listen.

I always try to take at least three days, possibly a week or more, to see how the team really behaves. What people say is very important, but keep in mind that they don’t always perceive things as they are. We are all biased, and you, coming from the outside, have a unique perspective that folks working in the team for months or years lack. During this time, try to note:

What pain points the team has? Maybe too many or too long meetings? Or too much tasks in the sprint? Too much pressure? Or the other way around – too little to do?
How is the communication within and outside the team? Are people on the same page? Are things getting agreed on during private conversations and then introduced?
Who works well with who. Are there are “pairs” that perform well together? How can you utilize this further?
Who is the natural leader of the pack? Who’s the “go-to” person? Who mentors others?
Are things reported as problematic during the intro calls happen often? How do they look from the outside?

After having these things out, you will not only know what people think, but also will have your own observations of how the team works. It will help you formulate any and all further steps. But do note that these might change and for sure does not paint the entire picture. Take it with a grain of salt, even if you are certain.

Start Formulating the Game Plan

Armed with all the knowledge you’ve accumulated throughout last weeks, it’s time to be the leader. One of the most important qualities of a team lead is the ability to play the long game.

This step is the hardest one, because it requires analyzing all the findings and condense them into actionable items. You most likely find two types of action points:

Short-term goals, or low-hanging fruits, such as:

Minor code problems, like flaky unit tests or pipelines;
Too long and/or numerous meetings.

Things like these can be addressed rather quickly, as they require little actual work. Too many meetings? See which one are the least beneficial or which don’t require every team member. Flaky tests can be at least investigated during one sprint, with a bit of luck, this problem can be taken care of by simply assigning someone on it full-time.

But there will, most likely, be more complex issues that you will need to spread and plan in time, for example:

Lack of stakeholder communication with the team;
Constant sprint overloading;
Internal conflicts.

Such things require your attention the most. You need to dive deep into this and analyze why they occur. For example, lack of stakeholder communication may be caused by chaos in the management, or by ignoring engineers and treating them as tools. It’s your job to build conscious recognition of your team. If sprints are overplanned, that’s an issue with either management, or the team, or both. Who forces these tasks into sprint? Why the team doesn’t fight back, and if they had, why it didn’t work? Are there conflicts? People don’t have to like each other, but they should at least stay professional to be able to work together. Not everybody is capable of that though, and it’s your job to make sure this conflict doesn’t spill on the entire team.

—

Doing these five steps should not only give you ideas of what the team really looks and works like, but also how the company works with the team. From there on out, you should formulate both short- and long-term plans to mitigate the issues and embolden the strengths.

Good luck!

Welcome, New Member sigh

Tomasz Buszewski — Fri, 27 Mar 2020 08:07:41 +0000

Taken from my blog: https://www.buszewski.com/writings/2020-03-27-welcome-new-member/

In IT, it is very common to have new team members. And yet, welcoming them is hardly something we’re good at.

Before then even come

There is a checklist I like to have before the new person will come. Simple points that make sure they feel good.

make sure their desk and chair is there and is clean (yes, I have cleaned a desk for someone, nothing wrong with it);
make sure their hardware is there, is working and set up properly;
make sure your team mates know that they are coming;
make sure all the accounts and accesses are granted (if this is impossible due to some restrictions, make them know beforehand);
make sure the access card is ready (this is important, it’s like you’re having a new family member but „you don’t get the keys yet”);
designate a buddy (more on that later);
prepare an issue (also, more on that later).

When I know that someone will come, let’s say, on Monday, I make sure to have this day clean of all meetings that are unnecessary.

Do a tour, thorough one

New environment is always stressful. For almost everyone. So make sure you make a tour across the office.

Don’t run across the entire floor asking to shake hands. Come on, how many pairs of name/face can you store in your head in one minute? Try doing it in batches, first meet the closest team mates, then spin away with other departments. Maybe even split this into more days, 30 minutes each, if your company is big.

Don’t show kitchen, toilets etc. when returning from somewhere. Go from your room, it will be easier to memorize the route this way.

Show where are cups and mugs are and how to use coffee machine. This is also a good moment to take a breather and drink something and have some small-talk.

Show where are office supplies. Something as trivial as getting a pen without the necessity to ask people about it will really boost your new team mate adoption.

Don’t let them go alone

Sitting people in front of their desks and walking away on the first day is the worst thing you can do. I got this treatment more than once, „here’s your seat and desk, settle in” and he walks away. What the fuck I am supposed to do? Where is… anything?

Instead, sit with them. Ask, do they need some time to set up their computer, or would they like you to tell them, what they’ll be needing.

If they’ll say they need some time alone, no problem, but don’t forget about them. Be back in an hour or two, just see how it’s going. Don’t hover, don’t be a helicopter. Just pop in, „you okay there, need anything” and that’s it.

Spend time with them

After the workstation is set up, there is time to set up the actual project. Don’t send the wiki link and be off. Such documents are often

outdated;
too long;
too technical;
assuming that whoever reads them have some domain knowledge.

This is something I call a dick move. But what if I don’t remember the process, you may ask. Well, that’s okay, open that goddamn Confluence and go through it together. Or even better, get someone who might know, and work together. This will also help the new one meet other members. Just make sure you don’t call in someone who’s harsh.

After that, make sure that someone will sit next to that person. Maybe you, maybe someone you designate to do this. Make sure this is a knowledgeable, communicative person. No point in sitting a guy with headphones from 9 to 5. This is often called a buddy system.

How to prep a buddy

Asking „who want’s to be a buddy for Anon here” is a bad move. There won’t be „me, me!” people yelling. There will be silence, and someone with a sense of responsibility will come forward only to regret it afterwards.

Instead, pick someone you know in your team early. This doesn’t have to be the best developer. It has to be the most communicative, friendly person. A few days before the new person arrives, get that someone on a one-on-one and ask, „could you be a buddy for Anon?” If you are a good lead, they won’t be afraid to say „no”, if they can justify it. If they’ll refuse, try the next person. Don’t push it. Forcing people into such interactions never goes well.

But let’s assume they are fine with it. So, what does a buddy do? Buddy simply is there for this person. Buddy is a go-to, when something breaks, something is not clear, something needs clarification.

And, once again, you can be that buddy, if you decide so.

Don’t let their questions go unanswered (or answered vaguely)

New people in the organization will have questions. They can be like a kid, asking all the time. And this is totally fine. It’s a sign they really are interested in this place. Make sure you answer them, and answer thoroughly. Sure, there’s no need to dive deep in the technical aspects on the first day, because they’ll won’t digest it all. But don’t answer with „we’ll get to that later” or „you don’t need this right now”. Even if they really don’t need it, there’s no harm in telling it.

Get them to lunch

„Hey, what time do you eat?” is a great question to ask during the day. „You want to grab something?” On the first day, there is so much going on, people may either forget, or be too shy to walk away from their station for lunch. Make sure that this is not the case. You can go together or in larger group, but make sure you don’t scare the new person. You can feel if this is someone comfortable with a crowd or not. Don’t try to „break their comfort zone”, you’re not a dickheaded coach.

Treat them as part of the team from day one

Great things may happen, if you treat new people like the old ones. Like they have always been here. Let’s say you team goes for lunch every day at the same time. Take them with you. You have a problem with your code, ask them, maybe they’ll help. Even if not, they will feel validated and needed. Look for such opportunities. Even the slightest gesture may prove beneficial.

Try having day-one commit

Nothing says „we need you, mate” more than allowing them to work right off the bat. After they set up, have coffee and lunch, give them a small task. Nothing fancy, nothing groundbreaking, just something small to stretch their legs. A small „atom” component, or a tiny test that was missing for a long time.

A lot of people will get something serious to do weeks after the first day. And this is horrible, both business-wise and company-wise. The former – you are paying this person. The latter – you will look like lazy slobs.

—

Caring for new people on board is often neglected. This is wrong and causes detachment. If you don’t care for me, why should I care for you, Company Name?

Checkboxes and radios – proper form design

Tomasz Buszewski — Wed, 18 Mar 2020 17:15:20 +0000

Crosspost from my blog: https://www.buszewski.com/writings/2020-03-18-proper-form-design-checkboxes-and-radios/

When building a form – and expecting a user to fill it – the most important thing is ease of use and recognizability.

Some time ago, in mid 2000s, Internet Explorer 6 and 7 were serious players. And I mean serious, every product had to be compatible with those guys. The Microsoft boys were really hustlin’, and every front-end developer knew that.

There was this one thing no /9 or !important couldn’t fix. It was the input[radio] and input[checkbox] fields. Styling those was practically impossible, as they never allowed any tinkering in properties other than border.

Of course, aesthetic-hungry webmasters developed a lot of JavaScript (most of the time in a form of jQuery plugin) that allowed to style the input however we wanted. But there were tradeoffs. Hard, often limited, development. Lack of accessibility. Requiring JavaScript (and back then, it wasn’t so obvious.) So the forms remained mostly untouched, and it was good.

And then, standardization came. Internet Explorer lost its significance. Suddenly, styling input[radio] wasn’t that impossible. We all used the :before trick. It allowed us to do something like this:

Not fancy enough? So, why don’t we break it?

(See it live.)

You see where I am going with this overlong exposure?

Such examples were very common back then. Round checkboxes and square radios. But I thought this was all left in the past, where poor interfaces prevailed.

But they are still here.

I got the munchies recently and decided to order a pizza via Internet. There is one I particularly like, it allows picking own ingredients. So I basically make the „Greek” pizza I ate when I was a kid. Form, more or less, looks like this:

See the problem? If yes, congratulations, if no, let me play in Sketch some more:

Now you see? All of this items look like radio buttons, while in reality, those are checkbox types.

This is not a design choice. No, design is making it more appealing while keeping the usability intact. This is a mistake. Done perhaps by someone with less experience in the field, but nevertheless, a mistake. Know better. Don’t commit such mistakes.

—

Rounded input[radio] and square input[checkbox] is something all users know for a long time. Those were the first „tick” fields we saw, probably somewhere in Windows settings panel. They were there, when first web pages that allowed actually doing something other than reading, hit the ‚net. And now they are here, and please, make them stay.

Lessons learnt from new buszewski.com

Tomasz Buszewski — Fri, 13 Mar 2020 15:40:42 +0000

Originally from my blog: https://www.buszewski.com/writings/2020-03-13-lessons-learnt-from-new-buszewski.com/

I’ve been building my new portfolio for four years, with different designs and technology stacks. And I’ve learnt quite a few things from it.

For starters, I’ll say that this iteration stands on Gatsby (so, React) and Styled Components, written in TypeScript. Data is sourced from local files in Markdown.

Before I’ll tell you, what did I learn, I will tell you, why did I choose to do things this way.

I’ve been fan of React for quite some time. More than four years, in current front-end world this seems like forever. I’ve started experimenting in 2015, using in 2016 and this is my go-to framework for UI ever since.

Gatsby was a natural choice for a React fan, so I didn’t even spent much time on alternatives. Perhaps I should. But since it had all that I like, including GraphQL and Markdown sourcing almost out of the box, I was bought.

Styled Components. The standard for styling next-gen web app, isn’t it? All the CSS-in-JS glory, ease of props handling, editor support. Everything is here.

And TypeScript. Actual standard for any serious JavaScript development, plus it really saved my ass more than couple of times in the past. It was a no-brainer.

So, why am I not fully satisfied?

Because it’s overengineered. Holy fuck, it is so overengineered, I am angry at myself for doing such a rookie mistake.

Let’s start from the beginning. I wanted to build views from components, so naturally, I’ve created a design system (with atomic design methodology) in Storybook.

Now, Storybook is really a great tool. And using it does help to have isolated components. But it also requires writing stories for every piece of code. Let’s take a look at a very simple blockquote element.

For reminder, it looks like this

First, code:

/**
 * @author tomek
 * @since 2020-02-26 10:27:24
 */

import * as React from "react";
import styled, { StyledComponentBase } from "styled-components";
import { theme } from "@ui";
import { ColorContext } from "@ui/Atoms/Section/Section";
import { Paragraph } from "@ui/Atoms";

type BlockquoteType = string &
  StyledComponentBase<"blockquote", any, {}, never>;

const Blockquote: BlockquoteType = styled.blockquote`
  opacity: 0.65;
  margin-bottom: 3rem;
  margin-left: 1rem;
  padding: 0 1rem;
  border-left: 1rem solid
    ${() => `var(--section-${React.useContext(ColorContext)}-highlight)`};

  & > ${Paragraph}:first-of-type {
    font-size: 2rem;
  }

  ${theme.breakpoints.desktop} {
    grid-column-start: 3;
    grid-column-end: 7;
    margin-left: 1.5rem;
  }
`;

export { Blockquote };

And story:

import * as React from "react";

import { text } from "@storybook/addon-knobs";
import { storiesOf } from "@storybook/react";

import { Blockquote } from "./";

storiesOf("Atoms/Blockquote", module).add("Normal", () => (
  <Blockquote>{text("Example text", "Hello")}</Blockquote>
));

While I know, this is super short, please note that this is basically styling an element in React and Styled Components way. Everything is a component, right? Looks kinda tedious, doing this for, like, ten elements? Or more? Yeah, it is tedious and in a long way, boring.

Don’t get me wrong, while building a big, really big application, like we did in 4Finance or Batmaid, this totally makes sense. But here? It’s way overblown. Unfortunately, it came to me a bit too late, so there was no point of going back.

Next thing that really slowed me down was, in fact, TypeScript. Why? Because everything has to be typed.

For those who are familiar with GraphQL, the problem may be well known. If you want to use queries as data source, you have to write the entire interface for it. It may look like this:

export interface IBlogEntry {
  title: string;
  pubdate: string;
  slugPubdate: string;
  summary: string;
  slug: string;
  featuredImage: null | any;
  photo?: null | any;
}

export interface IBlogNode {
  entry: {
    id: string;
    entry: IBlogEntry;
    fields: {
      slug: string;
    };
  };
}

As you can see, I’ve succumbed and used any. It wasn’t like this from the beginning, I actually had it typed, but as I changed the goddamn featuredImage query, I had to keep track in the interface. And it was so fucking tiresome, one evening I decided to just any it and be done.

Again, having typed such things is great. When you use it more than once. Here, it was just more work that wasn’t beneficial at all. Perhaps there is a magical tool that creates interfaces from GraphQL schema (if you know it, tell me, please). But for now, it’ll be like that, until I’ll have the time and willpower to change it. (So, like, never).

Last, but not least, is Gatsby. I know you can clone a starter and roll with it within seconds. Yes, but as I like to have control over what I do, I prefer to actually build the stack. So, gatsby new spastic (yes, I named it after a Squarepusher song) and then, well, plugins. I want TypeScript – plugin. I want Styled Components – plugin. I want PrismJS – plugin. I need to catch inner links – plugin. Google fonts – plugin. There is plugin for everything. Why this is bad? Because sometimes it would be easier just to do it manually. But, given how fragile can Gatsby be, it’s safer to stick to community-developed addons. Especially, when there is tempering with Webpack involved.

There is one extra thing that I’ve decided not to do at the beginning. Tests. Yes, the guy that talks about testing, coverage and TDD all the time didn’t do tests. Why? It is very simple – there is nothing to test, really. There is no logic in here, apart from a couple of if statements. Only actual tests that could be used here are E2E or visual regressions, but, again, given the size of this project, I chose to discard them.

—

Given all these, there was actually one thing that spawned the entire complain. File sizes. I know that current front-end is resource-heavy. But, for crying out loud, I’ve used only couple of additional plugins, namely Styled Components and React Markdown. And it’s goddamn gigantic. In total, it pulls over 350 KB of just JavaScript.

—

So, all that being said, what this actually fun? Yes, yes it was. After I configured everything, set up Storybook alongside TypeScript and Gatsby, added a plugin to resolve paths and spent a lot of time on configuration, it was really nice to work on this project.

What I would do differently? I would use a different framework for this, maybe Jekyll or Hugo. I would refrain from using React and Styled Components in favor of pure JavaScript (or VUE) with SCSS. Turning off the entire JS doesn’t really trip the page of anything. Header doesn’t hide, and links not SPA-like, without a nice animation. But apart from it? Works normally.

Perhaps, when I’ll be really bored, I will rewrite this using a simpler stack.

A note on naming colors

Tomasz Buszewski — Thu, 05 Mar 2020 13:28:25 +0000

Posted earlier on my blog.

Remember that text saying "in IT, naming thing is hard"? This is even harder when it comes to colors.

Most of the time, a color is already named. Red. Blue. Rebecca Purple. But those names bare no context. Anything can be blue. So, what to do, when we want to know, what we are dealing with?

Even more abstraction

One thing that I've used is to generate color names at random. With Name That Color, I was able to tell the difference between one shade of teal from the other. Even though they are visually different, in the code they are just different strings. Take a look at this:

:root {
  --color-spray: #74E5EF;
  --color-java: #24C7C0;
}

Seems pretty obvious and easy. Or does it?

Try to wait a bit. Forget some stuff. And suddenly, what is that "java" color? pops in your head.

Use contextual names

When you are getting your colors, they are for something. This is for the header text. That's for links. And that one's for the background. Why not name them as such?

:root {
  --color-bg: #fafafa;
  --color-text: #222;
  --color-links: #ffffaa;
}

This is the most readable thing you can do when naming colors. That way you won't have to care whether this color is "red" or "blue". It will be "background".

Seems obvious, but much too often I found people reinventing the wheel.

Bonus: theming

During the design phase, colors are carefully picked. But sometimes a need arises. Let's have a dark mode! Or let's have a colorblind mode! Using contextual names allowed to define themes with ease:

:root {
  --color-bg: #fafafa;
  --color-text: #222;
  --color-links: #ffffaa;
}

@media (prefers-color-scheme: dark) {
  :root {
    --color-bg: #000;
    --color-text: #666;
    --color-links: #fcfcfc;
  }
}

There you have it. Simply overwriting values basing on some external factors is very simple using such notation.

Naming things is hard. But using meaningful names will always be the way to go.

Don’t forget to forget your code

Tomasz Buszewski — Mon, 10 Feb 2020 21:23:14 +0000

How often do you find yourself coming back to the code you’ve written a few months ago?

I am a very forgetful person. I remember the basics, like David Bowie’s discography, At Seventeen lyrics and my wife’s phone number…-ish. But apart from that – nothing. Forgetfulness is my second nature and, even though I struggled at first, I have accepted and embraced it.

Forgetting to buy flour is one thing. Forgetting why did I write this particular code is something completely different. And while groceries have lists, I couldn’t find anything similar for my work. Until I had an epiphany.

Back at 2016, I was working on parkiet.com. As a senior developer, I have written hundreds of lines of code for the project. Some more important than others, but all required for something. And that something had escaped me more than I’d like to remember (which I don’t, duh).

I knew that something has to be done. But what?

Write documentation?

Great idea. And I wrote long paragraphs of JSDoc, quite often longer that it required. But problem with this was very evident – I really had to write additional lines, which were a) expensive, and b) boring. Plus, if I didn’t do this right after (or even before) writing the actual body of function, I might have had a problem of recollecting all the caveats such code had.

After couple of tried, I’ve decided to strip the docs from all the descriptions that were either vague or simply unnecessary. Basically, only type notes left.

Write thoughtful documentation!

I never like the expression „my code is my documentation”. No, your code is your code, your documentation is your documentation. With languages that lacks real types (in that example, JavaScript), thinking that something that:

function counter(acp, r) {
  if (acp.size) {
    return r + acp.size;
  }

  return r + 1;
}

will document itself is just reckless. So, how to turn this code into something more decent? A simple JSDoc would help:

/**
 * Function that sums current entities or increases the counter by 1;
 *
 * @param {Object} acp - object holding incoming value data;
 * @param {number} [acp.size] - value of current entity;
 * @param {r} r - current value
 * @returns {number}
 */
function counter(acp, r) {
  if (acp.size) {
    return r + acp.size;
  }

  return r + 1;
}

Adding these comments is making this code looks cleaner – even though I didn’t change a single line!

What’s also cool, JSDoc can be then extracted into a static documentation! And may look, for example, like this.

Write tests

Importance of writing tests is something I can’t stress enough. But, apart from the evident gain, it also helps to understand the code we are writing.

Let me take that simple function I have written before (counter) and test it!

describe("Counter tests", () => {
  it("should sum the values from entites with current one", () => {
    expect(counter({ size: 1 }, 0)).toBe(1);
    expect(counter({ size: 1 }, 1)).toBe(2);
  });

  it("should increase the current value by 1 if no apc is given", () => {
    expect(counter({}, 0).toBe(1);
    expect(counter({}, 1).toBe(2);
  });
});

These two simple tests are basically giving all the functionality away. And it’s super-simple to understand, thanks to great syntax provided by Jest (and by a lot of other test tools). In general, testing frameworks aim to make writing tests easy (that’s why they stay on the market) and tests themselves readable. A good test will always be easy to read.

Use typed language

I remember being very anti TypeScript or Flow. I thought that they only make me write more code to have the same result. And this actually is true – these „types” are being removed upon transpilation, so they do not pose any additional value to the client.

But! They pose a huge addition to the developers! While properly used JSDoc can solve a lot of problems, TypeScript and Flow have the advantage of editors support. Let me write counter function in TypeScript, really quick:

interface IEntityConfig {
  size?: number;
}

function counter(acp: IEntityConfig, r: number): number {
  if (acp.size) {
    return r + acp.size;
  }

  return r + 1;
}

Not much have changed, but it seems clearer. Now I know, what may come inside acp, what r is and what the function will return. Of course, this simple example doesn’t show a lot, but it is still illustrational.

Name your code properly

I’ve wanted to make this the last point. Because this is the most important thing. Naming functions and variables is hard, but it pays. Watch me change that crappy counter into a proper piece of code:

function increaseEntitiesCount(entity, currentState) {
  if (entity.size) {
    return currentState + entity.size;
  }

  return currentSize + 1;
}

See? No TypeScript, no JSDoc, no tests even. And yet, this is readable and clear.

Conclusion

Remembering is hard. That’s why I prefer to make things so obvious, I don’t have to remember what they do or what they even are. I will know this, when I read what I’ve written.

What is Redux, really? – Part 3

Tomasz Buszewski — Tue, 14 Jan 2020 10:12:46 +0000

Last time I've talked about Redux as a state manager. Now I want to talk about Redux as the state manager in a React application.

A need for state management in React applications

More often than not, Redux is being coupled with React, as it makes it feel more like a working application rather than just a collection of linked views. There is a trend of abstracting every possible action away from React's own state to Redux's store. But this is rarely a good decision, as this data is stored away and rarely accessed by more than one component.

Moving state up, making it accessible to more elements should be a decision made on an actual need rather than anything else. For example, if your application renders comments, what is the point in storing these anywhere else than in the context of their parent post?

But, sooner or later, it all comes to a point where it actually makes sense to abstract the state and make it global.

Connecting Redux to React

Redux itself is framework-agnostic. It means that it can be used with whatever other tooling there is. In the last article, I made a vanilla JS Redux implementation and it works just fine.

For React, there is a special binding called react-redux that provides useful functions to wrap existing components with Redux.

What is important to note here, is that even though this is a specific binding for a specific framework, implementation of Redux itself remains the same across all platforms. For this examples, I am using the code I've created the last time.

First thing is, to wrap the app with Provider component. It will make that all of its children will be able to access the store. It is as simple as

const App = () => (
  <Provider store={store}>
    <ProductList />
  </Provider>
);

Now every component that resides inside ProductList can subscribe itself to Redux store.

Connecting components

This is slightly more complex, as Redux leaves a lot of decisions up to the developer.

Every component can do two things – read state and dispatch actions. Not everyone has to do both, though.

Passing data from Redux to the React components is done by a higher-order component called connect. It decorates our instance with what we need.

Higher-order components (or HOCs) are functions that return a new component enhanced with some logic or data.

Let's assume that we need to pass the state of one of reducer – orders. To do this, we'll use a mapper function. It will accept an argument – our store – and return an object consisting of what we want.

A state mapper function – commonly known as mapStateToProps or simply mapState – is the first parameter of connect. It accepts two parameters, with mandatory state and optional ownProps. I will omit the latter for brevity. Please note that those parameters will be injected automatically, there is no need to do this manually:

const mapState = (state) => ({
  items: getOrders(store),
});

Selectors

You can see here the getOrders function. This is a selector. It is creating a facade to access the store without forcing the developers to know the details of implementation. This way, you can change the store and only replace the business logic without affecting the usage in components.

A simple selector can look like this:

export const getOrders = store => store.orders;

All it does is simply exposing (parts of) our state to the consumer. It can have more logic, filter or sort things. For example, we could have a selector called getShippedOrders which would look like this:

export const getShippedOrders = store => store.orders.filter(order => order.status === "SHIPPED");

Accessing passed properties

As I've said before, connect is a higher-order component. Which means, it has to accept our base component and then enhance it. To do it, we simply create a new variable:

const ProductListComponent = () => <div>Hello</div>
const ProductList = connect(mapState)(ProductListComponent);

Now, we can use it in a regular view, just like a normal component.

But, how to access these new properties that we've injected? Well, those are exposed as props! All we have to do is:

const ProductListComponent = (props) => {
  console.log(props); // items: [{...}, {...}]
  return <div>Hello</div>
};
const ProductList = connect(mapState)(ProductListComponent);

This data can be used within our view or passed down. A simple view utilizing this can look like this:

const ProductListContainer = (props) => (
  <List>
    {props.items.map(item => {
      return (
        <ListItem key={item.id}>
          Order #{item.id}
        </ListItem>
      );
    })}
  </List>
);

Dispatching actions

Great, so now we have some data retrieved from the Redux store. But, as I said previously, state management is not only reading, but also writing. In order to write to state, an action has to be dispatched.

Dispatching is handled in a similar fashion to reading. connect accepts second parameter – an object commonly known as mapDispatchToProps or mapDispatch. It looks like this:

const mapDispatch = {
  ship: setShipped,
};

This is the simplest example, simply assigning a function to a key in object. Now our connected component, ProductList, looks like this:

const ProductList = connect(mapState, mapDispatch)(ProductListComponent);

Now function ship is passed as a prop and can be executed:

const ProductListContainer = (props) => (
  <List>
    {props.items.map(item => {
      return (
        <ListItem key={item.id}>
          Order #{item.id}
          <Button onClick={() => props.ship(item.id)}>
            Ship it!
          </Button>
        </ListItem>
      );
    })}
  </List>
);

Conclusion

As you can see, Redux blends very good in a React application, as it strongly leverages composition.

Code sample on CodeSandbox

What is Redux, really? – Part 2

Tomasz Buszewski — Sun, 01 Dec 2019 16:50:24 +0000

What is Redux, really? – Part 2

Last time I talked about state management in general. Now let's see what Redux – the state manager for React – is all about.

Recap

To take full advantage of this article, it's important to remember what is a state manager. It's a tool that allows to both read and write information about the application. You can use it to inform one module about changes in the other one without making too much fuss.

Two fundaments of Redux – Actions and Reducers

Redux operates with many terms, such as store, state, dispatchers, selectors etc. But the most important are actions and reducers.

Action – request the change

Actions are the building blocks of an interactive state. They are responsible for "telling" the state how to change.

Here's an exemplary action that will change an order state from "awaiting" to "shipped":

const SET_ORDER_SHIPPED = "SET_ORDER_SHIPPED";
{ type: SET_ORDER_SHIPPED, payload: 123 }

Now let's explain what is happening here. type is the name of action that is being executed, and payload is the required information. Here, our type is SET_ORDER_SHIPPED and payload is 123 – our product's ID. In human terms, it would sound like "Change order 123 status to Shipped".

Why defining types as variables rather than strings?\
It's tempting to create action types as text, but this can generate problems in reducers. You have to be sure that there's no typos anywhere. Defining a constant name once and then using it in both action and reducer prevents such problems.

Dynamic actions – or, created actions

It's very easy to dispatch an action that has all the fields defined. But it's very cumbersome to create an action for every item, for example:

const SET_ORDER_1_SHIPPED = { type: "SET_ORDER_SHIPPED", payload: 1 };

const SET_ORDER_2_SHIPPED = { type: "SET_ORDER_SHIPPED", payload: 2 };

What we need here is an action creator. Something that will generate the action basing on some terms.

What is important about action creators is that they need to be pure functions. Meaning, every time an action is created, the result (and the reducer result) has to be exactly the same. They cannot interfere with anything from the outside.

So, let's create an action creator for our shipping:

const setShipped = id => {
  return {
    type: SET_ORDER_SHIPPED,
    payload: id,
  };
};

Now, running setShipped(123) will create an action that we want:

{ type: SET_ORDER_SHIPPED, payload: 123 }

What happens after an action is fired?

In Redux, actions aren't really "fired". They are being dispatched. Actually, you have to dispatch them. Basically, it looks like this: you click a button Mark the order as Shipped. Action SET_ORDER_SHIPPED is being dispatched and reducer receives it. After processing, the change is reflected in the store.

Reducer – make the change

Action alone is nothing. Who knows what SET_ORDER_SHIPPED means? Well, we should know. And our reducer should as well.

Reducer is responsible for receiving that action call and applying the change. Most of the time, it's in a form of switch statement:

switch(action.type) {
  case SET_ORDER_SHIPPED:
    return state.map(order => {
      if (order.id === action.payload) {
        return { ...order, status: "SHIPPED" }
      } else {
        return order;
      }
    });
  }

  default: {
    return state;
  }
}

What's important for reducers it that they always have to return the state. The whole application relies on it, and if something goes wrong, it will crash.

States and store – what's the difference?

Redux operates on two very important concepts – states and store. They are not, by any means, interchangeable.

There are multiple states. Every module can have its own state. They are responsible for housing all the information and make it available to the app. Example of states:

const orders = [
  { id: 1, items: [9, 8, 7], client: 234, status: "SHIPPED" },
  { id: 12, items: [8, 7, 6], client: 214, status: "AWAITING_PAYMENT" },
  { id: 123, items: [1], client: 345, status: "AWAITING_PAYMENT" },
];

const clients = [
  { id: 1, firstName: "Frank", lastName: "Ocean", addresses: [1] },
  { id: 12, firstName: "Marky", lastName: "Mark", addresses: [9, 8] },
  { id: 234, firstName: "John", lastName: "Smith", addresses: [2, 3, 5] },
];

const items = [
  { id: 1, name: "Lamp", description: "..." },
  { id: 2, name: "Desk", description: "..." },
  { id: 3, name: "Bulb", description: "..." }
];

States can be very good information storages. If you need to display items in various places in your store, a single source of data is a good idea.

There is always a single store. It's built with states, with every state being a separate entity. Example of store:

const store = {
  orders,
  items,
  clients,
};

Since there is only one store, it houses all the states and has an API that allows the app to interact with them.

You never modify the state directly. It always has to done via the store.

Single-state store

There is an option to have only one state, for example, housing only orders. While perfectly fine, it will probably result in two things – either growing to the point where it will be very hard to maintain, or being a very small collection of information that would work stored someplace else.

In my opinion, creating a single-state store is pointless. If you need to store very little information, keep it someplace else. If you don't know, how much data you'll store, create a multi-state store. It will scale much better, and refactoring single-state to multi-state can be tedious.

Conclusion

I hope this clears out Redux in general a bit. I know this is a lot of information, so I've prepared a code sample for this part. In there you'll find a working examples of an action, a reducer, state and store.

Code sample on CodeSandBox.

In the next part I'll explain how this all blends in React ecosystem.

The three states of data-driven UI

Tomasz Buszewski — Wed, 20 Nov 2019 16:39:13 +0000

How should our UI behave, when our logic doesn't really know, whether there will be any actual data?

I remember the times, when there was no such issue as "not knowing" about the data in the UI. We knew, and if it was there – we imported the template. If not – we didn't even display the section responsible. It was all server rendered and handled by a simple if condition.

{% if comments %}
  {% include "comments.html" with comments %}
{% endif %}

And that was it, really.

We can have similar approach today. Why not? In our React app, it would be as easy as to write

comments && <Comments />

This is a binary state. True or false, 1 or 0. Nothing more to it.

The third state

As clarified before, two states are true – there is some data, or false – there is not. But we can expand it, have an ambiguous in-the-middle one:

const STATE = {
  OK: "OK",
  FETCHING: "FETCHING",
  NO_DATA: "NO_DATA",
};

This will allow us to have more complex rendering and provide user with the actual information about what is happening.

Assuming the backend returns a JSON array, code can look like this:

const Comments = (props) => {
  const [fetchState, setFetchState] = React.useState(STATE.FETCHING);
  const [comments, setComments] = React.useState([]);

  React.useEffect(() => {
    (async () => {
      const { data } = await props.fetchComments({ id: props.id });
      setFetchState(data.length > 0);
    })();
  }, []);

  if (fetchState === STATE.OK) {
    return comments.map(comment => <Comment key={comment.id} {...comment} />);
  }

  if (fetchState === STATE.NO_DATA) {
    return <NoData message="No comments for this post" />;
  }

  return <Loading />;
};

We are using very extensive render fragment – two ifs and one default return. This is mostly for clarity, as this could be written in a shorter way. It now demonstrates purely, what will be displayed when. And, we could have more states, for example, when fetching will not be successful.

This approach is far better than basing on state derived from data. We could check comments array for length, and even turn it into null when fetch returns no result. But this introduces a risky type change – we'd transform an array into a null. We'd have to check this type every time we would like to do an operation on this value. This is far too error prone.

Conclusion

This is very basic and very simple example of how UI should be treated with async data. Displaying endless spinners when there's nothing fetched is very bad practice and should be avoided. With this approach, you can have cleaner and more intuitive UI and UX.

DEV Community: Tomasz Buszewski

Design Systems in React – Scaffolding and Setup (Part 0)

Bootstrapping and Storybook

Adding Tailwind

Adding linters

Defining our first component

Writing stories

Adding Plop to generate scaffolding

How to Run Technical Interviews

Describe the Interview Process

Bring Someone with You

Don’t Get Technical at the Beginning

Make Proper Introduction of Yourself and the Company

Ask About Real Life Problems

Have a Pair Programming Session…

…or a System Design Challenge

Leave Them Time for Questions

How to Add OpenAPI to your Express App?

Structure and Preparations

Adding TSOA for generating docs

Expanding the Controller

Bonus #1: Exposing the Swagger docs

Bonus #2: Generated Routing and Validation

5 Things to do First as a Team Leader

Meet with your team members

Meet with your stakeholders

Go Through the Codebase

Take a Step Back

Start Formulating the Game Plan

Welcome, New Member *sigh*

Before then even come

Do a tour, thorough one

Don’t let them go alone

Spend time with them

How to prep a buddy

Don’t let their questions go unanswered (or answered vaguely)

Get them to lunch

Treat them as part of the team from day one

Try having day-one commit

Checkboxes and radios – proper form design

Lessons learnt from new buszewski.com

A note on naming colors

Even more abstraction

Use contextual names

Bonus: theming

Don’t forget to forget your code

Write documentation?

Write thoughtful documentation!

Write tests

Use typed language

Name your code properly

Conclusion

What is Redux, really? – Part 3

A need for state management in React applications

Connecting Redux to React

Connecting components

Selectors

Accessing passed properties

Dispatching actions

Conclusion

What is Redux, really? – Part 2

What is Redux, really? – Part 2

Recap

Two fundaments of Redux – Actions and Reducers

Action – request the change

Dynamic actions – or, created actions

What happens after an action is fired?

Reducer – make the change

States and store – what's the difference?

Single-state store

Conclusion

The three states of data-driven UI

The third state

Conclusion

Welcome, New Member sigh