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.webp',
    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.webp',
    featured: false,
    readTime: '8 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 {BlogLayout, Testimonial} from "../../components";

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

export const meta = {
    timestamp: new Date('2022-05-05T12:00:00Z'),
    title: "Forward Digital is now on the communications marketplace!",
    authorName: "Harry Bendix-Lewis",
    summary: "On the back of successful projects with HP and the World Gold Council, we are now working with public sectors across the UK.",
    tags: ['General'],
    thumbnailUrl: '/blog/forward-digital-communication-marketplace.jpeg',
    featured: false,
    readTime: '2 min read',
    slug: 'forward-digital-communication-marketplace'
}

The team here at Forward Digital are incredibly excited to start working with public institutions across the UK. Having spent the last few months working closely with the team at GovData, we are pleased to announce our successful application.

Coming on the back of working with the likes of HP and the World Gold Council, coming in as specialists to help build and scale software for 9 figure plus companies. We were highlighted by GovData as an incredibly ambitious and driven micro-enterprise and were offered to start the application process to be in contention to work with all public sectors, such as the NHS or local councils.

As a remote-first and distributed team, we are not limited by geographic location. Good software can be written anywhere and we aim to materialise that with our public sector clients across the whole of the UK.

Having both spent the last 4 years working in the private sector, we have a network of satisfied clients;

<div className={'layout'}>
    <Testimonial
        imageUrl={'/testimonials/ben_cotton.jpg'}
        quote={'"Consistently delivered excellent quality code, quickly and efficiently...and always going the extra mile to ensure we hit our deadlines and delivered a great product."'}
        author={'Ben Cotton'}
        role={'Technology Director at Native Design'}
    />
</div>

Forward Digital is first and foremost a software development house. We build software for phones, the web and anything else. We have overseen huge architectural shifts from archaic code bases to modern and scalable solutions that have tens of thousands of visitors.

We have built MVP-prototypes and pitched ideas to companies, from London to San Francisco. We have scaled a startup from no users and no money to a steady monthly re-occurring revenue. We have materialised dreams for clients big and small and take pride in our work.

We are very much forward to working with public sections across the UK!

<div className={'layout'}>
    <Testimonial
        imageUrl={'/testimonials/alex.png'}
        quote={'"Harry and Reece were professional, practical and responsive during the entirety of the project, which included planning, development and QA.  I especially liked their candidness and promptness..."'}
        author={'Alex'}
        role={'Owner of scale'}
    />
</div>


On the back of successful projects with HP and the World Gold Council, we are now working with public sectors across the UK.

Forward Digital is now on the communications marketplace!

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

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

export const meta = {
    timestamp: new Date('2021-06-18T12:00:00Z'),
    title: "Implementing Sign in with Apple with a managed Expo workflow and a Nest.js backend",
    authorName: "Harry Bendix-Lewis",
    summary: "Enable ease of access for your Expo app by allowing users to use their Apple ids as a login method.",
    tags: ['IOS', 'Backend'],
    thumbnailUrl: '/blog/sign-in-with-apple.webp',
    featured: true,
    readTime: '15 min read',
    slug: 'implementing-Sign-in-with-Apple-with-a-managed-Expo-workflow'
}

Making your whole authentication process as seamless a possible is vital to ensuring that any potential users don't get put off by filling out a long-winded create account form.

Back in WWDC 2019 Apple introduced Sign in with Apple, this allows users to authenticate with their Apple Id with forced 2FA. A seamless solution to getting users into your app.

Today I will be running through the steps to integrate this into your managed Expo project using a Nest.js backend to authenticate that user and handle the user accounts.

Before we begin I will make the assumption the reader is familiar with:

- Expo
- Nest.js
- JavaScript
- TypeScript

Although the backend code will be using Nest, a lot of the code will be transferrable to any other Node backend framework you may be using.

## What do we need?

### Expo

For our managed Expo project, we will need to add:

1. `"expo-apple-authentication"` by running: `expo install expo-apple-authentication` which will install the version compatible with your SDK version. This tutorial is written for **SDK41**.

> There are extra configuration steps you need to follow that can be found [here](https://docs.expo.io/versions/latest/sdk/apple-authentication/#configuration)

### Backend

For our Nest.js backend we need to add:

1. [https://github.com/auth0/node-jsonwebtoken](https://github.com/auth0/node-jsonwebtoken) (`npm install jsonwebtoken`)
 - We use this to verify the JWT token was signed by Apple's public key
2. [https://github.com/auth0/node-jwks-rsa](https://github.com/auth0/node-jwks-rsa) (`npm install jwks-rsa`)
 - We use this to retrieve the signing keys from Apple's keys API endpoint and to retrieve Apple's public key
3. [https://github.com/auth0/jwt-decode](https://github.com/auth0/jwt-decode) (`npm install jwt-decode`)
 - We use this to decode the JWT generated by the Sign in with Apple button

## The auth flow

1. A user presses the Sign in with Apple button and logins in through the native Apple modal
2. Once authorised through 2FA on the device, will return to us a JWT token with a nullable name value. (plus other values, we don't need to worry about these)
3. Determine if the user is attempting to log in or create an account
4. We send the JWT token off to our backend with the user's name (if they are creating an account)
5. We then decode the JWT token, get Apple's public key and verify the JWT token was signed by Apple
6. Validate the token against our bundle id
7. At this point, we can safely assume they are authenticated with Apple and we can either login them in through our backend auth or create an account on our database using the values we have from step 2.

## An overview of the Expo package

Expo's `expo-apple-authenticator` is in effect a one-stop-shop with everything you need for your app.

> The Sign-in with Apple button will only appear on iOS devices, so make sure to consider this when building the UI.

The package contains the functions for displaying the modal and even comes bundled with the button itself, although this isn't required if you want to use a custom button.

<Codeblock
    language={'tsx'}
    value={`
<AppleAuthentication.AppleAuthenticationButton
	buttonType={AppleAuthentication.AppleAuthenticationButtonType.CONTINUE}
	buttonStyle={AppleAuthentication.AppleAuthenticationButtonStyle.BLACK}
	cornerRadius={BUTTON_BORDER_RADIUS}
	style={{
		width: BUTTON_WIDTH,
		height: BUTTON_HEIGHT,
	}}
	onPress={async () => {
		//
	}}
/>
`}
/>

There's also plenty of style options so the button fits in line with other buttons on the app. `BUTTON_BORDER_RADIUS`, `BUTTON_WIDTH` and  `BUTTON_HEIGHT` are custom values I declared for all buttons on the app.

When a user presses the Sign in with Apple button they will be presented with a native modal that sits on top of your app, with module fields dependent on the scope you requested.

You have access to two scopes:

<Codeblock
    language={'tsx'}
    value={`
const credential = await AppleAuthentication.signInAsync({
	requestedScopes: [
		AppleAuthentication.AppleAuthenticationScope.FULL_NAME,
		AppleAuthentication.AppleAuthenticationScope.EMAIL,
	],
});
`}
/>

<img alt={meta.title} src={'https://d33wubrfki0l68.cloudfront.net/59ac2da39902a203391f624c4fa1d93cea0c187f/0676c/images/siwa-scopes.png'} style={{maxWidth: '100%'}} />

If the user doesn't cancel the modal, the response will look something like:

<Codeblock
    language={'tsx'}
    value={`
export type AppleAuthenticationCredential = {
  user: string;
  state: string | null;
  fullName: AppleAuthenticationFullName | null;
  email: string | null;
  realUserStatus: AppleAuthenticationUserDetectionStatus;
  identityToken: string | null;
  authorizationCode: string | null;
};
`}
/>

We only really care about 4 fields that get returned:

- `user` - this is a stable unique identifier that will persist between app versions/device changes for the app.
- `fullName` - The user's name object, includes family name, given name, nickname etc.
- `email` - The user's email, used for the backend to create a user account
- `identityToken` - A JWT token that stores information about the audience, issuer and user.

### Email and name access

**Be warned!**

The `email` and `fullName` will only be populated **ONCE.** The first time they press the button, this applies even if they change their device or update the app. A user's email is still available in the JWT token, but once `fullName` gets pulled down the first time, **you can never request it again and subsequent requests will return null.**

### Is the user creating an account or logging in?

As this button will act as both a create account button and a login button, how do we determine which the user is trying to do?

As mentioned above we know the first time they press the button, email and name values will be populated. If the name and email values are undefined, it is a fair assumption this is the users first time on the app and they are trying to create an account.

> What is the problem with this? If the user signs in through the button, pulls down the name and email values but, say, the device crashes/the subsequent API call fails or they kill the app; they can't create an account through the Sign up with Apple button.

One mitigation of this is to cache the name value to the phone's storage if it is populated and so if any edge-case happens that causes the device to lose the name then we can fall back to the cache.

Save the name value to the cache with the key value of the `credential.user` as we know this is a stable unique identifier.

<Codeblock
    language={'tsx'}
    value={`
// Expo Apple button
onPress={async () => {
	try {
		const credential: AppleAuthenticationCredential = await AppleAuthentication.signInAsync({
			requestedScopes: [
				AppleAuthentication.AppleAuthenticationScope.FULL_NAME,
				AppleAuthentication.AppleAuthenticationScope.EMAIL,
			],
		});
		const cachedName: string = await Cache.getAppleLoginName(credential.user);
		const detailsArePopulated: boolean = (!!credential.fullName.givenName && !!credential.email);
		if (!detailsArePopulated && !cachedName) {
			await login(credential.identityToken);
		} else if (!detailsArePopulated && cachedName) {
			await createAccount(cachedName, credential.user, credential.identityToken);
		} else {
			await createAccount(
				credential.fullName.givenName, credential.user, credential.identityToken,
			);
		}
	} catch (error) {
		if (error.code === 'ERR_CANCELED') {
			onError('Continue was cancelled.');
		} else {
			onError(error.message);
		}
	}
}}
`}
/>

You can see in the above code snippet we are:

1. Requesting the user's email and name
2. Retrieving the name value stored in the cache (if any)
3. If both the cache and credential values are undefined, we are assuming they have already used the button successfully to create an account, so start the login flow
4. If the cached name is declared but the credential details are not, we are assuming something happened between requesting the values from Apple and the server creating them an account, so create an account using the cached name
5. Otherwise, create an account with the requested values that are populated.

> This is not bulletproof! If the user requests the details but the cache gets cleared/they change devices before creating an account, they will not be able to create an account using this flow. We hedged a bet that this was edge case enough to warrant the risk.

## Decoding and validating the JWT token

If the user is creating an account or logging in, we need to handle decoding and validating the JWT token sent in the payload to our Nest.js API.

Using Nest.js we need to create two new endpoints to handle creating an account and logging in. Both these endpoints I will add a respective guard to. It's in this guard that we call the Apple auth strategy code.

From experience, I couldn't use the existing login and create account endpoints as these require the information we receive *after* decoding and validating the token, not once the request is made on the device.

Login guard:

<Codeblock
    language={'tsx'}
    value={`
public async canActivate(context: ExecutionContext): Promise<boolean> {
	const request = context.switchToHttp().getRequest();
	const response = context.switchToHttp().getResponse();
	const token: string = <string>request.body.identityToken;
	const jwt: JwtTokenSchema = await this.apple.ValidateTokenAndDecode(token);
    try {
        const [sessionId, user]: [string, IUser] = await this.login.AttemptLogin(jwt.email);
        if (sessionId && user) {
            request.user = user;
            response.set('Auth-Token', sessionId);
            response.set('Access-Control-Expose-Headers', 'Auth-Token');
            return true;
        }
    } catch (error) {
        throw new HttpException('Validation failed for login.', HttpStatus.UNAUTHORIZED);
	}
    return false;
}
`}
/>


The most important line is:

<Codeblock
language={'tsx'}
value={`
const jwt: JwtTokenSchema = await this.apple.ValidateTokenAndDecode(token);
`}
/>


`this.apple` is an injected service that handles the JWT decoding and validating.

### Getting Apple's public key

Before we use the JWT token, we need to make sure that it was signed by Apple's private key. To do that, we need Apple's public key to verify the signature.

Firstly we need to decode the JWT token sent by the client and extract the `kid` value found in the token's header.

<Codeblock
    language={'tsx'}
    value={`
import jwtDecode, { JwtHeader } from 'jwt-decode';
// rest of file
const tokenDecodedHeader: JwtHeader & { kid: string } = jwtDecode<JwtHeader & { kid: string }>(token, {
    header: true,
});
`}
/>

> The "kid" (key ID) Header Parameter is a hint indicating which key was used to secure the JWS. This parameter allows originators to explicitly signal a change of key to recipients. The structure of the "kid" value is unspecified. Its value MUST be a case-sensitive string. Use of this Header Parameter is OPTIONAL.
When used with a JWK, the "kid" value is used to match a JWK "kid" parameter value.

Then we need to perform an HTTP request to Apple's `auth/keys` public endpoint to return an object which contains an array of keys. Read more about this [here](https://developer.apple.com/documentation/sign_in_with_apple/fetch_apple_s_public_key_for_verifying_token_signature).


<Codeblock
    language={'tsx'}
    value={`
const applePublicKey: { keys: Array<{ [key: string]: string }> } = await this.api.Get(
	'https://appleid.apple.com/auth/keys',
);
`}
/>

(`this.api.Get` is a HTTP client we built for Nest, [find out more here](/blog/creating-a-framework-agnostic-api-module-in-typescript))

This endpoint will return a JSON Web Key Set which will look like:

<Codeblock
    language={'tsx'}
    value={`§
{
  "keys": [
    {
      "kty": "RSA",
      "kid": "AIDOPK1",
      "use": "sig",
      "alg": "RS256",
      "n": "lxrwmuYSAsTfn..."
      "e": "AQAB"
    },
    {
        //
    }
  ]
}
`}
/>

As the keys array typically has more than one element, we need to filter the `keys` array to the one that has a matching `kid` value from the decoded header of the JWT token.

<Codeblock
    language={'tsx'}
    value={`
const kid: string = tokenDecodedHeader.kid;
const sharedKid: string = applePublicKey.keys.filter(x => x['kid'] === kid)[0]?.['kid'];
`}
/>

Now we need to get Apple's public key using the `kid` value. To do this we use the package mentioned above: `jwks-rsa`.

<Codeblock
    language={'tsx'}
    value={`
const client: jwksClient.JwksClient = jwksClient({
	jwksUri: 'https://appleid.apple.com/auth/keys',
});
const key: jwksClient.CertSigningKey | jwksClient.RsaSigningKey = await client.getSigningKey(sharedKid);
const signingKey: string = key.getPublicKey();
`}
/>

If all is dandy, we should now have Apple's public key that we can use to verify our JWT token was signed with the same key. Thanks to `jsonwebtoken`:

<Codeblock
    language={'tsx'}
    value={`
try {
	const res: JwtTokenSchema = <JwtTokenSchema>jwt.verify(token, signingKey);
} catch (error) {
	// token is invalid
}
`}
/>

I wrote my own `JwtTokenSchema` for type safety:

<Codeblock
    language={'tsx'}
    value={`
export type JwtTokenSchema = {
	iss: string;
	aud: string;
	exp: number;
	iat: number;
	sub: string;
	nonce: string;
	c_hash: string;
	email: string;
	email_verified: string;
	is_private_email: string;
	auth_time: number;
};
`}
/>

Now we have the decoded JWT token we just need to perform some basic validation before we proceed with the rest of the auth process.

<Codeblock
    language={'tsx'}
    value={`
private ValidateToken(token: JwtTokenSchema): void {
	if (token.iss !== 'https://appleid.apple.com') {
		throw { message: 'Issuers do not match!' };
	}
	if (token.aud !== this.audience) {
		throw { message: 'Audiences do not match!' };
	}
}
`}
/>

`this.audience` is your app's bundle ID. This will change depending on if you are on Expo or in production. I do a ternary in the class' constructor to set this:

<Codeblock
    language={'tsx'}
    value={`
this.audience = this.isInProd ? 'co.repetitio.repetitio' : 'host.exp.Exponent' // this will be your bundle id, found in app.json
`}
/>

Now we should have the decoded token that we have validated against Apple's public key and can safely assume that the user is whom they say they are and are trying to login into the correct app. The full class is linked at the bottom.

From here you are free to proceed to the log in process or create them an account.

[I have uploaded the code to a public repo so you can take a deeper look here.](https://github.com/Forward-Digital/Sign-up-with-Apple-Nestjs)

Thanks for reading!


Enable ease of access for your Expo app by allowing users to use their Apple ids as a login method.

Implementing Sign in with Apple with a managed Expo workflow and a Nest.js backend

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

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

export const meta = {
    timestamp: new Date('2021-07-12T12:00:00Z'),
    title: "Using an S3 object storage provider in Node.js",
    authorName: "Reece Charsville",
    summary: "How to implement an S3 object storage into your Nodejs projects with AWS, Vultr or Digital Ocean.",
    tags: ['Backend'],
    thumbnailUrl: '/blog/s3_object_storage.jpg',
    featured: true,
    readTime: '15 min read',
    slug: 'using-an-s3-object-storage-provider-in-nodejs'
}

Today I am going to be running through how to implement an S3 object storage with Node.js. If you would like to see the full code example you can view it on GitHub [here](https://github.com/Forward-Digital/node-s3-storage-example).

## Introduction

For those who don't know S3 object storage is a cloud service for hosting files. It is accessible via an API, which means it can easily be integrated into your projects. There are hundreds of uses cases but to give a quick example we can look at Facebook. Facebook allows you to upload profile pictures, when you upload your photo you are using the S3 API to upload your image. Now the image is uploaded it is accessible on a public URL. This is the URL that is used whenever other users access the site. 

Some of the most popular providers for S3 storage include Amazon AWS, Vultr and Digital Ocean. They all provide the same service but have a few differences when it comes to price, locations, capacities and bandwidths, so it's worth looking around to see which one suits your needs best.

My first experience with S3 was using AWS. AWS is great.....but its also very confusing, especially for a backend developer like me who tries to stay clear of DevOps as much as he can. I trawled through the AWS documentation trying to understand how to implement the S3 service and after many hours of playing with buckets, policies and IAM roles I got it working. After my ordeal I decided to try other providers to see how the implementations differ (In the hope of finding a simpler solution). It turns out that implementations are the same across providers! 

So, I will run you through a very simple example of how to implement a basic S3 object storage in Nodejs. The example I am going to give uses Express and multer for the file upload, however the object storage code is framework agnostic and only requires the aws-sdk.

### Preparing our Node.js project

Before we can connect to our S3 provider there are 4 things you will need. These are:

- The buckets endpoint URL
- The bucket name
- Access key
- Secret access key

These should be provided to you once you have set up your bucket through your chosen providers dashboard. You will want to ensure that your keys are kept private and securely. So in this example we will use dotenv environment variables. 

Firstly, lets create our `.env` file in our project root:

<Codeblock
    language={'js'}
    value={`
S3_BUCKET_NAME=your_bucket_name // e.g my-bucket
S3_ENDPOINT_URL=your_endpoint_url // e.g https://eu.amazons3.com/
S3_ACCESS_KEY=your_access_key
S3_SECRET_KEY=your_secret_access_key
`}
/>

Now we have the information for creating a connection, lets go ahead and install the packages for initialising a connection.

The first thing we need is the `aws-sdk` this is the npm package used for connecting and interacting with an S3 storage. Run the following command to install:

<Codeblock
    language={'markdown'}
    value={`
npm install aws-sdk
`}
/>

In this example we are using TypeScript so we can also install some type definitions. If you are using JavaScript then you can ignore this step.

<Codeblock
    language={'markdown'}
    value={`
npm install --save-dev @aws-sdk/types
`}
/>

### Setting up the connection

Once installed we can create our `connection.ts` :

<Codeblock
    language={'typescript'}
    value={`
import * as S3 from 'aws-sdk/clients/s3';
\n
export default function Connect(path: string | null = ''): S3 {
    return new S3({
        apiVersion: 'latest',
        endpoint: \`\${process.env.S3_ENDPOINT_URL}\${path}\`,
        credentials: {
            accessKeyId: process.env.S3_ACCESS_KEY,
            secretAccessKey: process.env.S3_SECRET_KEY,
        },
    });
}
`}
/>

Lets go through this code line by line. So firstly we import the S3 client from the aws-sdk. The aws-sdk includes a lot of features, so we only need to import the S3 client for this implementation. 

Next we create our Connect function. This function will new up an S3 client using the credentials that we stored in our environment variables. 

Our connect function takes in an optional `path` parameter. When this is set we can specify the path that we want to upload our file to. For example we may want to upload an image to a subdirectory called images. So we would set the path to 'images'. This path is then appended to the endpoint URL. So as an example our endpoint now becomes `https://eu.amazons3.com/images`. If we don't set the path parameter the connection will default to the buckets root.

In our configuration we also provide an S3 API version. In this example I will use latest but you may want to pick a version that works for you. You can read up more about API versions and why you should pick one then read [here](https://docs.aws.amazon.com/sdk-for-javascript/v2/developer-guide/locking-api-versions.html).

### Uploading a file

Now we have a working S3 client instance we can use it to upload files. Lets create a function for uploading a file. For this example we are using multer, so TypeScript users you can install the types with `npm i --save-dev @types/multer`.

Our `upload.ts` will look like this:

<Codeblock
    language={'typescript'}
    value={`
import { PutObjectOutput, PutObjectRequest } from 'aws-sdk/clients/s3';
import {AWSError} from 'aws-sdk/lib/error';
import * as S3 from 'aws-sdk/clients/s3';
import Connect from './connection';
\n
export default async function Upload(bucket: string, file: Express.Multer.File, objectName: string, path: string | null = null): Promise<string> {
    return new Promise<string>((resolve, reject) => {
        const s3: S3 = Connect(path);
        const params: PutObjectRequest = { Bucket: bucket, Key: objectName, Body: file.buffer, ACL: 'public-read', ContentType: file.mimetype };
        s3.putObject(params, (err: AWSError, data: PutObjectOutput) => {
            if (err) reject(err);
            resolve(\`\${process.env.S3_ENDPOINT_URL}\${bucket}/\${path}/\${objectName}\`);
    });
});
}
`}
/>

In our Upload function we are passing in 4 parameters:

| Parameter | Description |
| --- | --- |
| ``bucket``  | This is the name of the bucket you set up with the provider and what we have stored in our environment variable (e.g my-bucket).  |
| ``file``  | This is the actual file that we are uploading. |
| ``objectName``  | This is the name that we would like to use when we store the file in the cloud. This name should include your file extension. If you are uploading a gif then this should be ``image.gif`` as oppose to just ``image``. |
| ``path`` | (Optional) This is passed straight through to the connection we made previously. So by default it is set to null, which would mean the file is uploaded to the root of the bucket. If you supply ``'images'`` to this parameter then the file you upload will be stored in a subdirectory called images. |

Our Upload function will return a Promise. This will resolve the URL of our uploaded file once the S3 client has finished uploading. 

Inside our new Promise, we first use our Connect function to get an initialised S3 client, passing through our optional `path` parameter.

Then we create our S3 request parameters. In the parameters we set 5 options:

| Parameter | Description |
| --- | --- |
| ``Bucket`` | This is the name of the bucket. We set this using our bucket parameter. |
| ``Key`` | This is the name that is used when the file is stored in the bucket. We use our objectName parameter here. |
| ``Body`` | This is the file we are uploading. This option takes a file buffer. So we use our parameter ``file.buffer`` |
| ``ACL`` | This option is used to specify the access of the file we are uploading. In this example we are using ``'public-read'``. This means that anyone who has the URL of the file we upload can read it. If you want to read more about the different ACL types then read here. |
| ``ContentType`` | This is used to tell S3 the type of file we are uploading. It takes in a file mime type. We pass this in using our file parameters ``file.mimetype``. |

Next we call the putObject method on the S3 client. We pass in our request parameters above, and define a callback. The callback will give us an error if the upload fails. So we can check if this has a value in our callback and reject our Promise if there is an error. If there is no error then we can resolve our promise with the URL of our object. We construct the URL of our uploaded object using the endpoint URL, bucket name, path and object name. So as an example if uploaded image.gif to an images folder inside our my-bucket, then the URL would be `https://eu.amazons3.com/my-bucket/images/image.gif`

### Deleting a file

When it comes to deleting a file the process is very similar to upload. 

We can create a `delete.ts`:

<Codeblock
    language={'typescript'}
    value={`
import {DeleteObjectOutput, DeleteObjectRequest} from 'aws-sdk/clients/s3';
import {AWSError} from 'aws-sdk/lib/error';
import * as S3 from 'aws-sdk/clients/s3';
import Connect from './connection';
\n
export default async function Delete(bucket: string, objectName: string, path: string | null = null): Promise<DeleteObjectOutput> {
    return new Promise<DeleteObjectOutput>((resolve, reject) => {
        const s3: S3 = Connect(path);
        const params: DeleteObjectRequest = { Bucket: bucket, Key: objectName };
        s3.deleteObject(params, (err: AWSError, data: DeleteObjectOutput) => {
            if (err) reject(err);
            resolve(data);
        });
    });
}
`}
/>

This function takes in 3 of the parameters we have seen before:

| Parameter | Description |
| --- | --- |
| ``bucket`` | The name of our bucket we created with the provider and stored in the environment variables. |
| ``objectName`` | The name that we used when storing the object. E.g ``image.gif`` |
| ``path`` | The path to the object. E.g ``'images'`` would delete the object with the objectName supplied inside the images subdirectory. If null this defaults to the root of the bucket. |

Inside our Promise we use our Connect function to get an initialised S3 client.

We create our request parameters. Setting the `Bucket` and `Key` options using our functions parameters.

Then we use the `deleteObject` method on the client, passing in our request parameters and defining a callback. Just like before we check if the callback has errored and reject the promise if an error occurs.

If no error occurs then we resolve the `deleteObject` response.

### Setting up our Express endpoints

We have defined some functions to connect to our S3 provider, upload objects and delete objects. The next question is how do we use them?

We will use Express and Multer as an example to demonstrate how to use them.

Using our Express app we can define a POST endpoint like the following:

<Codeblock
    language={'typescript'}
    value={`
app.post(
    '/upload',
    multer().single('formFile'),
    async (req, res) => {
        if(!req.file) res.status(400).send('Bad Request: No file was uploaded');
        // If you want to retain the original filename and extension just use originalname like below
        // const filename: string = req.file.originalname;
        const fileExtension: string = req.file.originalname.split('.').pop();
        const filename: string = \`my-custom-filename.\${fileExtension}\`;
        const url: string = await Upload(process.env.S3_BUCKET_NAME, req.file, filename, 'images/logo');
        res.status(201).send(url);
    });
`}
/>


This creates an endpoint called /upload which accepts multi-part form data. We use the multer middleware with this endpoint. The multer middleware will look in the submitted form data for the field with the key `formFile`. This key should be paired with a file. The middleware then attaches the file object to the request under the property `file` .

In our handler we check that a file has been supplied and throw a Bad Request response if none was sent.

In the example I have shown how to use a custom filename. We read the file extension from our files original name first. Then we create a new filename, appending the original file extension e.g `my-custom-filename.gif` .

Next we call our Upload function. We pass in the bucket name stored in our environment variables; the file in the request; our custom filename; and in the example I am uploading to the subdirectory `images/logo`. 

After awaiting our Upload we will have the URL of the uploaded file and we can send this in our endpoints response object.

If you would like to see how to use the delete function with an Express endpoint then take a look at the example project.

### Example project

I have created a full working example project on GitHub which uses the code we have gone through today. Check it out [here](https://github.com/Forward-Digital/node-s3-storage-example).

How to implement an S3 object storage into your Nodejs projects with AWS, Vultr or Digital Ocean.

Using an S3 object storage provider in Node.js

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: false,
    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

Implementing Sign in with Apple with a managed Expo workflow and a Nest.js backend

Using an S3 object storage provider in Node.js

Why don't we build something together?

Let's talk!