import {Codeblock, BlogLayout} from "../../components";

export default ({ children }) => <BlogLayout metadata={meta}>{children}</BlogLayout>

export const meta = {
    timestamp: new Date('2021-06-04T12:00:00Z'),
    title: "Applying Domain-Driven Design principles to a Nest.js project",
    authorName: "Harry Bendix-Lewis",
    summary: "By applying domain-driven design principles to a Nest.js project we can ensure our code base is scalable, maintainable and easy to understand.",
    tags: ['Backend'],
    thumbnailUrl: '/blog/domain-driven-design-nestjs.jpeg',
    featured: true,
    readTime: '15 min read',
    slug: 'creating-a-framework-agnostic-api-module-in-typescript'
}

Hey, today I'm going to be writing about how you can apply domain-driven design (DDD) principles to a Nest.js project.

I've created a quick repository showing the architecture explained in this blog. [Find it here.](https://github.com/hbendix/domain-driven-nest)

## Disclaimer

- I am by no means an expert in DDD, we merely decided to adopt it for [Repetitio](https://www.repetitio.co) when we re-wrote the server.
- I will not cover what DDD is in this blog, please refer to this [dev.to blog post](https://dev.to/microtica/the-concept-of-domain-driven-design-explained-1ccn) or the [DDD bible](https://www.amazon.co.uk/Domain-Driven-Design-Tackling-Complexity-Software/dp/0321125215).
- [Nest.js](https://nestjs.com/) - A progressive Node.js framework for building efficient, reliable and scalable server-side applications. It mirrors Angular's architecture style and is built with TypeScript from the ground up.

## Why Nest?

Nest is opinionated on how to structure your code, this works well in a DDD case as you need to be able to put strict boundaries around your code as to keep your code maintainable and readable. If you are looking for a powerful and scalable framework for your Node.js application, I highly recommend Nest.js.

## So why would we do this?

Having used Nest.js in production for about 4 months we ended up, due to the project being unrestricted without clear boundaries, with a mess of spaghetti code for our server and API. We're talking about `services` that are 600+ LOC long.

This is by no means a reflection of Nest.js, but rather a reflection of what happens to codebases without strict rules and boundaries implemented.

We decided to jump on the bandwagon and start to look into DDD as a way forward after we had decided to rewrite the server.

So ultimately what we wanted to get out of this exercise is a codebase that by nature of design stays tameable.

## How do you do this?

We found that DDD outlines a clear structure to your code that not only makes sense but can minimise the amount of code/methods/classes that resides in aspects of your domain.

To use our old server as an example; we had a service called `user.service.ts` that contained ALL logic for the user. Now, as with most applications, the user tends to take a center stage and encapsulates a lot of domain logic. Therefore, our service became huge, covering the entire user logic. It became hard to read and understand what each method was trying to achieve and what actions it was performing.

So let us use this example and apply some DDD logic to it, firstly we decided to be very strict with our domain layer, therefore in the user domain we only care about our user domain model, all other relationships are abstracted out into a new domain layer or a subdomain.

We kept the usage simple and made a class per action, rather than lumping them all into the same omnipotent, omniscient service. By the fact of simplifying, our domain layer becomes very functional with each class performing typically one action, with the methods within further reflecting this.

# Our architecture

This is our architecture: (using a very generic user as an example for the different files and services)

<Codeblock language={'markup'} value={
`src/
   /API
      /User
         UserController.ts
         CreateUserDTO.ts
      APIModule.ts
   /Auth
      AuthModule.ts
   /Database
      DatabaseModule.ts
   /Domain
      /User
         CreateUser.ts
         IUserRepository.ts
         User.ts
         UserModule.ts
   /Persistence
      /User
         UserRepository.ts
         UserRepositoryModule.ts
         UserEntity.ts
   /Utils
      /Mappers
         /User
            CreateUserDTOToUser.ts
      /Services
         /Email
            EmailSenderService.ts
   AppModule.ts
   Environment.ts
   main.ts`} />

The `Module` in this case is a Nest Module. We decided that each Domain would have its module, as would each persistence entity. However, we decided to lump all API endpoints into one module, as the only thing importing the `APIModule` was the `AppModule` on application bootstrap.

## API

This layer contains all our endpoints and controllers. We tried to make a Controller class mirror a domain entity. So, if we had a user domain, we'd have a user controller. This pattern extends to the persistence layer too.

This is also an obvious space to declare any DTOs - sending or receiving.

## Auth

This is where all our Guards, Strategies and general Auth configuration lies.

## Database

You guessed it, this layer is responsible for connecting to any kind of data store, or multiple data stores for that matter.

## Domain

The most important part of our codebase. The domain is a reflection of the problem we are trying to solve. This is broken up into our domain models (each warranting their folder). Our domain model, in our case, is a TypeScript types file.

We want to keep our domain layer pure from third party artefacts, so within our domain we should only reference our code. We don't want to see MongoDB schemas, third-party packages, reference to any database-specific logic or anything related to our API layer.

We define an interface that mocks our repository layer. This is defined in our domain layer as it is directly related to our domain. We are outlining how we want to be able to mutate our domain models, we are not bothered with the implementation (that is the persistence layer's job).

A few rules we adhere to with our domain layer:

- The domain actions should only accept the domain model as a parameter or an Id in string form. DTOs should be mapped _before_ calling our domain layer.
- Leave all third-party libraries, packages etc outside the domain layer. It should be third-party dependency-free.
- It should only reference code that exists in the domain layer
- In theory, you should be able to cut and paste your domain layer it into any project (language-dependent) and it should work.

### Dependency-free domain

One of the biggest mental challenges is organising your code in such a way that your domain layer is only dependent on other classes and files within your domain layer.

For example, to communicate with the persistence layer we can introduce the `UserRepositoryModule` as a dependency to our `UserModule` but would go against a key component of DDD - a dependency free domain. It's also why we have a `User.ts` (domain) and `UserEntity.ts` (persistence). One is our domain model, in its purest form. The other, our domain model but with the added attributes/functionality for whatever data store.

One way (and thanks to [SeWaS](https://github.com/SeWaS) for showing me how) we can use interface injection, rather than typical module injection to communicate with the persistence layer.

`DomainAction.ts` is just a generic name which represents the many actions our domain will perform.

<Codeblock language={'ts'} value={
`// Domain/User/DomainAction.ts
import { Injectable } from '@nestjs/common';
import { Injectable, Inject } from '@nestjs/common';
import { UserRepository } from '../../Persistence/User/Repository';
import { IUserRepository } from './IUserRepository';
\r
const UserRepo = () => Inject('UserRepo');
\r
@Injectable()
export class DomainAction {
   constructor(
      @UserRepo() private readonly userRepository: IUserRepository,
   ) {}
}`} />

<Codeblock language={'ts'} value={
`// Persistence/User/UserPersistenceProvider.ts
import { Provider } from "@nestjs/common";
import { UserRepository } from "./Repository";
\r
export const UserRepoProvider: Provider = {
    provide: 'UserRepo',
    useClass: UserRepository
}`} />

<Codeblock language={'ts'} value={
`// Persistence/User/UserRepositoryModule.ts
import { UserRepoProvider } from './UserPersistenceProvider';
\r
@Module({
   providers: [UserRepoProvider],
   exports: [UserRepoProvider],
})
export class UserRepositoryModule {}`} />

### Domain structure

Each domain action that gets performed on our domain model should constitute its own file and class. The name of this class should be explicit and leave no-one guessing as to its purpose.

For example:

<Codeblock language={'markup'} value={
`/Domain
   /User
      Create.ts
      Update.ts
      Delete.ts
      GetEmail.ts
      RemoveToken.ts
      IUserRepository.ts
      UserEntity.ts
      UserModule.ts`} />

We can even drop the User from the name of the class as it is implied due to it residing within the user domain.

## Persistence

Our persistence layer is where all our database queries are performed. This will contain the entity's Module and its Repository. The repository in this sense is a class that contains all database operations. Again, this should mirror our domain entities 1:1 and should typically only contain around 4/5 methods - predominately CRUD operations. Unlike our domain layer, we couple multiple actions within the same class.

## Utils

These typically share functionality required across our domain.

This is where we store all our mappers that map data-transfer-objects to domain models and vice versa.

It is a good place to store singleton services, like the example, an email sender service.

# Typical flow through our server

As I feel the need to show _some_ code, I'll show some snippets of how this all looks if we were to create a very basic user in a purely fictional server. Obviously, I'm excluding import statements here.

<Codeblock language={'ts'} value={
`// the user DTO we receive from the client
export class CreateUserDTO {
   @IsString()
   @IsNotEmpty()
   public name: string;
\r
   @IsString()
   @IsNotEmpty()
   public password: string;
}`} />


Class validator is great for validation, couple that with an `AuthGuard` (in the `Auth` layer) and you can handle all exceptions for your code in one place and handle the response object.

<Codeblock language={'ts'} value={
`// UserController.ts
@Controller('user')
export class UserController {
   constructor(
      private readonly user: Create,
   ) {}
\r
   @Post()
   public async Register(@Body() createUser: CreateUserDTO): Promise<HttpStatus> {
      // all our mappings get done in static classes
      const domainModel: User = UserMap.mapCreateDTOToUserModel(createUser);
      await this.user.Create(domainModel);
      return HttpStatus.OK;
   }`} />

As our domain is only concerned with **our domain** we need to make sure that all API layer related objects get mapped to the domain appropriate model, hence our mapping happening in the API layer.

<Codeblock language={'ts'} value={
`// /Domain/User/Create.ts
const UserRepo = () => Inject('UserRepo');
const EmailService = () => Inject('EmailService');
\r
@Injectable()
export class Create {
   constructor(
      @UserRepo() private readonly userRepository: IUserRepository,
      @EmailService() private readonly email: IEmailSenderService,
   ) {}
\r
   public async Register(user: User): Promise<void> {
      const registeredUser: User = await this.repository.Create(user);
      await this.email.SendEmail(registeredUser.email, EmailOptions.AccountCreationEmailOptions, {
         userId: registeredUser._id,
      });
   }
}`} />

The `EmailSenderService` is an example of shared logic across our domain that would exist in the `Utils` layer mentioned above.

<Codeblock language={'ts'} value={
`// /Persistence/User/UserRepository.ts
\r
@Injectable()
export class UserRepository implements IUserRepository {
   constructor(@InjectModel('User') private readonly user: Model<UserEntity>) {}
\r
   public async Create(newUser: User): Promise<UserEntity> {
      return new Promise<UserEntity>((resolve, reject) => {
         const createdUser: UserEntity = new this.user(newUser);
         this.user.create(createdUser, (err: GenericError, addedEntity: UserEntity) => {
            if (err) {
               reject(err);
            }
\r
            resolve(addedEntity);
         });
      });
   }
}`} />

We can also see the need to have two types of `User`, one for our domain which is the purest form of our domain model and one that exists in our persistence layer that would be very similar to our domain model but would contain third-party (in this case, database-related) attributes or logic specific to our persistence layer.

This further re-enforces the need for our domain layer to be pure of all third-party artefacts.

# Summary

This is a brief overview of the architecture we've employed at Repetitio. By holding ourselves to such rigid rules we've found our codebase has been pleasantly manageable, nothing like it was before! With clear logical layers to our server, it is easy to navigate and understand, allowing us to easily dive in and iterate with an ever-evolving set of requirements.

I've created a quick repository showing the architecture explained in this blog. [Find it here.](https://github.com/hbendix/domain-driven-nest)


By applying domain-driven design principles to a Nest.js project we can ensure our code base is scalable, maintainable and easy to understand.

Applying Domain-Driven Design principles to a Nest.js project

import {Codeblock, BlogLayout} from "../../components";

export default ({ children }) => <BlogLayout metadata={meta}>{children}</BlogLayout>

export const meta = {
    timestamp: new Date('2021-06-04T12:00:00Z'),
    title: "Creating a framework-agnostic API module in TypeScript",
    authorName: "Harry Bendix-Lewis",
    summary: "Mimicking the powerful HttpClient from Angular. The final product is a type-safe and generic API module for any project using TypeScript.",
    tags: ['Frontend'],
    thumbnailUrl: '/blog/http-module.jpeg',
    featured: true,
    readTime: '18 min read',
    slug: 'creating-a-framework-agnostic-api-module-in-typescript'
}

Hello, today I'm going to be writing about how to write a framework-agnostic API module in TypeScript. This is my first ever technical blog so please be my harshest critic.

Due to the day job demands, I've recently transitioned from writing Angular UIs to writing primarily React UIs. I'm not going to get into the finer points of Angular vs React, framework vs library, as that horse is long dead!

However, one thing I do miss from the Angular days is the `HttpClient` provided by Angular. It ['provides simplified client HTTP API for Angular applications'](https://angular.io/guide/http). That it does.

Today I'm going to show how I write something similar using TypeScript, which is more explicit and more functional than our Angular counterpart.

Please note as this is written entirely in TypeScript I will make no assumptions about what framework you are using. I will also tailor this tutorial to be generic that either `fetch` or `Axios` can be used. However, I will touch on some Axios specific features further down the post.

Another assumption; if you are reading this, you are familiar with TypeScript. So let's jump straight into it.

[If you just wanna see the code, no danger! I uploaded it here. Enjoy.](https://github.com/hbendix/API-Module)

# Why?

Good question. By writing an API module is allows us to encapsulate all our API calls into a single module/folder within our codebase. By splitting up each facet of an API call (creating the URL, passing the data, handling the correct Http verb) we can easily test, maintain and understand our codebase or someone else's. Code readability to me is of the utmost importance and should be valued above much else.

The API module will:
1. Handle the sending and receiving of all server calls
1. Create our server compliant URLs, handle all parsing of parameters required and set global headers for all requests
1. Encapsulate a generic Client Factory layer that will handle our `POST`,`PUT`,`GET` and `DELETE` request, whilst also giving us type safety and IntelliSense
1. Serve as a logical layer to declare and reference any data transfer objects (DTO) your API sends or receives
1. Allow the developer to be as verbose as required for each server call, as to minimise confusion and emphasis readability of the codebase
1. Be easy to test as each step on the process is small, simple and functional

To give you a brief example, we can see the differences:

<Codeblock language={'ts'} value={
`// oh look at me I'm not using an API module
function updateUserDetails (user: User): Promise<any> {
  return fetch(
    method: 'PUT',
    headers: {
      "Content-type": "application/x-www-form-urlencoded; charset=UTF-8"
    },
    body: JSON.stringify(user)
  )
}
\r
import * as API from "api";
// ohohhh yeah look at that API module
function updateUserDetails (user: User): Promise<API.UserDTO> {
   try {
      return API.getUserDetails(user);
   } catch (error) {
      // handle the error
   }
}`
} />

**DRY!**

Write an API module once and never worry about URLs, headers, return types ever again. Cover your API module in tests (easy using a functional approach) and never fret about your server calls again!
# Let us begin
Right, if you've come this far your either sold or intrigued.

I will be using the `getUserDetails` and other user-centric calls in these examples.
Folder structure is simple:

<Codeblock language={'markup'} value={
`/src
   /API
      /Client
         Client.ts
         Headers.ts
         HttpInstance.ts // axios only
         ResponseCode.ts
         index.ts
      /URL
         CreateQueryString.ts
         CreateUrl.ts
         JoinPaths.ts
         index.ts
      /User
         GetUserDetails.ts
         DeleteUser.ts
         // etc
      index.ts
   / //rest of app`
} />

The `Client` folder is where the actual server calls happen through the use of factories that handle each respective Http verb.

The `URL` folder will parse our base url, any params and remove all unwanted characters.

Here, the `User` is an example but you can start to see how I am very explicit and verbose. Each file within `/User` performs one simple action, which is immediately identifiable at a glance.

How many times have you been burned by having say: `user.service.ts` which contains all server calls for your user domain, soon it is 600 LOC and completely unreadable. We mitigate that entirely by spitting each action our user can perform into its own file. This results in more files, however, this is an improvement over a monolithic service (IMO).

# URL
Our URL layer needs to ultimately create the correct URL for the API. We need to:
1. Sort any parameters into a key-value pair query string
1. Join our base URL with the params
1. Make our URL error-proof

<Codeblock language={'ts'} value={
`export type CreateUrl = (baseUrl: string, template: string, param?: object | undefined) => string;`
} />
I may call `createUrl` like so:

<Codeblock language={'ts'} value={`createUrl('https://example.com/', '/api/user/', { userId: '123', token: 'abc5' }),`} />

Which produces:

<Codeblock language={'markup'} value={'https://example.com/api/user?userId=123&token=abc5'} />

## Creating the API URL

Our `createUrl` needs to first and foremost join the `baseUrl` and the `template` together. This is where `JoinPaths.ts` comes into the ring, as seen in the folder structure overview above.

We need to ensure we don't simply join two strings together, as shown in the code above, this could result in a bad API URL, for example:
<Codeblock language={'sass'} value={'https://example.com//api/user/?userId=123'} />

We need to take both strings in as an array to be able to trim the trailing and leading slashes and handle the slashes from with the `JoinPaths` file.

<Codeblock language={'ts'} value={
`const trimLeadingSlash = (path: string): string => (
   // if first character is slash, return string minus first char
   path.charAt(0) === '/' ? path.substr(1) : path
);
\r
const trimTrailingSlash = (path: string): string => (
   // if last character is slash, return string minus last char
   path.substr(-1) === '/' ? path.substr(0, path.length - 1) : path
);
\r
export const joinPaths = (...segments: Array<string>): string => (
   segments.reduce(
      (path: string, currentSegment: string) => (\`\${trimTrailingSlash(path)}/\${trimLeadingSlash(currentSegment)}\`),
   )
);`
} />

This allows anyone working on this codebase to not have to worry about trivial problems like leading and trailing slashes. We move the responsibility into our API module and if you write some unit tests you can sleep safely knowing `JoinPaths` will look after your URLs.

## Sort the parameters

So now we have a URL that has been parsed and formatted, we can append our API parameters to it. Ultimately, we need to iterate through the object we passed into `createUrl()`.

Typically there are two ways to pass parameters to a server:

<Codeblock language={'markup'} value={'https://example.com/api/:token'} />

or

<Codeblock language={'markup'} value={'https://example.com/api?token=token'} />

Let's not discriminate and create a parameter pattern that will allow us to decide on the fly which way we please.

<Codeblock language={'ts'} value={
`let url: string = joinPaths(baseUrl, template);
const queryParams: object = {};
Object
   .keys(params)
   .filter(key => params[key] !== undefined && params[key] !== null)
   .forEach(key => {
      const paramPlaceHolder: string = \`\${key}\`;
\r
      if (template.indexOf(paramPlaceHolder) > -1) {
         url = url.replace(paramPlaceHolder, params[key]);
      } else {
         queryParams[key] = params[key];
      }
   });`
} />

Here we're iterating and filtering over each key in the parameter object, then we either do one of two things:

If the parameters being passed in match the template then we assume the token is being passed out of parameters like `:token` and we replace the template match with the parameter value.

Otherwise, we add the key-value pair to our new `queryParams` object defined above.

Now that all remains is to put it all together and sort the query parameters:

<Codeblock language={'ts'} value={
`export const createKeyValuePair = (key: string, value: any): string => {
   if (Array.isArray(value)) {
      return value.map(x => createKeyValuePair(key, x)).join('&');
   }
\r
   return \`\${encodeURIComponent(key)}=\${encodeURIComponent(value)}\`;
};
\r
export const createQueryString = (params: object): string => (
   params && Object
      .keys(params)
      .filter(key => params[key] !== undefined && params[key] !== null)
      .map(key => createKeyValuePair(key, params[key]))
      .join('&')
);`
} />

The above code will iterate over all the parameters in the object we created in the previous step, each parameter we call a recursive function that first checks to if the passed in value is an array and if so then work through each element in the array and create the parameters.

Otherwise, return the value in the format the server is expecting. By joining each element with an ampersand we will create:

<Codeblock language={'sass'} value={'?key=value'} />

Again, array or object both use cases get covered.

Now all is todo is add the `createQueryString` reference and return the URI:

<Codeblock language={'ts'} value={
`url = url.replace(/\/{.*}/, '');
const queryString: string = createQueryString(queryParams);
return \`\${encodeURI(url)}\${queryString && \`?\${queryString}\`}\`;`
} />

This code appears below the object parameter code we wrote above.

Now the URL is sorted we can turn our attention to the generic factories.

# Factories

What are the factories? They will be the layer that is responsible for actually making the request to the server. This layer acts as a wrapper around either the `Axios` client or the native `fetch` client. We also need to handle each HTTP verb and leverage TypeScript to allow IntelliSense. This is the `/Client` folder from the folder structure overview above.

<Codeblock language={'ts'} value={
`import { AxiosRequestConfig, AxiosResponse, AxiosError } from 'axios';
import { axios } from './HttpInstance';
\r
const sendRequest = <T>(config: AxiosRequestConfig): Promise<T> => axios.request<T, AxiosResponse<T>>(config)
   .then(res => Promise.resolve(res.data))
   .catch((error: AxiosError) => Promise.reject(error?.response?.data ?? error));
\r
export const getFactory = <T>(url: string) => sendRequest<T>(
   { url, method: 'GET' as const },
);
\r
export const postFactory = <T, K>(url: string, body: T) => sendRequest<K>(
   {
      url,
      method: 'POST' as const,
      data: body,
   },
);
\r
export const putFactory = <T, K>(url: string, body: T) => sendRequest<K>(
   {
      url,
      method: 'PUT' as const,
      data: body,
   },
);
\r
export const deleteFactory = (url: string) => sendRequest<void>(
   { url, method: 'GET' as const },
);`
} />

The above code is for the Axios client, however, for `fetch` it's almost identical but you will need to handle the stringification yourself and make sure to reject the request promise if `res.ok` is `false`, [as with `fetch` a failed request does not get caught in the `catch` block of a promise.](https://developer.mozilla.org/en-US/docs/Web/API/Response/ok)

We declare each verb as it's own factory function, and through the use of generics and declare the response and request types we will declare when calling these functions.

# Actions

Now we've sorted the request URL, parameters and created a layer to communicate with the API, now we need to introduce our actions layer. This is where I like to declare DTOs and will act as a buffer between the application and our API module.

<Codeblock language={'ts'} value={
`// ../API/User/createAccount.ts
import { createUrl } from '../URL/CreateUrl';
import { environmentVariables } from '../../../environment';
import { postFactory } from '../Client';
\r
const route: string = 'user';
export type CreateDTO = {
   password: string;
   confirmPassword: string;
   email: string;
   name: string;
}
export const createAccount = async (payload: CreateDTO): Promise<{
   token: string,
   userId: string
}> => postFactory(
   createUrl(environmentVariables().apiUrl, route),
   payload,
);`
} />

From the example above you can see all the pieces coming together and can see the TypeScript generics in play. It's clear from a glance exactly what this code is doing, what the data looks like and how the data will look on a successful request.

Please note the `environmentVariables()` function just returns the base URL of the server.

Now all you need to do is call and await `createAccount` and make sure to wrap it in a try/catch block. That's it! You now have an API module that handles all the things you need to make a request to your server without you ever having to repeat yourself or worry about incorrect syntax/data structures.

# Axios specifics

## Headers
I like to create an Axios instance on application load that will take a headers object as an argument, this ensures that you don't have to keep creating/passing in a headers object. Fire and forget!

<Codeblock language={'ts'} value={
`export const defaultHeaders: Record<string, string> = {
   'Content-Type': 'application/json',
   Accept: 'application/json',
   credentials: 'include',
};
export const axios: AxiosInstance = Axios.create({
   timeout: 10000,
   headers: {
      ...defaultHeaders,
   },
});`
} />

## Interceptors

I also like to register interceptors for the client (`axios`) we initialise above (so all requests and responses get accounted for)

<Codeblock language={'ts'} value={
`export function RegisterInterceptor(setState: (value: Action) => void) {
   axios.interceptors.response.use(response => response, async (error: AxiosError) => {
      if (!error.response) {
         // no response from the server (is the user offline?)
         throw error;
      }
      if (error.response.status === 403) {
         await clearCache();
         setState({
            type: StateActions.LOGGED_OUT,
         });
\r
         throw error;
      }
\r
      throw error;
   });
}`
} />

You can see my interceptor is used to handle unauthorised messages and log out the user. You can also use this layer to handle any response type or no response at all for your client.

Lastly, register this interceptor on application load, something like:

<Codeblock language={'tsx'} value={
`// app.tsx
    import * as API from './src/API';
\r
// app component code:
    React.useEffect(() => {
    API.RegisterInterceptor(setState);
}, []);`
} />

That is it all! I hope you learnt something today. [All the code I've uploaded to a GitHub repository here. Enjoy.](https://github.com/hbendix/API-Module) :)


Mimicking the powerful HttpClient from Angular. The final product is a type-safe and generic API module for any project using TypeScript.

Creating a framework-agnostic API module in TypeScript

import {Codeblock, BlogLayout} from "../../components";

export default ({ children }) => <BlogLayout metadata={meta}>{children}</BlogLayout>

export const meta = {
    timestamp: new Date('2021-06-04T12:00:00Z'),
    title: "When to use TailwindCSS over CSS",
    authorName: "Harry Bendix-Lewis",
    summary: "An in-depth look at the use cases for Tailwind CSS over CSS",
    tags: ['Frontend'],
    thumbnailUrl: '/blog/tailwind-vs-css.jpeg',
    featured: true,
    readTime: '7 min read',
    slug: 'when-to-use-tailwindcss-over-css'
}

I find the premise of [TailwindCSS](https://tailwindcss.com/) exciting, an un-opinionated CSS framework that has an extensive list of utility classes by which to build UIs.

Coming from a background of using Bootstrap 3 quite heavily before we collectively decided as an industry that Bootstrap is past it (we did do that right? I can't keep up), there was plenty to complain about; their use of `!important` would keep me up at night, [jQuery](https://jquery.com/) was great - in 2008, among others.

In their defence, they also did a lot right. The Bootstrap grid system is still fantastic, the modal is equally great and ultimately they made building consistent and functional UIs a breeze. For that alone, I'll always be grateful.

There has been an appetite for something _more_ in recent memory. Something a bit, simpler? I think Tailwind (or rather the creators) realised people were looking for something just like Tailwind, so they made it.

There are whole swathes of developers out there who believe CSS is black magic and anyone that is remotely fluent in it is this all-powerful style-sheet, colour, whitespace, Shoreditch coffee drinking genius. When someone comes to me with a CSS issue they have spent "the last few days trying to solve" and I did it in one line (`position: relative` folks) from then on I was considered a sorcerer of black magic.

These whole swathes of developers are pre-dominantly backend developers and trust me guys CSS is a bizarre bit of kit, the main difference is exposure (as with most things), so I'm not gunning at ya. I sympathies with never really knowing how CSS works, I still don't think I do.

What I'm ultimately trying to say is, Tailwind came along and said: "don't worry about that nonsense, do it all in HTML and never write another line of CSS again". Immediately interest was piqued and Tailwind became very popular.

I finally found a use-case to try out Tailwind (this website uses it, as well) and thought I write my thoughts about it and how I think it compares to using good ol' CSS (or SCSS/LESS whatever takes your fancy).

# So, how is Tailwind?

Tailwind has shined when I've been using it to get something up and running quickly, be it a prototype or a proof-of-concept. You can just focus on building your component (if we were using React, for example), there's no worry with importing stylesheets and ensuring they get parsed correctly.

Tailwind is extendable to be able to interject your styles and colour schemes, add your classes and modify existing ones. Tailwind also allows you to target pseudo-classes right in the class name, which is probably my favourite feature.

I think Tailwind's use of utility classes bodes well for component-based frameworks as it allows you to encapsulate styles to minimise class name bleed. As one component can encapsulate the template and the corresponding style, rather than having them in two separate places. This applies to small components (which they all should be, of course 😝) to not have complicated components made more complicated by hundreds of class names.

Tailwind also comes with the ability to "apply" Tailwind classes in your style sheets. So your `button` goes from:

<Codeblock value={`<button class="text-blue bg-blue-500 hover:bg-blue-800 hover: text-white" />`} language={'markup'} />

to:
<Codeblock value={`<button class="btn-blue" />`} language={'markup'} />

<Codeblock language={'sass'} value={
`.btn-blue {
   @apply text-blue;
   @apply bg-blue-500;
   \r
   &:hover {
      @apply bg-blue-800;
      @apply text-white;
   }
}`} />

Which helps in minimising the class name spam. However, this begs my most important question...

# Does it scale?

Increasingly, I am re-writing my applications that are using TailwindCSS and moving all the HTML classes to the SCSS style-sheets. Why?

<Codeblock language={'tsx'} value={
`<div className="flex md:w-2/3 w-full p-2 md:p-8">
   <div className="flex flex-col items-start justify-center text-center md:text-left">
      <h1 className="font-black header-text-xl md:text-6xl">{title}</h1>
      <h2 className="text-2xl md:text-3xl mt-2 opacity-75">{description}</h2>
      <div className="flex w-full mt-6 justify-center md:justify-start">
         <Link to={findOutMoreLink}>
            <button type="button" className="bg-red-500 hover:bg-red-700 text-white font-bold py-2 px-4 rounded text-2xl ml-auto">
               {findOutMoreLinkText}
            </button>
         </Link>
      </div>
   </div>
</div>`} />

That is not readable (and that is a very tame example). At the very least, you need to _study_ that HTML block to start to figure out how it is styled or what it is trying to convey.

With a bit of clever SCSS you can transform the block above to something more akin to:

<Codeblock language={'tsx'} value={
`<div className="wrapper two-thirds">
   <div className="content">
      <h1>{title}</h1>
      <h2>{description}</h2>
      <div className="center">
         <Link to={findOutMoreLink}>
            <button
               type="button"
               className="btn btn-red"
            >
               {findOutMoreLinkText}
            </button>
         </Link>
      </div>
   </div>
</div>`}
/>

Sure, you still need to go to the SCSS file and read that understand how it styled, but that is the purpose of SCSS. Are we not crossing streams, muddying the waters, by merging the styling and markup into the same file?

When I view HTML I want to see the semantics of the file. When I view the stylesheet I want to see how the content is styled.

If I've decided to move all my Tailwind classes to custom SCSS style-sheets, then why wouldn't I just use SCSS? Spoiler: this is exactly what I've done.

Now I get complete control over my styling, I can use variables and all the other lovely functionality bundled with SCSS and can apply proven architectural structures to my styling that makes it easier to read and understand.

It is far easier to organise your code when you can have a distinction between your stylesheets and your templates. It also allows you to structure your styles and take full advantage of all the utility that comes with SCSS.

Ultimately I had projects where I was struggling to understand how to tweak the UI as I found following all the class names so difficult.

If I, the author of the code, was struggling to follow it - how would anyone else?

# Tailwind fills a niche

It is a great tool, but I can only see myself using it if I need to prototype something fast, or a backend heavy side-project with a minimal front-end. That is where Tailwind shines.

If your project has scalability concerns or it is a style heavy project then I recommend to run your own SCSS architecture and follow something like the [7-1 pattern](https://www.learnhowtoprogram.com/user-interfaces/building-layouts-preprocessors/7-1-sass-architecture) (which is by far my favourite way of organising my SCSS). This allows you to reap all the benefits of using SCSS and keeps a clear concern between your style-sheets (here be styles) and your HTML (here be HTML).


An in-depth look at the use cases for Tailwind CSS over CSS

Our thoughts and musings

Featured posts

Applying Domain-Driven Design principles to a Nest.js project

Creating a framework-agnostic API module in TypeScript

When to use TailwindCSS over CSS

Why don't we build something together?

Let's talk!