Forem: Damien Chazoule

Oxlint x Prettier: The Modern Approach To Starting Your JavaScript Project

Damien Chazoule — Wed, 03 Dec 2025 17:34:12 +0000

The JavaScript ecosystem evolves rapidly, and with it, development tools. While ESLint has long dominated the linting landscape, a revolutionary new alternative is emerging: The JavaScript Oxidation Compiler, better known by the acronym "OXC" (or "Oxlint").

It's very easy to initialize a new JavaScript project; all you need is a code editor, a runtime environment, a terminal, and you're good to go!

Similarly, it's just as easy to ruin a Web project by making the code unreadable, unmaintainable, and thus generating technical debt...

Indeed, since JavaScript is a weakly typed language* (*types are determined late at runtime), anything goes:

Omitting semicolons at the end of lines;
Using single and double quotes in the same code block;
Declaring variables without using them;
Lines of code that are too long...

This flexibility of the language is both a strength and a weakness, which must be addressed by defining best practices before starting development. Thus, properly structured code will promote collaborative work and project scalability.

To achieve this, two essential tools will bring rigor to your Web project: the linter and the formatter.

Definitions:

Linter: Code analysis tool that detects syntax problems.

Formatter: Tool that formats code to make it readable.

NB: I emphasize that these are two distinct tools. While the linter can format certain parts of the code, this is not its role. This task is reserved for the formatter.

The JavaScript Oxidation Compiler ⚓

OXC is part of the VoidZero ecosystem, founded by Evan You (creator of VueJS) in September 2024. The VoidZero team is methodically rebuilding the JavaScript toolchain from the ground up, focusing on performance, compatibility, and developer experience.

OXC is 50 to 100 times faster than ESLint depending on the number of rules and CPU cores used. It finishes in less than a second for most codebases with a few hundred files, and finishes in a few seconds for larger projects.

OXC is a linter powered by Rust for JavaScript and TypeScript designed to be fast and simple to adopt. Since its first announcement in December 2023, the project has undergone significant improvements and now delivers its first stable version.

Starting Your JavaScript Project

To illustrate how each tool works, I propose creating a new JavaScript project (without framework) using ViteJS.

npm create vite@latest my-awesome-project -- --template vanilla-ts

Like a cooking recipe, let's install the initial dependencies provided with ViteJS, then add the new libraries: Oxlint and Oxfmt!

npm install --save-dev oxlint oxfmt

Once the linter and formatter dependencies are properly installed, you still need to create their respective configuration files: .oxlintrc.json and .oxfmtrc.json (.jsonc format is also supported).

Linter Configuration

Let's start by configuring the linter to use it in our new project.

Here's an initial version of the .oxlintrc.json file:

{
  "env": {
    "browser": true,
    "node": true
  },
  "ignorePatterns": ["dist/**", "node_modules/**", "*.config.js"],
  "rules": {
    "no-console": "warn",
    "no-unused-vars": [
      "warn",
      {
        "argsIgnorePattern": "^_",
        "varsIgnorePattern": "^_"
      }
    ]
  }
}

This first configuration is sufficient to run Oxlint (a.k.a "OXC") from a new terminal to check the syntax of JavaScript files: npx oxlint [file|dir]

I recommend adding this execution as a script in your package.json: npm run lint

{
  "name": "my-awesome-project",
  "private": true,
  "version": "0.0.0",
  "type": "module",
  "scripts": {
    "dev": "vite",
    "build": "vite build",
    "preview": "vite preview",
    "lint": "oxlint src"
  },
  "devDependencies": {
    "oxfmt": "^0.16.0",
    "oxlint": "^1.31.0",
    "vite": "^7.2.5"
  }
}

By adding a console.log() statement to a .ts file in your project, you should get the following result after invoking the linter.

  ⚠ eslint(no-console): Unexpected console statement.
   ╭─[src/counter.ts:5:5]
 4 │     counter = count;
 5 │     console.log(`count is ${counter}`);
   ·     ───────────
 6 │     element.innerHTML = `count is ${counter}`;
   ╰────
  help: Delete this console statement.

Found 1 warning and 0 errors.

NB: OXC has a default rule configuration. Some come from ESLint, others for managing TypeScript, and still others are exclusive to OXC. To learn more: npx oxlint --rules.

Prettier Configuration

Now, let's configure the formatter by editing the .oxfmtrc.json file:

{
  "arrowParens": "avoid",
  "bracketSameLine": true,
  "printWidth": 120,
  "singleAttributePerLine": true,
  "singleQuote": true,
  "trailingComma": "none"
}

NB: Oxfmt supports Prettier's default configuration, so you can easily switch between them. In the file above, I only redefine the parameters I want for my project.

Just like "Oxlint", you now just need to run "Oxfmt" (npx oxfmt [file|dir]) to format JavaScript/TypeScript files.

It's better to save a new script in your package.json: npm run format

{
  "name": "my-awesome-project",
  "private": true,
  "version": "0.0.0",
  "type": "module",
  "scripts": {
    "dev": "vite",
    "build": "vite build",
    "preview": "vite preview",
    "lint": "oxlint src",
    "format": "oxfmt src"
  },
  "devDependencies": {
    "oxfmt": "^0.16.0",
    "oxlint": "^1.31.0",
    "vite": "^7.2.5"
  }
}

Oxlint x Prettier: The Modern Approach

Unlike ESLint which requires complex plugins to integrate Prettier, OXC adopts a simpler and more modern approach. The linter designed to detect erroneous or unnecessary code without requiring default configurations.

The idea is to let OXC focus on what it does best: ultra-fast static code analysis, while Prettier exclusively handles formatting. It can be interesting to run both tools in parallel for complete verification.

Let's add a script that combines both tools:

{
  "scripts": {
    "dev": "vite",
    "build": "vite build",
    "preview": "vite preview",
    "lint": "oxlint src",
    "lint:format": "oxlint src && oxfmt --check src",
    "format": "oxfmt src"
  }
}

No more need to manage conflicts between ESLint and Prettier rules. Each tool has its well-defined responsibility.

NB: If you want to keep Prettier, since version 3.6, it's possible to go further with this new approach by using the official @prettier/plugin-oxc plugin. This plugin allows Prettier to directly use OXC's Rust parser, thus improving its execution speed.

Conclusion

The "Oxlint" + "Oxfmt" combination represents the natural evolution of JavaScript/TypeScript code quality tools. By clearly separating responsibilities and focusing on performance, this approach offers a superior developer experience while maintaining the rigor necessary for a professional project.

To go further, I invite you to install the OXC extension (and enable the experimental features: oxc.fmt.experimental). This way, you'll benefit from additional features such as syntax highlighting when linting rules are not respected, or automatic code formatting when saving the file.

Enjoy 👍

How To Build An API With Node, Without Additional Framework (SQL Included)

Damien Chazoule — Fri, 25 Jul 2025 06:41:21 +0000

This is not just a post... That's a how-to guide!

Introduction

Every technical project has its file structure. Whether it's a traditional MVC structure, organization by components or pages, by features, or even hexagonal architecture ("Ports/Adapters" for the insiders 😉), many possibilities are conceivable before even starting to code.

"We structure our project like the previous one. Copy/Paste: it works!"

Often considered secondary to the benefit of an application that executes quickly (and without error), the chosen architecture nevertheless has a crucial place in the project, to ensure the sustainability of current and future developments...

Like project management strategies that have evolved over time (I'm thinking particularly of Agility and its principles), project organizations have become democratized. The classic MVC evolved to MV-VM (Model-View/View-Model) to give way to MVW ("W" for "Whatever")... Although, for the past few years, we've been hearing mostly about "Clean" architectures, particularly with the "Ports/Adapters" and "Onion" models (organization by concentric layers).

Much more than a simple "arrangement" of components, classes, functions or modules, in the associated folder, it's about making the business part of your application independent of technical concepts (the data access layer, HTTP configuration, application routing, etc.).

NB: I really advise you to ask yourself the architecture question, if only to have a horizon on the file structure to use during your developments, in order to avoid a major refactoring of your project at 90% completion 😅

It's thanks to development strategies such as TDD (Test Driven Development), DDD (Domain Driven Development) or BDD (Behavior Driven Development) that SOLID principles emerged. Indeed, these methods highlighted the limitations of traditional approaches and favored the adoption of principles such as SOLID, which are now the foundation of modern architectures.

If I mention all this in the preamble, it's to justify the technical orientation of my project. In the rest of ~~this post~~ this guide, we're going to talk about how to "build an API with Node, without additional frameworks", but in a SOLID way (and also with some OOP principles).

NB: Although I try to apply SOLID principles as best as possible, I sometimes find myself thinking too long about achieving these goals: single responsibility of components, reusability of properties, inversion of control (and dependency injection), etc... In these cases, I remind myself that "perfect is the enemy of good", then... I commit! Maybe I'll come back to my development later (or maybe not).

Hello World 👋

Let's get to the heart of the matter, namely, how to expose a REST API for user management from Node, without additional libraries.

I emphasize this aspect because it's rather simple to create a Backend application with Express or Fastify. Moreover, these libraries are quite efficient for manipulating HTTP requests and responses, often by simplifying JSON serialization, HTTP status management, or REST routing.

Below, we'll discover (or rediscover) that it's possible to do this solely from the node:http module.

import { createServer, IncomingMessage, Server, ServerResponse } from 'node:http';

type ApplicationRequest = IncomingMessage;
type ApplicationResponse = ServerResponse<IncomingMessage> & {
  req: IncomingMessage;
};

interface ApplicationRouter {
  listener: (request: ApplicationRequest, response: ApplicationResponse) => Promise<void>;
}

class HttpProvider {
  constructor(private server: Server) {}

  static handleListeners = (...routers: ApplicationRouter[]) => {
    return async (request: ApplicationRequest, response: ApplicationResponse) => {
      for (const router of routers) {
        await router.listener(request, response);
      }

      try {
        response.setHeader('Content-Type', 'application/json');
        response.statusCode = 400;
        response.end(JSON.stringify({ message: "Cannot Get '/'" }));
      } catch {
        console.log('Ignored Default Behavior');
      }
    };
  };

  start(port: number) {
    this.server.listen(port, () => {
      console.log(`Server Is Running On Port ${port}`);
    });
  }

  stop() {
    this.server.close(() => {
      console.log('Server Is Shutting Down...');
    });
  }
}

const requestHandler = HttpProvider.handleListeners();

const server = createServer(requestHandler);
const app = new HttpProvider(server);

app.start(8080);

Here's a first version of the class responsible for starting the application. Its scope is limited to managing the service (start() / stop()) as well as listening to future incoming requests provided by the routing classes. Moreover, with the handleListeners() function, I anticipate the upcoming routing, particularly for the implementation of the user management CRUD.

Centralizing the Routers from this function allows chaining several route handlers in a modular way, while keeping the response logic in a single entry point. By default, the function will terminate its execution with a response having a status code equivalent to Bad Request, and the following message: Cannot Get "/". This mechanism is reminiscent of the behavior of a "dispatcher" middleware, where each route handler is executed in turn until a response is sent.

import { ApplicationRequest } from '../providers/ApplicationRequest';
import { ApplicationResponse } from '../providers/ApplicationResponse';
import { ApplicationRouter } from '../routers/ApplicationRouter';

class HelloController {
  greeting(_request: ApplicationRequest, response: ApplicationResponse) {
    response.setHeader('Content-Type', 'application/json');
    response.statusCode = 200;
    response.end(JSON.stringify({ message: 'Hi!' }));
    return;
  }
}

class HelloRouter implements ApplicationRouter {
  static PATHNAME = '/api/hello';

  constructor(private helloController: HelloController) {}

  async listener(request: ApplicationRequest, response: ApplicationResponse) {
    const baseUrl = `http://${request.headers.host}`;
    const url = new URL(request.url, baseUrl);

    const strictPathName = new RegExp(`^${HelloRouter.PATHNAME}$`);

    if (request.method === 'GET' && strictPathName.test(url.pathname)) {
      return this.helloController.greeting(request, response);
    }
  }
}

Above, two new classes complement the application initialization. These are respectively a controller as well as the routing associated with the /api/hello endpoint. HelloRouter encapsulates HelloController (by dependency injection), then calls the controller's greeting method upon receiving a GET request.

import { createServer } from 'node:http';

import HelloController from './infrastructure/controllers/HelloController';
import HttpProvider from './infrastructure/providers/HttpProvider';
import HelloRouter from './infrastructure/routes/HelloRouter';

const helloController = new HelloController();
const helloRouter = new HelloRouter(helloController);

const requestHandler = HttpProvider.handleListeners(helloRouter);

const server = createServer(requestHandler);
const app = new HttpProvider(server);

app.start(8080);

By instantiating the controller and defining the routing, we can provide a context to the requestHandler function which will then be processed by the server. Thus, upon receiving an HTTP request, the Node server will check the request information (the path and the REST method invoked) before landing in the default use case.

This design allows me to divide finely by functionality, rather than having global routing with multiple responsibilities...

Before finishing with this first step, let's set up a "Clean" architecture (according to the model popularized by Robert C. Martin) by structuring our application as above. This way, classes are separated from each other in the manner of one file === one responsibility.

src/
├── core/
├── infrastructure/
│   ├── controllers/
│   │   └── HelloController.ts
│   ├── providers/
│   │   ├── ApplicationRequest.ts
│   │   ├── ApplicationResponse.ts
│   │   └── HttpProvider.ts
│   └── routes/
│       ├── ApplicationRouter.ts
│       └── HelloRouter.ts
└── index.ts

In this exercise, the "IoC" container is represented by the src/index.ts file. As the application's entry point, it's responsible for instantiating the different components and applying inversion of control.

The Core 🎯

This is where everything really begins / where your application comes to life!

The Core groups together the classes and algorithms related to business logic. Generally, whether you've opted for hexagonal architecture, or concentric layers, or simply derived from the other two models, you'll find:

Domain business entities (or POJO - Plain Old JavaScript Object, for Java nostalgics);
Services associated with these classes (i.e., the algorithms for creation, data retrieval, or updating);
Interfaces that define how external services (data sources, controllers, etc.) should behave so that the Core can interact with them (without explicitly knowing them).

In this second part, we get to the serious stuff by initializing the first elements of the user management CRUD:

The User business class;
~~The service~~ The use cases** for user creation and retrieval;
The interfaces for inversion of control.

** About use cases...

Some implementations (like hexagonal architecture) centralize all the business logic of a domain in a single service. You'll find the creation, reading, updating, and deletion methods in the same file, exposed by an interface.

Other architectures opt for a finer separation: one file per use case, having a single method (execute() or invoke()). This breakdown is more verbose, but often simpler to test, maintain, and evolve.

class User {
  readonly id: string;
  readonly firstName: string;
  readonly lastName: string;
  readonly email: string;

  constructor(id: string, firstName: string, lastName: string, email: string) {
    this.id = id;
    this.firstName = firstName;
    this.lastName = lastName;
    this.email = email;
  }

  toString(): string {
    return JSON.stringify(this);
  }
}

export default User;

We start with the domain entity. Here, we model a simple business object representing a user, with 4 essential fields and a constructor dedicated to their initialization. The use of the readonly keyword (specific to TypeScript) ensures the immutability of these properties once the instance is created, thus strengthening the object's integrity.

NB: In the absence of business logic in the accessors, we voluntarily choose to do without Getters/Setters to lighten the code and focus on its readability.

import { NewUser } from '../interfaces/NewUser';
import { UserRepository } from '../interfaces/UserRepository';

export class CreateUser {
  constructor(private userRepository: UserRepository) {}

  async execute(newUser: NewUser): Promise<User> {
    const id = Math.random().toString(32).substring(2, 10);

    try {
      const user = new User(id, newUser.firstName, newUser.lastName, newUser.email);
      const createdUser = await this.userRepository.create(user);
      return createdUser;
    } catch (err) {
      throw new Error('Internal Server Error');
    }
  }
}

export class GetAllUsers {
  constructor(private userRepository: UserRepository) {}

  async execute(): Promise<User[]> {
    return this.userRepository.findAll();
  }
}

export class GetOneUser {
  constructor(private userRepository: UserRepository) {}

  async execute(id: string): Promise<User> {
    const user = await this.userRepository.findById(id);
    if (user === null) {
      throw new Error('User Not Found');
    }
    return user;
  }
}

Above, you'll find the use cases (not to mention functional services) for creating and retrieving one or more users.

NB: Here, for the post's benefits, this is a single code portion; but for optimal organization, it would be preferable to have one exported class per file (prefer export default rather than export).

You'll have noticed that use cases don't act directly on data, and that's normal since that's the objective of a "Clean" model. Instead, they know how the application service behaves (via its UserRepository interface) without ever having access to a concrete implementation. It's up to the "IoC" container (cf. src/index.ts) to inject dependencies, allowing the interconnection of technical infrastructures and the Core.

import User from '../domain/User';

// Input DTO
export interface NewUser {
  firstName: string;
  lastName: string;
  email: string;
}

export interface UserRepository {
  findAll: () => Promise<User[]>;
  findById: (id: string) => Promise<User | null>;
  create: (user: User) => Promise<User>;
  // TODO: update: (user: User) => Promise<User>;
  // TODO: delete: (id: string) => Promise<number>;
}

These first elements*** (namely the domain business entity, use cases, and interface) constitute a minimal base for implementing the Core, it remains to know how the infrastructure works...

*** About the Core content...

The Core can include more elements such as:

Business exceptions, to handle errors specific to the use case (UserNotFoundError, UserConflictError, etc.), rather than a generic technical error;
"Object-Values" for finer management of domain business entity fields, particularly regarding their respective validation.

NB: I invite you to consult the project sources on GitHub to learn more.

At the end of this second part, here's the structure after implementing the Core:

src/
├── core/
│   ├── domain/
│   │   └── User.ts
│   ├── interfaces/
│   │   ├── NewUser.ts
│   │   └── UserRepositoryPort.ts
│   └── use-cases/
│       ├── CreateUser.ts
│       ├── GetAllUsers.ts
│       └── GetOneUser.ts
├── infrastructure/
└── index.ts

Infrastructure ⚙️

Point of contact between business logic and the external world.

To be able to expose a user management API, we'll need a controller, the routing associated with the endpoints, as well as the implementation responsible for reading and writing data.

Let's take things in order with the Router. I propose a class that implements the ApplicationRouter interface and has a single method (listener) taking the HTTP request and response as parameters. This same function will then be called by the previous HttpProvider.

import UserController from '../controllers/UserController';
import { ApplicationRequest } from '../providers/ApplicationRequest';
import { ApplicationResponse } from '../providers/ApplicationResponse';
import { ApplicationRouter } from './ApplicationRouter';

class UserRouter implements ApplicationRouter {
  static PATHNAME = '/api/users';

  constructor(private userController: UserController) {}

  async listener(request: ApplicationRequest, response: ApplicationResponse) {
    const baseUrl = `http://${request.headers.host}`;
    const url = new URL(request.url as string, baseUrl);

    const strictPathName = new RegExp(`^${UserRouter.PATHNAME}$`);
    const pathNameWithId = new RegExp(`^${UserRouter.PATHNAME}/[^/]+$`);

    if (request.method === 'GET') {
      if (strictPathName.test(url.pathname)) {
        return this.userController.getAll(request, response);
      }

      if (pathNameWithId.test(url.pathname)) {
        return this.userController.getOne(request, response);
      }
    }

    if (request.method === 'POST' && strictPathName.test(url.pathname)) {
      return this.userController.createOne(request, response);
    }
  }
}

export default UserRouter;

The Router acts as a "dispatcher": it isolates the routing logic by mapping endpoints to controller methods, without handling business logic.

From this component, we can see that the application will expose the /api/users endpoint both in GET and POST. Depending on the path (presence or absence of the identifier in the URL) and the REST verb used, the application will execute the methods associated with the controller. The controller will then be responsible for writing the HTTP response.

In summary, here's the routing for user management:

/api/users in GET
/api/users/:id in GET
/api/users in POST

import { NewUser } from '../../core/interfaces/UserInput';
import CreateUser from '../../core/use-cases/CreateUser';
import GetAllUsers from '../../core/use-cases/GetAllUsers';
import GetOneUser from '../../core/use-cases/GetOneUser';
import { ApplicationRequest } from '../providers/ApplicationRequest';
import { ApplicationResponse } from '../providers/ApplicationResponse';
import UserRouter from '../routes/UserRouter';
import { bodyParser } from '../utils';

class UserController {
  constructor(
    private createUser: CreateUser,
    private getAllUsers: GetAllUsers,
    private getOneUser: GetOneUser
  ) {}

  async getAll(_request: ApplicationRequest, response: ApplicationResponse) {
    const users = await this.getAllUsers.execute();
    response.setHeader('Content-Type', 'application/json');
    response.statusCode = 200;
    response.end(JSON.stringify(users));
    return;
  }

  async getOne(request: ApplicationRequest, response: ApplicationResponse) {
    const baseUrl = `http://${request.headers.host}`;
    const url = new URL(request.url as string, baseUrl);

    const pathNameWithId = new RegExp(`^${UserRouter.PATHNAME}/([^/]+)$`);
    const matches = url.pathname.match(pathNameWithId);

    if (!matches) {
      response.setHeader('Content-Type', 'application/json');
      response.statusCode = 400;
      response.end(JSON.stringify({ message: `Cannot Get ${UserRouter.PATHNAME}` }));
      return;
    }

    const [_input, id] = matches;

    try {
      const user = await this.getOneUser.execute(id);

      response.setHeader('Content-Type', 'application/json');
      response.statusCode = 200;
      response.end(JSON.stringify(user));
      return;
    } catch (err) {
      response.setHeader('Content-Type', 'application/json');
      response.statusCode = 404;
      response.end(JSON.stringify({ message: err.message }));
      return;
    }
  }

  async createOne(request: ApplicationRequest, response: ApplicationResponse) {
    const body = await bodyParser<NewUser>(request);

    try {
      const user = await this.createUser.execute(body);

      response.setHeader('Content-Type', 'application/json');
      response.statusCode = 201;
      response.end(JSON.stringify(user));
      return;
    } catch (err) {
      response.setHeader('Content-Type', 'application/json');
      response.statusCode = 500;
      response.end(JSON.stringify({ message: err.message }));
      return;
    }
  }
}

export default UserController;

Let's now discuss the controller's role. The objective of UserController is to invoke the use case and describe the HTTP response. By injecting the CreateUser, GetUser, and GetAllUsers dependencies, the controller can retrieve data, then enrich the HTTP response body.

Since we're working with Node from scratch without additional frameworks, we'll need to format the data as character strings, and configure the HTTP response headers to interpret the returned value in JSON format.

NB: To retrieve the HTTP request body, I use a custom bodyParser function (available on GitHub) as well as an input DTO: NewUser.

import { createServer } from 'node:http';

import CreateUser from './core/use-cases/CreateUser';
import GetAllUsers from './core/use-cases/GetAllUsers';
import GetOneUser from './core/use-cases/GetOneUser';

import HelloController from './infrastructure/controllers/HelloController';
import HttpProvider from './infrastructure/providers/HttpProvider';
import HelloRouter from './infrastructure/routes/HelloRouter';

// TODO: const userRepository = new UserRepositoryAdapter();

const getAllUsersUseCase = new GetAllUsers(userRepository);
const getOneUserUseCase = new GetOneUser(userRepository);
const createUserUseCase = new CreateUser(userRepository);

const userController = new UserController(getAllUsersUseCase, getOneUserUseCase, createUserUseCase);
const userRouter = new UserRouter(userController);

const requestHandler = HttpProvider.handleListeners(userRouter);

const server = createServer(requestHandler);
const app = new HttpProvider(server);

app.start(8080);

The application is starting to take shape... But wouldn't the part responsible for data access be missing!? 🤔

Data Access Layer 📊

Let's talk data properly! Before discussing the possibility of persisting data in a database (directly from Node), here's a first implementation of UserRepository with data stored in memory.

import User from '../../core/domain/User';
import UserRepository from '../../core/interfaces/UserRepositoryPort';

class UserRepositoryAdapter implements UserRepository {
  private users: User[] = [];

  async findAll(): Promise<User[]> {
    return this.users;
  }

  async findById(id: string): Promise<User | null> {
    return this.users.find(user => user.id === id) ?? null;
  }

  async create(user: User): Promise<User> {
    this.users = [...this.users, user];
    return user;
  }

  // TODO: async update(user: User): Promise<User> {}
  // TODO: async delete(id: string): Promise<number> {}
}

export default UserRepositoryAdapter;

This is the last piece missing from the puzzle 🧩 By instantiating UserRepositoryAdapter from the project's entry point, we should have a first version of an operational user management CRUD (although limited) with in-memory access (and without additional frameworks).

NB: As a reminder, the controller calls a use case (CreateUser, GetAllUsers, or GetOneUser), which relies on the UserRepository interface, which is concretely implemented here by UserRepositoryAdapter.

TypeScript requires a compilation step before execution. Although Node "is starting" to offer native support for .ts, I opted here for ESBuild (an ultra-efficient bundler), to generate a JavaScript file executable simply with Node: esbuild src/index.ts --bundle --format=esm --outfile=dist/index.js --platform=node --target=node22.14 && node dist/index.js

SQLite From Scratch 🪶

Let's not settle for simple in-memory access, which is reset with each application restart... Let's persist our data with SQL.

Node version 22.5.0 introduces an API to communicate with an embedded SQL database (cf. SQLite). By introducing an abstraction to control the execution of SQL queries, we can manipulate user data with simplicity and security.

NB: Note that the API is subject to change, Node is quite explicit about this, with the following message when launching the application: ExperimentalWarning: SQLite is an experimental feature and might change at any time

import { DatabaseSync, SupportedValueType } from 'node:sqlite';

class SqlManager {
  private database;

  constructor(database: DatabaseSync) {
    this.database = database;
  }

  execute(sql: string) {
    this.database.exec(sql);
  }

  query<T>(sql: string) {
    const statement = this.database.prepare(sql);
    return (...params: SupportedValueType[]): T => statement.get(...params) as T;
  }

  queryAll<T>(sql: string) {
    const statement = this.database.prepare(sql);
    return (...params: SupportedValueType[]): Array<T> => statement.all(...params) as Array<T>;
  }

  mutate(sql: string) {
    const statement = this.database.prepare(sql);
    return (...params: SupportedValueType[]): { changes: bigint } => {
      const result = statement.run(...params);
      return { changes: result.changes };
    };
  }
}

export default SqlManager;

Here's the SQL abstraction I propose. Node's API for SQLite offers two ways to execute SQL queries:

Either via exec(), to simply execute a query in the database (for creating a table, for example);
Or via prepare(), to create a parameterized statement of a query (ideal for avoiding SQL injection) and execute it in a second step.

This second possibility is really interesting (and justifies my design ;). Whether it's query(), queryAll(), or mutate(), each of these functions remembers the SQL query (and its parameters) to then react in three distinct ways:

get() to execute the query and retrieve a value;
all() to execute the query and retrieve a list of values;
run() to retrieve information after executing the query (notably the number of impacted entities);

Each of these operations executes (with or without parameters) one and only one time. This means that to retrieve updated values (again), you'll need to mount a parameterized statement. Hence the interest of the SqlManager abstraction!

Now that we understand how SQLite works for Node, let's add a concrete implementation for persisting user data in the database:

import { DatabaseSync } from 'node:sqlite';
import SqlManager from '../providers/SqlManager';

export const CREATE_TABLE_USERS = `
  CREATE TABLE IF NOT EXISTS users (
    id VARCHAR(8) PRIMARY KEY,
    first_name VARCHAR(32) NOT NULL,
    last_name VARCHAR(32) NOT NULL,
    email VARCHAR(128) NOT NULL UNIQUE
  );
`;

export const CREATE_USER = `
  INSERT INTO users (id, first_name, last_name, email)
  VALUES (?, ?, ?, ?)
`;

export const SELECT_ALL_USERS = `
  SELECT * FROM users
`;

export const SELECT_USER = `
  SELECT * FROM users WHERE id = ?
`;

export interface UserEntity {
  id: string;
  first_name: string;
  last_name: string;
  email: string;
}

class UserManagement extends SqlManager {
  constructor(database: DatabaseSync) {
    super(database);
    this.createTable();
  }

  createTable() {
    this.execute(CREATE_TABLE_USERS);
  }

  createUser(id: string, firstName: string, lastName: string, email: string) {
    const statement = this.mutate(CREATE_USER);
    const { changes } = statement(id, firstName, lastName, email);
    console.log('createUser::changes', changes);
  }

  selectAllUsers() {
    const statement = this.queryAll<UserEntity>(SELECT_ALL_USERS);
    return statement();
  }

  selectUserById(id: string) {
    const statement = this.query<UserEntity>(SELECT_USER);
    return statement(id);
  }
}

export default UserManagement;

NB: Same remark as for use cases, you'll find here the implementation of the data persistence layer, as well as the constants representing the SQL queries; for better organization, it would be preferable to break down the code more finely...

Finally, let's modify the UserRepository class to point to the database data, rather than a strategy of storing data in memory:

import User from '../../core/domain/User';
import { UserRepository } from '../../core/interfaces/UserRepository';
import { UserEntity } from '../persistence/UserEntity';
import UserManagement from '../persistence/UserManagement';

const toUser = (entity: UserEntity): User =>
  new User(entity.id, entity['first_name'], entity['last_name'], entity.email);

class UserRepositoryAdapter implements UserRepository {
  constructor(private userPersistance: UserManagement) {}

  async findAll(): Promise<User[]> {
    const entities = this.userPersistance.selectAllUsers();
    return entities.map(toUser);
  }

  async findById(id: string): Promise<User | null> {
    const entity = this.userPersistance.selectUserById(id);
    if (!entity) return null;
    return toUser(entity);
  }

  async create(user: User): Promise<User> {
    this.userPersistance.createUser(user.getId(), user.getFirstName(), user.getLastName(), user.getEmail());
    return user;
  }

  // TODO: async update(user: User): Promise<User> {}
  // TODO: async delete(id: string): Promise<number> {}
}

export default UserRepositoryAdapter;

There we are! Let's finish the exercise by updating our entry point and launching the application.

import { createServer } from 'node:http';
import { DatabaseSync } from 'node:sqlite';

import CreateUser from './core/use-cases/CreateUser';
import GetAllUsers from './core/use-cases/GetAllUsers';
import GetOneUser from './core/use-cases/GetOneUser';

import UserRepositoryAdapter from './infrastructure/adapters/UserRepositoryAdapter';
import UserController from './infrastructure/controllers/UserController';
import UserManagement from './infrastructure/persistence/UserManagement';
import HttpProvider from './infrastructure/providers/HttpProvider';
import UserRouter from './infrastructure/routes/UserRouter';

const database = new DatabaseSync('./foobar.db'); // ':memory:'

const userManagement = new UserManagement(database);
const userRepository = new UserRepositoryAdapter(userManagement);

const getAllUsersUseCase = new GetAllUsers(userRepository);
const getOneUserUseCase = new GetOneUser(userRepository);
const createUserUseCase = new CreateUser(userRepository);

const userController = new UserController(getAllUsersUseCase, getOneUserUseCase, createUserUseCase);
const userRouter = new UserRouter(userController);

const requestHandler = HttpProvider.handleListeners(userRouter);

const server = createServer(requestHandler);
const app = new HttpProvider(server);

app.start(8080);

Conclusion

We've just laid the foundations of a modular and properly structured application, relying on the principles of "Clean" architecture. If you've followed all the steps in this guide, you should have a structure equivalent to this:

src/
├── core/
│   ├── domain/
│   │   └── User.ts
│   ├── interfaces/
│   │   ├── NewUser.ts
│   │   └── UserRepositoryPort.ts
│   └── use-cases/
│       ├── CreateUser.ts
│       ├── GetAllUsers.ts
│       └── GetOneUser.ts
├── infrastructure/
│   ├── adapters/
│   │   └── UserRepositoryAdapter.ts
│   ├── controllers/
│   │   └── UserController.ts
│   ├── persistence/
│   │   ├── UserEntity.ts
│   │   ├── UserManagement.ts
│   │   └── UserQueries.ts
│   ├── providers/
│   │   ├── ApplicationRequest.ts
│   │   ├── ApplicationResponse.ts
│   │   ├── HttpProvider.ts
│   │   └── SqlManager.ts
│   └── routes/
│       ├── ApplicationRouter.ts
│       └── UserRouter.ts
└── index.ts

We could push the "Clean" architecture ideology even further by opting for a more "strict" organization with three distinct parts (application / domain / infrastructure), but this structure already constitutes a robust foundation that conforms to SOLID principles and is efficient in terms of readability, testability, and scalability.

This breakdown allows you to adapt or replace a technical component without impacting the other layers. Moreover, the progressive addition of persistence via SQLite proves that it's possible to integrate a technology without ever disturbing the application's Core; this is the true strength of this architecture!

Beyond the architecture, it's particularly interesting to know how to handle HTTP interactions with Node without additional libraries. In an era where frameworks are often the answer to "Quick and Dirty" projects, returning to the essentials offers an objective perspective on how a Web server works, while maintaining complete control over the technical stack.

Finally, the Node platform continues to evolve. The native arrival of SQLite is a major advancement, opening the door to other possibilities in the medium term. When will MongoDB integration come? What about database unification through a standardized API!? What was previously reserved for alternative environments such as Deno is gradually becoming accessible from Node itself.

This Is Tuple Context Pattern

Damien Chazoule — Sat, 05 Apr 2025 07:31:04 +0000

Hello There 👋

I'm back with a brand new post for React and Preact developers, and especially anyone leveraging the Context API feature.

The approach I'm about to present is designed to make Context usage in a large-scale application more robust and easy-to-use. In this post, we assume that you're using just one Context as the single source of truth to handling business data, but this trick can be adapted to multiple Contexts as well.

Without any further delay, let me introduce you to my pattern, which I have modestly named "Tuple Context"", inspired by a practice I discovered while working with the Solid framework.

How To Context...

Let's go step by step, recalling how to create a Context with the React library ⚛

import { createContext, useContext, useState } from 'react';

const AppContext = createContext(null);

const initialUser = {
  firstName: '',
  lastName: '',
  email: '',
  roles: []
};

export default function AppProvider({ children }) {
  const [counter, setCounter] = useState(0);
  const incrementCounter = () => setCounter(value => value + 1);
  const decrementCounter = () => setCounter(value => value - 1);
  const resetCounter = () => setCounter(0);

  const [user, setUser] = useState(initialUser);
  const fullName = `${user.firstName} ${user.lastName}`;
  const setFirstName = firstName => setUser(u => ({ ...u, firstName }));
  const setLastName = lastName => setUser(u => ({ ...u, lastName }));
  const setEmail = email => setUser(u => ({ ...u, email }));
  const addRole = role => setUser(u => ({ ...u, roles: [...u.roles, role] }));
  const delRole = role => setUser(u => ({ ...u, roles: u.roles.filter(r => r !== role) }));
  const resetUser = () => setUser(initialUser);

  const ctxValues = {
    counter,
    setCounter,
    incrementCounter,
    decrementCounter,
    resetCounter,
    user,
    fullName,
    setUser,
    setFirstName,
    setLastName,
    setEmail,
    addRole,
    delRole,
    resetUser
  };

  return <AppContext.Provider value={ctxValues}>{children}</AppContext.Provider>;
}

export const useAppContext = () => useContext(AppContext);

Above, we declare a new Context (AppContext) that exposes two reactive variables (counter and user), a derived reactive variable (fullName), and functions to mutate the Context's state (such as setCounter or setUser).

We also assume that we are correctly using the declared <AppProvider /> component by wrapping the application, or at least the <Counter /> and <UserForm /> components (as shown in the example).

import { useAppContext } from './AppContext';

export default function Counter() {
  const { counter, incrementCounter, decrementCounter } = useAppContext();

  return (
    <div className="my-auto flex flex-col gap-y-2">
      <span>Counter Value : {counter}</span>

      <div className="mx-auto flex flex-row gap-x-4">
        <button
          type="button"
          onClick={incrementCounter}>
          +1
        </button>
        <button
          type="button"
          onClick={decrementCounter}>
          -1
        </button>
      </div>
    </div>
  );
}

Then, in practice, from the <Counter /> component, we fetch the values relating to the counter data (whether it's a reactive variable, or a state mutation function), to feed the render template, especially for the events of the "+1/-1" buttons.

NB : Here, useAppContext acts as a shortcut to inject Context values from inside the component, avoiding explicit imports of AppContext and useContext from this last one.

import { useAppContext } from './AppContext';

function UserForm({ handleSubmit }) {
  const { fullName, setFirstName, setLastName, resetUser } = useAppContext();

  return (
    <form
      className="my-auto flex flex-col gap-y-2"
      onSubmit={handleSubmit}>
      <span>FullName : {fullName}</span>

      <div className="flex flex-col gap-y-2">
        <label htmlFor="firstName">FirstName</label>
        <input
          id="firstName"
          type="text"
          onChange={e => setFirstName(e.target.value)}
        />
      </div>

      <div className="flex flex-col gap-y-2">
        <label htmlFor="lastName">LastName</label>
        <input
          id="lastName"
          type="text"
          onChange={e => setLastName(e.target.value)}
        />
      </div>

      <div className="mx-auto flex flex-row gap-x-4">
        <button
          type="button"
          onClick={resetUser}>
          Cancel
        </button>
        <button type="submit">Submit</button>
      </div>
    </form>
  );
}

In the same way as for the previous component (but starting from <UserForm />), we fetch values related to the user data without worrying about the organization of the Context.

Indeed, since it's just a JSON object, we can get the user and fullName variables, as well as the setFirstName, setLastName, setEmail, addRole, delRole or resetUser functions without any complexity.

Introducing: The Tuple Context Pattern

The weakness of this design lies in the value provided to the Context.Provider, or rather its structure... "It's just a JSON object"*! As a result, as your application evolves, it may host an increasing number of values (including 5 main reactive variables, 10 derived variables, and 2 dozens of mutation functions), all placed at the same level.

That's where the "Tuple Context" pattern comes into play!

export default function AppProvider({ children }) {
  const [counter, setCounter] = useState(0);
  const incrementCounter = () => setCounter(value => value + 1);
  const decrementCounter = () => setCounter(value => value - 1);
  const resetCounter = () => setCounter(0);

  const [user, setUser] = useState(initialUser);
  const fullName = useMemo(() => `${user.firstName} ${user.lastName}`, [user]);
  const setFirstName = firstName => setUser(u => ({ ...u, firstName }));
  const setLastName = lastName => setUser(u => ({ ...u, lastName }));
  const setEmail = email => setUser(u => ({ ...u, email }));
  const addRole = role => setUser(u => ({ ...u, roles: [...u.roles, role] }));
  const delRole = role => setUser(u => ({ ...u, roles: u.roles.filter(r => r !== role) }));
  const resetUser = () => setUser(initialUser);

  const ctxValues = {
    counter,
    user,
    fullName
  };

  const ctxDispatchers = {
    setCounter,
    incrementCounter,
    decrementCounter,
    resetCounter,
    setUser,
    setFirstName,
    setLastName,
    setEmail,
    addRole,
    delRole,
    resetUser
  };

  return <AppContext.Provider value={[ctxValues, ctxDispatchers]}>{children}</AppContext.Provider>;
}

As its name suggests, this approach structures the data exposed by the Context, like a fixed-size array (similar to useState).

So, the array is structured into two elements:

The 1st parameter exposes constants/reactive variables;
The 2nd parameter exposes functions that mutate the Context state;

export default function Counter() {
- const { counter, incrementCounter, decrementCounter } = useAppContext();
+ const [{ counter }, { incrementCounter, decrementCounter }] = useAppContext();

  return {/* ... */}
}

The idea is pretty simple, isn't it? Nothing revolutionary, just a little trick that makes sense 😉

In practice, the Tuple parameters can be used independently:

Either extract the left-hand operand exclusively, when you just need to access the Context values;
Or extract the right-hand operand (omitting the left one), when you need to update these values;

NB: In this second case, I recommend using the "underscore" convention to specify that it is an unused parameter, and to benefit from better readability: const [_, { setCounter, setUser }] = useAppContext()

export default function UserForm() {
- const { fullName, setFirstName, setLastName, resetUser } = useAppContext();
+ const [{ fullName }, { setFirstName, setLastName, resetUser }] = useAppContext();

  return {/* ... */}
}

In JavaScript, this requires some logic... On the other hand with TypeScript, it's a real pleasure!

TypeScript Forever 💙

At first glance, typing this kind of Context isn't straightforward (it's less intuitive than a simple JSON object)... However, it's essential to properly define the data types to make exposed values easier to use, as well as to make the import of reactive variables (or mutation functions - or both 🙃) inside components more robust.

import React, { createContext, type ReactNode, useContext, useMemo, useState } from 'react';

interface User {
  firstName: string;
  lastName: string;
  email: string;
  roles: [];
}

interface AppContextState {
  counter: number;
  user: User;
  fullName: string;
}

interface AppContextDispatchers {
  setCounter: React.Dispatch<React.SetStateAction<number>>;
  incrementCounter: () => void;
  decrementCounter: () => void;
  resetCounter: () => void;
  setUser: React.Dispatch<React.SetStateAction<User>>;
  setFirstName: (value: string) => void;
  setLastName: (value: string) => void;
  setEmail: (value: string) => void;
  addRole: (value: string) => void;
  delRole: (value: string) => void;
  resetUser: () => void;
}

const AppContext = createContext<[AppContextState, AppContextDispatchers] | null>(null);

const initialUser = {
  firstName: '',
  lastName: '',
  email: '',
  roles: []
};

interface AppProviderProps {
  children: ReactNode;
}

export default function AppProvider({ children }: AppProviderProps) {
  const [counter, setCounter] = useState(0);
  const incrementCounter = () => setCounter(value => value + 1);
  const decrementCounter = () => setCounter(value => value - 1);
  const resetCounter = () => setCounter(0);

  const [user, setUser] = useState(initialUser);
  const fullName = useMemo(() => `${user.firstName} ${user.lastName}`, [user]);
  const setFirstName = firstName => setUser(u => ({ ...u, firstName }));
  const setLastName = lastName => setUser(u => ({ ...u, lastName }));
  const setEmail = email => setUser(u => ({ ...u, email }));
  const addRole = role => setUser(u => ({ ...u, roles: [...u.roles, role] }));
  const delRole = role => setUser(u => ({ ...u, roles: u.roles.filter(r => r !== role) }));
  const resetUser = () => setUser(initialUser);

  const ctxValues = {
    counter,
    user,
    fullName
  };

  const ctxSetters = {
    setCounter,
    incrementCounter,
    decrementCounter,
    resetCounter,
    setUser,
    setFirstName,
    setLastName,
    setEmail,
    addRole,
    delRole,
    resetUser
  };

  return <AppContext.Provider value={[ctxValues, ctxSetters]}>{children}</AppContext.Provider>;
}

export const useAppContext = () => {
  const ctx = useContext(AppContext);
  if (!ctx) {
    throw new Error('useAppContext must be used within an AppProvider');
  }
  return ctx;
};

That's all, folks!

Let me know if you find this idea useful, or if you're already using this pattern in your applications. For the rest, it's up to you 😎👌

WTF Is Reactivity !?

Damien Chazoule — Wed, 18 Dec 2024 17:50:52 +0000

Reactivity Models Explained

Foreword

It’s been (already) 10 years since I started developing applications and websites, but the JavaScript ecosystem has never been more exciting than it is today!

In 2022, the community was captivated by the concept of "Signal" to the point where most JavaScript frameworks integrated them into their own engine. I’m thinking about Preact, which has offered reactive variables decoupled from the component lifecycle since September 2022; or more recently Angular, which implemented Signals experimentally in May 2023, then officially starting from version 18. Other JavaScript libraries have also chosen to rethink their approach...

Between 2023 and until now, I’ve consistently used Signals across various projects. Their simplicity of implementation and usage has fully convinced me, to the extent that I’ve shared their benefits with my professional network during technical workshops, training sessions, and conferences.

But more recently, I started asking myself if this concept was truly "revolutionary" / if there are alternatives to Signals? So, I delved deeper into this reflection and discovered different approaches to reactive systems.

This post is an overview of different reactivity models, along with my understanding of how they work.

NB: At this point, you’ve probably guessed it, I won’t be discussing about Java’s "Reactive Streams"; otherwise, I’d have titled this post "WTF Is Backpressure!?" 😉

Theory

When we talk about reactivity models, we're (first and foremost) talking about "reactive programming", but especially about "reactivity".

The reactive programming is a development paradigm that allows to automatically propagate the change of a data source to consumers.

So, we can define the reactivity as the ability to update dependencies in real time, depending on the change of data.

NB: In short, when a user fills and/or submits a form, we must react to these changes, display a loading component, or anything else that specifies that something is happening... Another example, when receiving data asynchronously, we must react by displaying all or part of this data, executing a new action, etc.

In this context, reactive libraries provide variables that automatically update and propagate efficiently, making it easier to write simple and optimized code.

To be efficient, these systems must re-compute/re-evaluate these variables if, and only if, their values have changed! In the same way, to ensure that the broadcasted data remains consistent and up-to-date, the system must avoid displaying any intermediate state (especially during the computation of state changes).

NB: The state refers to the data/values used throughout the lifetime of a program/application.

Alright, but then… What exactly are these "reactivity models"?

PUSH, a.k.a "Eager" Reactivity

The first reactivity model is called "PUSH" (or "eager" reactivity). This system is based on the following principles:

Initialization of data sources (as known as "Observables")
Components/Functions subscribe to these data sources (these are the consumers)
When a value changes, data is immediately propagated to the consumers (as known as "Observers")

As you might have guessed, the "PUSH" model relies on the "Observable/Observer" design pattern.

1st Use Case : Initial State and State Change

Let’s consider the following initial state,

let a = { firstName: "John", lastName: "Doe" };
const b = a.firstName;
const c = a.lastName;
const d = `${b} ${c}`;

Using a reactive library (such as RxJS), this initial state would look more like this:

let a = observable.of({ firstName: "John", lastName: "Doe" });
const b = a.pipe(map((a) => a.firstName));
const c = a.pipe(map((a) => a.lastName));
const d = merge(b, c).pipe(reduce((b, c) => `${b} ${c}`));

NB: For the sake of this post, all code snippets should be considered as "pseudo-code."

Now, let’s assume that a consumer (a component, for example) wants to log the value of state D whenever this data source is updated,

d.subscribe((value) => console.log(value));

Our component would subscribe to the data stream; it still needs to trigger a change,

a.next({ firstName: "Jane", lastName: "Doe" });

From there, the "PUSH" system detects the change and automatically broadcasts it to the consumers. Based on the initial state above, here’s a description of the operations that might occur:

State change occurs in data source A!
The value of A is propagated to B (computation of data source B);
Then, the value of B is propagated to D (computation of data source D);
The value of A is propagated to C (computation of data source C);
Finally, the value of C is propagated to D (re-computation of data source D);

One of the challenges of this system lies in the order of computation. Indeed, based on our use case, you’ll notice that D might be evaluated twice: a first time with the value of C in its previous state; and a second time with the value of C up to date! In this kind of reactivity model, this challenge is called the "Diamond Problem" ♦️.

2nd Use Case : Next Iteration

Now, let’s assume the state relies on two main data sources,

let a = observable.of({ firstName: "Jane", lastName: "Doe" });
let e = observable.of("");
const b = a.pipe(map((a) => a.firstName));
const c = merge(a, e).pipe(reduce((a, e) => `${e} ${a.lastName}`));
const d = merge(b, c).pipe(reduce((b, c) => `${b} ${c}`));

d.subscribe((value) => console.log(value));
e.next("Phoenix");

When updating E, the system will re-compute the entire state, which allows it to preserve a single source of truth by overwriting the previous state.

State change occurs in data source E!
The value of A is propagated to B (computation of data source B);
Then, the value of B is propagated to D (computation of data source D);
The value of A is propagated to C (computation of data source C);
The value of E is propagated to C (re-computation of data source C);.
Finally, the value of C is propagated to D (re-computation of data source D);

Once again, the "Diamond Problem" occurs... This time on the data source C which is potentially evaluated 2 times, and always on D.

Diamond Problem

The "Diamond Problem" isn't a new challenge in the "eager" reactivity model. Some computation algorithms (especially those used by MobX) can tag the "nodes of the reactive dependency tree" to level out state computation. With this approach, the system would first evaluate the "root" data sources (A and E in our example), then B and C, and finally D. Changing the order of state computations helps to fix this kind of problem.

PULL, a.k.a "Lazy" Reactivity

The second reactivity model is called "PULL". Unlike the "PUSH" model, it is based on the following principles:

Declaration of reactive variables
The system defers state computation
Derived state is computed based on its dependencies
The system avoids excessive updates

It’s this last rule that is most important to remember: unlike the previous system, this last one defers state computation to avoid multiple evaluations of the same data source.

1st Use Case : Initial State and State Change

Let's keep the previous initial state...

In this kind of system, the initial state syntax would be in the following form:

let [a, setA] = state({ firstName: "John", lastName: "Doe" });
const b = computed(() => a.firstName, [a]);
const c = computed(() => a.lastName, [a]);
const d = computed(() => `${b} ${c}`, [b, c]);

NB: React enthusiasts will likely recognize this syntax 😎

Declaring a reactive variable gives "birth" to a tuple: immutable variable on one side; update function of this variable on the other. The remaining statements (B, C and D in our case) are considered as derived states since they "listen" to their respective dependencies.

setA({ firstName: "Jane", lastName: "Doe" });

The defining characteristic of a "lazy" system is that it doesn't propagate changes immediately, but only when explicitly requested.

effect(() => console.log(d), [d]);

In a "PULL" model, using an effect() (from a component) to log the value of a reactive variable (specified as a dependency) triggers the computation of the state change:

D will check if its dependencies (B and C) have been updated;
B will check if its dependency (A) has been updated;
A will propagate its value to B (computing the value of B);
C will check if its dependency (A) has been updated;
A will propagate its value to C (computing the value of C)
B and C will propagate their respective value to D (computing the value of D);

An optimization of this system is possible when querying dependencies. Indeed, in the scenario above, A is queried twice to determine whether it has been updated. However, the first query could be enough to define if the state has changed. C wouldn't need to perform this action... Instead, A could only broadcast its value.

2nd Use Case : Next Iteration

Let's complicate the state somewhat by adding a second reactive variable "root",

let [a, setA] = state({ firstName: "Jane", lastName: "Doe" });
let [e, setE] = state("");
const b = computed(() => a.firstName, [a]);
const c = computed(() => `${e} ${a.lastName}`, [a, e]);
const d = computed(() => `${b} ${c}`, [b, c]);

effect(() => console.log(d), [d]);
setE("Phoenix");

One more time, the system defers state computation until it is explicitly requested. Using the same effect as before, updating a new reactive variable will trigger the following steps:

D will check if its dependencies (B and C) have been updated ;
B will check if its dependency (A) has been updated ;
C will check if its dependencies (A and E) have been updated ;
E will propagate its value to C, and C will fetch the value of A via memoization (computing the value of C) ;
C will propagate its value to D, and D will fetch the value of B via memoization (computing the value of D) ;

Since the value of A hasn't changed, recomputing this variable is unnecessary (same thing applies to the value of B). In such cases, the use of memoization algorithms enhances performance during state computation.

PUSH-PULL, a.k.a "Fine-Grained" Reactivity

The last reactivity model is the "PUSH-PULL" system. The term "PUSH" reflects the immediate propagation of change notifications, while "PULL" refers to fetching the state values on demand. This approach is closely related to what is called "fine-grained" reactivity, which adheres to the following principles:

Declaration of reactive variables (we're talking about reactive primitives)
Dependencies are tracked at an atomic level
Change propagation is highly targeted

Note that this kind of reactivity isn't exclusive to the "PUSH-PULL" model. Fine-grained reactivity refers to the precise tracking of system dependencies. So, there are PUSH and PULL reactivity models which also work in this way (I'm thinking about Jotai or Recoil.

1st Use Case : Initial State and State Change

Still based on the previous initial state... The declaration of an initial state in a "fine-grained" reactivity system would look like this:

let a = signal({ firstName: "John", lastName: "Doe" });
const b = computed(() => a.value.firstName);
const c = computed(() => a.value.lastName);
const d = computed(() => `${b.value} ${c.value}`);

NB: The use of the signal keyword isn't just anecdotal here 😉

In terms of syntax, it’s very similar to the "PUSH" model, but there is one notable and important difference: dependencies! In a "fine-grained" reactivity system, it’s not necessary to explicitly declare the dependencies required to compute a derived state, as these states implicitly track the variables they use. In our case, B and C will automatically track changes to the value of A, and D will track changes to both B and C.

a.value = { firstName: "Jane", lastName: "Doe" };

In such a system, updating a reactive variable is more efficient than in a basic "PUSH" model because the change is automatically propagated to the derived variables that depend on it (only as a notification, not the value itself).

effect(() => console.log(d.value));

Then, on demand (let's take the logger example), the use of D within the system will fetch the values of the associated root states (in our case A), compute the values of the derived states (B and C), and finally evaluate D. Isn't it an intuitive mode of operation?

2nd Use Case : Next Iteration

Let's consider the following state,

let a = signal({ firstName: "Jane", lastName: "Doe" });
let e = signal("");
const b = computed(() => a.value.firstName);
const c = computed(() => `${e.value} ${e.value.lastName}`);
const d = computed(() => `${b.value} ${c.value}`);

effect(() => console.log(d.value));
e.value = "Phoenix";

Once again, the "fine-grained" aspect of the PUSH-PULL system allows for automatic tracking of each state. So, the derived state C now tracks root states A and E. Updating the variable E will trigger the following actions:

State change of the reactive primitive E!
Targeted change notification (E to D via C);
E will propagate its value to C, and C will retrieve the value of A via memoization (computing the value of C);
C will propagate its value to D, and D will retrieve the value of B via memoization (computing the value of D);

This is that prior association of reactive dependencies with each other that makes this model so efficient!

Indeed, in a classic "PULL" system (such as React's Virtual DOM, for example), when updating a reactive state from a component, the framework will be notified of the change (triggering a "diffing" phase). Then, on demand (and deferred), the framework will compute the changes by traversing the reactive dependency tree; every time a variable is updated! This "discovery" of the state of dependencies has a significant cost...

With a "fine-grained" reactivity system (like Signals), the update of reactive variables/primitives automatically notifies any derived state linked to them of the change. Therefore, there’s no need to (re)discover the associated dependencies; the state propagation is targeted!

Conclusion(.value)

In 2024, most web frameworks have chosen to rethink how they work, particularly in terms of their reactivity model. This shift has made them generally more efficient and competitive. Others choose to be (still) hybrid (I'm thinking about Vue here), which makes them more flexible in many situations.

Finally, whatever the model chosen, in my opinion, a (good) reactive system is built upon a few main rules:

The system prevents inconsistent derived states;
The use of a state within the system results in a reactive derived state;
The system minimizes excessive work ;
And, "for a given initial state, no matter the path the state follows, the system's final result will always be the same!"

This last point, which can be interpreted as a fundamental principle of declarative programming, is how I see a (good) reactive system as needing to be deterministic! This is that "determinism" that makes a reactive model reliable, predictable, and easy to use in technical projects at scale, regardless of the complexity of the algorithm.

ESLint x Prettier: The Right Way To Start A JavaScript Project

Damien Chazoule — Sat, 29 Jun 2024 06:06:39 +0000

In 2022, ESLint (v8.21.0) introduced a new configuration system nicknamed "Flat Config." This post is dedicated to this edition.

It's very easy to initialize a new JavaScript project; you just need a code editor, a runtime environment, a terminal, and you're good to go!

Similarly, it's just as easy to ruin a web project by making the code unreadable, unmaintainable, and thus generating technical debt...

Indeed, since JavaScript is a very loosely typed language, anything is quickly allowed:

Omitting semicolons at the end of lines;
Using single and double quotes within the same block of code;
Declaring variables but not using them;
Lines of code that are too long...

This flexibility of the language is both a strength and a weakness, which should be addressed by defining best practices before development begins. Thus, properly structured code will promote collaborative work and the scalability of the project.

To achieve this, there are two essential tools that will bring rigor to your web project: the linter and the formatter.

Definitions

Linter: A code analysis tool that detects syntax issues.

Formatter: A tool that formats the code to make it readable.

NB: I insist on the fact that these are two distinct tools. Although the linter can format some parts of the code, it isn't its role. This task is reserved for the formatter.

Starting Your JavaScript Project

To illustrate how each tool works, I suggest creating a new JavaScript project (without a framework) using ViteJS.

npm create vite@latest my-awesome-project -- --template vanilla

Like a recipe, let's install the initial dependencies provided with ViteJS, and then add the new libraries: ESLint and Prettier!

npm install --save-dev eslint @eslint/js prettier eslint-config-prettier eslint-plugin-prettier

NB: For future reference, a project scaffolded with ViteJS operates directly in module mode. This means your .js files are implicitly .mjs files. Likewise, you will need to explicitly name your files .cjs to write with CommonJS syntax.

Once the linter and formatter dependencies are correctly installed, you still need to create their respective configuration files: eslint.config.js and prettier.config.js.

NB: ESLint and Prettier configuration files can take several forms, including the following: .eslintrc.js, .eslintrc.cjs, .eslintrc.json, .eslintrc.yaml, .prettierrc, .prettierrc.json, .prettierrc.yaml, .prettierrc.js, prettier.config.cjs, or .prettierrc.toml.

Linter Configuration

Let's start by setting up the linter to use it in our new project.

Here is an initial version of the eslint.config.js file:

import globals from 'globals';
import js from '@eslint/js';

export default [
  {
    files: ['**/*.js', '**/*.jsx']
  },
  {
    languageOptions: {
      globals: {
        ...globals.browser,
        ...globals.node
      }
    }
  },
  js.configs.recommended,
  {
    rules: {
      'no-console': 'warn'
    }
  }
];

This initial configuration is sufficient to run ESLint from a new terminal to check the syntax of JavaScript files: npx eslint [file|dir]

I recommend adding this execution as a script in your package.json: npm run lint

{
  "name": "my-awesome-project",
  "private": true,
  "version": "0.0.0",
  "type": "module",
  "scripts": {
    "dev": "vite",
    "build": "vite build",
    "preview": "vite preview",
    "lint": "eslint"
  },
  "devDependencies": {
    "@eslint/js": "^9.5.0",
    "eslint": "^9.5.0",
    "eslint-config-prettier": "^9.1.0",
    "eslint-plugin-prettier": "^5.1.0",
    "prettier": "^3.3.0",
    "vite": "^5.2.0"
  }
}

By adding a console.log() statement in a .js file of your project, you should get the following result after invoking the linter.

/home/dmnchzl/my-awesome-project/counter.js
  5:5  warning  Unexpected console statement  no-console

✖ 1 problem (0 errors, 1 warning)

Prettier Configuration

Now, let's set up the formatter by editing the prettier.config.js file:

export default {
  arrowParens: 'avoid',
  printWidth: 120,
  semi: true,
  singleQuote: true,
  trailingComma: 'none',
};

NB: Prettier has a default configuration. In the above file, I only override the parameters I want for my project.

Similar to ESLint, you now just need to run Prettier (npx prettier --write [file|dir]) to format the JavaScript files.

It's also possible to save a new script in your package.json: npm run format

{
  "name": "my-awesome-project",
  "private": true,
  "version": "0.0.0",
  "type": "module",
  "scripts": {
    "dev": "vite",
    "build": "vite build",
    "preview": "vite preview",
    "lint": "eslint",
    "format": "prettier --write \"**/*.{js,jsx}\""
  },
  "devDependencies": {
    "@eslint/js": "^9.5.0",
    "eslint": "^9.5.0",
    "eslint-config-prettier": "^9.1.0",
    "eslint-plugin-prettier": "^5.1.0",
    "prettier": "^3.3.0",
    "vite": "^5.2.0"
  }
}

ESLint x Prettier

The last step is to interface the two tools! This means controlling the formatter's syntax through the linter.

To do this, simply add Prettier's configuration to the ESLint rules (don't forget to enable the plugin):

import globals from 'globals';
import js from '@eslint/js';
import prettierRecommended from 'eslint-plugin-prettier/recommended';

export default [
  {
    files: ['**/*.js', '**/*.jsx']
  },
  {
    languageOptions: {
      globals: {
        ...globals.browser,
        ...globals.node
      }
    }
  },
  js.configs.recommended,
  prettierRecommended,
  {
    rules: {
      'no-console': 'warn',
      'prettier/prettier': [
        'warn',
        {
          arrowParens: 'avoid',
          printWidth: 120,
          semi: true,
          singleQuote: true,
          trailingComma: 'none'
        }
      ]
    }
  }
];

And there you go! From now on, ESLint will be able to alert you whenever the Prettier format is not respected.

Try removing one or more semicolons at the end of a line or misaligning your lines...

/home/dmnchzl/my-awesome-project/counter.js
  2:18  warning  Insert `;`                      prettier/prettier
  3:22  warning  Replace `(count)` with `count`  prettier/prettier
  4:20  warning  Insert `;`                      prettier/prettier
  5:46  warning  Insert `;`                      prettier/prettier
  6:4   warning  Insert `;`                      prettier/prettier
  7:67  warning  Insert `;`                      prettier/prettier
  8:16  warning  Insert `;`                      prettier/prettier

Now you know that the rigor of a web project does not come alone; it also relies on many tools, including the linter and the formatter.

To go further, I invite you to install the ESLint and Prettier extensions, depending on your favorite code editor (Visual Studio Code in my case). This way, you will benefit from additional features such as syntax highlighting when linting rules are not followed, or automatic code formatting upon file saving.

Enjoy 👍

Better Use pNPM

Damien Chazoule — Mon, 06 Nov 2023 07:03:42 +0000

pNPM is a (another one) package manager for Node.

Ok, Ok!! There's already NPM (or better Yarn), so why change!? Well, for performance reasons, obviously 😎👌 According to the metrics, pNPM is 2x faster than NPM 🚀

Explanation

Like its counterparts, pNPM takes security very seriously by ensuring the integrity of dependencies used by one (or more *) JavaScript project(s), through a "lock" file strategy (pnpm-lock.yaml).

* NB: Just as NPM (and Yarn before it), pNPM supports monolithic projects, or more commonly called: "workspaces".

What we appreciate the most about pNPM is the way it handles node_modules. In fact, the big difference in using this package manager lies in the organization of dependencies.

NPM (and Yarn) have a "flat" node_modules tree; in other words, all libraries are on the same level... pNPM works differently, listing dependencies by hard and symbolic links.

Moreover, pNPM keeps all libraries in a single location on disk: the "store". So, even if you fetch several versions of the same dependency, pNPM takes care of differentiating between them, and then only retrieves the necessary changes.

NB: Remember, with NPM, you fetch all dependencies when installing a project, and that for each project. As a result, each version is stored independently, taking up more memory space... The pNPM store isn't only efficient, it also saves a lot of disk space.

This mode of operation makes pNPM more robust than its rivals, since it is not allowed to use an unsaved dependency in the package.json file.

In fact, with a traditional package manager, it's possible to use libraries implicitly, as long as they are retrieved from another dependency.

Use Case

When creating a new project with the "official" React CLI tool (for now): npx create-react-app my-project; most of the project libraries are embedded in the react-scripts dependency. This makes it possible to use ESLint or Jest implicitly. ⚠️ SPOILER ALERT: this is not good practice!!!

This kind of use can create major problems for future development/application maintenance... For exemple, if react-scripts updates one or other of the libraries, the behavior of your unit tests (i.e. Jest) will be affected. Even worse, what would be the consequence of removing Jest (in favor of another test runner)? That's why, the use of "transitive" dependencies isn't recommended! By the way, this is a part of the left-pad's story...

NB: To reproduce a resilience mechanism (similar to pNPM) for NPM or Yarn, you can use dependency-check to ensure that your project is compliant.

Migration

Convinced by this introduction? Then it's time to get down to business! The first step to migrate from NPM (or Yarn) to pNPM is installing the package manager: npm i -g pnpm (alternative methods exist).

Then, into existing project, which already has a package-lock.json file (or Yarn equivalent), just follow the instruction: pnpm import.

Finally, you can delete your node_modules and retrieve them (again) from pNPM: pnpm install

NB: Overall, pNPM is based on the NPM API, so the pnpm install, pnpm config set and pnpm run your:script commands are fully supported!

Let's take a look at the following package.json, and compare the before/after using the new package manager:

{
  "name": "react-only",
  "version": "0.0.1",
  "description": "React + DOM (Only)",
  "main": "index.js",
  "scripts": {
    "start": "echo \"¯\\_(ツ)_/¯\" && exit 0"
  },
  "dependencies": {
    "react": "~18.2.0",
    "react-dom": "~18.2.0"
  },
  "license": "WTFPL"
}

When installing the above dependencies with NPM, you'll end up with a "flat" structure for your project:

/
├── node_modules/
│   ├── js-token
│   ├── loose-envify
│   ├── react
│   ├── react-dom
│   └── scheduler
├── package.json
└── package-lock.json

File tree with NPM

On the other hand, when using pNPM to install react and react-dom, all dependencies (including indirect dependencies) are retrieved inside the hidden .pnpm folder (and identified by version); only project-specific libraries are present at the root level of node_modules (by a symbolic link). So, it's impossible to call js-token, loose-envify or scheduler directly!

/
├── node_modules/
│   ├── .pnpm/
│   │   ├── js-token@4.0.0
│   │   ├── loose-envify@1.4.0
│   │   ├── react@18.2.0
│   │   ├── react-dom@18.2.0
│   │   └── scheduler@0.23.0
│   ├── react -> .pnpm/react@18.2.0/node_modules/react
│   └── react-dom -> .pnpm/react-dom@18.2.0/node_modules/react-dom
├── package.json
└── pnpm-lock.yaml

File tree with pNPM

After that, the choice of pNPM seems obvious, if only for the readability of node_modules. Don't worry, you won't be the first to migrate to this next-generation package manager, projects such as Prisma, Vue or even SvelteKit have done it, as well as Microsoft. Enjoy 👍

Migrate A WebApp From CRA To Vite

Damien Chazoule — Wed, 20 Sep 2023 06:16:56 +0000

~~Harder~~ Easier, Better, Faster, Stronger 🎵

Introduction

Create React App (or CRA for short) is a must-have in the JavaScript ecosystem, used to "scaffold" / initialize a new React project. Most component-oriented frameworks have their own ("official") CLI tool for this kind of task: @angular/cli a.k.a ng, @vue/cli a.k.a vue, etc...

However, in recent years (2020), a new tool has emerged, popularized by the open-source community (and Evan You, its creator): Vite!

Like CRA which relies mainly on Webpack to provide a ready-to-use JS/TS project; Vite relies on ESBuild (and Rollup's intuitive interface) to create a new Web project. In 2023, Vite stands out as a major player in the current and future Web, by providing the following functionalities:

ESM Native Support

The power of ESM (ECMA Script Module) during development

CRA relies on CommonJS syntax, while adding Babel plugins to support modern functionalities, such as import/export, etc... On the other hand, Vite natively (and implicitly) supports .esm syntax.

In other words, you can develop directly with async / await (at the top level), or import your .tsx / .jsx files directly into the application's entry point (index.html) without worrying about the compilation phase.

ESMs (or explicitly .mjs files) have their own context that allows them to evaluate the latest syntax supported by the JS environment (browsers / NodeJS). * Vite will then compile all this for you!

* NB: By setting the type key to module in the package.json, you convert your project to ESM format. The impact of this concerns your "classic" .js files, that's to say in CommonJS format. Typically configuration files, such as .eslintrc.js or prettier.config.js (which contains this statement: module.exports = {}), will need to be suffixed .cjs to work in an ESM environment. Indeed, a "module" project doesn't implicitly support the CommonJS syntax, as well as for the default projects (non-ESM), which will have to use the .esm mention to natively support some advanced features.

Faster by default

Time saving during development 🚀

The switch from Webpack to Vite comes with a change at the development server level.

With Webpack, providing a development environment requires browsing all the resources (JS files, JSX components, and other modules...) to then launch the development server.

With native support for ECMAScript modules (made possible by ESBuild), Vite runs the development server first, then loads each resource as needed ("code-splitting" style).

How the Webpack development server works

How the Vite development server works

Time saving during compilation 🚀

Another notable change with Vite (and React) is support for Speedy Web Compiler (SWC for short).

When switching from Webpack to ESBuild, you'll have the option of keeping your "good old" Babel compiler to package/build your application, or switching to its Rust equivalent (20x faster in theory).

Currently, not all Vite-based libraries benefit from this feature... But as far as React is concerned, there's a working plugin, so you might as well take advantage of it! 😉

Maintenance

In 2023, Vite is more than mature with these 4 major releases! Unlike Create React App, whose updates are increasingly slow, the open-source community wants to upgrade its new Frontend development tool! Moreover, Vite currently offers a choice of 7 component-oriented frameworks (with an out-of-the-box TypeScript environment), in addition to VanillaJS:

npm create vite@latest
✔ Project name: … hello-world
? Select a framework: › - Use arrow-keys. Return to submit.
    Vanilla
    Vue
❯   React
    Preact
    Lit
    Svelte
    Solid
    Qwik
    Others

Some of these main frameworks * have already chosen to migrate their CLI tool to Vite (especially vue, but also svelte, which has "dropped" degit in favor of this last one). Maybe it's time to get started!

* NB: Since version 16 of Angular (May 2023), the framework developed by Google offers an ESBuild "preset" to optimize development performance.

Migration (Step-by-Step)

Initialization

The 1st step of this migration work consists in initializing a new React environment based on Vite (rather than installing the dependencies needed for the project one by one...). To do that, I recommend that you follow instructions given by the following command: npm create vite@latest

You should end up with a similar structure, relatively close to Create React App:

/
├── public/
├── src/
│   ├── assets/
│   ├── App.css
│   ├── App.tsx
│   ├── index.css
│   ├── main.tsx
│   └── vite-env.d.ts
├── .eslintrc.cjs # Oh ! CommonJS Syntax :)
├── index.html
├── package.json
├── tsconfig.json
└── tsconfig.node.json
└── vite.config.ts

If you look closer, especially in the package.json, there's no longer any reference to react-script (essential for CRA projects), which was responsible for executing Webpack's specific tasks (start, build, test). This time, everything is based on Vite. *

* NB: In the same way, the npm run preview script available with Vite, is equivalent to the npx serve -s build recommended by Create React App (and Vercel) for testing the release of your Web application.

Configuration

NB: At this point, I invite you to set up a file formatting strategy (via Prettier 😎👌) and configure ESLint according to your needs.

As you can see, the 2nd step consists in configuring your new project. To do that, most of the work is focus on the vite.config.js file.

If you went through the following CLI statement: npm create vite@latest during initialization, you should already have an up-to-date configuration!

However, let’s add support for SVGs (from import statement) and your potential module reference aliases: npm i -D vite-plugin-svgr

import path from 'path';
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react-swc';
import svgr from 'vite-plugin-svgr';

export default defineConfig({
  plugins: [react(), svgr()],
  resolve: {
    alias: {
      '@': path.resolve(__dirname, './src'),
      '~': path.resolve(__dirname, './src')
    }
  }
});

vite.config.js

The baseUrl property associated with paths is essential for TypeScript compilation, as well as the use of the "hyperlink" feature from the IDE. You can also use the configuration below in a jsconfig.json file for JavaScript (non-TS) projects.

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["src/*"],
      "~/*": ["src/*"]
    }
  }
}

tsconfig.json

Another file to modify (perhaps the most important!? 🤔), the entry point of your application: the index.html

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <!-- Before -->
    <!-- <link rel="icon" type="image/png" href="%PUBLIC_URL%/favicon.png" /> -->
    <!-- After -->
    <link rel="icon" type="image/svg+xml" href="/vite.svg" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Vite + React + TS</title>
  </head>
  <body>
    <div id="root"></div>
    <!-- Oh ! ESM Syntax :D -->
    <script type="module" src="/src/main.tsx"></script>
  </body>
</html>

✂️ Copy / 📋 Paste

Ctrl +C / +V

The next step is simply to copy / paste the sources present in your previous project / to your new Vite structure. If you have not left the CRA context, simply move the content of the src folder to that of Vite, while paying attention to references in the JavaScript entry point of your project: main.tsx.

NB: Think about aliases! Make sure that all of your imports match your vite.config.js / tsconfig.json or jsconfig.json configuration.

Also consider changing access to environment variables from process.env to import.meta.env (like ESM syntax).

Tests !!! ⚙️

Vitest is the new Jest

Let's not forget the tests during this migration work!

CRA recommends using Jest for unit testing (which is already a good choice). If you have a pre-configured project with Jest, this step should go rather "fast" 🙂

Let's start by installing the new dependencies related to Vitest (replacing Jest): npm i -D vitest @vitest/coverage-v8 @testing-library/jest-dom @testing-library/react jsdom

Then let's configure your project to support Vitest as a global variable:

import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react-swc';
import svgr from 'vite-plugin-svgr';

export default defineConfig({
  // ...
  test: {
    globals: true,
    environment: 'jsdom',
    setupFiles: ['src/setupTests.ts'],
    coverage: {
      provider: 'v8',
      include: ['src/**/*.{js,jsx,ts,tsx}']
    }
  }
});

vite.config.js

{
  "compilerOptions": {
    "types": ["vitest/globals"]
  }
}

tsconfig.json

Finally, replace all references to Jest with Vitest, as follows:

import { vi } from 'vitest';
import { fireEvent, render, screen } from '@testing-library/react';
import MyComponent from '../MyComponent';

test('should triggers click event', () => {
  const onClickMock = vi.fn(); // jest.fn();
  render(<MyComponent onClick={onClickMock} />);
  fireEvent.click(screen.getByText('Click Me'));
  expect(onClickMock).toHaveBeenCalled();
});

Vitest's API is very close to Jest, since it's entirely inspired by this last one. With a few exceptions: importActual. It's up to you to run some tests: npx vitest; or with code coverage: npx vitest --run --coverage

NB: It's possible to emulate Vitest in a smoother interface with the @vitest/ui dependency. I invite you to test that, by simply executing the following instruction: npx vitest -- --ui

At the end of this last step, you will have fully migrated your Web application from CRA to Vite (or at least 99% of your project). Well done! 👏 And... Welcome to the future 🎉🎊

Conclusion

The migration from Create React App to Vite doesn't change the content of the application... However, it significantly improves the Development eXperience (DX), especially with the "Hot Module Replacement" (HMR) support, allowing you to change project resources, without having to restart the development server.

On the other hand, the React community can take advantage of the power of Rust, thanks to a ready-to-use plugin, to gain performance when compiling the project. I guess other component-oriented frameworks will follow that way...

Finally, the Test Runner change (from Jest to Vitest) also boosts performance when running unit tests, due to a lighter (and modern) library.

Despite its young age (compared to others), Vite is increasingly used (as well as ESBuild) with more than 6 million NPM downloads in August 2023 (i.e. NPM Trends), unlike Webpack, which sees its number of users decline...

NB: Note that, Vite benefits from a multitude of community plugins, including support for Electron, Storybook and PWA mode.

Choosing Vite means having a head start in Web development, because of its simplicity, its compatibility with Rollup, but also due to the ability to change frameworks (at any time) without major breaking changes: "one bundler to rule them all!"

ABC... Tests ⚙️

Damien Chazoule — Fri, 02 Jun 2023 06:14:28 +0000

Unit testing for Web development

NB: This post follows a talk on the same topic; here is the support of this presentation: https://slides.com/damienchazoule/abc-tests

Once Upon A Time...

Unit testing are the job of all developers, whether they are frontend or backend experts (or even fullstack).

In 1994, the first unit tests were created for the SmallTalk language: SUnit.

3 years later, Kent Beck (xUnit's creator) meets Erich Gamma and brings SUnit to the Java language, called JUnit!

At the beginning of the 2000s (more exactly 2001), the xUnit family grows with the arrival of a new one: JSUnit.

The goal of unit tests is to verify the proper functioning of all or part of an application / a development. In the same way, these tests can indicate possible post-delivery issues of a project (during the maintenance phase).

Unit tests are part of Agility, especially with the e*Xtreme **Programming (XP* for friends) method which includes the TDD pattern during the iterations of a project. Test Driven Development means writing unit tests even before the development of functionalities / technical components, as well as comments in the code and / or technical documentation.

Different Kinds Of Tests

There are several "degrees" / levels of unit testing, but each works the same way:

Setting up the test environment
Executing the test / unit test suite
Validation / control of test results
Finally, resetting the test environment

The 1st tests to perform ("simple" / "basic" tests) are to test the functions, the algorithms, the business logic in the code.

NB: This kind of test helped my son (6 years old at the time) to understand that it's possible to add 2 numbers and get a negative result. Even a sum() function can be fun to test 😉

The 2nd degree of unit testing concerns component-oriented frameworks (Angular, React, Vue, etc...). These tests aim to validate the behavior of a single component / or a set of components (in a complex context, the router for example). Here, we'll get closer to the BDD* pattern.

Finally, there are end-to-end (E2E) tests to verify a user journey / business use case. For example, if you need to check the correct operation of a form, in order to obtain an estimate, or something else... These kinds of tests are there for that!

Simple / Basic Testing

Make your choice....

There are many unit testing solutions in JavaScript. Promoted by the AngularJS (R.I.P) ecosystem, in the 2010s, the Karma test engine and its assertion library Jasmine had their heyday. Note that Jasmine is neither more nor less than the evolution of JSUnit!

At the same time, the Mocha testing framework started to be talked about, an alternative solution to Karma which interfaces with any assertion library. Some time later, after the AngularJS fork (led by Evan You), Vue will embed the Mocha x Chai pair as the default testing solution for its component-oriented framework.

With React, Facebook has redesigned a new unit testing solution that is much simpler in terms of configuration. Jest, by the way, is far from being a "joke", since it carries both the test engine and the assertion library. It is "THE" all-in-one solution for those who want to test their application / code, because of its simplicity (but also its speed).

At this point, I would have already told you to choose Jest without hesitation. But in 2023, the new generation of JavaScript libraries is here! of course, I want to talk about Vite, but especially Vitest. It's all in the name 🚀 This last one interfaces perfectly with the Vite bundler, and takes the main lines of its predecessor Jest.

How To Test ?

Let's get practical, by creating a new JavaScript project (with the next-gen bundler):

npm create vite@latest abc-tests -- --template react-swc
npm install --save-dev vitest

NB: Above, I scaffold the project with the React framework + Speedy Web Compiler for a faster compilation than with Babel!

Let's start slowly by creating a 1st utils.js file, then by writing a simple function:

/**
 * Format date to 'dd/mm/yyyy' pattern
 *
 * @param {Date} dateToFormat
 * @returns {string} Formatted date
 */
export const formatDate = (dateToFormat) => {
  if (dateToFormat instanceof Date) {
    const dd = dateToFormat.getDate();
    const mm = dateToFormat.getMonth() + 1;
    const yyyy = dateToFormat.getFullYear();

    return `${dd}/${mm}/${yyyy}`;
  }

  throw new Error('Not a Date');
};

utils.js

Now, let's test this 1st formatting function from the code below, and the following terminal instruction: npx vitest

import { describe, it, expect } from 'vitest';
import { formatDate } from './utils';

describe('formatDate', () => {
  it('should returns formatted date', () => {
    const mayTheFourth = new Date('2023-05-04');
    expect(formatDate(mayTheFourth)).toEqual('21/5/2023');
  });

  it('should throws an error', () => {
    expect(formatDate('2023-05-04')).toThrowError('Not a Date');
  });
});

utils.test.js

And that's it, it's relatively simple after all! No ? Here, both test cases are covered, i.e. on success, but also on error when the date isn't of type Date. Here are some other examples:

import { suite, test, expect } from 'vitest';
import { toCapitalize } from './utils';

suite("concat or evaluate, that's the question", () => {
  test('it should concat 2 values', () => {
    expect('11' + 1).toEqual('111');
  });

  test('it should evaluate 2 values', () => {
    expect('11' - 1).toEqual(10);
  });
});

NB: There are some keywords to remember when it comes to frontend-oriented unit testing. The describe and suite keywords allow you to declare a test suite, usually associated with a feature. The keywords it and test are relatively self-explanatory, it's simply the test. Finally, expect, the main one / the assertion! Note that it is more used than test because of the following word association "it should..."; it works less well with "test" 😋

It is obviously possible to test asynchronous functions, especially in the context of API testing. Here is a simulation of a service function:

/**
 * Get next value from current
 *
 * @param {number} currentValue
 * @returns {Promise} { nextValue }
 * @throws {Error} NaN
 */
export const getNextValue = (currentValue) => {
  return new Promise((resolve, reject) => {
    setTimeout(() => {
      if (typeof currentValue === 'number') {
        const nextValue = currentValue + 1;
        resolve({ nextValue });
      } else {
        reject(new Error('Not an Number'));
      }
    }, 1000);
  });
};

counterService.js

And here are the associated tests, in case of success, as well as in case of error:

import { describe, it, expect } from 'vitest';
import * as CounterService from './counterService';

describe('CounterService', () => {
  it('should returns next value', async () => {
    const { nextValue } = await CounterService.getNextValue(41);
    expect(nextValue).toEqual(42);
  });

  it('should throws an error', async () => {
    expect(await CounterService.getNextValue('41')).toThrowError('Not an Number');
  });
});

counterService.test.js

Some tests may seem trivial or even obvious at first glance, but this is rarely the case. In the context of mapping functions (between backend and frontend), the interest is great, since it makes it possible to quickly diagnose regressions / changes at the API signature level. I therefore strongly advise you to split your code as much as possible in order to facilitate testing.

Component Testing

Make your choice (again)...

This is where the Behavior Driven Development* pattern makes sense.

Just as for "classic" unit tests, there are several solutions for testing the components of your application.

Historically, AirBnB comes first with Enzyme! Equipped with an API close to jQuery (to manipulate components), Enzyme allows to mount / render a React component in a virtual DOM (the famous JSDOM). This unit testing framework has a shallow mode allowing to mount a single component (without children), so in a "unitary" way; and a mount mode to render the parent component and the child components associated with it, and thus technically to reach the componentDidMount / componentDidUpdate functions of the React component lifecycle.

Enzyme's direct competitor is none other than Testing Library. Arrival later than this last one. Testing Lib(rary) has a more explicit (and simpler: queryBy* / getBy* / findBy*) modern API for rendering a component and its children through a single function. This library aims to provide better testing practices for component-oriented frameworks. In fact, Testing Lib is agnostic and can be used with Angular, React, Vue, Svelte, Cypress, etc...

How To Test ?

Once again, let's get down to practice by adding the required dependencies and setting up the test environment:

npm i -D @testing-library/jest-dom @testing-library/react jsdom

import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react-swc';

// https://vitejs.dev/config/
export default defineConfig({
  test: { environment: 'jsdom' }, // 👈 TODO
  plugins: [react()]
});

vite.config.js

Consider the (default) <App /> component below:

import { useState } from 'react';
import * as CounterService from './counterService';
import styles from './app.module.css';

export default function App({ defaultValue = 0, ...props }) {
  const [count, setCount] = useState(defaultValue);

  const handleClick = async (currentValue) => {
    if (props.onClick) props.onClick({ prevValue: currentValue });

    try {
      const { nextValue } = await CounterService.getNextValue(currentValue);
      setCount(nextValue);
    } catch (err) {
      // eslint-disable-next-line
      console.log(err.message);
    }
  };

  return (
    <div className={styles.app}>
      <h1>Vite + React</h1>
      <div className={styles.card}>
        <button onClick={() => handleClick(count)}>Increment</button>
        <p>Count: {count}</p>
      </div>
    </div>
  );
}

App.jsx

Next, let's run some "behavior" oriented tests:

import { expect, describe, afterEach, it, vi } from 'vitest';
import { cleanup, render, screen, fireEvent } from '@testing-library/react';
import matchers from '@testing-library/jest-dom/matchers';
import App from './App';

expect.extend(matchers);

describe('<App />', () => {
  afterEach(cleanup);

  it('should renders', () => {
    render(<App />);
    expect(screen.getByText('Vite + React')).toBeInTheDocument();
  });

  it('should match snapshot', () => {
    const container = render(<App />);
    expect(container).toMatchSnapshot();
  });

  it('should increment the count value', async () => {
    render(<App defaultValue={41} />);
    expect(screen.getByText('Count: 41')).toBeInTheDocument();

    const btn = screen.getByRole('button', { name: 'Increment' });
    fireEvent.click(btn);

    expect(await screen.findByText('Count: 42')).toBeInTheDocument();
  });

  it('should triggers the click event', () => {
    const onClickMock = vi.fn();
    render(<App defaultValue={41} onClick={onClickMock} />);

    const btn = screen.getByRole('button', { name: 'Increment' });
    fireEvent.click(btn);

    expect(onClickMock).toHaveBeenCalled();
    expect(onClickMock).toHaveBeenCalledWith({ lastCount: 41 });
  });
});

App.test.jsx

Above, several test cases:

The first should renders simply renders a component and checks its content;
The second should match snapshot creates an image of your component and allows you to detect any differences when your component evolves. In this specific case, you will have to update your snapshot;
The 3rd test case checks the value of the count variable before and after clicking on the button;
Finally, in the 4th test case, we inject a "mocked" function to our component, we click on the button, then we check that this function has been called with the right arguments;

fireEvent does a lot of things related to events in the DOM, such as filling the fields of a form. For simple cases, why not... For more complex cases, better leave that to end-to-end testing...

Mock Service Worker (MSW)

It's impossible to talk about API unit testing without talking about Mocker Service Worker. MSW acts as a middleware between your application and APIs, intercepting requests at the network level. So, it is no longer necessary to mock Axios or Fetch to control the algorithms related to API calls and returns.

MSW supports REST(ful) requests and GraphQL queries, and offers two modes: worker mode (ideal for developing and debugging your application), and server mode for backend and unit testing.

Straight from the documentation, here's how to install and initialize the worker:

npm i axios && npm i -D msw
npx msw init public --save

Let's enhance the "fake" service previously created by adding a function calling the "real" service:

import axios from 'axios';

/**
 * Post current value to get next
 *
 * @param {number} currentValue
 * @returns {Promise} { nextValue }
 * @throws {Error} 40x or 50x
 */
export const postCurrentValue = async currentValue => {
  try {
    const response = await axios.post('/api/counter', { currentValue });
    return response.data; // { nextValue }
  } catch {
    throw new Error('Not an 20x');
  }
};

counterService.js

NB: Below, here is the code to execute at the entry point (index.js) of your project to mock the API /api/counter return, when running the application.

import { rest, setupWorker } from 'msw';

const handlers = [
  rest.post('/api/counter', async (req, res, ctx) => {
    const { currentValue } = await req.json();

    if (typeof currentValue === 'number') {
      const nextValue = currentValue + 1;
      return res(ctx.delay(1000), ctx.json({ nextValue }));
    }

    return res(ctx.status(422, 'Unprocessable Entity'));
  })
];

const worker = setupWorker(...handlers);
worker.start();

And now, here is how the server mode (alternative to the worker mode) works in the context of unit tests (always in the case of success, but also of failure):

import { describe, beforeAll, afterEach, afterAll, it, expect } from 'vitest';
import { setupServer } from 'msw/node';
import { rest } from 'msw';
import * as CounterService from './counterService';

describe('postCurrentValue', () => {
  const server = setupServer();

  beforeAll(() => server.listen());
  afterEach(() => server.resetHandlers());
  afterAll(() => server.close());

  it('should returns next value', async () => {
    server.use(
      rest.post('/api/counter', (req, res, ctx) => {
        return res(ctx.json({ nextValue: 42 }));
      })
    );

    const result = await CounterService.postCurrentValue(41);
    expect(result.nextValue).toBeDefined();
  });

  it('should throws an error', async () => {
    server.use(
      rest.post('/api/counter', (req, res, ctx) => {
        return res(ctx.status(400, 'Bad Request'));
      })
    );

    const err = await CounterService.postCurrentValue('41').catch(err => err);
    expect(err.message).toEqual('Not an 20x');
  });
});

counterService.test.js

End-To-End Testing

Make your choice (again and again)...

For more complex tests, especially business use cases, there is end-to-end testing. The interest of these tests is to prove the proper execution of a functional course, and to play your application in real cases / close to the final use.

To do this, Cypress has become a key player in end-to-end testing. With a detailed documentation and an active community, this framework makes it possible to emulate a user journey, directly in a browser (Chrome, Firefox or Edge) and to follow its progress visually. With the arrival of Testing Library, Cypress has enhanced its API, and now has getBy* functions (getByText, getByRole, etc...) to manipulate DOM elements.

As an alternative to Cypress, there is Playwright. Supported by Microsoft, it offers a simple and fast configuration for end-to-end testing. Unlike Cypress, Playwright plays business use cases from one or more "headless" browsers (Chromium, Firefox, Webkit) in parallel. It is also available in several languages: JavaScript, Java, Python and C# (unlike its counterpart). Finally, this framework benefits from an API similar to Testing Lib since October 2022, to the delight of developers... 🙏

How To Test ?

What could be more concrete than showing you Playwright in action. To do so, let me demonstrate the power of codegen mode:

npm install --save-dev @playwright/test
npx playwright install
npx playwright codegen --viewport-size=800,600 http://localhost:5173

NB: npx playwright install allows you to install the "headless" browsers on which you will run your tests, namely Chromium, Firefox and WebKit.

NB: The DIY Redux application is a development made as part of work around State Management (i.e. React Vs. Vue).

Playwright's codegen mode is magic! It allows to simulate the functional test case, while recording each of your actions. Then just adapt the selectors, add assertions according to your needs, and run Playwright again (playwright test) to have a complete end-to-end test case.

import { test, expect } from '@playwright/test';

test.use({
  viewport: {
    height: 600,
    width: 800
  }
});

test('it should fill form and move to next (then to next)', async ({ page }) => {
  await page.goto('http://localhost:5173/');

  await expect(page.getByRole('heading', { name: 'Identity' })).toBeVisible();

  await page.getByPlaceholder('Abramov').click();
  await page.getByPlaceholder('Abramov').fill('Chazoule');

  await page.getByPlaceholder('Dan').click();
  await page.getByPlaceholder('Dan').fill('Damien');

  await page.getByRole('button', { name: 'Next' }).click();

  await expect(page.getByRole('heading', { name: 'Professional' })).toBeVisible();

  const firstComboBox = await page.getByRole('combobox').nth(0);
  firstComboBox.selectOption('Front');

  const secondComboBox = await page.getByRole('combobox').nth(1);
  secondComboBox.selectOption('JavaScript');

  await page.getByPlaceholder('Go, Rust...').click();
  await page.getByPlaceholder('Go, Rust...').fill('TypeScript');

  await page.getByRole('button', { name: 'Next' }).click();

  await expect(page.getByRole('heading', { name: 'Fantasy' })).toBeVisible();

  await page.getByPlaceholder('Cliff').click();
  await page.getByPlaceholder('Cliff').fill('Ragnar');

  await page.getByRole('button', { name: 'Previous' }).click();
  await expect(page.getByPlaceholder('Go, Rust...')).toHaveValue('TypeScript');

  await page.getByRole('button', { name: 'Next' }).click();
  await expect(page.getByPlaceholder('Cliff')).toHaveValue('Ragnar');
});

Code Coverage

What about code coverage in all this? 🤔 Code coverage is a metric that determines the code rate performed. This indicator highlights the percentage of code statements, covered branches, executed functions, as well as lines of code not covered (explicitly).

Be careful! It is important to differentiate between tests and the coverage rate! Indeed, the code coverage rate is calculated according to the unit tests executed, but a successful test does not necessarily mean that the code is entirely covered... In the same way, we must also ask ourselves about the interest of an optimal coverage; 100% coverage is sometimes utopian or pointless if it does not bring any added value to the project (security, scalability, maintainability).

With Vitest, the code coverage tool is not included by default, unlike Jest, which relies on Babel to provide this functionality, without installing any additional dependencies.

However, it is possible to obtain code coverage using the C8 library:

npm i -D @vitest/coverage-c8
npx vitest --coverage

-------------------|---------|----------|---------|---------|---------------
File               | % Stmts | % Branch | % Funcs | % Lines | Uncovered Line
-------------------|---------|----------|---------|---------|---------------
All files          |   96.73 |    93.33 |     100 |   96.73 |
 App.jsx           |    92.1 |    83.33 |     100 |    92.1 | 16-18
 counterService.js |     100 |      100 |     100 |     100 |
 utils.js          |     100 |      100 |     100 |     100 |
-------------------|---------|----------|---------|---------|---------------

So, the result above highlights the fact that most of the lines are covered, except for lines 16 to 18 of the App.jsx file (according to previous tests). Looking closer, we see that it is a console.log(). What's the point of going through here? Is there any code missing!? Or is it normal...

The Final Word

Very often, unit tests are synonymous with extra costs for the project (especially for frontend projects because they do not guarantee data integrity, unlike the backend). This is both true and false... Unit testing is a habit to be acquired. The more developers get used to testing their code, the less it will cost the project. In the same way, the flex of the unit test, makes it possible to better split its algorithms, to better organize its technical projects, and so to guarantee a better maintainability of the source code.

The mistake not to make on the frontend is to leave a project "abandoned" without regular maintenance (more than 6 months) and especially without testing (nor comments)... The Web evolves quickly, frontend projects must be updated at the same frequency. In the same way, unit tests guarantee a level of quality and understanding of the code! So the durability of a Web project depends in part on its unit tests 👌

To the question "is it doubtful to test?", I answer that I don't doubt anymore! I test my developments because it's natural (and fun) 🙂

To Go Further...

In order to provide good quality code for your frontend projects, it is possible to interface the SonarQube quality measurement tool with Vitest. In fact, Vitest is able to provide two types of reports: coverage reports and test reports. By combining these two tools with your CI/CD (GitHub Actions, GitLab CI, etc...) you will be able to guarantee some level of quality, by defining a coverage rate to be reached (although controversial) but above all by ensuring that the unit tests are working properly and automatically 👍

NB: SonarQube is a relatively visual tool, and one that allows project actors (other than developers) to quickly identify the robustness of the generated code (red / green indicators).

Finally, we have already seen the "classic" unit tests, component-oriented tests, but also end-to-end tests; there is a last category of tests: the Mutation Testing! The goal of these kinds of tests is to perform a multitude of "faulty" use cases to know if our application is robust. At the moment, I have only found one tool to do that. The JavaScript ecosystem will continue to evolve in the next few years, so we can expect to see this kind of test become more common. To be continued...

Building A P2P Network With Deno 🌐

Damien Chazoule — Fri, 04 Nov 2022 07:30:48 +0000

Developing a peer-to-peer system in JavaScript, this is possible with Deno!

Recently, I discovered the SolidJS framework, and I very quickly wanted to put into practice what I had learned by developing a robust application. For this, I decided to code a web interface to control the actions of a node in a peer-to-peer network. Okay, but what's a peer-to-peer network?

A P2P system (or peer-to-peer network) is a technical data exchange architecture in which each "user" is both a client, but also a server. In this kind of structure, the user is called "node" or even "peer". There are 2 types of P2P networks:

Centralized systems, having a main server, source of truth of the application data
Decentralized systems, where each node guarantees the integrity and authenticity of the data

NB: It was through my interest in the concepts of "blockchain" and decentralized applications (DApps) that I decided to set up this project and to create a peer-to-peer network, from scratch.

Naturally, I immediately sought to develop this kind of system in... JavaScript! That's indeed possible, thanks to the WebSocket protocol. In this post, I propose to build, step by step, a (decentralized) P2P network based, not on ExpressJS x SocketIO, nor NestJS (to speed up the project), but directly from Deno 🦕

Part I - Server Initialization

NB: I've already mentioned what Deno is in a previous post, I invite you to take a look if you want to know more, and what differences exist with its counterpart Node.

In a P2P system, a node is both client and server. So, first step: "set up the server"; let's go!

import { serve } from 'https://deno.land/std@0.159.0/http/server.ts';

async function handler(req: Request): Promise<Response> {
  return new Response(
    JSON.stringify({
      message: 'Hello World'
    })
  );
}

serve(handler, { port: 3030 });

server.ts

Like ExpressJS, these few lines are enough to initialize an HTTP server, in order to get the "Hello World" message (in JSON format) from any route. Test it by making a call to http://localhost:3030 directly from your browser, after starting your server: deno run --allow-net server.ts

NB: Note that here I use version 1.26.0 of Deno, as well as version 0.159.0 of its modules. Deno is secure by default, so the --allow-net parameter is required to allow network access.

First API

Time to add some logic to this simple server. We will therefore create a first variable to store WebSocket clients / peers specific to the current node. As a reminder, in a decentralized model, each peer guarantees the integrity and authenticity of its data.

import { serve } from 'https://deno.land/std@0.159.0/http/server.ts';

let allPeers = [];

async function handler(req: Request): Promise<Response> {
  const url = new URL(req.url);

  if (url.pathname === '/peers' && req.method === 'GET') {
    return new Response(JSON.stringify(allPeers));
  }

  return new Response(
    JSON.stringify({
      message: 'Hello World'
    })
  );
}

serve(handler, { port: 3030 });

server.ts

Here is how to simply expose an API with Deno, without using an additional library (Alosaur, Servest, etc...). Here, we make available the /peers route to retrieve the list of peers associated with the server. This time, start your server and navigate to the URL http://localhost:3030/peers to see the result (i.e. an empty array for now...).

Part II - WebSocket Support

Let's talk about the main topic, adding support for the WebSocket standard. The server will thus be able to react in real time to the reception of data from another server on the same network.

import { serve } from 'https://deno.land/std@0.159.0/http/server.ts';

let allPeers = [];

async function handler(req: Request): Promise<Response> {
  const url = new URL(req.url);

  if (url.pathname === '/peers' && req.method === 'GET') {
    return new Response(JSON.stringify(allPeers));
  }

  const upgrade = req.headers.get('upgrade') || '';
  let response, socket: WebSocket;

  try {
    ({ response, socket } = Deno.upgradeWebSocket(req));
  } catch {
    // Request isn't trying to upgrade to WebSocket
    return new Response(
      JSON.stringify({
        message: 'Hello World'
      })
    );
  }

  socket.onopen = () => console.log('on:open');
  socket.onmessage = () => console.log('on:message');
  socket.onclose = () => console.log('on:close');
  socket.onerror = () => console.log('on:error');

  return response;
}

serve(handler, { port: 3030 });

server.ts

This "update" allows the original server to support the WebSocket protocol. For information, this Web specification allows two-way communication between a client and a server, in a single TCP request.

WebSocket Client

So far, no real change. If we start our server (deno run --allow-net server.ts) we don't see any apparent change. However, the server is now able to react to WebSocket transactions (if requested by a compatible client). Let's implement a new API that will also give more meaning to the application.

import { serve } from 'https://deno.land/std@0.159.0/http/server.ts';
import { urlWrapper } from './utils.ts';

let allPeers = [];

async function handler(req: Request): Promise<Response> {
  const url = new URL(req.url);

  // ...

  if (url.pathname === '/peer' && req.method === 'POST') {
    const body = await req.json();

    if (!body.targetUrl) {
      return new Response(JSON.stringify({ message: 'URL Value Fail' }), {
        status: 400,
      });
    }

    const [_, wsUrl] = urlWrapper(body.targetUrl);
    const wsClient = new WebSocket(wsUrl);

    wsClient.onopen = () => {
      allPeers = [...allPeers, wsClient];
    };

    wsClient.onclose = () => {
      allPeers = allPeers.filter((client) => {
        const reUrl = new RegExp(wsUrl);
        return !reUrl.test(client.url);
      });
    };

    return new Response(JSON.stringify({ message: `New Peer: '${wsUrl}'` }), {
      status: 201,
    });
  }

  // ...

  return response;
}

serve(handler, { port: 3030 });

server.ts (code snippet)

Here is the second API to create a new WebSocket client. Explicitly, the user will need to provide the client node's target URL via a REST protocol POST call. When the client is opened (onopen), it is added to the peer list of the current server; on the other hand, when the client is closed (onclose), this same client is removed from the list. Finally, the API returns a simple message with a status 201 (CREATED), or an HTTP 400 code (BAD REQUEST) if the URL value isn't present in the body of the call. Since this is a POST request, it is necessary to use a REST client: cURL, Postman, etc...; to query the API.

/**
 * @param {string} url
 * @returns {string[]} HTTP URL + WS URL
 */
export const urlWrapper = (url: string) => {
  // That's an HTTP URL
  if (/^(http:\/\/)/.test(url)) {
    const wsUrl = url.replace('http://', 'ws://');
    return [url, wsUrl];
  }

  // That's an WS URL
  if (/^(ws:\/\/)/.test(url)) {
    const httpUrl = url.replace('ws://', 'http://');
    return [httpUrl, url];
  }

  // There's no protocol...
  return [`http://${url}`, `ws://${url}`];
};

utils.ts

NB: I use an intermediate function to format the URL. Indeed, the creation of a new WebSocket client requires the presence of its protocol (ws://) rather than the character string specific to an HTTP URL (http://). My method (although perfectible) can retrieve one or the other, depending on the value entered by the user when querying the API.

To test this second API, I invite you to follow the following process:

In a terminal, start a server (on the default port 3030)
Change the port (4040), then start a new server in a 2nd terminal
Finally, from a REST client, query the API /peer as POST, from the 1st server (http://localhost:3030/peer), with the body { "targetUrl": "127.0. 0.1:4040" }

curl -H "Content-Type: application/json" -X POST -d '{"url": "127.0.0.1:4040"}' http://localhost:3030/peer

POST request via cURL

If everything goes well, you should see the 2nd terminal (the one whose server is started on port 4040) display an "on:open" message. This information can be explained by the fact that the 1st server opened a client to the second. Similarly, if you ask the 1st server to find out the list of its nodes, it should have completed the list with the following peer: ws://127.0.0.1:4040

curl -H "Content-Type: application/json" -X GET http://localhost:3030/peers

GET request via cURL

Okay, but... Where are we with all this!? At the end of this chapter, you should have two "nodes" of your P2P network (if you have followed the tutorial carefully, and you haven't started a 3rd instance):

A "fake" node started on port 3030 which is only server
A "real" node started on port 4040 which is both client (from the first node) and server

In summary, the 1st server is able to send and receive data to 4040. On the other hand, the 2nd server receives the data but cannot send any in turn to 3030. Conclusion, we aren't yet in a peer-to-peer system...

Part III - The "Handshake" 🤝

Now, what remains to be done (compared to the previous part) is a "Handshake" 🤝 / or pairing method. This process allows a node to open a client to a server, so that the latter connects to it in turn. Let's put this in place!

Pong !

A.K.A "The Receiver"

import { serve } from 'https://deno.land/std@0.159.0/http/server.ts';
import { urlWrapper } from './utils.ts';

let allPeers = [];

async function handler(req: Request): Promise<Response> {
  const url = new URL(req.url);

  // ...

  socket.onopen = () => console.log('on:open');

  socket.onmessage = ({ data }) => {
    const parsedData = JSON.parse(data);

    switch (parsedData.type) {
      case 'HANDSHAKE':
        const [_, wsUrl] = urlWrapper(parsedData.payload);
        const wsClient = new WebSocket(wsUrl);

        wsClient.onopen = () => {
          allPeers = [...allPeers, wsClient];
        };

        wsClient.onclose = () => {
          allPeers = allPeers.filter((client) => {
            const reUrl = new RegExp(wsUrl);
            return !reUrl.test(client.url);
          });
        };
        break;

      default:
        throw new Error();
    }
  };

  socket.onclose = () => console.log('on:close');
  socket.onerror = () => console.log('on:error');

  return response;
}

serve(handler, { port: 3030 });

server.ts (code snippet)

In this 1st part of the code, the server will react to the reception of a message with the type "HANDSHAKE" 🤝, then it will open a client to the WebSocket URL of the target, previously passed as a value (payload) of this same message.

NB: With TypeScript, I advise you to use enums rather than constants for your types, it's smarter 😉

Ping !

A.K.A "The Emitter"

import { serve } from 'https://deno.land/std@0.159.0/http/server.ts';
import { urlWrapper } from './utils.ts';

let allPeers = [];

async function handler(req: Request): Promise<Response> {
  const url = new URL(req.url);

  // ...

  if (url.pathname === '/peer' && req.method === 'POST') {
    const body = await req.json();

    if (!body.targetUrl) {
      return new Response(JSON.stringify({ message: 'Target URL Value Fail' }), {
        status: 400,
      });
    }

    const [_, wsUrl] = urlWrapper(body.targetUrl);
    const wsClient = new WebSocket(wsUrl);

    wsClient.onopen = () => {
      allPeers = [...allPeers, wsClient];

      wsClient.send(
        JSON.stringify({ type: 'HANDSHAKE', payload: '127.0.0.1:3030' })
      );
    };

    wsClient.onclose = () => {
      allPeers = allPeers.filter((client) => {
        const reUrl = new RegExp(wsUrl);
        return !reUrl.test(client.url);
      });
    };

    return new Response(JSON.stringify({ message: `New Peer: '${wsUrl}'` }), {
      status: 201,
    });
  }

  // ...

  return response;
}

serve(handler, { port: 3030 });

server.ts (code snippet)

Then, we will enrich the service responsible for creating a peer / a node, so that it sends a message to the target server, when opening a new WebSocket client. Thus, each of the two servers (according to this tutorial) will be able to communicate with each other. Test it according to the process of the previous part. Again, if all goes well, each terminal should display the message "on:open" which means that each server has opened a client to the other. That's it! Your peer-to-peer system is functional 👍

Part IV - Data Broadcast

Since we have an operational peer-to-peer network, it's time to move on to sending data between nodes, especially by communicating globally. To do this, we will have to implement a new type of data, enrich this new data structure and access it via APIs, and of course, distribute them to our network.

import { serve } from 'https://deno.land/std@0.159.0/http/server.ts';
import { urlWrapper } from './utils.ts';

let allPeers = [];
let allRecords = [];

async function handler(req: Request): Promise<Response> {
  const url = new URL(req.url);

  // ...

  if (url.pathname === '/records' && req.method === 'GET') {
    return new Response(
      JSON.stringify(allRecords.map((record) => record.value))
    );
  }

  if (url.pathname === '/record' && req.method === 'POST') {
    const body = await req.json();

    if (!body.record) {
      return new Response(JSON.stringify({ message: 'Record Value Fail' }), {
        status: 400
      });
    }

    allRecords = [
      ...allRecords,
      {
        key: Math.random().toString(36).slice(2),
        value: body.record
      }
    ];

    allPeers.forEach((client) => {
      client.send(
        JSON.stringify({
          type: 'NEW_RECORD',
          payload: allRecords[allRecords.length - 1]
        })
      );
    });

    return new Response(
      JSON.stringify({ message: `New Record: '${body.record}'` }),
      { status: 201 }
    );
  }

  // ...

  return response;
}

serve(handler, { port: 3030 });

server.ts (code snippet)

First, we create two new APIs (respectively in GET and POST) for retrieving a list of records (allRecords), as well as adding a new element (record). Moreover, during the insertion of this record, a WebSocket message is sent to all peers of the current server. The information is therefore distributed in a global way.

import { serve } from 'https://deno.land/std@0.159.0/http/server.ts';
import { urlWrapper } from './utils.ts';

let allPeers = [];
let allRecords = [];

async function handler(req: Request): Promise<Response> {
  const url = new URL(req.url);

  // ...

  socket.onopen = () => console.log('on:open');

  socket.onmessage = ({ data }) => {
    const parsedData = JSON.parse(data);

    switch (parsedData.type) {
      case 'HANDSHAKE':
        const [_, wsUrl] = urlWrapper(parsedData.payload);
        const wsClient = new WebSocket(wsUrl);

        wsClient.onopen = () => {
          allPeers = [...allPeers, wsClient];
        };

        wsClient.onclose = () => {
          allPeers = allPeers.filter((client) => {
            const reUrl = new RegExp(wsUrl);
            return !reUrl.test(client.url);
          });
        };
        break;

      case 'NEW_RECORD':
        const foundedRecord = allRecords.find(
          (record) => record.key === parsedData.payload.key
        );

        if (!foundedRecord) {
          allRecords = [...allRecords, parsedData.payload];
        }
        break;

      default:
        throw new Error();
    }
  };

  socket.onclose = () => console.log('on:close');
  socket.onerror = () => console.log('on:error');

  return response;
}

serve(handler, { port: 3030 });

server.ts (code snippet)

On the other hand, the server receives the message of type "NEW_RECORD", then we insert the value of the message (payload) as a new element of the record list, if there isn't already listed. Note that the record is identified by a unique and random key (Thanks to the object Math 😉)

So I invite you to test this operation, by starting an additional server (in a new terminal):

Start a 1st server (on the default port 3030)
Start a 2nd server by changing the port (4040)
Start a 3rd server by changing the port (5050)
Add the 4040 and 5050 nodes to the 3030 server peer list
Save one or more data from the /record API of the first server
Check record contents from node 4040 or 5050

curl -H "Content-Type: application/json" -X POST -d '{"targetUrl": "127.0.0.1:4040"}' http://localhost:3030/peer
curl -H "Content-Type: application/json" -X POST -d '{"targetUrl": "127.0.0.1:5050"}' http://localhost:3030/peer
curl -H "Content-Type: application/json" -X POST -d '{"record": "hello"}' http://localhost:3030/record
curl -H "Content-Type: application/json" -X POST -d '{"record": "world"}' http://localhost:3030/record
curl -H "Content-Type: application/json" -X GET http://localhost:4040/records

List of cURL requests

Part V - Command-Line Interface

As you will have noticed several times, the test process is not really optimal... Changing the port by hand is relatively heavy. Don't panic, this last (bonus) part, will allow you to be more flexible in creating nodes for your peer-to-peer system.

import { parse } from 'https://deno.land/std@0.159.0/flags/mod.ts';
import { serve } from 'https://deno.land/std@0.159.0/http/server.ts';
import { urlWrapper } from './utils.ts';

const parsedArgs = parse(Deno.args);

const HOST = parsedArgs.host || '127.0.0.1';
const PORT = +parsedArgs.port || 3030;

let allPeers = [];
let allRecords = [];

async function handler(req: Request): Promise<Response> {
  // ...

  wsClient.send(
    JSON.stringify({ type: 'HANDSHAKE', payload: `${HOST}:${PORT}` })
  );

  // ...

  return response;
}

serve(handler, { hostname: HOST, port: PORT });

server.ts (code snippet)

These few additional lines of code should allow you to manipulate the host and the port more easily: deno run --allow-net server.ts --port 5050. Let's go further in this same logic by allowing the addition of peers (already started) when the server is launched.

import { parse } from 'https://deno.land/std@0.159.0/flags/mod.ts';
import { serve } from 'https://deno.land/std@0.159.0/http/server.ts';
import { urlWrapper } from './utils.ts';

const parsedArgs = parse(Deno.args);

const HOST = parsedArgs.host || '127.0.0.1';
const PORT = +parsedArgs.port || 3030;

let allPeers = [];
let allRecords = [];

async function handler(req: Request): Promise<Response> {}

serve(handler, {
  hostname: HOST,
  port: PORT,
  onListen: ({ hostname, port }) => {
    console.log(`Server started on http://${hostname}:${port}`);
  }
});

if (parsedArgs.peers) {
  const parsedPeers: string[] = parsedArgs.peers.split(',');

  parsedPeers.forEach((peer) => {
    const [_, wsUrl] = urlWrapper(peer);
    const wsClient = new WebSocket(wsUrl);

    wsClient.onopen = () => {
      allPeers = [...allPeers, wsClient];

      wsClient.send(
        JSON.stringify({ type: 'HANDSHAKE', payload: `${HOST}:${PORT}` })
      );
    };

    wsClient.onclose = () => {
      allPeers = allPeers.filter((client) => {
        const reUrl = new RegExp(wsUrl);
        return !reUrl.test(client.url);
      });
    };
  });
}

server.ts (code snippet)

Here we are! Thanks to this last parameter you are ready to launch your P2P network 👍 Now just make it grow, little by little, by connecting the Deno 🦕 to each other. You are free to add complexity, security and why not "blockchain" concepts. Enjoy!

Discover A New Framework: SolidJS 🧑‍💻

Damien Chazoule — Fri, 02 Sep 2022 11:18:09 +0000

The world of Web development is constantly evolving, and new JavaScript libraries are appearing (always more interesting), day after day...

This year (once again), I challenged myself to experiment with a new technology. As the Web is constantly evolving, it's important to get up to date every 6 months. Following the last "State Of JS" survey's results, I found two new frameworks that seemed promising to me: AlpineJS x SolidJS

NB: I'm enthusiast, I thirst for knowledge, and recently I wanted to learn something fresh, like the discovery of Svelte in 2019.

After reading two or three documentations, and analyzing several dozen lines of code, I preferred to choose SolidJS, especially because of the JSX omnipresence, as well as concepts similar to my everyday tool, namely: React!

In this post, I'll obviously talk about what SolidJS is, but especially about how I understood this new framework in a learning process (from theory to practice). I wouldn't fail to mention the dependencies that revolve around its ecosystem. Finally, we will see if this last one keeps its promise of "fine-grained reactivity", while being simple and efficient.

WTF is SolidJS!?

NB: Before talking about the main topic, a short explanation... As part of the work on setting up a peer-to-peer network in JavaScript (upcoming post...), I wanted to have an interface / an application to control actions related to a node (other than Postman). Rather than developing this from already known basics, I started to learn more in detail what SolidJS really is, and to implement it in a large-scale project. Here is my learning process!

Like many JavaScript libraries before it, SolidJS is a component-oriented framework for building Web interfaces. Although close to React in some of its concepts (and its syntax), it wants to be lighter and more reactive than this last one, like Svelte. Indeed, SolidJS advocates "fine-grained reactivity" by making changes directly from the DOM, rather than through a virtual DOM.

As a result (and according to performance tests of the open-source community), this new tool would be both faster than React, Vue, Preact (even if it has a lighter virtual DOM than React), as well as Svelte, and would be the first in terms of speed and memory allocation!

Get started with SolidJS

Getting started with SolidJS is child's play (I still recommend having the basics of JavaScript, as well as the mastery of some component-oriented framework notions, to fully understand what reactivity is...). By using the Rich Harris's library (degit), we can scaffold the project. Therefore, the JavaScript environment will be pre-configured to work from a bundler, ~~not Webpack this time~~, but Vite!

Powered mainly by the Vue community, Vite is a new kind of JavaScript tool, to start a new Web project very quickly, while offering a modern environment. Inspired by RollupJS (but also ESBuild), Vite has many features, including:

NPM dependency management
Pre-bundle of sources (saving a lot of time at startup)
Hot Module Replacement (HMR)
Native TypeScript support
On-the-fly JSX transpilation
Support for CSS modules
Dynamic import management
Build optimization, etc.

NB: Vite ecosystem also brings Vitest for unit testing, as an alternative to Jest.

SolidJS offers a wide range of templates to initialize a new project, with the choice of language: JavaScript or TypeScript; the integration of a ready-to-use UI library (including the great TailwindCSS), but also the implementation of an unit test engine: Jest / Vitest (optional).

import { render } from 'solid-js/web';
import { createSignal, onMount, onCleanup } from 'solid-js';

const CountingComponent = () => {
  const [count, setCount] = createSignal(0);
  const interval = setInterval(() => {
    setCount(count => count + 1);
  }, 1000);

  onMount(() => console.log('Mounted'));
  onCleanup(() => clearInterval(interval));

  return <div>Count value is {count()}</div>;
};

render(() => <CountingComponent />, document.getElementById('root'));

Counter component with SolidJS

import { render } from 'react-dom';
import { useState, useEffect } from 'react';

const CountingComponent = () => {
  const [count, setCount] = useState(0);
  const interval = setInterval(() => {
    setCount(count => count + 1);
  }, 1000);

  useEffect(() => {
    console.log('Mounted');
    return cleanup = () => clearInterval(interval);
  }, []);

  return <div>Count value is {count}</div>;
};

render(() => <CountingComponent />, document.getElementById('root'));

Counter component with React

Above, here's what a first single counter component might look like with SolidJS, and its opposite on the React side. We quickly notice the similarities between these two libraries. And yet, SolidJS seems to be more explicit and simple!

Indeed, rather than having a useEffect hook to handle the mounting and unmounting behaviors of the component (through a cleanup function), SolidJS exposes its actions with functions of its life cycle: onMount and onCleanup.

Similarly, the createSignal API is relatively identical to React's useState hook in how its works, since the data flow is unidirectional. On one side the accessor (immutable), and on the other the "setter". However, there is a significant difference with SolidJS! The "fine-grained reactivity" concept is based on the principle that components only renders once, and that functions associated with the Signals are executed as soon as they're updated. Changes will then be impacted directly in the DOM. Since the access to the value of a Signal is only possible by calling it (presence of parentheses), I consider the accessor more like a "getter", rather than a constant... Signals are the key concept of SolidJS!

Overall SolidJS is really easy to take in hand, learning its API is also easier due to rich documentation and a "playground" section to understand each aspect of this library, and to gain in skill step by step.

Although basic, SolidJS is a complete framework, since it also offers a routing solution (npm install solid-app-router), a "code splitting" feature through asynchronous component loading (made possible by the bundler), or even the ability to render your application server-side (SSR). So SolidJS, ranks among the big ones (React, Vue, etc.) as a Web library to create user interfaces.

Building user interfaces

Enough theory, now let's move on to practice! And what better way to put it into practice than to evolve in a concrete case… To do this, I suggest you to create a new project, to handle the feeding and display of a modal, in order to approach the reactivity notions of SolidJS. Let's go!

npx degit solidjs/templates/js-vitest my-awesome-app
cd my-awesome-app
npm install

Et voilà! You should see a new directory appear (my-awesome-app in my case), lite in terms of dependencies, but already pre-configured to work /vit/!

NB: As part of my work, I also added TailwindCSS support to project initialization (npx degit solidjs/templates/js-tailwindcss), then merged both Vite configurations manually.

import { mergeProps, Switch, Match, Show } from 'solid-js';
import { IconInfo, IconSuccess, IconWarning, IconError } from './icons';

export const Modal = (props) => {
  const merged = mergeProps({
    type: 'INFO',
    title: 'Info',
    onOk: () => console.log('Ok')
  }, props);

  return (
    <div class="container">
      <div class="modal__background" />

      <div class="modal">
        <span class="modal__icon">
          <Switch fallback={<IconInfo class="text-blue-700 bg-blue-100" />}>
            <Match when={merged.type === 'SUCCESS'}>
              <IconSuccess class="text-green-700 bg-green-100" />
            </Match>

            <Match when={merged.type === 'WARNING'}>
              <IconWarning class="text-orange-700 bg-orange-100" />
            </Match>

            <Match when={merged.type === 'ERROR'}>
              <IconError class="text-red-700 bg-red-100" />
            </Match>
          </Switch>
        <span>

        <span class="modal__title">{merged.title}</span>

        {props.children}

        <div class="modal__actions">
          <Show when={typeof props.onCancel === 'function'}>
            <button class="modal__action-cancel" type="button" onClick={props.onCancel}>
              Cancel
            </button>
          </Show>

          <button class="modal__action-ok" type="button" onClick={merged.onOk}>
            Ok
          </button>
        </div>
      </div>
    </div>
  );
}

Modal.jsx

The modal represents a stateless component that visually extends across the screen (considering the dark background and centering of the main element), and which only waits for props values to come to life. This also simplify unit testing with Vitest (and Testing Library).

The SolidJS API can make the syntax a bit verbose at first "Vue" 😉, but its components are essential to effect a change in the DOM, because of a virtual DOM lack. So its simplicity lies in a clever combination of Signals (immutable) and components (<Show>, <Switch>, <For>, etc.) in order to make the DOM reactive to the right places!

NB: Note that here, we use the mergeProps API to impose default props values. Again, it's important to use this function to conserve reactivity, rather than initializing these same values directly from the component's signature (like with React).

import { render } from 'solid-js/web';
import { createSignal, onMount, Show } from 'solid-js';
import { Modal } from './Modal';

export const App = () => {
  const [showModal, setShowModal] = createSignal(false);
  const [modalType, setModalType] = createSignal('');
  const [modalTitle, setModalTitle] = createSignal('Lorem ipsum');

  onMount(() => {
    if (showModal()) {
      setTimeout(() => {
        setModalType('SUCCESS');
        setModalTitle('Everything is good');
      }, 1500);

      setTimeout(() => {
        setModalType('ERROR');
        setModalTitle('Something is wrong');
      }, 3000);
    }
  });

  return (
    <div class="app">
      <Show when={showModal()}>
        <Modal
          type={modalType()}
          title={modalTitle()}
          onOk={() => {
            setModalType('WARNING');
            setShowModal(false);
          }}>
          <p>Lorem ipsum dolor sit amet</p>
        </Modal>
      </Show>

      <button style={{ margin: 'auto' }} onClick={() => setShowModal(currentVal => !currentVal)}>
        {showModal() ? 'Hide Modal' : 'Show Modal'}
      </button>
    </div>
  );
};

render(() => <App />, document.getElementById('app'));

main.jsx

In terms of usage, the triggering of the modal's display (as well as its feeding) takes place via Signals, from the parent component. Above, I had fun changing the modal's appearance over time, to observe the reactivity. One more time, it may seem verbose, but it's simple and effective!

This mode of operation is sometimes not enough, especially when developing an application at scale, or when using a routing system (npm install solid-app-router), to split the pages of its application. Handling the modal should be possible by using a "props drilling" logic (parent to child, child to sub-child, etc.), but we should quickly fall into a complexity linked to component nesting, as well as their maintenance... No problem! As for modals, there is the <Portal> component; for everything else, there is the "Context" API!

import { mergeProps, Switch, Match, Show, Portal } from 'solid-js';
import { IconInfo, IconSuccess, IconWarning, IconError } from './icons';

export const Modal = props => (
  <Portal mount={document.getElementById('modal')}>
    <ModalComponent {...props} />
  </Portal>
);

// Move <Modal /> To <ModalComponent />
export const ModalComponent = props => {
  const merged = mergeProps(
    {
      type: 'INFO',
      title: 'Info',
      onOk: () => console.log('Ok')
    },
    props
  );

  return <div class="container">{/* ... */}</div>;
};

Modal.jsx

Context API

NB: In a previous post, I explain how it's possible to implement a "homemade" Redux, with React's Context API, here the logic is the same...

import { createContext, createEffect, createSignal, useContext } from 'solid-js';
import { createStore } from 'solid-js/store';

const store = createContext();

const { Provider } = store;

export const useStore = () => {
  return useContext(store);
};

const StateProvider = props => {
  const [currentIdx, setCurrentIdx] = createSignal(0);
  const [state, setState] = createStore({
    email: 'morty.smith@pm.me'
  });

  createEffect(() => {
    console.log('currentIdx', currentIdx());
  });

  const value = [
    {
      currentIdx,
      fieldValues: state
    },
    {
      incrementIndex() {
        setCurrentIdx(prevCurrentIdx => prevCurrentIdx + 1);
      },
      decrementIndex() {
        setCurrentIdx(prevCurrentIdx => prevCurrentIdx - 1);
      },
      getField(key) {
        return state[key] || '';
      },
      setField(key, value) {
        setState({ [key]: value });
      }
    }
  ];

  return <Provider value={value}>{props.children}</Provider>;
};

export default StateProvider;

StateProvider.jsx

import { Form, InputField } from './components';
import { useStore } from './StateProvider';

const StateConsumer = () => {
  const [{ currentIdx }, { getField, setField }] = useStore();

  return (
    <Form index={currentIdx()}>
      <InputField
        label="Email"
        type="email"
        placeholder="rick.sanchez@pm.me"
        defaultValue={getField('email')}
        handleChange={e => setField('email', e.target.value)}
      />
    </Form>
  );
};

StateConsumer.jsx

State Management (via the Context API), is an ideal reactive programming paradigm for large developments, avoiding the problem of "props drilling", but also the presence of double / triple data... In this way, it's said that the "store" is the only source of truth of the application.

NB: To learn more about this topic, don't hesitate to consult the source code of my project on Gitlab and Vercel.

Would you like some extra unit tests?

The ecosystem powered by SolidJS, advocates modern technologies such as PNPM, Vite, Vitest but also Testing Library. Based on the implementation of Preact, the SolidJS team brings the component-oriented unit testing framework, which has already proven itself with React, Vue, Angular, Cypress, etc.

import { render, fireEvent } from 'solid-testing-library';
import { describe, it, expect, vi } from 'vitest';
import { Modal } from './Modal';

describe('<Modal />', () => {
  it('Should Render', () => {
    const { getByText, unmount } = render(() => (
      <Modal title="> Modal Title Goes Here <">
        <p>Lorem ipsum dolor sit amet</p>
      </Modal>
    ));

    expect(getByText('> Modal Title Goes Here <')).toBeInTheDocument();
    expect(getByText('Lorem ipsum dolor sit amet')).toBeInTheDocument();
    unmount();
  });

  it('Should Trigger onClick Event(s)', async () => {
    const mockedOnCancel = vi.fn();
    const mockedOnOk = vi.fn();

    const { getByText, unmount } = render(() => (
      <Modal type="WARNING" title="Warning" onCancel={mockedOnCancel} onOk={mockedOnOk} />
    ));

    const cancelBtn = getByText('Cancel');
    fireEvent.click(cancelBtn);
    expect(mockedOnCancel).toHaveBeenCalled();

    const okBtn = getByText('Ok');
    fireEvent.click(okBtn);
    expect(mockedOnOk).toHaveBeenCalled();

    unmount();
  });
});

Modal.test.jsx

Simplicity + Reactivity === Performance

I really enjoyed playing with this new framework (as often with JavaScript technologies). There are many notions of its counterparts, as well as new ones such as Signals, or the createResource function (very useful for querying APIs). I didn't have great difficulty creating my node control application (from scratch), since this last one offers great flexibility in project organization. So, the Developer eXperience is optimal!

NB: Unlike React (or Vue), SolidJS compiles its code during the development period (like Svelte). In this way, it's able to effectively and quickly effect changes in the "real" DOM; one bonus point in favor of DX! 👍

This first overview makes me want to know more and propose the approach in professional situation. Perhaps replacing Preact, or even React... SolidJS doesn't offer only components and features demonstrated above. If I had to make a quick list, this library also offers:

Dynamic rendering of an element list, from (not Array.prototype.map but) its <For> component
Encapsulation of asynchronous calls (as resources), for better visibility of the loading state, as well as the presence (or not) of error(s)
Interface display in case of lazy loading (components or resources), via the <Suspense> component
Display of interfaces in case of error(s), to avoid application crash
The SSR operating mode, for performance gains, but also for better SEO (here SolidJS, directly confronts Nuxt, Next or SvelteKit)
Or, the "store" reconciliation, allowing Redux to coexist in a scaled application

Due to its easy-to-understand concepts, and despite the absence of a virtual DOM, SolidJS has proven its strength and stability (in 5 years of development), pushing reactivity in its purest form: Signals! Just like Svelte, this future-oriented framework has bright days ahead of it. This is my favorite of the year! ❤️

After Nuxt, What's Next? 💭

Damien Chazoule — Mon, 28 Feb 2022 09:40:09 +0000

New post, new topic, this time I take you into the thick of JAMStack to talk to you about SSG, SSR, SEO, through Nuxt and Next frameworks, not to mention the wonderful world of UnifiedJS.

You will understand, here I'll talk about... JavaScript (once more time 😉). But before that, a small introduction to contextualize things...

Previously...

In early 2022, I started implementing a translation feature for my portfolio.

NB: At the origin, my portfolio was only translated into English, and those around me kept asking me to have it available in my native language, i.e. French.

My project being initially developed from a JAMStack framework, I'm oriented to an already existing "i18n" plugin. After setting it, I quickly realized that it didn't fit my needs perfectly. Indeed, I wanted a "hybrid" mode allowing me to translate simply (via a classic "key - value" system), but also to be able to translate by myself (especially for posts). So I had to (re)code part of the utility in order to achieve a suitable result... But still, far from being optimized.

Following this observation, I started a migration work, because even if I had more flexibilities, I might as well test several other technologies in detail! So I went from Gridsome to Next (via Gatsby, then Nuxt).

NB: My heart is torn between React and Vue since years, this time I let myself be tempted by React (it's also the library that I mostly use every day, so one more point in favor of it).

This work lasted until February (between comparisons, migration, implementation of internationalization, tests, etc...) Anyway! What to enjoy and (re)discover modern and efficient technologies.

I transcribe here (in the form of a series), some advantages and disadvantages that I have been able to identify for the use of each of these frameworks.

WTF Is JAMStack!?

As a reminder, JAMStack is a technical environment that consists of building a website / application from JavaScript, reusable APIs and serving it in HTML format ("M" is for Markup) using a static site generator.

The data that will be used to feed the website / application can be retrieved locally (via Markdown files for example), or remotely, via CMS APIs. The static site generator then builds a stable release (including all necessary resources and pages) ready to be uploaded on a hosting service.

This technical environment offers many advantages, such as better responsiveness (due to the recovery of all resources during the build phase), better scalability (the developer is not constrained by a heavy architecture, he can focus on the frontend), and especially a better SEO (each page can manage its attributes related to SEO).

NB: JAMStack frameworks are built around the PRPL pattern, to optimize the performance of websites / applications on smartphones and devices with a weak internet connection.

Ep 1. Vue + JAMStack = Gridsome

At the middle of this ecosystem is the Gridsome open-source framework, powered by the Vue community. As for this last one, it benefits from an active developer network and well-done documentation.

npm install -g @gridsome/cli
gridsome create my-portfolio

The Gridsome CLI makes scaffolding your JAMStack project architecture very simply. Furthermore, the real power of this kind of framework lies in its tree structure of files / folders which brings the routing to the highest level.

<template>
  <Layout>
    <div class="post-title">
      <h1>{{ $page.post.title }}</h1>

      <PostMeta :post-date="$page.post.date" :time-to-read="$page.post.timeToRead" />
    </div>

    <div class="post">
      <div class="post__header">
        <g-image v-if="$page.post.coverImage" alt="Cover Image" :src="$page.post.coverImage" />
      </div>

      <div class="post__content" v-html="$page.post.content" />

      <PostTags :post-tags="$page.post.tags" />
    </div>
  </Layout>
</template>

<page-query>
  query Post($id: ID!) {
    post: post(id: $id) {
      content
      title
      date(format: "YYYY-MM-DD")
      description
      coverImage(width: 720, blur: 10)
      tags
      path
      timeToRead
    }
  }
</page-query>

<script>
  import PostMeta from '~/components/PostMeta.vue';
  import PostTags from '~/components/PostTags.vue';

  export default {
    components: {
      PostMeta,
      PostTags
    },
    metaInfo() {
      return {
        title: this.$page.post.title,
        meta: [
          {
            name: 'description',
            content: this.$page.post.description
          }
        ]
      };
    }
  };
</script>

Gridsome has a (magic) API in GraphQL format (here between <page-query> tags) to retrieve content and integrate it into the component, through the $page variable. In addition, it embeds a part of RemarkJS (🚨 #SpoilerAlert 🚨 Cf. The Wonderful World Of UnifiedJS) inside its API, to transform Markdown files into HTML format.

This framework also includes the vue-meta dependency for metadata management. So, it's very easy to add or update the data responsible for the good SEO of your website, and this for each "page" or "template" type component.

As mentioned earlier, project structure matters, since components placed in the "pages" folder, will create their own routes according to their naming (in practice, a 404.vue file will create a /404 page). On the other hand, for the generation of pages on the fly, it's better to use the "templates" folder.

+-- content                     # *.md Are Here
+-- public                      # Static Files
+-- src
    +-- components
    +-- layouts
    +-- pages                   # Explicit Pages
    +-- templates               # Dynamic Page Templates
+-- gridsome.config.js
+-- gridsome.server.js
+-- package.json

Still in the framework architecture, the gridsome.server.js file is used to manipulate the Gridsome API, especially to create dynamic pages (based on "templates" components). Among the use cases, there are dependencies related to Gridsome; example with "sources" plugins that load data (asynchronously) and make them available from the GraphQL interface.

Finally, the gridsome.config.js file speaks for itself, since it allows to enrich the project's configuration, whether it's the title, the description of the website (in a SEO context), etc... Or to integrate additional libraries (support for "i18n" locales for example).

NB: That may be the downside of this kind of technology. Many turnkey features come from plugins (with their own configuration). Unfortunately, if you want to go deeper with a library, there's no other way than to pull the project locally and (re)develop part of the code; otherwise settle for the basic features...

Gridsome is a small nugget in the world of web development. It benefits from a strong community, as well as many "starters" which serve as a basis for the development of a new website. If you start with a JAMStack framework, it will quickly be ready to use, to expose local data (in .md, .mdx formats) or remote, from a CMS interface (Strapi, Forestry or Contentful).

It met my need for 2 years, but now it's time to change...

Ep 2. The Great, Gatsby ✨

Gatsby is the dark side of the force (if you consider Gridsome as its bright side). In other words, Gatsby is the equivalent of this last one in the React ecosystem.

npm install -g gatsby-cli
gatsby new

Just like its counterpart, Gatsby has a CLI tool to build a new JAMStack project. The difference is that it works with a "questions - answers" system. So, you can choose to add the support for Markdown files, to integrate a UI library (styled-component / emotion), but also to configure the use of a CMS.

It has a lot of concepts in common with Gridsome, especially for the routing management through the "pages" folder, dynamizing pages using the "templates" folder convention, retrieving local or remote data via a GraphQL API, etc...

import React from 'react';
import { Helmet } from 'react-helmet';
import { graphql } from 'gatsby';
import { GatsbyImage } from 'gatsby-plugin-image';
import Layout from '@/components/Layout';
import PostMeta from '@/components/PostMeta';
import PostTags from '@/components/PostTags';

export default function Post({ data: { post } }) {
  const { frontmatter, fields } = post;
  const { childImageSharp } = frontmatter.coverImage;

  return (
    <>
      <Helmet>
        <title>{frontmatter.title}</title>
        <meta name="description" content={frontmatter.description} />
      </Helmet>

      <Layout>
        <div className="post-title">
          <h1>{frontmatter.title}</h1>

          <PostMeta postDate={frontmatter.date} readingTime={fields.readingTime} />
        </div>

        <div className="post">
          <div className="post__header">
            {frontmatter.coverImage && (
              <GatsbyImage
                alt="Cover Image"
                src={childImageSharp.gatsbyImageData}
              />
            )}
          </div>

          <div className="post__content" dangerouslySetInnerHTML={{ __html: post.html }} />

          <PostTags postTags={frontmatter.tags} />
        </div>
      </Layout>
    </>
  );
}

export const query = graphql`
  query Post($id: ID!) {
    post: markdownRemark(id: { eq: $id }) {
      html
      frontmatter {
        title
        date(formatString: "YYYY-MM-DD")
        description
        coverImage {
          childImageSharp {
            gatsbyImageData(quality: 90, width: 720, formats: [WEBP])
          }
        }
        tags
      }
      fields {
        slug
        readingTime {
          minutes
        }
      }
    }
  }
`;

Here, you notice the use of a GraphQL API (again) to inject data as component props (even if the syntax differs somewhat from Gridsome, it's basically the same structure). Thanks to the gatsby-transformer-remark dependency (🚨 #SpoilerAlert 🚨 Cf. The Wonderful World Of UnifiedJS), previously installed when querying the CLI, the framework becomes able to exploit files in .md format.

NB: I also had to add the gatsby-remark-reading-time plugin to get the reading time per post, where Gridsome did it implicitly.

This framework supports modern image formats (WebP) very well, ideal for optimizing the refresh time of a website. For SEO, it will be necessary to go through an additional library (especially react-helmet), to apply the metadata on the different pages.

Gatsby's strong point is its SaaS mode. If you don't want to deploy your application on a traditional web server (Apache / Nginx), there are alternatives JAMStack solutions, such as Netlify or Vercel, but also... Gatsby Cloud! The framework has its own product for an optimal experience! 👌

I use Gatsby since version 2.0 with the Orluk Photography project. I have never been disappointed by this tool, it supports TypeScript quite well (better since version 3.0), and interfaces perfectly with a CMS (Strapi, I love you 💜). But, given the similarities with Gridsome, you might as well keep this last one; or try something new...

Ep 3. Nuxt : One "Meta" Framework To Rule Them All!

Just as popular as Gatsby *, there's Nuxt! I always wanted to try this framework, and I must say that Debbie O'Brien's posts confirmed my enthusiasm for this library of the Vue ecosystem.

Nuxt perfectly embraces the JAMStack philosophy, but it does much more than that. Indeed, it has three modes of operation:

The Single Page App mode (SPA for friends);
The "static" mode (SSG), allowing to build the application using a static site generator;
The "universal" mode, which allows the application to be rendered via a NodeJS server.

With Server Side Rendering, the user will access the website faster than in CSR mode. The Client Side Rendering relies on JavaScript to provide the HTML; while SSR mode first provides the static content (i.e. HTML), then the JavaScript, etc... Aside from performance gains, this mode of operation allows indexing robots to browse the website more easily (since the pages are directly accessible).

Anyway! It was time to play with this framework!!! 🔥

NB: Version 3.0 has just been released in public beta, I preferred to develop from a stable version that has already proven itself.

npx create-nuxt-app my-portfolio

As for Gatsby, the Nuxt CLI is simply great because it allows you to initialize a project with a full configuration. You can choose: the JavaScript or TypeScript language, the SSG or SSR mode, the CSS framework to use (including TailwindCSS), the unit tests engine, the Prettier implementation, etc...

Nuxt has many assets, including the Vuex integration by default (allowing to manage data using the "state management" pattern for applications at scale), but most importantly a file-based browsing system (which is not unlike that of Gridsome), with the famous "pages" folder.

However, for fetching data, this is a different story. There's no more GraphQL API to rely on. This time, things have to be done from scratch! Maybe not...

<template>
  <Layout>
    <div class="post-title">
      <h1>{{ post.title }}</h1>

      <PostMeta :post-date="post.date" :reading-time="post.readingTime" />
    </div>

    <div class="post">
      <div class="post__header">
        <img v-if="post.coverImage" :src="post.coverImage" alt="Cover Image" width="720" height="405" />
      </div>

      <nuxt-content class="post__content" :document="post" />

      <PostTags :post-tags="post.tags" />
    </div>
  </Layout>
</template>

<script>
  import PostMeta from '~/components/PostMeta.vue';
  import PostTags from '~/components/PostTags.vue';

  export default {
    components: {
      Layout,
      PostMeta,
      PostTags
    },
    async asyncData({ app, $content, params }) {
      const post = await $content(params.slug).fetch();
      return { post };
    },
    head() {
      return {
        title: this.post.title,
        meta: [
          {
            hid: 'description',
            name: 'description',
            content: this.post.description
          }
        ]
      };
    }
  };
</script>

To help me access and read my Markdown files (and turn them into Markup), I used one of the many Nuxt community modules, namely @nuxt/content. Now, thanks to an API accessible by the $content variable, I'm able to retrieve the front-matter and the content of my .md files to use them inside my <template>.

Apart from this 1st integration, I also had to add a dependency for SEO feed (npm i vue-meta), a second dependency for the translation functionality (npm i vue-i18n), as well as utility functions (such as reading time calculation).

NB: To calculate the reading time, I created a simple function that I then injected into the $content API, thanks to a "hook" in the Nuxt configuration.

import { readingTime } from './src/utils';

export default {
  // ...nuxt.config.js
  hooks: {
    'content:file:beforeInsert': document => {
      if (document.extension === '.md') {
        document.readingTime = readingTime(document.text);
      }
    }
  }
};

After having correctly configured my Nuxt environment, and (re)developing my dynamic pages, I carried out performance tests with Google Lighthouse, and I realized that some points could be optimized, especially for the image management (score ~= 70). Again, I had to install another open-source module (@nuxt/images / nuxt-optimized-images), to support WebP format.

Verdict? Nuxt is really cool! I fell in love with its SSR mode. Unfortunately it requires a few tweaks (here and there) to be fully operational / effective. Okay, what's next...

Ep 4. What's Next? 💭 #SeasonFinale

I (re)discovered Next during their conference last October. There's so much to say about this framework...

NB: Starting with the fact that Svelte's creator, Rich Harris, joined the Vercel teams recently 👍

Popularized by React, this framework is the equivalent of Nuxt. It benefits from similar concepts, such as page management by the same name folder. The difference is that the dependencies added to Next will be more like "standard" JavaScript libraries rather than framework-related plugins (after all, React is a JavaScript library, not a framework 😎).

npx create-next-app

Lighter than its counterparts, the CLI tool simply generates the project tree (including react, react-dom and next). Next focuses on a SSR deployment rather than CSR (although possible with the next export command). So, it will compile the necessary resources and then serve them on the server side.

+-- content                     # *.md Are Here
+-- public                      # Static Files
+-- src
    +-- components
    +-- pages                   # Explicit Pages
    +-- services                # Data Fetching
    +-- utils
+-- next.config.js
+-- package.json

Above is the structure I use for my portfolio project. There's very little configuration in the next.config.js file, I only registered my locales there for my internationalization feature, as well as the configuration of the PWA mode (but this is another story).

import Head from 'next/head';
import Image from 'next/image';
import Layout from '@/components/Layout';
import PostMeta from '@/components/PostMeta';
import PostTags from '@/components/PostTags';
import { getPostBySlug, getAllPostSlugs } from '@/services/contentService';
import { markdownToHtml } from '@/utils/markdownUtil';

export default function Post({ post }) {
  return (
    <>
      <Head>
        <title>{post.title}</title>
        <meta name="description" content={post.description} />
      </Head>

      <Layout>
        <div className="post-title">
          <h1>{post.title}</h1>

          <PostMeta postDate={post.date} timeToRead={post.timeToRead} />
        </div>

        <div className="post">
          <div className="post__header">
            {post.coverImage && (
              <Image alt="Cover Image" src={post.coverImage} width={720} height={405} />
            )}
          </div>

          <div className="post__content" dangerouslySetInnerHTML={{ __html: post.content }} />

          <PostTags postTags={post.tags} />
        </div>
      </Layout>
    </>
  );
}

export const getStaticProps = async ({ params: { slug } }) => {
  const post = getPostBySlug(slug, [
    'content',
    'title',
    'date',
    'description',
    'coverImage',
    'tags',
    'timeToRead'
  ]);
  const content = await markdownToHtml(post.content);

  return {
    props: {
      post: {
        slug,
        ...post,
        content
      }
    }
  };
};

export const getStaticPaths = async () => {
  const allPostSlugs = getAllPostSlugs();

  return {
    paths: allPostSlugs.map((slug) => ({
      params: {
        slug
      }
    })),
    fallback: false
  };
};

Next doesn't have a ready-to-use GraphQL API, nor modules for exploiting .md / .mdx formats; it's up to the developer to code the functions he needs. Thanks to the use of NodeJS, and the winning combo of its fs and path modules, it's possible to access the file system. Then, you will have to do some transformations with RemarkJS (🚨 #SpoilerAlert 🚨 Cf. The Wonderful World Of UnifiedJS) to expose the content of Markdown files in HTML format.

import fs from 'fs';
import join from 'path';
import matter from 'gray-matter';
import { getReadingTime } from '@/utils';

export const getPostBySlug = (slug, fields = []) => {
  const realSlug = slug.replace(/\.md$/, '');
  const postsDir = path.join(process.cwd(), 'content');
  const fullPath = path.join(postsDir, `${realSlug}.md`);
  const file = fs.readFileSync(fullPath, 'utf-8');
  const { data, content } = matter(file);

  const item = {};

  fields.forEach((field) => {
    if (field === 'slug') {
      item[field] = realSlug;
    }

    if (field === 'content') {
      item[field] = content;
    }

    if (field === 'timeToRead') {
      item[field] = getReadingTime(content);
    }

    if (typeof data[field] !== 'undefined') {
      item[field] = data[field];
    }
  });

  return item;
};

After experimenting with Gridsome, Gatsby and Nuxt, it's a bit confusing not to have a function for handling data directly available from an import... But it's finally a good thing, since you better understand what it's hiding under the hood.

However, this React metaframework gave me the best development experience! In addition to having a complete routing system, Next also embeds the <Head /> component to enrich the page metadata of the application. Moreover, thanks to its <Image /> component (and not <img>), it offers a good optimization in the management of JPEG, PNG formats and... WebP, to get a better score on Google Lighthouse.

NB: Powered by Vercel, it's recommended to deploy its application on the service of the same name, to have a detailed overview of your website performance.

Where Next surprised me the most is during the compilation of the project (next build). Since version 12.0, the framework has improved its way of building its production release based on the Rust language, with the Speedy Web Compiler library (rather than Babel). This results in a considerable time saving (3 to 5 times faster than the previous version). I can only recommend to you!

The Wonderful World Of UnifiedJS #SpinOff

During this migration work, I took the time to discover what UnifiedJS really is. This ecosystem includes more than a hundred plugins to manipulate content. Whether it's <html>, .md/ .mdx formats or plain text, UnifiedJS's open-source libraries are able to browse each of these formats (using a tree syntax) and automate some tasks, such as syntax control, interpretation of code blocks, nodes transformation, or minification.

This grouping includes:

RemarkJS, for processing Markdown files
RehypeJS, for processing HTML files

import { remark } from "remark";
import directive from "remark-directive";
import gist from "./remarkGist";
import gfm from "remark-gfm";
import html from "remark-html";
import prism from "remark-prism";

export const markdownToHtml = async (markdown) => {
  const result = await remark()
    .use(directive)
    .use(gist)
    .use(gfm)
    .use(html)
    .use(prism)
    .process(markdown);

  return result.toString();
};

In the example above, I use RemarkJS to transform the content of a .md file (##Hello, **World**) into HTML (<h2>Hello, <strong>World</strong></h2>). I also add support for enhanced GitHub syntax (GFM) to support tables and task lists. Finally, I use the Prism plugin to colorize code blocks (by language), according to a CSS theme.

import { visit } from 'unist-util-visit';

export default function remarkGist() {
  return (tree, file) => {
    visit(tree, (node) => {
      if (
        node.type === 'textDirective' ||
        node.type == 'leafDirective' ||
        node.type === 'containerDirective'
      ) {
        if (node.name !== 'github') return;

        const data = node.data || (node.data = {});
        const attributes = node.attributes || {};
        const id = attributes.id;

        if (node.type === 'textDirective') file.fail("Text directives for 'GitHub' not supported", node);
        if (!id) file.fail('Missing gist ID', node);

        data.hName = 'iframe';
        data.hProperties = {
          src: `https://gist.github.com/${id}`,
          width: 720,
          height: '100%',
          frameBorder: 0,
        };
      }
    });
  };
}

It's possible to develop your own transformation functions, to support video formats, or the addition of the Snippets from GitHub / GitLab, etc... Still in the example, I use a plugin allowing me to interpret directives, then I transform those corresponding to the ::github type by retrieving the Gist (from its identifier / URL) and embedding it in a <iframe> tag. With RehypeJS, I could also get the code (in RAW format) to pass it between <pre> and <code> tags. Everything is possible with UnifiedJS!

This "wonderful world" is supported by the JAMStack community, with contributors like Netlify, Vercel or Gastby. I strongly advise you to venture there (if not already done through "magic" plugins). Don't forget to equip yourself with your two best tools: RemarkJS et RehypeJS! 🧑‍💻

Building A Robust Backend Server With NestJS 🚧

Damien Chazoule — Mon, 25 Oct 2021 06:00:30 +0000

It's time to talk about it... Not ~~Next~~, nor ~~Nuxt~~, but Nest!

P r o l o g u e

Some time ago, I challenged myself to build a robust backend solution in JavaScript. Many developers believe that JavaScript isn't secure enough, efficient or simply organized to manage data through APIs. I'll convince you otherwise....

For this new project, I chose technologies that are on the rise, in particular PostgreSQL but especially NestJS. So, I gave up my good old database that is MongoDB, in favor of a more traditional database.

NB: I was a little bit rusty at first, but going back to relational database was a real good idea; if only to retrieve data from several tables in one call, unlike NoSQL which requires as many calls as there are documents to query... Finally, SQL is like riding a bike, it's unforgettable 😉

NestJS is a framework for creating high-scalability server applications (powered by NodeJS). This one is based on Typescript and combines three development paradigms:

The Object Oriented Programming #OOP
The Functional Programming #FP
The Functional Reactive Programming #FRP

NestJS starts from the observation that Web frameworks (especially those component-oriented), aren't structured enough... Except one: Angular! So, it's inspired by this last one to provide a complete library for backend developments.

NB: Indeed, Angular has a similar organization, but unlike NestJS, the structure of this one is (in my opinion) more restrictive than anything else... I prefer its counterparts like React and Vue (and Svelte) which offer more flexibility in frontend application design. However, I'm convinced that this "heavy" architecture can be a substantial help to those who are new to frontend development.

Finally, NestJS embeds the ExpressJS engine or that of Fastify (at choice), to deliver a robust and powerful HTTP server. So, you can talk about a framework of frameworks (meta-framework!? 🤔) For this project, I chose to use Fastify which seems more than promising...

I n i t i a l i z a t i o n

It's time to code! 🧑‍💻 Let's start by installing the main NestJS dependency, then initialize a new project: hello-community

npm i -g @nestjs/cli
nest new hello-community

So, do you see the similarities with Angular? 🙃 Using the NestJS command line interface, you get an "modules - controllers - services" architecture:

Controllers are responsible for exposing application routes
Services handle communication between data sources
Modules link services with controllers

NB: In addition to initializing the project, the NestJS CLI will allow you to individually scaffold these same files (nest generate <module|controller|service>). So useful!

Now, let's take a closer look at the main.ts file, entry point of the application. By default, NestJS will mount an HTTP server based on ExpressJS. But, in my case, I'm gonna need Fastify, which (let's remember) is supposed to be faster and lighter than its counterpart.

To do this, it's necessary to add the @nestjs/platform-fastify dependency to the project, then adapt the main.ts file code.

import { NestFactory } from '@nestjs/core';
import { FastifyAdapter, NestFastifyApplication } from '@nestjs/platform-fastify';
import { AppModule } from './app.module';

async function bootstrap() {
  const app = await NestFactory.create<NestFastifyApplication>(
    AppModule,
    new FastifyAdapter()
  );
  await app.listen(3000);
}

bootstrap();

main.ts

Et voilà ! Just go to http://localhost:3000, to see your first Hello World! (or Hello Community! if you've been curious) 👏

NB: By specifying the 0.0.0.0 string as a second parameter of the listen() function, you'll be able to access your endpoints within the same local network.

It's hard to see a real difference between ExpressJS and Fastify on a simple call. Although... I noticed a small difference when loading. According to Google Chrome, this first Hello World! loads 239 bytes with ExpressJS, versus 176 bytes via Fastify (confirmed by Mozilla Firefox). It's clear that this framework is (at least) lighter than its predecessor.

C R U D

Let's make things more interesting / more concrete by implementing your first REST(ful) API. For that, you can use the CLI tool to create files one by one (module / controller / service), or generate the whole set directly (i.e. a new CRUD resource).

The nest g resource command does this for you. By typing the resource name (users) and specifying that it's a REST API, you quickly get a ready-to-use controller and service.

One of benefits of this mode of operation is that NestJS also generates some development patterns, including the well-known DTO (Data Transfer Object) of developers. #OOP

import { HttpException, HttpStatus, Injectable } from '@nestjs/common';
import { CreateUserDto } from './dto/create-user.dto';
import { UpdateUserDto } from './dto/update-user.dto';
import { User } from './interfaces/user.interface';
import { generateUuid } from '../utils';

@Injectable()
export class UsersService {
  users: User[] = [];

  findAll(): User[] {
    return this.users;
  }

  findOne(id: string): User {
    const user = this.users.find(user => user.id === id);
    if (user) return user;
    throw new HttpException('No User Found', HttpStatus.NOT_FOUND);
  }

  findOneByEmail(email: string): User {
    const user = this.users.find(user => user.email === email);
    if (user) return user;
    throw new HttpException('No User Found', HttpStatus.NOT_FOUND);
  }

  create(createUserDto: CreateUserDto): { createdId: string } {
    const uuid = generateUuid();
    this.users = [
      ...this.users,
      {
        id: uuid,
        ...createUserDto
      }
    ];
    return { createdId: uuid };
  }

  update(id: string, updateUserDto: UpdateUserDto): { updatedId: string } {
    let founded = false;
    this.users = this.users.map(user => {
      if (user.id === id) {
        founded = true;
        return { ...user, ...updateUserDto };
      }
      return user;
    });
    if (founded) return { updatedId: id };
    throw new HttpException('No User Found', HttpStatus.NOT_FOUND);
  }

  remove(id: string): { removedId: string } {
    const length = this.users.length;
    this.users = this.users.filter(user => user.id !== id);
    if (length !== this.users.length) return { removedId: id };
    throw new HttpException('No User Found', HttpStatus.NOT_FOUND);
  }
}

users.controller.ts

For this first resource, I suggest you to keep the controller as it is (users.controller.ts), but adapt the service code (users.service.ts), in order to simulate a data source.

NB: For practical reasons (prevent the size of this post from growing fast), I chose to show the type of my data. In a real case, I advise you to put it in the right places, namely in interfaces and enums (or simply models) folders.

Make sure you have registered your users.module.ts module at the main module level (app.module.ts), then launch the application (npm run start). You should be able to start playing with your API via the REST protocol (and Postman of course 😎).

S e c u r i t y

Serious things start here... If you go back quickly, you notice that your endpoints are all reachable with the same level of security (that is to say none). Furthermore, the user's password is directly saved in the database... So, it's necessary to secure all of this!

First step: the password obfuscation. NestJS supports data encryption (with the NodeJS crypto module), but also data hashing. Here, I chose to use the bcrypt library to hash my strings, to guarantee unidirectional (and optimal) security! 👌

Let's install dependencies (npm i --save bcrypt && npm i --save-dev @types/bcrypt) and modify the user creation service to secure its password.

import * as bcrypt from 'bcrypt';

@Injectable()
export class UsersService {
  // ...

  async create(createUserDto: CreateUserDto): Promise<{ createdId: string }> {
    const uuid = generateUuid();

    const salt = await bcrypt.genSalt();
    const hash = await bcrypt.hash(password, salt);

    this.users = [
      ...this.users,
      {
        id: uuid,
        password: hash,
        ...createUserDto
      }
    ];
    return { createdId: uuid };
  }

  // ...
}

users.service.ts

Second step: securing calls using an authentication protocol. This second task is more complex since it requires the implementation of one or more authentication strategies. Fortunately, NestJS already has a "guard" concept allowing to "validate / invalidate" routes of the application. Let's go!

npm install --save @nestjs/passport passport passport-local passport-jwt
npm install --save-dev @types/passport-local @types/passport-jwt

The best way to establish this kind of operation (with NodeJS) is to use Passport. On the design side, I'll have to create a new authentication route that will provide me a token to validate /users/:id endpoints (GET, PATCH and DELETE). That's why, I recover (above) two strategies:

The LOCAL strategy, allows simple authentication (based on the username / password pair)
The JWT strategy, is based on the validity of a token over time

Again, you'll have to use the command line interface to instantiate a module, a controller and a service (nest g <module|controller|service> auth). Furthermore, you will have to create two new files corresponding to the Passport strategies respectively.

import { Injectable, UnauthorizedException } from '@nestjs/common';
import { PassportStrategy } from '@nestjs/passport';
import { Strategy } from 'passport-local';
import { User } from '../users/interfaces/user.interface';
import { AuthService } from './auth.service';

@Injectable()
export class LocalStrategy extends PassportStrategy(Strategy) {
  constructor(private authService: AuthService) {
    super({
      usernameField: 'email'
    });
  }

  async validate(email: string, password: string): Promise<User> {
    const user = await this.authService.validateUser(email, password);
    if (user) return user;
    throw new UnauthorizedException();
  }
}

local.strategy.ts

NB: Here, you'll notice that I replaced the default behavior of the LOCAL strategy, to use the email / password pair.

import { Injectable } from '@nestjs/common';
import { PassportStrategy } from '@nestjs/passport';
import { ExtractJwt, Strategy } from 'passport-jwt';

interface Payload {
  id: string;
  email: string;
  iat: string;
  exp: string;
}

@Injectable()
export class JwtStrategy extends PassportStrategy(Strategy) {
  constructor() {
    super({
      jwtFromRequest: ExtractJwt.fromAuthHeaderAsBearerToken(),
      ignoreExpiration: false,
      secretOrKey: process.env.JWT_SECRET
    });
  }

  async validate(payload: Payload) {
    return { userId: payload.id, userEmail: payload.email };
  }
}

jwt.strategy.ts

NB: In a real case, I'd advise against exposing the JWT secret! It's better to fetch it in another way, through the file .env (the @nestjs/config module can then be useful) or another process...

import { Injectable } from '@nestjs/common';
import { JwtService } from '@nestjs/jwt';
import * as bcrypt from 'bcrypt';
import { User } from '../users/interfaces/user.interface';
import { UsersService } from '../users/users.service';

type UserOrNull = User | null;

@Injectable()
export class AuthService {
  constructor(private usersService: UsersService, private jwtService: JwtService) {}

  async validateUser(email: string, password: string): Promise<UserOrNull> {
    const user = await this.usersService.findOneByEmail(email);
    const isMatch = await bcrypt.compare(password, user.password);

    if (user && isMatch) {
      return user;
    }
    return null;
  }

  async login(user: { id: string; email: string; }) {
    const payload = { userId: user.id, userEmail: user.email };

    return {
      access_token: this.jwtService.sign(payload)
    };
  }
}

auth.service.ts

import { Controller, Post, Request, UseGuards } from '@nestjs/common';
import { AuthGuard } from '@nestjs/passport';
import { AuthService } from './auth.service';

@Controller('auth')
export class AuthController {
  constructor(private readonly authService: AuthService) {}

  @UseGuards(AuthGuard('local'))
  @Post('login')
  async login(@Request() req) {
    return this.authService.login(req.user);
  }
}

auth.controller.ts

import { Module } from '@nestjs/common';
import { JwtModule } from '@nestjs/jwt';
import { PassportModule } from '@nestjs/passport';
import { UsersModule } from '../users/users.module';
import { AuthController } from './auth.controller';
import { AuthService } from './auth.service';
import { JwtStrategy } from './jwt.strategy';
import { LocalStrategy } from './local.strategy';

@Module({
  imports: [
    PassportModule,
    JwtModule.register({
      secret: 'Hello_Community',
      signOptions: { expiresIn: '300s' }
    }),
    UsersModule
  ],
  controllers: [AuthController],
  providers: [AuthService, LocalStrategy, JwtStrategy],
  exports: [AuthService]
})
export class AuthModule {}

auth.module.ts

After all this, some explanations are mandatory. Let’s start with the controller...

When calling the /login endpoint, the user will "POST" his credentials in email / password format.

Then, NestJS will protect the route by the LOCAL "guard" which will take care of checking the user presence into the database. If the user with the unique email address is found, the password will then be checked by bcrypt (auth.service.ts).

If things go well, the login() function will be played with the information relating to the user (especially the unique identifier and the email) which will be necessary to generate a token with 5 minutes (300s) validity.

Finally, at the endpoint return, you should retrieve a JWT token (access_token) which will authenticate the other calls of your REST API. To do this, two final things:

Add the JWT "guard" on the /users/:id endpoints (users.controller.ts)
Add the Bearer <token> in the header of the call(s)

P R I S M A

Now let's talk about the data part. From now on, you will have to connect to your database (previously installed on your machine: sudo apt install postgresql), then query it in a REST(ful) way, namely with GET, POST, PATCH, DELETE, etc...

One last time, a difficult choice is required, between:

The database driver (low level query)
The "Query Builder" (such as KnexJS)
The ORM - Object Relational Mapping (high level query)

NB: As an example, with MongoDB, I used to develop with Mongoose (which is an ODM - Object Document Mapper) to query my NoSQL data source. Having made the choice of SQL with Postgres, it will be essential to use a new library...

Don't panic! NestJS is here 🎉 And it already has "connectors" for some libraries, including: Sequelize, TypeORM or even Prisma. I preferred to exclude Sequelize from the challengers list (despite its popularity), since I want to be able to re-use the "chosen one" for future development with NoSQL (I can't live without Mongo 😅). In fact, the only possible choice is none other than Prisma. By the way, I was pleasantly surprised by its concept and its intuitive API! It's time to install this new dependency, and then initialize the database schema.

npm install prisma --save-dev
npx prisma init

By executing Prisma's init command, you should see a new folder appear at the root of your project, with a first draft of the schema. I invite you to complete it as follows:

datasource db {
  provider = "postgresql"
  url      = "postgresql://<username>:<password>@<host>:<post>/hello-community?schema=public"
}

generator client {
  provider = "prisma-client-js"
}

enum Gender {
  X
  Y
}

model User {
  id        String  @id @default(uuid())
  email     String  @unique
  password  String
  firstName String?
  lastName  String?
  gender    Gender
}

schema.prisma

As explicit as it is, the database schema will allow you to initialize your PostgreSQL database. Clearly, by executing this last one (with the migrate command), Prisma will transcribe the information above in SQL script, to create your tables (with the right fields and the right types) and add your relations (primary and foreign keys). It will eventually run the query directly into the database.

npx prisma migrate dev --name init

NB: From there, your base is created. You can connect to it and see the result; or take a look at the SQL query present in the migration.sql file (in the prisma folder).

npm i @prisma/client
nest g module prisma
nest g service prisma

The database is properly created, but you still have to make the link between PostgreSQL (via Prisma) and NestJS. Using the NestJS CLI tool (above), I generated two new files:

prisma.module.ts
prisma.service.ts

import { Module } from '@nestjs/common';
import { PrismaService } from './prisma.service';

@Module({
  providers: [PrismaService],
  exports: [PrismaService]
})
export class PrismaModule {}

prisma.module.ts

import { Injectable, OnModuleDestroy, OnModuleInit } from '@nestjs/common';
import { PrismaClient } from '@prisma/client';

@Injectable()
export class PrismaService extends PrismaClient implements OnModuleInit, OnModuleDestroy {
  async onModuleInit() {
    await this.$connect();
  }

  async onModuleDestroy() {
    await this.$disconnect();
  }
}

prisma.service.ts

One last step: usage! Do you remember your CRUD above? Let's make it evolved! Now, there is no longer any question of simulating your database, let's request it directly. For that, the Prisma API is simply magical! It generates (thanks to the database schema) the types corresponding to models, and provides you with intuitive functions to query your SQL database. See for yourself the result with functions for creating and retrieving a user.

NB: Don't forget to register your new module (prisma.module.ts) in the users module imports, otherwise it's impossible to request your data source...

import { HttpException, HttpStatus, Injectable } from '@nestjs/common';
import { User, Prisma } from '@prisma/client';
import * as bcrypt from 'bcrypt';
import { PrismaService } from '../prisma/prisma.service';

@Injectable()
export class UsersService {
  constructor(private prisma: PrismaService) {}

  // ...

  async findOne(id: string): Promise<User> {
    const user = await this.prisma.user.findUnique({ where: { id } });
    if (user) return user;
    throw new HttpException('No User Found', HttpStatus.NOT_FOUND);
  }

  // ...

  async create({ password, ...userCreateInput }: Prisma.UserCreateInput): Promise<{ createdId: string }> {
    const salt = await bcrypt.genSalt();
    const hash = await bcrypt.hash(password, salt);

    const user = await this.prisma.user.create({
      data: {
        password: hash,
        ...userCreateInput
      }
    });

    return { createdId: user.id };
  }

  // ...
}

users.service.ts

NB: For practical reasons (prevent the size of this post from growing fast), I present here only two functions present in the service, but you can consult the rest of the code on GitHub.

E p i l o g u e

NestJS is a little nugget of Web development! I had a lot of fun developing this new backend solution in TypeScript. Everything is very well structured. By the way, the CLI is a great help when it comes to scaffold all or part of a REST resource.

Overall, I was pleasantly surprised by its organization, which makes me think of the frameworks such as SpringBoot (for Java) or Django (for Python). The files are stored in their place and you find yourself there. It just goes to show that the MVC pattern is always a safe bet...

NB: In a more objective way, I asked the opinion of another developer specialized in Java, and I assure you, he had no problem to immerse himself in the code (thanks to TypeScript).

Speaking of security, NestJS respects its part of the contract without reinventing things, since it relies mostly on the Passport dependency to consolidate its endpoints. It can also define the HTTP headers security by simply integrating middlewares provided by the Helmet library. The same for encryption and data hashing, these concepts aren't new and exist in other backend frameworks as well.

I didn't talk about unit tests previously, but they are present in this project. NestJS also makes a good choice by "dropping" the Karma / Jasmine pair in favor of Jest. It's very easy to mock Prisma data sources, to focus on controller calls, or on the function of a service.

By having powerful concepts and well-done documentation NestJS stands out as a reference in backend JavaScript development. It's a customizable framework (by embracing the ExpressJS engine, or switching to that of Fastify), and yet very complete with its lots of plugins, such as the possibility to add OpenAPI documentation via Swagger, or add GraphQL abstraction to your REST(ful) calls, etc...

In the future, I'll not longer hesitate in my choice of technical base for NodeJS, I'll simply opt for NestJS 👍

S o u r c e C o d e

https://github.com/dmnchzl/hellocommunity