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 {BlogLayout} from "../../components";

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

export const meta = {
	timestamp: new Date('2024-04-23T12:00:00Z'),
	title: "Best Practices for Adopting Open-Source Software in 2024",
	authorName: "Harry Bendix-Lewis",
	summary: "In this article, we will discuss the best practices for adopting open-source software, including the internal considerations organisations must make, the metrics by which to judge the quality of OSS components, the approval process, and the licensing of OSS components.",
	tags: ['General'],
	thumbnailUrl: '/blog/adoption-oss.jpg',
	featured: true,
	readTime: '10 min read',
	slug: 'best-practices-for-adopting-open-source-software'
}

Open-source adoption includes the strategic and tactical considerations of introducing open-source software to your organisation. Having a robust adoption process is critical to ensuring that new open-source components are correctly evaluated before being integrated into the organisation’s systems.

In this article, we will discuss the best practices for adopting open-source software, including the internal considerations organisations must make, the metrics by which to judge the quality of OSS components, the approval process, and the licensing of OSS components.

## OSS Policy

An OSS policy is a formal document that outlines the rules and guidelines for using open-source software within an organisation.

Our literature review found an OSS policy to be a recurring theme in the best practices for adopting open-source software. Best practices recommend that organisations have a formal OSS policy in place.

An OSS policy should ([Hammond, 2009](https://www.eclipse.org/org/foundation/membersminutes/20090326StrategySummit/OSS-WYPAUT3_JeffreyH.pdf));

- Be concise
- Developer consumable
- Involve general counsel early and often
- Classify OSS license types
- Take control of the process
- Measure internalisation
- Be revisited and revised on a regular basis

It should include the goals for OSS adoption, the acquisition process, the rules for the business case, and guidelines for the appropriate use of OSS ([Hammond, 2009](https://www.eclipse.org/org/foundation/membersminutes/20090326StrategySummit/OSS-WYPAUT3_JeffreyH.pdf)).

Lacking a formal policy for OSS usage and adoption, which typically includes licencing guidelines, can lead to legal and security risks ([Schofield, 2008](https://www.theguardian.com/technology/blog/2008/dec/12/cisco-fsf-opensource)).

However, a policy alone is not enough. It is essential to ensure that all employees understand and follow the policy. Most importantly, the policy steps should apply to the organisational context ([Osborne et al., 2023](https://www.linuxfoundation.org/the-european-public-sector-open-source-opportunity)).

Open-source policies are a formal way for an organisation to set guidance and rules for using open-source software. As we will see later, most developers use their own discretion rather than a formal organisational process, which can lead to inconsistencies and licensing risks.

A policy is an excellent way for an organisation to ensure that all developers are following the same process, the correct stakeholders are included in the adoption process, and that the process is tailored to the organisation’s needs.


## Maturity Models


Maturity models are a way to evaluate the quality of open-source software components. They can play a key role in the adoption process, as they allow for evaluating OSS components before they are integrated into the organisation’s systems. We found that there are several maturity models for evaluating OSS components; however, there wasn’t a consensus on which model was the best.


Fundamentally, the adoption of OSS components differs from the adoption of proprietary software due to the fact OSS is stored in public repositories, accessible by anyone, and is often developed by a community of developers ([Umm-e-Laila et al., 2016](https://www.researchgate.net/publication/318339374_Comparison_of_Open_Source_Maturity_Models)). Due to this, the quality of open-source software can be very different from one product to another; therefore, evaluation methods have been developed to evaluate OSS components properly.


The most popular OSS evaluation methods are the Capgemini-Open Source Maturity Model (C-OSSM), Navicasoft-Open Source Maturity Model (N-OSSM), Qualification and Selection of Open Source (QSOS), Open Business Readiness Rating (Open BRR) and Easiest Open Source (E-OSS) ([Umm-e-Laila et al., 2016](https://www.researchgate.net/publication/318339374_Comparison_of_Open_Source_Maturity_Models)).


None of those interviewed were familiar with these models, let alone using them in their organisation. This suggests that these models are not widely used in practice. We also found, from our literature review, that there is no consensus on which model is the best, with [Umm-e-Laila et al., 2016](https://www.researchgate.net/publication/318339374_Comparison_of_Open_Source_Maturity_Models) going as far as to say that “in order to take advantage of OSS properly, it is recommended to propose a new framework/model that will eliminate the weakness of all models.”.


We can conclude that while maturity models are an excellent way to evaluate OSS components, there is no consensus on which model is the best, and they are not widely used in practice. From our interviews, we found that most developers judge the maturity of OSS components based on their own discretion, usually stemming from their own experiences and the experiences of their colleagues.


## Trust in Open-Source Software

Trust in OSS is a critical concept when adopting OSS components. How does one come to trust an OSS component? More often than not, “there is no sound basis for trust in the Software Ecosystems (SECO) hubs”, with trust being considered “founded or unfounded” ([Hou et al., 2022](https://www.researchgate.net/publication/365699098_A_systematic_literature_review_on_trust_in_the_software_ecosystem)).

Trust is subjective and based on the end-developer’s perception and intrinsic and extrinsic motivations. When adopting a new OSS component, the developer will consider intrinsic factors such as:

- Source code
- Reliability
- Security

Extrinsic factors such as:

- Documentation
- Structural assistance
- Cost

Quality is the most discussed factor in trustworthiness, with most developers considering the quality of the OSS component as the most critical factor in trustworthiness ([Hou et al., 2022](https://www.researchgate.net/publication/365699098_A_systematic_literature_review_on_trust_in_the_software_ecosystem)).

From our literature review and the interviews, we found that each developer uses their own trust model and that there is no documented process for evaluating the trustworthiness of OSS components within an organisation.

Outside of academic papers, trustworthiness wasn’t mentioned in any of the best practices we reviewed.

This is a significant gap in the best practices landscape, as trust plays a vital role in adopting OSS components.


## Approval process


The approval process is a formal process for evaluating and approving OSS components before they are integrated into the organisation’s systems. It’s an opportunity for the organisation to evaluate the OSS component and ensure that it meets the organisation’s needs and standards, and engage relevant stakeholders in the approval process.


When adopting OSS, there are several “deal-breakers” that can prevent the adoption of an OSS component. Outlined by [Spinellis, 2019](https://ieeexplore.ieee.org/document/8909944/authors), these include:


- Lacking functionality

- Incompatible license

- Nonfunctional properties


Businesses should approve OSS based on technical needs, licensing, longevity, and business factors like cost and benefits. Yet, businesses must balance risk with commercial advantages and be willing to adapt their methods quickly. The approval process should be formal, with a clear set of guidelines and rules, and should be managed by a central team and engage relevant stakeholders ([Butler et al., 2022](https://www.sciencedirect.com/science/article/pii/S0164121221002442#b37)).


When selecting an OSS component, ensure it demonstrates the following security and maintenance best practices ([Department of Defense, 2022](https://dodcio.defense.gov/Portals/0/Documents/Library/SoftwareDev-OpenSource.pdf)):


- **Detection Tool Usage:** Actively employs detection tools within its integration pipeline and externally.

- **Vulnerability Reporting Transparency:** Has a clear process for the open reporting and documentation of security vulnerabilities.

- **Security Review History:** Possesses a record of security reviews.

- **Cybersecurity Testing:** Undergoes regular cybersecurity assessments, notably third-party audits, to verify security measures.

- **Issue Resolution:** Demonstrates a commitment to promptly addressing and resolving reported issues.

- **Timely Vulnerability Remediation:** Shows a track record of quickly remedying vulnerabilities.


We found that an approval process was a recurring theme in the best practices for adopting open-source software. Every interviewee demonstrated some approval process for the adoption of OSS components. Smaller companies tended to build a minimal viable product (MVP) with the OSS in question; larger teams had a multistep process that involved multiple stakeholders.


The US [Department of Defense, 2022](https://dodcio.defense.gov/Portals/0/Documents/Library/SoftwareDev-OpenSource.pdf) recommendations primarily emphasise the quantifiable attributes of OSS dependencies, including security features and measurable performance metrics. In contrast, [Butler et al., 2022](https://www.sciencedirect.com/science/article/pii/S0164121221002442#b37) analysis portrays the approval process as somewhat ambiguous, describing it as more reliant on assessment and discretion than on strict, predefined criteria.


To conclude, the approval process for adopting open-source software is dynamic and customised to each organisation’s specific requirements, yet it remains a universally acknowledged standard that all entities conform to.


## Software Bill of Materials


Software Bill of Materials (SBOM) is a formal list of components used in a software system. It allows for tracking OSS components and their dependencies, which is essential for managing the security and compliance risks associated with OSS.


Since 2018, SBOMs have surged in popularity, driven in part by a collaborative effort headed up by the American National Telecommunications and Information Administration’s (NTIA) multi-stakeholder process ([National Telecommunications and Information Administration, n.d.](http://ntia.gov/SBOM)). This work culminated in the US government’s issuance of an executive order mandating the use of SBOMs in all federal software ([The White House, n.d.](https://www.whitehouse.gov/briefing-room/presidential-actions/2021/05/12/executive-order-on-improving-the-nations-cybersecurity/)) in direct response to the SolarWinds supply chain attack ([Schwartz, 2021](https://www.cybersecuritydive.com/news/solarwinds-1-year-later-cyber-attack-orion/610990/)).


The two primary standards for SBOM are SPDX and CycloneDX.


SPDX17 is an open standard developed by the Linux Foundation to communicate details of a SBOM, including components, licenses, copyrights, and security references, recognised internationally as ISO/IEC 5962:202118 ([System Package Data Exchange (SPDX®) 2024](https://spdx.dev)). CycloneDX19, originating from the Open Web Application Security Project (OWASP) community, is an SBOM standard crafted for application security and supply chain component analysis, now extended to encompass a broader array of applications such as software-as-a-service BOM (SaaSBOM) ([CycloneDX 2024](https://cyclonedx.org/)).


Both formats are popular, yet organisations are advised to select the format that most aptly meets their specific requirements ([Alvarenga, 2023a](https://www.crowdstrike.com/cybersecurity-101/secops/software-bill-of-materials-sbom/)).


At a minimum, an SBOM must contain three categories ([United States Department of Commerce, 2021](https://www.ntia.gov/blog/ntia-releases-minimum-elements-software-bill-materials));


**Data fields** Data fields must be standardised and contain essential information on each component for effective tracking and management. The aim is to ensure these components can be easily identified throughout the software supply chain, linking them to other valuable data sources ([United States Department of Commerce, 2021](https://www.ntia.gov/blog/ntia-releases-minimum-elements-software-bill-materials)). Naming conventions should try and follow the guidance outlined by [NTIA Multistakeholder Process on Software Component Transparency Framing Working Group, 2021](https://www.ntia.gov/files/ntia/publications/ntia_sbom_framing_2nd_edition_20211021.pdf).


**Automation Support** Automation support is essential for the effective use of SBOMs, as it allows for the automatic generation and updating of SBOMs, which is essential for managing the large number of OSS components used in modern software systems.


The data formats that are being used to generate and consume SBOMs are:


- Software Package Data eXchange (SPDX)

- CycloneDX13

- Software Identification (SWID) tags


**Practices and Processes** Practices and processes are essential for the effective use of SBOMs, as they allow for the effective management of OSS components and their dependencies, necessary for managing the security and compliance risks associated with OSS.


There are two elements that should be explicitly stated in the SBOM:


Frequency – When a software component is updated or new information about its components is discovered, the supplier must issue an updated SBOM to reflect these changes ([United States Department of Commerce, 2021](https://www.ntia.gov/blog/ntia-releases-minimum-elements-software-bill-materials)).


Depth – An SBOM must include all primary components and their transitive dependencies, ensuring top-level dependencies are detailed enough to identify all subsequent dependencies recursively ([United States Department of Commerce, 2021](https://www.ntia.gov/blog/ntia-releases-minimum-elements-software-bill-materials)).


## Licencing


The licensing of OSS components is a crucial consideration when adopting OSS as it can significantly impact the organisation’s ability to use the OSS component and considerably affect the organisation’s ability to distribute the software that uses the OSS component.


As of 2022, 78% of open source components are under permissive licenses, which allow users wide freedom to use, modify, and distribute the software, with minimal requirements on how it can be redistributed. Meanwhile, copyleft licenses, which require that any modified versions of the software also be distributed under the same license terms, make up the remaining 22% of open source components ([Murray, 2022](https://www.mend.io/blog/open-source-licenses-in-2022-trends-and-predictions/)).


The Apache License is the most popular OSS license, with 30% of all OSS projects using it ([Murray, 2022](https://www.mend.io/blog/open-source-licenses-in-2022-trends-and-predictions/)).


Larger organisations (>5000 employees) are more likely to have an internal legal team familiar with OSS licensing when compared to small organisations (100 employees) 31.46% vs 22.30%, respectively ([OpenLogic, 2023](https://www.openlogic.com/resources/2023-state-open-source-report)).


To help reduce the risk of legal problems arising with the use of open-source software ([Mathpati, 2023](https://cobalt.io/blog/risks-of-open-source-software)), organisations should watch over all open-source code being brought into the organisation, ensuring that licence requirements are met. To achieve this, there are several tools available, such as ([The Linux Foundation, 2024](https://www.linuxfoundation.org/tools-for-managing-open-source-programs/)):


- **Black Duck Protex** – A fee-based tool for license compliance and open source management.

- **Copyright review tools** – Command line utilities for copyright file management.

- **FOSSA** – Automates code dependency tracking and license compliance.

- **FOSSology** – An open-source toolkit from the Linux Foundation for license compliance featuring a web UI for compliance workflows.


Managing the licensing of OSS components is a key consideration when adopting OSS. Large organisations often have the advantage of an internal legal team to navigate open-source software (OSS) licensing, a resource that smaller organisations lack. Therefore, relying on internal legal teams for OSS license management cannot be deemed a universally applicable best practice, as it disadvantages smaller entities. The easiest way to manage your OSS licensing is to use a tool that can automatically track and manage the licensing of OSS components, as outlined by [The Linux Foundation, 2024](https://www.linuxfoundation.org/tools-for-managing-open-source-programs/).

## Conclusion

In this article, we have discussed the best practices for adopting open-source software, including the internal considerations organisations must make, the metrics by which to judge the quality of OSS components, the approval process, and the licensing of OSS components.

The adoption of open-source software is a complex process that requires careful consideration of the organisation’s needs and the OSS components being adopted. Having a robust adoption process is critical to ensuring that new open-source components are correctly evaluated before being integrated into the organisation’s systems.

We can see that the current literature is broad and extensive, with many different opinions on the best practices for adopting open-source software. However, there are some recurring themes, such as the need for an OSS policy, the importance of an approval process, and the need to manage the licensing of OSS components.

We hope that this article has provided you with some valuable insights into the best practices for adopting open-source software and that you can use this information to improve your organisation’s OSS adoption process.


In this article, we will discuss the best practices for adopting open-source software, including the internal considerations organisations must make, the metrics by which to judge the quality of OSS components, the approval process, and the licensing of OSS components.

Best Practices for Adopting Open-Source Software in 2024

import { BlogLayout } from '../../components';

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

export const meta = {
	timestamp: new Date('2024-05-11T12:00:00Z'),
	title: "Best Practices for Fostering Collaboration with the Open-Source Community in 2024",
	authorName: "Harry Bendix-Lewis",
	summary: "This post delves into effective practices for engaging with and contributing to the open-source community, enhancing both your projects and the broader ecosystem.",
	tags: ['General'],
	thumbnailUrl: '/blog/contributing-oss.jpg',
	featured: true,
	readTime: '10 min read',
	slug: 'best-practices-for-fostering-collaboration-with-the-open-source-community',
}


Open-source software (OSS) has become an integral part of modern software development, with many organisations relying on open-source components to build their products.

However, using open-source software comes with its own set of challenges, such as security risks, licensing issues, and the need to contribute back to the community.

In this post, we delve into effective practices for engaging with and contributing to the open-source community, enhancing both your projects and the broader ecosystem.

## Open Source Program Office

An Open Source Program Office (OSPO) is a corporate entity that is responsible for managing an organisation’s open-source efforts. The OSPO is a “central nervous system” for open source within an organisation and provides governance, oversight, and support for all things related to open source ([Haddad, 2022](https://www.linuxfoundation.org/research/a-deep-dive-into-open-source-program-offices)). It trains staff, promotes efficient software development with open-source parts, guides open-sourcing projects, ensures legal compliance, and builds community engagement.

An OSPO helps bridge the gap between an organisation’s internal development and the external open-source community, helping to ensure that the organisation is a good steward of open-source software and can reap the benefits of open-source adoption, all the while minimising risks ([TODO Group, 2023](https://ospoglossary.todogroup.org/ospo-definition/)).

Six common characteristics of successful open source programs ([Walker, 2016](https://opensource.com/business/16/5/whats-open-source-program-office)) are:

- Value marketing and branding highly.
- Choose open-source communities that match your tech goals.
- Get good legal advice to balance risk and innovation.
- Your open-source efforts should support your product goals.
- Explain your support plans clearly to everyone involved.
- Hire someone passionate about open source to lead.

Uber, for example, was motivated to create its own OSPO because of the need to streamline support for various open-source initiatives. For instance, there was a significant demand for advice on incorporating open-source technology into external products from engineers. Key concerns included navigating compliance, licensing, and related legal matters. Additionally, there was a crucial need to offer engineers direction on how to release Uber’s own software as open source, whether by initiating new projects or contributing to existing ones ([Uber Case Study n.d.](https://todogroup.org/resources/case-studies/uber/)).

“It was natural and organic for Uber to create an open source program office since it allowed us to build our platform and scale the technology at unprecedented speed […] in essence, Uber loves open source because it’s essential to our success.” ([Hsieh, n.d.](https://todogroup.org/resources/case-studies/uber/)).

Since the OSPO is a relatively new concept, with Google opening one of the first OSPOs in 2004 ([Google, 2022](https://opensource.google/about)), the literature references mostly large corporate entities with the resources to create an OSPO. The Linux Foundation recommends a minimum of five employees to start a successful OSPO ([Haddad, 2022](https://www.linuxfoundation.org/research/a-deep-dive-into-open-source-program-offices)). Therefore, an OSPO is not best suited for smaller organisations that cannot afford to dedicate the resources to an OSPO.

## Open Sourcing Previously Proprietary Software

Open-sourcing previously proprietary software is the process of releasing software to the open-source community for free use and modification. This process can be beneficial for organisations; it allows for increased innovation, collaboration, and community engagement and can lead to the development of features that are beneficial to the organisation, as well as the resolution of issues that impact the organisation’s operations.

There are a series of examples of organisations open-sourcing previously proprietary software. Some of the most notable examples include:

**Microsoft Open-sourcing .NET** By open-sourcing .NET, Microsoft allowed for a single, collaborative codebase across platforms rather than separate implementations. Ultimately, open development allows more community engagement to provide feedback and contributions, making the stack better for all ([Landwerth, 2014](https://devblogs.microsoft.com/dotnet/net-core-is-open-source/)).

**Microsoft Open-sourcing Powershell** Microsoft open-sourced PowerShell to make it more widely available and helpful for system administrators and developers who work with multiple operating systems. By making it open source and available cross-platform, more people can use PowerShell to automate tasks and manage their diverse computing environments that include different OSes ([Foley, 2016](https://www.zdnet.com/article/microsoft-open-sources-powershell-brings-it-to-linux-and-mac-os-x/)).

**NVIDIA Open-sourcing PhysX** NVIDIA open-sourced PhysX because physics simulation has “dovetails” with AI, robotics, and computer vision. NVIDIA considered physics simulation “foundational for so many things” and open-sourcing it would allow it to be developed and applied more widely than NVIDIA could do alone ([Lebaredian, 2018](https://blogs.nvidia.com/blog/physx-high-fidelity-open-source/)).

**Microsoft Open-sourcing Live Writer** Microsoft open-sourced Live Writer to allow the community to continue to develop and improve it, as Microsoft no longer had the resources to maintain it ([ARS STAFF, 2015](https://arstechnica.com/information-technology/2015/12/microsoft-open-sources-live-writer-beloved-but-abandoned-blogging-tool/)).

The primary motivation for open-sourcing previously proprietary software is to allow for increased community engagement, feedback, and contributions, making the software better for all.

However, open-sourcing previously proprietary software does have some technical considerations. For example, the software must be properly documented, the code must be clean and well-structured, and the software must be properly licensed. We saw from the interviews that these technical considerations are usually a deal-breaker and the reason why organisations do not open-source their software.

## Hiring

To reduce the risk of using OSS, organisations should hire internal staff to manage OSS. Develop in-house proficiency and aim to reduce reliance on external service providers by cultivating organisational expertise to oversee projects. This approach will enable quicker deployment of upgrades and enhancements ([Team Srijan, 2010](https://materialplus.srijan.net/resources/blog/migrating-open-source-survival-guide-smes)).

Smaller organisations might not necessarily hire new personnel but rather delegate the responsibility to an existing staff member who is recognised as a subject-matter expert within the specific area (Interviewee 8, 2024). This approach is viable because, as noted, “In general, open source developers are experienced users of the software they write. They are intimately familiar with the features they need, and what the correct and desirable behavior is” ([Mockus et al., 2000](https://dl.acm.org/doi/10.1145/337180.337209)). This innate understanding significantly mitigates one of the primary challenges in large software projects: the lack of domain knowledge. Consequently, smaller organisations can effectively rely on their in-house experts, capitalising on their comprehensive knowledge and experience.

Hiring is a significant investment, and it is not always feasible for smaller organisations to hire new personnel to manage OSS.

## Culture

Open source has always been deeply rooted in culture, originating as a grassroots movement advocating for software freedom. Culture encompasses a broad spectrum, and individuals and organisations get involved in open source for various reasons.

When inquiring about the cultural drivers behind companies’ engagement in open source, innovation emerged as the leading motivation, with 84% of respondents to Fintech Open Source Foundation State of Open Source Survey affirming it as a critical factor ([Ellison et al., 2021](https://www.finos.org/reports/2021-state-of-open-source-in-financial-services)).

Uber instituted internal standards for governing and incentivising contributing upstream and back to the community to encourage ongoing, regular involvement in open-source projects. Contributing back to the open-source community is one of the best ways to help ensure open-source project sustainability ([Uber Case Study n.d.](https://todogroup.org/resources/case-studies/uber/)).

A big part of culture is fostering an environment where developers feel comfortable taking an unconventional route to solve a problem ([Autodesk Case Study n.d.](https://todogroup.org/resources/case-studies/autodesk/)), and where they are encouraged to share code and collaborate with others ([Abernathy, n.d.](https://todogroup.org/resources/case-studies/meta/)).

An organisation’s culture is a significant factor in the adoption of open-source software, one that is quite hard to quantify and measure. There was very little mention of culture in the best practices we reviewed, and from our interviews, we found that there isn’t an “open-source” culture but rather a more collaborative and innovative culture that is conducive to using open-source software.

## Contributions

Active engagement in the open-source community offers substantial rewards. When you contribute to the projects your organisation utilises, you’re boosting its reputation and playing a significant role in steering the software’s development path. Such proactive participation can lead to the development of features that are beneficial to your organisation, as well as the resolution of issues that impact your operations.

Contributing to the open-source ecosystem extends beyond just coding. Offering documentation, identifying bugs, and aiding in translations represent other crucial ways to contribute. Through these contributions, you help cultivate a mutually beneficial relationship with the community ([Yborra, 2024](https://vaultinum.com/blog/managing-open-source-software-integration-in-software-development#best-practices-for-managing-open-source-software-integration)).

Contributing also helps keep the open-source component active and maintained. In recent years, a notable challenge has been the shortage of contributions or ongoing maintenance for projects, affecting even highly utilised packages like gorilla/mux, which have struggled to secure maintainers and consequently, had to archive their projects ([Norblin, 2023](https://www.scaleway.com/en/blog/foss-giving-back/)).

Another way to contribute is through financial support. A recent survey by DigitalOcean found that only 20% of respondents had been paid for their contributions to open source, while 53% agreed or strongly agreed that individuals should be compensated for their work ([DigitalOcean, 2022](https://anchor.digitalocean.com/rs/113-DTN-266/images/DigitalOcean-Currents_June-2022.pdf)). This suggests that there is room for improvement in financial support for open-source contributors ([Tandochain, 2023](https://tandochain.medium.com/the-importance-of-financial-support-for-open-source-software-bb486f32b145)).

More work is being done to support financial contributions to open source; notable examples include GitHub Sponsors and Open Source Collective, both offering platforms for financial support of open-source projects ([Open Source Collective 2024](https://www.oscollective.org/); [Explore GitHub Sponsors 2024](https://github.com/sponsors/explore)).

Contributing to the open-source community is a best practice for managing the security risks associated with OSS. Most of the literature we reviewed mentioned contributing to the open-source community as a best practice. However, from our interviews, very few organisations contribute to the open-source community, and those that do do so in a limited capacity.

## Hosting Events

Hosting events is a great way to engage with the open-source community. Events can be an excellent way to engage with the open-source community, and they can take many forms, from hackathons to conferences to meet-ups.

[Schumacher, 2022](https://www.youtube.com/watch?v=6UMCe5o0KBw), went as far as to say that corporate organisations looking to lead in open source should host events, as they are a great way to engage with the community and build relationships.

However, our interviews found that hosting events is not widely used in practice and that the best practices landscape does not reflect the real-world use of hosting events. Companies do send their employees to events, but larger organisations typically host events, as smaller organisations do not have the resources to host events.


## Conclusion

In conclusion, fostering collaboration with the open-source community is essential for organisations that rely on open-source software. By engaging with the community, contributing back to the community, and hosting events, organisations can enhance their projects and the broader ecosystem.

However, there are challenges to fostering collaboration with the open-source community, such as the need to hire internal staff to manage OSS, the technical considerations of open-sourcing previously proprietary software, and the cultural challenges of adopting open-source software.

Despite these challenges, the benefits of fostering collaboration with the open-source community are significant. By following best practices for engaging with and contributing to the open-source community, organisations can enhance their projects and the broader ecosystem, ultimately leading to better software for all.


This post delves into effective practices for engaging with and contributing to the open-source community, enhancing both your projects and the broader ecosystem.

Best Practices for Fostering Collaboration with the Open-Source Community in 2024

import { BlogLayout } from '../../components';

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

export const meta = {
	timestamp: new Date('2024-05-01T12:00:00Z'),
	title: "Best Practices for Managing the Security Risks Associated with Open-Source Software in 2024",
	authorName: "Harry Bendix-Lewis",
	summary: "Open-source software (OSS) is a critical component of modern software development. However, it also introduces security risks. This blog post explores best practices for managing the security risks associated with OSS.",
	tags: ['General'],
	thumbnailUrl: '/blog/managing-oss.jpg',
	featured: true,
	readTime: '10 min read',
	slug: 'best-practices-for-managing-the-security-risks-associated-with-open-source-software',
}

Open source software (OSS) is a critical component of modern software development. It allows developers to leverage existing code, reduce development time, and focus on building new features.

However, OSS also introduces security risks. Vulnerabilities in OSS components can expose organisations to cyber threats, data breaches, and financial losses. To mitigate these risks, organisations must adopt best practices for managing the security risks associated with OSS.

In this blog post, we explore best practices for managing the security risks associated with OSS.

We review the literature, conduct interviews with industry experts, and analyse case studies to identify key strategies for securing OSS components. Our research highlights the importance of regular vulnerability assessments, tooling, continuous monitoring, binary repositories, risk management and mitigation, static application security testing, and forking as essential practices for managing the security risks associated with OSS.

## Regular vulnerability assessments

Regular vulnerability assessments identify, prioritise, and apply patches to systems and software to address vulnerabilities. As the OSS landscape constantly evolves, organisations encounter thousands of new vulnerabilities. Yet, many businesses do not have a robust patch management strategy in place and fail to implement critical patches promptly, leaving them vulnerable to security breaches ([Hackerone, 2024](https://www.hackerone.com/knowledge-center/what-vulnerability-assessment-benefits-tools-and-process)).

With an estimated 84% of open source components having at least one vulnerability ([Sawers, 2021](https://venturebeat.com/2021/04/13/synopsys-84-of-codebases-contain-an-open-source-vulnerability/)), regular vulnerability assessments are essential for managing the security risks associated with OSS.

A rough overview of the process is as follows ([Hackerone, 2024](https://www.hackerone.com/knowledge-center/what-vulnerability-assessment-benefits-tools-and-process)):

1. **Initial Preparation** – Defining the scope and goals of the vulnerability testing to ensure a targeted and practical assessment.
2. **Vulnerability Testing** – Running automated tests to identify vulnerabilities within the systems included in the predefined scope.
3. **Prioritise Vulnerabilities** – Assessing which vulnerabilities are most critical, requiring immediate attention, and evaluating their potential business impact.
4. **Create Vulnerability Assessment Report** – Produce a detailed report outlining medium and high-priority vulnerabilities found and recommended remediation strategies.
5. **Continuous Vulnerability Assessment** – Conducting scans for vulnerabilities on a continuous basis to verify if previous vulnerabilities have been effectively remediated and to discover new ones.

Regular vulnerability assessments are frequently mentioned in the best practices for managing the security risks associated with OSS. Without automated vulnerability assessments, it is difficult to keep up with the large number of OSS components used in modern software systems and the many vulnerabilities discovered each year. Therefore, with automation, regular vulnerability assessments are a best practice for managing the security risks associated with OSS.

## Tooling

Tooling is the functionality that allows for automating the management of OSS components. It can be very useful as a way to manage the large number of OSS components used in modern software systems without introducing unnecessary manual work. Any software project that actively works to reduce security vulnerabilities is less risky. Therefore, tools that aid in identifying security vulnerabilities within software projects are critical ([Department of Defense, 2022](https://dodcio.defense.gov/Portals/0/Documents/Library/SoftwareDev-OpenSource.pdf)).

There are three tools found from our literature review that are considered “leaders”; Snyk, Sonatype, and Synopsys (Black Duck) ([Worthington et al., 2023](https://www.forrester.com/report/the-forrester-wave-tm-software-composition-analysis-q2-2023/RES178483)). These tools are designed to help organisations manage the security risks associated with OSS. They can be used to automate vulnerability assessments, manage licensing, enforce an OSS policy, and generate SBOMs. With this in mind, due to the diversity of OSS components, there is no one-size-fits-all solution ([Wen et al., 2019](https://ieeexplore.ieee.org/document/9073010)).

We consider tooling to be a best practice for managing the security risks associated with OSS. It enables organisations of all sizes to manage many OSS components used in modern software systems without introducing unnecessary manual work. There is a lot of research into tooling, and a wide range of tools are available. We found that many tool-promoting papers and articles are written by the companies that produce the tools, so it is down to the organisation to evaluate the tools and decide which one is best for them.

## Continuous monitoring

Modern software applications are built using a complex web of dependencies, including open-source libraries and frameworks. This process is typically recursive, with each dependency having its dependencies, and so on ([Dietrich et al., 2023](https://arxiv.org/pdf/2306.05534.pdf)). Infamously, this web of dependencies can lead to security vulnerabilities, as seen in the equifax data breach ([Fruhlinger, 2020](https://www.csoonline.com/article/567833/equifax-data-breach-faq-what-happened-who-was-affected-what-was-the-impact.html)) and the log4j vulnerability ([Gallo, 2022](https://builtin.com/cybersecurity/log4j-vulerability-explained)).

Continuous monitoring is the process of monitoring OSS components for vulnerabilities and other security risks on an ongoing basis. These can be manual but are often automated and part of an organisation’s CI/CD pipeline. It is crucial for application developers to detect dependencies on vulnerable libraries as soon as possible, to assess their impact precisely, and to mitigate any potential risk ([Ponta et al., 2020](https://dl.acm.org/doi/10.1007/s10664-020-09830-x)).

Now more than ever, developers are using automation to secure their dependencies; in 2023, developers merged 60% more pull requests from GitHub’s Dependabot, a tool that automates dependency updates, than in 2022 ([Daigle, 2023](https://github.blog/2023-11-08-the-state-of-open-source-and-ai/)).

Software composition analysis (SCA) can be used to conduct regular vulnerability assessments, can be implemented as part of the continuous integration/continuous deployment (CI/CD) pipeline, and can be used to enforce an OSS policy ([Alvarenga, 2023a](https://www.crowdstrike.com/cybersecurity-101/secops/software-bill-of-materials-sbom/)). SCAs will provide an inventory of all open-source components used in a project, including their versions and licenses, and will also identify any known vulnerabilities in these components; effectively, producing an SBOM ([Alvarenga, 2023a](https://www.crowdstrike.com/cybersecurity-101/secops/software-bill-of-materials-sbom/)).

Due to the dynamic nature of the open-source ecosystem, continuous monitoring is essential for managing the security risks associated with OSS. An SCA is a great way to monitor OSS components continuously and can be implemented as part of the CI/CD pipeline and can be used to enforce an OSS policy. It is a best practice for managing the security risks associated with OSS.

## Binary repositories

A binary repository manager is a tool designed to store and manage binary files (the compiled version of your source code) and their metadata. Some popular binary repository managers include JFrog Artifactory, Sonatype Nexus Repository, and GitHub Packages.

A binary repository manager is indispensable for managing open-source components effectively. It facilitates the caching of local copies of these elements, ensuring that frequently used packages remain accessible even during downtimes of external repositories. This capability is essential for maintaining continuous project development and operations without interruptions.

Moreover, such a tool distinguishes between approved third-party artefacts and those pending approval, significantly improving the management and visibility of open-source components within projects. It also allows access to specific libraries to be excluded and limited, thereby safeguarding projects from incorporating non-compliant artefacts ([Wainstein, 2018](https://www.altexsoft.com/blog/5-best-practices-for-managing-open-source-components/)).

By caching versions of all open-source software components, you also safeguard against incidents like the left-pad debacle, where the withdrawal of a minor package from the npm package manager (a package manager for the JavaScript programming language) resulted in widespread failure in numerous projects ([Williams, 2016](https://www.theregister.com/2016/03/23/npm_left_pad_chaos/)).

There is a licensing concern, specifically with GPL-licensed open-source software. The GPL license requires that any software distributed that includes or is derived from GPL-licensed code must itself be available under the GPL. If a binary repository contains GPL software and is shared externally, the entire repository may need to be open-sourced. For example, Microsoft released Hyper-V drivers with GPL-licensed binaries, leading to Microsoft having to open-source the drivers in question ([Linux Network Plumber, 2009](https://linux-network-plumber.blogspot.com/2009/07/congratulations-microsoft.html)).

Binary repositories appear to be a polarising issue in the literature. The [Department of Defense, 2022](https://dodcio.defense.gov/Portals/0/Documents/Library/SoftwareDev-OpenSource.pdf) recommended binary repositories as a best practice for managing the security risks associated with OSS, whereas [Anand, 2023](https://security.salesforce.com/blog/seven-best-practices-to-secure-your-open-source-components) (Salesforce) mentioned securing a repository as a best practice, but didn’t mention binary repositories specifically.

## Risk management and mitigation

Risk management and mitigation is the process of identifying, assessing, and prioritising risks, and then taking steps to reduce or eliminate them.

According to the Open Worldwide Application Security Project (OWASP), the most significant risk associated with open source software is “Vulnerable and Outdated Components” and has moved from 9th to the 6th most critical risk to web applications ([OWASP, 2020](https://owasp.org/www-project-top-ten/)).

OSS vulnerabilities grew by 50% year-on-year — from just over 4,000 in 2018 to over 6,000 in 2019 ([Zorz, 2020](https://www.helpnetsecurity.com/2020/03/13/open-source-vulnerabilities-2019/)).

One reason for the increase in vulnerabilities is the growing number of open source components being used in software projects from developers utilising the speed and convenience of open source, especially under time pressure, without considering the security implications. This highlights the need for formal processes to manage the risks. Typically, these correlated to implementing some continuous monitoring and regular vulnerability assessments, as outlined in Section 4.2.1 and 4.2.3 ([Anand, 2023](https://security.salesforce.com/blog/seven-best-practices-to-secure-your-open-source-components), [Chandler et al., 2022](https://www.mayerbrown.com/en/insights/publications/2022/10/the-importance-of-tracking-and-managing-the-use-of-open-source-software}), [Mathpati, 2023](https://cobalt.io/blog/risks-of-open-source-software)). Such efforts should avoid being overly laborious and manual to ensure they do not frustrate developers and slow down the development process ([Contrast Security, 2020](https://www.contrastsecurity.com/hubfs/Understanding-the-Risks_guide_042020_Final.pdf?hsLang=en)).

Like those outlined in this report, the most effective way to mitigate OSS risks is to follow best practices ([Chandler et al., 2022](https://www.mayerbrown.com/en/insights/publications/2022/10/the-importance-of-tracking-and-managing-the-use-of-open-source-software})).

Interestingly, our interviews and case studies found that the approach to risk and risk mitigation varied from organisation to organisation. Larger organisations seemed more proactive in mitigating risk, with dedicated teams and processes in place. Whereas smaller organisations were more reactive, only taking action when a risk materialised and looking to improve their processes after the event. This suggests there is a gap in the best practices landscape, as it doesn’t consider the different approaches to risk management and mitigation based on the size of the organisation.

## Static application security testing

Static application security testing (SAST) is a method of testing the security of an application by examining its source code, byte code, or binary code for security vulnerabilities.

Frequent scanning and security assessment of your repository aids in detecting security concerns at early stages, minimising the chance of significant security problems developing later on. Static code analysis tools can pinpoint typical security weaknesses, and dependency vulnerability scanners can highlight any recognised problems in your project’s dependencies ([Anand, 2023](https://security.salesforce.com/blog/seven-best-practices-to-secure-your-open-source-components)). SAST goes hand in hand with the continuous monitoring of OSS components, as it allows for detecting vulnerabilities in OSS components as soon as possible, allowing for their impact to be assessed and mitigated, see Section 4.2.3.

From our research, SAST is only suggested by Salesforce as a best practice. However, current tooling is comprehensive and can be used to automate the continuous monitoring of OSS components, as outlined in Section 4.2.2. Therefore, SAST can be considered a technical implementation of continuous monitoring.

## Forking

Forking is the process of creating a new project based on an existing project. It allows you to monitor alterations in open-source components, as there will always be a connection to the original repository. One of the key advantages mentioned in the definition of open-source is the explicit permission granted to duplicate and independently alter the source code of an open-source project as desired ([The Open Source Definition 2024](https://opensource.org/osd)).

However, it’s important to be mindful that opting to create a private fork entails the responsibility of integrating any updates from the upstream version of the component. This responsibility grows as the differences between the forked components and the original increase. An ideal situation for forking is when you take an open-source component from a project that is unlikely to receive many updates in the future ([Wainstein, 2018](https://www.altexsoft.com/blog/5-best-practices-for-managing-open-source-components/)).

The process often includes creating a distinct OSS developer community (OSS-DC) for the forked version, allowing the organisation to focus on modifying or enhancing specific components of the software—usually those deemed critical for their purposes ([Méndez-Tapia et al., 2021](https://www.scitepress.org/Papers/2021/104970/104970.pdf)).

Forking does get mentioned in varying mediums as a best practice. However, the added responsibility of integrating updates from the upstream version of the component is often overlooked, and from our interviews, we found that forking is not widely used in practice.


## Conclusion

In this blog post, we explored best practices for managing the security risks associated with open-source software. We reviewed the literature, conducted interviews with industry experts, and analysed case studies to identify key strategies for securing OSS components.

Our research highlights the importance of regular vulnerability assessments, tooling, continuous monitoring, binary repositories, risk management and mitigation, static application security testing, and forking as essential practices for managing the security risks associated with OSS.

By adopting these best practices, organisations can reduce the likelihood of security breaches, data loss, and financial losses associated with OSS vulnerabilities. We recommend that organisations implement these practices to enhance the security of their software systems and protect their data and assets.


Open-source software (OSS) is a critical component of modern software development. However, it also introduces security risks. This blog post explores best practices for managing the security risks associated with OSS.

Best Practices for Managing the Security Risks Associated with Open-Source Software in 2024

Crafting a bulletproof specification document is the bridge between your brilliant idea and the developers who can make it sing.

Starting your Music Tech Project: Creating a Developer-Friendly Specification Document

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!

An in-depth guide on how you can optimise the performance of your Next.js website.

How to optimise a Next.js site in 2023

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: false,
    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: false,
    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 {BlogLayout} from "../../components";

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

export const meta = {
    timestamp: new Date('2023-01-10T16:11:00Z'),
    title: "Web app vs mobile app: Which should I use?",
    authorName: "Reece Charsville",
    summary: "What to consider when deciding between a web app or a mobile app for your project.",
    tags: ['Mobile', 'Web'],
    thumbnailUrl: '/blog/web-app-vs-mobile-app.webp',
    featured: true,
    readTime: '15 min read',
    slug: 'web-app-vs-mobile-app'
}

When working with a client some frequent questions we get asked are “should I use a web app or a mobile app?” and “should it be a native app or a hybrid app”? There isn't a one-size-fits-all answer. The answer depends on a few factors specific to your project and its requirements. I will outline some of the key differences between the two, the benefits of each and the cost implications.

## Push Notifications

A push notification is a message that is sent to a user's mobile device by a mobile application that the user has installed. These notifications can be used to alert users to new content or updates within the app, such as a new message, breaking news, or a sale. Push notifications are often delivered in real-time and can be customized to include things like images, sounds, or vibrations to grab the user's attention. However, push notifications are not available on web applications.

One of the main benefits of push notifications is that they can be used to re-engage users with an app. When users receive a push notification, they are more likely to open the app and interact with the content or feature that the notification is promoting. This can be particularly useful for businesses, as it can lead to increased sales or engagement. Additionally, push notifications can also help to keep users informed of important updates or news, without the need for them to open the app or check for updates manually. Furthermore, they increase retention and can help to improve brand loyalty.

The catch to this is that push notifications must be used carefully. If a user is frequently receiving notifications that are not relevant then they may start to find them annoying and this could lead to the user uninstalling your app entirely.

Push notifications are often not a requirement for your application but can be a great addition to help improve user experience. Although they are not available on web applications, there are alternative solutions that often suffice. For example email alerts.

## Offline Capability

A key benefit of a mobile app is its offline capabilities. When working with a web app you can only access it when you have an internet connection. This can be a particular problem if a user is trying to use your app when they are in an area with bad service or is using a device that relies on WiFi and does not have internet access.

Mobile applications are installed onto the device. This means that they can still run and perform certain actions without connecting to the internet. If your app is able to still function without an internet connection then this can be a very powerful tool. It is also possible to queue requests. This means that even if your mobile app does require an internet connection, requests can be queued and sent off when the device regains internet access.

However, there are some caveats to this. Mobile app development is not straightforward and so integrating a queue system into your mobile app is going to take an app developer some time. This can therefore have some implications on the total cost.

Is it a big deal? More often than not whether its a web app or a mobile app they require an internet connection to store data, so it is not uncommon to see applications not working without it. Not only that, but internet access is becoming much more widespread anyway. Sometimes a simple indication to the user that they are offline is enough.

Personally, I would say offline capability is only a real benefit if your app can perform its duties without internet access. The exception to this would be that you have the budget to implement some more advanced functionality to handle an offline mode. If you don't need an offline mode then this should not sway you to a mobile app instead of a web app.

## Device Capabilities

Mobile apps are developed to run on specific platforms, such as iOS or Android, and have access to the device's hardware, software and capabilities like the camera, GPS, sensors, microphone, and more. This allows them to provide a more engaging experience to users. For example, a mobile camera app can directly access the device's camera and take photos, a navigation app can access the GPS to provide turn-by-turn directions, and a fitness app can access the device's accelerometer to track movement and activity.

Web applications, on the other hand, are limited to the features and capabilities provided by the browser. For example, a web application that is designed to take photos would need to use the device's camera through the browser's built-in features, which would not provide the same level of control and functionality as a mobile app. Similarly, a web application can access the device's location through the browser by using the Geolocation API, but the level of accuracy, granularity and details available is not comparable with a mobile app.

Access to device capabilities is important when you are trying to decide between a mobile app and a web application. For some apps, access to the mobile device functionality is integral to the functionality and therefore it makes sense for it to be a mobile app. For others, the device functionality can be used to improve the user experience or add to the overall seamlessness of the app, but it is not required or always worth the extra cost and app development time.

## User Experience

The user experience (UX) of a mobile app and a web app can be quite different, due to the way they are designed and the platforms on which they run.

Mobile apps are specifically designed for smaller screens and touch-based interfaces. They are typically optimized for use on a single device, such as a smartphone or tablet. This allows for a more seamless and intuitive experience, as the design and layout of the app can be tailored to the specific device and its capabilities. Mobile applications also tend to be faster, smoother, and more responsive than web apps, as they are developed to take advantage of the device's hardware.

Web apps, on the other hand, are designed to be accessed on a wide variety of devices and screen sizes. They are typically optimized for use with a mouse and keyboard, and the layout and design must be able to adapt to different screen sizes and resolutions. They can also bean less performant as they rely on the internet connection, and the experience may vary depending on the quality of the connection.

In terms of software development, a mobile app can be much more difficult, especially if building a native app. It requires in-depth knowledge of the differences between Android and iOS and how to handle that. Hybrid applications can help solve some of these issues but there is still a lot that needs to be done as part of the mobile app testing phase to ensure you create the best UX for your cross platform app. Web app development is much easier as it relies on more widely used web technologies like HTML, CSS and Javascript. There are also a lot of resources and libraries out there to aid with UX design and development, making it much easier for a web developer. This can mean a better user experience can be developed in a shorter amount of time.

## Play Store/Apple App Store

Mobile apps are typically distributed through app stores, such as the Apple App Store or Google Play Store. These app stores give developers a way to reach a large audience of potential users. When an app is made available on an app store, it can be easily discovered by users through search and browsing. Additionally, the app store's ranking and curation system can be leveraged to promote popular or well-reviewed apps, which can give them greater visibility.

App stores can also provide other features that improve discoverability, such as recommendations, featured apps and charts that show the top apps based on downloads or user ratings. This can make it easier for users to discover and download new apps, even if they are not actively looking for them. Additionally, App stores also provide reviews, ratings and app descriptions to help users decide if the app is worth downloading or not.

However the stores are very crowded places, so it is still a very competitive market when trying to appear higher up in the stores. It is also a lot more work that you need to consider, there are things like creating assets for store pages, writing store page listings, curating required policy documents for each app store and ensuring your app can make it through Apple's strict review system. These additional things take more time and therefore cost more money.

Web applications need to be accessed via a web browser and require the user to know the URL of the application. Unlike mobile apps, web apps don't have a centralized distribution point, which means they aren't discoverable through a single platform or marketplace. Users have to find the web application by searching the web, or through promotions, advertising or word of mouth. This can make it more challenging for web applications to reach a large audience and acquire new users. This is where SEO comes into play. There is an entire industry built around getting websites and web apps higher up in search and making them more discoverable. Meaning there are a lot of options out there for aiding in discoverability, whether it's online tools or SEO professionals. In some cases, you may find that good SEO is more powerful than just being on the app stores, and you don't have to worry about all of the extra work involved in getting your mobile app on the app store.

Another benefit of using a web app is that it is a much easier process to push out updates. Mobile apps require you to generate new builds for both your android app and your ios app, which must then be uploaded to the stores. You then need to create the new release on the stores and submit them for review before they can be pushed out to users. Once they pass review it is not going to be instantaneous that every user is on the latest version, as it is down to the user when they install the updates. On the other hand, when you want to update your web app it is just a case of pushing the update to your hosting service. Once the update is deployed anyone who accesses your web app will be on the latest version.

## Cost

In the previous sections, we have touched on a few of the factors that can cause mobile applications to be a little more expensive than web applications. It is not always the case but I will reiterate and outline the differences.

The first thing to consider is complexity. Does your app require the use of device hardware? If it is a necessity then you may find that it is more cost-effective to build a mobile application. This is because it is easier for a mobile application to access device hardware (e.g camera or GPS). But, generally speaking, mobile app development is harder than web app development, so if you do not require access to specific mobile device functionality then it will most likely be cheaper to develop a web app. This does not just apply to the initial development phase either, software needs to be maintained and due to mobile app development being more complex, it can mean maintenance costs are also higher.

Hosting costs are another big thing to consider. When you build a mobile app you have the additional costs incurred by the Apple App Store and Google Play Store. This can mean more time is spent pushing updates, curating store assets and making updates to get your app through app store reviews. Whereas a web app is hosted with a provider of your choice. There are countless hosting providers out there so it is a competitive market. This makes it easier to get better deals on hosting. That's not to say web apps are always cheaper to host, as some web apps can become expensive if you are handling very high volumes of traffic, but it is easy to keep track of your traffic with tools like google analytics and google workspace.

If you do decide to go down the mobile platform route, then you must also decide whether you would like to have a native mobile app or a hybrid mobile app. In this case, a hybrid mobile app is significantly more cost-effective. A native application requires you to essentially build two apps, each with its own challenges and knowledge requirements.

## Summary

To summarise, it is a question that should be researched and considered extensively before you start development. It also requires you to have a good idea of what the requirements are for your app. If you are not sure what your requirements are or if you need a mobile app or a web app, then get in touch with us. At Forward Digital we like to help with the requirements-gathering process and can provide a quote for both a mobile app and a web app, so you can easily compare the costs and differences.


What to consider when deciding between a web app or a mobile app for your project.

Web app vs mobile app: Which should I use?

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