DEV Community: Philipp Rich

Feature sliced design vs clean architecture

Philipp Rich — Wed, 23 Jul 2025 12:04:27 +0000

Introduction

This post is an extension of my previous article about clean architecture
implementation in React. In this post, I'm going to compare Feature-Sliced Design
with Clean Architecture to better understand the topic myself.

Feature-Sliced Design Summary

FSD is a modern architectural methodology for frontend which claims to be more practice-oriented
in contrast to "theoretical" (as some say) Clean Architecture or Domain-Driven Design.
I personally see FSD as an attempt to combine technical-based layers with
domain-based slicing and focus on a front-end part, rather than a whole system.

According to FSD, an app is divided by 6 technical (I see them more as technical) Layers, then each Layer
is divided by domain-based Slices, and finally, each Slice is divided by technical-based Segments.

Source: feature-sliced.github.io

Similar to traditional layered architectures, FSD enforces its layer dependency rules.

The trick with layers is that modules on one layer can only know about and import from modules from the layers strictly below.

Slices cannot use other slices on the same layer, and that helps with high cohesion and low coupling.

I think that the trickiest part is to decide in which layer, slice, and segment specific code should belong.
Even official FSD examples had multiple iterations with slightly different slicing logic.
But it also has benefits by providing such flexibility.

Flow of Development

I think FSD and Clean Architecture have opposite development flows. Clean Architecture
is usually explained as business-domain oriented, meaning that development starts with
defining domain model entities, followed by application use cases, and ending up at the UI part
on the framework layer. In contrast, FSD, being front-end oriented, follows a "pages-first" philosophy, meaning that
development starts from application pages and ends up in a shared core.
I guess FSD can be seen as a part of Clean Architecture. And the whole system will have 2 development flows (top-down, bottom-up) pointing to each other:

Layer Isolation

As far as my research goes, Clean Architecture explicitly describes the necessity
of dependency injection to adhere to the Dependency Inversion Principle of SOLID.
In my Clean Architecture implementation
I used composition root to prevent direct dependencies between clean architecture layers.

On the other hand, FSD does not address the Dependency Inversion Principle. FSD does not
restrict direct imports (if imported modules are on underlying layers), which in
theory might increase coupling.

Implementation

When I started this article, I planned to create a "hello world" example, like I did with
Clean Architecture previously. However,
I realized that it isn't worth it for the following reasons:

There is a large collection of FSD example projects, which are better than my simple "hello world."
According to FSD's page-first philosophy, the best way to implement my simple example (explained in my Clean Architecture post) is to place everything in the Pages layer, because my example does not have shared logic and has only a single page. Also, there are a lot of questions regarding the slicing logic of an app, which is not strictly defined by FSD. Thus, I'm just going to briefly explain how I would implement my feature:

└── 📁src
    └── 📁app
        ├── app.ts
    └── 📁pages
        └── 📁homepage
            └── 📁ui
                ├── Homepage.tsx
            └── 📁model
                ├── Notebook.ts
            └── 📁api
                ├── notebookTauriRepository.ts
            └── index.ts
    └── vite-env.d.ts

app/App.tsx: Entry point to the application. Traditional React's App.tsx.
homepage/ui/Homepage.tsx: Self-explanatory. Here will be the page which should display the notebook's name. It directly imports methods from the model segment to get the notebook's name.
homepage/model/Notebook.ts: Here might be what I placed in an application layer in FSD: methods for getting notebook's data, for example, Notebook.getNotebookName().
homepage/api/notebookTauriRepository.ts: Is a kind of adapter to the Tauri file reader mechanism. It will read the file, pass the result to Notebook.getNotebookName(), which will extract the notebook's name and pass it to the homepage.

So, a primitive feature requires only a single layer. Separation will be needed if there is
shared code. For example: if an app has 3 pages and every page requires access to notebook data, then
notebookTauriRepository.ts might be moved to the widgets layer. If there are multiple widgets which require
notebookTauriRepository.ts, then it might be moved to the features layer and so on, up to the shared layer.

Afterword

FSD is quite an unconstrained framework, giving very few strict rules and varying
pretty much even in simple examples. FSD tries to adhere to the natural front-end development flow.
The main worry I have is that it does not address the Dependency Inversion Principle,
which in theory creates tight coupling between layers. If shared UI is changed,
then all the imports in upper layers should be fixed, making it look like shotgun surgery.

References

Happy coding!
Feedback is appreciated.

How to apply clean architecture in React app

Philipp Rich — Thu, 10 Jul 2025 18:03:36 +0000

Introduction

This article is an attempt to consolidate my explorations of the clean architecture.
It's goal is to provide a hello-world implementation of the clean architecture.
The example, used in this article is a simplified scenario I have in savings notebook app I'm currently working on.
The example source code available at GitHub

Prerequisites

Basic knowledge of React, TypeScript and Classes

Summary of Clean Architecture

If you haven't explored a topic of the Clean Architecture yet, look at the articles I
attached at the references section. They describe it much better then I would, thus
I'm going to focus on consolidation and application of clean architecture.

Clean Architecture is a type of Layered Architecture which is based on a variety of layered architectures such as
Hexagonal or Onion. One of the key purpose of layered architectures is to separate a system into
individual layers with a loose coupling between them. This separation leads to better maintainability of a system and
ease of replacement of it's parts. For example, if application is built with a layered architecture in mind,
changing it's database fom MongoDB to MySql should not require rewriting half of an application's codebase.

To facilitate separation between the layers, the layered architecture enforces the dependency rule.
Dependency rule restricts layers to depend on each other. And a common pattern to satisfy
a dependency pattern is a dependency injection.

Layers

In Clean Architecture there are 4 layers:

Enterprise business rules Also referred to as a domain model. This is where the core entities are defined
Application business rules Sometimes seen as a part of a domain layer, which separated into model and application. In this layer the application use cases are defined
Adapters This layer serves the bridge between frameworks and application business rules and serve the main idea of separation of layers
Frameworks This layer is a representation of external services the app is using. For example database or ui library. Yes, react will be a part of framework layer.

The dependency rule manifest that the layers may depend only on inner layers. For example,
application business rules must not import the modules, related to database management(frameworks layer)

// application-layer/useCases.ts

import { Notebook } from "@domain";
import mongoose from "mongoose" // we must not import specific DB mechanism here, because it relates to an outer layer

/*
* UseCase to return Notebook
*/
class GetNotebook {
    constructor(private notebookMongoose: mongoose) {}

    async execute() {
        await this.notebookMongoose.connect...

        ...

        return new Notebook(name, creationDate);
    }
}

Flow of control

In the clean architecture the common control flow
of the app starts at the outer layer(usually GUI or CLI interface), and proceeds to another parts of outer layer(ie database) via inner layers.

Source: https://crosp.net/blog

Scenario description

My app is an android savings notepad build with react and tauri. Notebook is an entity,
where user's balances are stored. For the sake of simplicity in this example it will have
only name and creationDate properties. Notebook's data is stored locally and accessed
via tauri plugin-fs. It will be mocked in this example.

I'm going to implement a simplest scenario in which the name of a Notebook will be
displayed on a page.

Project structure

The project were divided into clean architecture layers. index.ts is just an API,
which re-exports its folder content

└── 📁src
    └── 📁0-domain-model
        ├── index.ts
        ├── notebook.ts
    └── 📁1-application
        ├── index.ts
        ├── ports.ts
        ├── useCases.ts
    └── 📁2-adapters
        ├── index.ts
        ├── notebookController.ts
        ├── tauriNotebookRepository.ts
    └── 📁3-frameworks
        └── 📁services
            ├── index.ts
            ├── tauriFileReader.ts
        └── 📁ui
            ├── App.tsx
            ├── index.css
            ├── main.tsx
    ├── composition.ts
    └── vite-env.d.ts

Domain model

Domain model must not depend on any other layer, so in Notebook module there is
no imports.
In this example classes will be used, however clean architecture itself does not
imply the necessity to use OOP. Objects or closures or other structures can be
used to implement it as well.

// domain-model/notebook.ts

class Notebook {
    // this syntax automatically assigns name and creationDate to `this.name` and `this.creationDate`
    constructor(
        public name: string,
        public creationDate: number,
    ) {}
}

export { Notebook };

Application layer

I'm going to start with creating the useCase, which needs to return the notebook entity:

//application/useCases.ts

import { Notebook } from "@domain"; // Clean architecture allows to depend on inner layer

type GetNotebookInterface = {
    execute: () => Promise<Notebook>;
};

class GetNotebook implements GetNotebookInterface {
    async execute() {
        console.log(
            `[Application layer] GetNotebook is executing and creating instance of domain class...`,
        );
        // ...
        return new Notebook(name, creationDate);
    }
}

In order to work, this useCase requires to read the data of a notebook, which is stored in filesystem.
I have a mock of specific tauri plugin which pretends to read the data from an android device.
It requires fileUri and returns a string content of a file. It represents external module,
provided by tauri framework, which I can't change and gonna use as it is.

class TauriFileReader {
    readFile(fileUri: string): Promise<string> {
        console.log(
            `[Framework layer] tauriFileReader reads file from ${fileUri}...`,
        );
        const fileData = "NotebookName,1751969945";
        return new Promise((res) => setTimeout(() => res(fileData), 450));
    }
}

export const tauriFileReader = new TauriFileReader();

The naive way to make GetNotebook use case work is to import tauriFileReader:

// application/useCases.ts

import { Notebook } from "@domain";
import { tauriFileReader } from "@tauri"; // Clean architecture forbids importing from external layers

type GetNotebookInterface = {
    execute: () => Promise<Notebook>;
};

class GetNotebook implements GetNotebookInterface {
    constructor(private notebookReader: tauriFileReader) {} 
    async execute() {
        console.log(
            `[Application layer] GetNotebook is executing and creating instance of domain class...`,
        );
        const notebookData = await this.notebookReader// ...
        // ...
        return new Notebook(name, creationDate);
    }
}

However, it will violate the Rule of dependencies, making application layer dependent on
specific data retrieval mechanism. Imagine the situation: app grows and you need to add
a new feature - cloud sync, so notebook will be retrieved not via tauriFileReader but from
ModngoDb via mongoose. You will need to edit a use case and rewrite it's logic:

- import { tauriFileReader } from "@tauri";
+ import mongoose from "mongoose";

This is what layered architecture and a concept of loose coupling try to avoid. Ideally,
inner layers of application should not change. It is implied that they are covered by tests
and changing everything is very expensive and counter-productive.

Clean architecture way to make GetNotebook use case work with tauriFileReader
is to specify the port, which is used by GetNotebook

Port is an entry or exit point of an application. This is an interface which is
defined at the application layer which specify which external services (like tauriFileReader)
the app requires to work.

However a port should not point to a concrete service (like tauriFileReader)
and instead should point to an abstraction. This aligns with a dependency inversion principle

I'm going to specify the port as a TypeScript interface. To define the port I should rely
on the GetNotebook needs, rather than on tauriFileReader implementation. To return Notebook
instance, GetNotebook require name and creationDate - this is what I will specify
as a desired output of abstract external component (this component is actually an adapter),
the use case depends on.

// application/ports.ts

/**
 * Output port for service, which gets Notebook from somewhere.
 */
export type NotebookRepositoryPort = {
    readNotebook: () => Promise<{ name: string; creationDate: number }>;
};

// application/useCases.ts

import { Notebook } from "@domain";
import type { NotebookRepositoryPort } from "./ports"; // port is defined in the same layer, so the dependency rule is not violated

class GetNotebook {
    constructor(private notebookRepository: NotebookRepositoryPort) {}

    async execute() {
        console.log(
            `[Application layer] GetNotebook is executing and creating instance of domain class...`,
        );
        const { name, creationDate } = await this.notebookRepository.readNotebook();
        return new Notebook(name, creationDate);
    }
}

Adapters

Adapter layer connects application layer with external services (framework layer).
Adapter depends on application port on the one side and concrete service
on the other side.

tauriNotebookRepository must implement the interface NotebookRepositoryPort,
specified in the application layer. This adapter requires external service TauriFileReader
and this case is identical to previous one from the application layer: I can not import
TauriFileReader directly from outer layer to meet the rule of dependencies. And I
will just specify the interface of this service.

TauriFileReader requires uri which I mocked for simplicity. I specified uri
only inside the adapter, because it is related to specific data retrieval mechanism and
inner layer should not depend on it.

// adapters/tauriNotebookRepository
import type { NotebookRepositoryPort } from "@application"; // imports from inner layers allowed

/**
 * Mocked uri
 * In a real world scenario we would get it from somewhere, for example from
 * user's config in localStorage.
 *
 * It's important to not pass this uri to methods related to inner layers.
 * For example we should not pass this uri from a UI form directly to the `useCase`
 * because it will make `useCase` depend on external `tauriFileReader`.
 * Imagine if we gonna replace this specific local file reader mechanism with
 * mongoDb, which will not need uri, but will need another parameters to work.
 */
const fileUri = "our/file/uri";

type FileReaderInterface = {
    readFile(uri: string): Promise<string>;
};

/**
 * Secondary (driven) adapter which access Notebook content via
 * specific mechanism `tauriFileReader`
 */
class TauriNotebookRepository implements NotebookRepositoryPort {
    constructor(
        private fileReader: FileReaderInterface,
        private uri = fileUri,
    ) {}

    async readNotebook() {
        console.log(
            `[Adapters layer] TauriNotebookRepository is executing readNotebook()...`,
        );
        const notebookData = await this.fileReader.readFile(this.uri);

        // adapter performs some logic to manipulate external service output
        // and outputs result in a format, required by application's port
        // (NotebookRepositoryPort)
        const [name, creationDate] = notebookData.split(",");
        return {
            name,
            creationDate: Number(creationDate),
        };
    }
}

export { TauriNotebookRepository };

Controller

So far I defined:

Notebook entity in the model layer
getNotebook use case and its NotebookRepositoryPort in application layer
TauriNotebookRepository adapter in adapters layer
tauriFileReader as an external service in framework layer

The application flow of control starts at application layer, and ends at tauriFileReader

The remaining part is to connect UI with a getNotebook use case. Use case will be invoked
from ui with a standard useEffect:

// framework/ui/App.tsx

import { useEffect, useState } from "react";
// import { getNotebook } ??

function App() {
    const [name, setName] = useState<string | null>(null);

    useEffect(() => {
        async function getNotebookName() {
            console.log("[Framework layer] UI event calls the controller");
            const notebookName = await getNotebook.execute().name;
            setName(notebookName);
        }

        try {
            getNotebookName();
        } catch {
            console.error("Error happened while getting the name");
        }
    });

    if (!name) return <p>Loading...</p>;
    return <p>The notebook's name is {name}</p>;
}

export default App;

However it is common not to call use case directly, but use a controller, which is
a part of adapters layer. And just like with NotebookRepository adapter, it is required
to specify a port for it in application layer.

// application/ports.ts

/**
 * Input port for controller, which requests Notebook data
 */
export type NotebookControllerPort = {
    getNotebookName: () => Promise<string>;
};

notebookController must satisfy newly defined port and requires getNotebook
use case to run. To loosen the coupling, getNotebook interface must be used
instead of useCase itself.

// adapters/notebookController.ts

import type {
    GetNotebookInterface,
    NotebookControllerPort, 
} from "@application"; // it is ok to import from inner layer

/**
 * Primary (driving) adapter. Executes specific useCase (can be multiple usecases)
 * In this example it formats output in some way.
 */
export class NotebookController implements NotebookControllerPort {
    constructor(private getNotebookUseCase: GetNotebookInterface) {}

    /**
     * @returns notebook name in upper case
     */
    async getNotebookName() {
        console.log(
            `[Adapters layer] NotebookController is executing getNotebookName()...`,
        );
        const notebook = await this.getNotebookUseCase.execute();

        return notebook.name.toUpperCase();
    }
}

Finally, I can import notebookController, but again, I must follow dependency inversion principle
and avoid dependency on a concrete implementation of notebookController and depend on
interface. I created separate component which takes controller with NotebookControllerPort
interface in props. In real world scenario it might be better ways to pass this dependency,
but i'm trying to implement canonical clean architecture in the most simple way.

// framework/ui/NotebookCard.tsx

import type { NotebookControllerPort } from "@application"; // import from inner layer is fine
import { useEffect, useState } from "react";

export function NotebookCard ({notebookController}: {notebookController: NotebookControllerPort}) {
  const [name, setName] = useState<string | null>(null);

    useEffect(() => {
        async function getNotebookName() {
            console.log("[Framework layer] UI event calls the controller");
            const notebookName = await notebookController.getNotebookName();
            setName(notebookName);
        }

        try {
            getNotebookName();
        } catch {
            console.error("Error happened while getting the name");
        }
    });

    if (!name) return <p>Loading...</p>;
    return <p>The notebook's name is {name}</p>;
}

Now, flow of an application starts at the UI in framework layer, flow through inner layers
and ends at the fileReader in framework layer.

Bringing all together

I ended up with a collection of loosely coupled modules. But the application will
not work because defined modules requires concrete implementations of their dependencies,
which I did not pass to them. To bring all the pieces together, I need use
composition root. It is a place often at the entry point of an app, where all the actual dependencies
is injected in their consumers. Composition root does not conceptually relates to any of architecture
layers mentioned before

// composition.tsx
import { NotebookController, TauriNotebookRepository } from "@adapters"; // TS module "/Users/philipp/Documents/GitHub/clean-architecture-feature/src/2-adapters/index"
import { GetNotebook } from "@application";
import { tauriFileReader } from "@frameworks/services";
import { NotebookCard } from "@frameworks/ui/NotebookCard";

/*
This is an example of manual dependency injection.

Automatic dependency injection techniques, like dependency injection container 
might be used. 

For js/ts there are inversifyJs and ts-loader libraries for automatic
dependency injection
*/

const notebookRepository = new TauriNotebookRepository(tauriFileReader);
const getNotebook = new GetNotebook(notebookRepository);
const notebookController = new NotebookController(getNotebook);

export function NotebookContainer() {
    return <NotebookCard notebookController={notebookController} />;
}

To complete this example, I import NotebookContainer with all injected dependencies in App:

// framework/ui/App.tsx

import { NotebookContainer } from "../../composition";

function App() {
    return <NotebookContainer />;
}

export default App;

The result

App working as expected, returning:

The notebook's name is NOTEBOOKNAME

And console illustrates the expected flow of control:

[Framework layer] UI event calls the controller...
[Adapters layer] NotebookController is executing getNotebookName()... 
[Application layer] GetNotebook is executing and creating instance of domain class...
[Adapters layer] TauriNotebookRepository is executing readNotebook()...
[Framework layer] tauriFileReader reads file from our/file/uri...

In current implementation, the parts of a system can be easily replaced without the need
of rewriting the other parts. For example to replace tauriFileReader with mongoDbAPI it only
required to create new MongoNotebookRepository adapter and inject it in a composition root.
Application layer, domain layer and other parts of adapters layer will not need any changes.

References

Happy coding!

I built open-source app to stop micromanaging my finance

Philipp Rich — Fri, 23 May 2025 12:13:08 +0000

Throughout my life, I've tried to get on top of my finances and understand my financial performance. I experimented with numerous finance tracker apps, but none of them truly worked for me.

The main issue was their demand for regular input—logging expenses, scanning receipts, categorizing transactions, and tracking goals. This felt like a burden, and I soon realized that I don't need to micromanage my transactions.

It's pointless for me to know if this week's spending is higher than last week's, or if I spent more on clothes this month than usual. What I truly want is a high-level overview of my savings. Did my wealth increase over the year? Is it worthwhile to diversify savings between CNY and USD? What's the total of my savings spread across several banks, brokers, and crypto-wallets?

To answer these questions, I don't need to track every financial detail; I just need to record my savings monthly, or even at longer intervals. This realization led me to create a simple Google Spreadsheet where I recorded my savings every month or two.

I was very happy with the result: it took me just 10 minutes per month to update my current savings (by editing existing records instead of starting from scratch), and I gained a clear overview of my savings. I could see my total savings in various currencies, their distribution, how much I had left in the country I immigrated from, and whether my money was "working" or just sitting in non-deposit accounts.

From Spreadsheet to App

Initially, I moved all the spreadsheet logic into a web app. I used this app for a few years and then decided to share it with the world. However, distributing a free web app proved tricky. I still had to maintain the infrastructure and worry about saving sensitive user data in MongoDB. That's why I decided to evolve it into a standalone Android app.

So, I started developing an open-source Android version of this app. All data is stored directly on your device, and you can even use it with other tools like spreadsheets for further analysis.

It's in the early stages of development, but you can already start creating your savings notepad.

Small demo: https://youtu.be/abH2uFe2hh0?si=PGXfDr_ZygNBuBfq

Apk available at github: https://github.com/skorphil/savnote/releases/tag/0.5.0

Your feedback is welcome, and feel free to contribute if you're interested!

Tauri File Management on Android

Philipp Rich — Mon, 10 Mar 2025 17:03:32 +0000

How to implement file management in a Tauri-based Android app.

Introduction

Recently, I decided to revive an old project of mine—a personal savings journal. Initially built with Next.js and MongoDB Atlas, this setup required database maintenance and hosting, which felt excessive for such a small application. Additionally, sharing it with the community was challenging, leaving me as the sole user.

My new idea is to develop an offline, mobile-first app that stores all user data locally. This approach eliminates the need for infrastructure maintenance and allows for easy distribution as an Android app (an iOS developer account is too costly for a non-profitable, open-source app).

My research led me to the Tauri framework, a lightweight alternative to Electron. To finalize my tech stack decision, I started by implementing the riskiest and least familiar feature: saving and reading data on an Android device. During this exploration, I wrote an article and created a playground app for experimenting with file management in Tauri.

Tauri Overview

Tauri is a cross-platform framework similar to Electron. Its main advantage is the use of native web views, which reduces the package size significantly—around 30MB for a simple React app. However, this might present challenges for more complex applications. As a JavaScript developer, the primary drawback for me is Tauri's Rust backend, making it tricky to write backend logic. Fortunately, my app only requires saving and reading a local database, so I decided to give it a try.

Setting Up a Project

Starting a new project was straightforward. Refer to the official documentation or check out my playground repo. The most challenging part was setting up PATH variables and installing additional Android SDK packages after installing android-studio:

Install ndk within android-studio: Settings > Languages & Frameworks > SDK Tools.
Set the NDK_HOME and ANDROID_HOME PATH variables (ANDROID_HOME is visible in Settings > Languages & Frameworks):

export ANDROID_HOME=YOUR_PATH/Android/sdk
export PATH=$ANDROID_HOME/cmdline-tools/latest/bin:$ANDROID_HOME/platform-tools:$PATH

export NDK_HOME=$ANDROID_HOME/ndk/29.0.13113456
export PATH=$PATH:$NDK_HOME

Initialize the Android project:

pnpm tauri android init

After completing these steps, pnpm tauri android dev worked seamlessly, launching the Android emulator or using a connected phone.

Tauri File Management Plugins

Tauri offers several official plugins for file system manipulation:

The file-system plugin is designed for silently reading and writing files, while the dialog plugin explicitly asks the user to pick a file using the system file explorer.

Tauri Capabilities

Capabilities | Tauri

Configuring permissions for plugins was the most frustrating part. Tauri limits permissions by default, requiring manual specification of locations and permissions for the file-system plugin. Restarting the dev server was necessary after changing capabilities, and error messages were often unclear, making it difficult to determine whether the issue was with capabilities configuration or Android permissions.

Silently Managing Files

In my playground project, I created <ReadFileCard>, <ReadFilePath>, and <WriteFileCard> components to experiment with file management. Reading and writing files is straightforward:

import { readTextFile } from "@tauri-apps/plugin-fs";

async function readTxtFile(fileName: string) {
  const file = await readTextFile(fileName);
  // or using BaseDirectory (look at docs)
  return file;
}

The baseDirectory mapping to the Android file system is not obvious. Some paths map as follows:

BaseDirectory.Home points to the external shared directory: /storage/emulated/0
BaseDirectory.LocalData, BaseDirectory.AppData, and others point to internal private storage: /data/user/0/com.myapp.app
BaseDirectory.Document points to internal shared storage: /storage/emulated/0/Android/data/com.myapp.app/documents

As a user, I could only access /storage/emulated/0/* with the built-in file manager, while /storage/emulated/0/Android/data/ showed no paths. However, it was accessible via adb shell.

Android Limitations

You cannot create files or folders directly in ExternalStorage. Instead, use directories like Documents, Download, Pictures, or Videos. For example, use /storage/emulated/0/Documents/MyFolder/file.txt instead of /storage/emulated/0/MyFolder/file.txt.

On Android 10 and above, you can create files and folders in these directories without permissions, but you cannot read files created by other apps. In this case, use a dialog to read the files.

For Android 9 and earlier, the app must explicitly ask for user permission to access files in Documents, Downloads, etc. To access files in /storage/emulated/0/ on any Android version, the app must explicitly ask for user permission.

Currently, Tauri does not provide a plugin for requesting user permission to access external storage. Therefore, I changed the minimum supported Android version to 10:

// src-tauri/tauri.conf.json
"bundle": {
+   "android": {
+      "minSdkVersion": 29
+   }
}

Capabilities

To work with /storage/emulated/0/Documents/*, configure the capabilities as follows:

// src-tauri/capabilities/default.json
{
  "identifier": "fs:allow-write",
  "allow": [
    {
      "path": "$HOME/Documents/*"
    }
  ]
},
{
  "identifier": "fs:allow-create",
  "allow": [
    {
      "path": "$HOME/Documents/*"
    }
  ]
},
{
  "identifier": "fs:allow-read-text-file",
  "allow": [
    {
      "path": "$HOME/Documents/*"
    }
  ]
}

Explicitly Managing Files

In my playground project, I created <ReadExtFileCard> and <WriteExtFileCard> components to experiment with file management using the dialog plugin. This plugin does not require additional permissions and allows access to any file the user selects in the file explorer. For example, to read a file using both dialog and file-system plugins:

import { open } from "@tauri-apps/plugin-dialog";
import { readTextFile } from "@tauri-apps/plugin-fs";

...

onClick={async (e) => {
  try {
    const directory = await loadExtFile(); // `dialog` returns selected path
    const content = await readTxtFile(directory); // Now file system plugin has permissions to selected path
    setState(`File: ${directory} content: ${content}`);
  } catch (error) {
    setState(error as string);
  }
}}

...

async function loadExtFile() {
  const path = await open({
    multiple: false,
    directory: false,
  });
  return path;
}

async function readTxtFile(fileName: string) {
  const fileContent = await readTextFile(fileName);
  return fileContent;
}

Check out playground app: https://github.com/skorphil/tauri-fs-android-starter

Happy coding!

Migrating to React Router Framework: Challenges Beyond the Official Guide

Philipp Rich — Thu, 27 Feb 2025 10:25:50 +0000

My experience migrating from React Router library to the framework and the challenges missing from the official guide.

Motivation and tech stack

My small side project pixenum.com initially was a purely client SPA based on React and React Router(library mode).
I used Vite and Yarn Berry with PnP. For state management I used Redux.
This architecture comes with a cost of poor SEO. Traditional client side SPAs use an index file with minimum content in it, like this:

// index.html
...
    <body>
        <div id="root"></div>
    </body>
</html>

Content then being loaded from .js scripts. But search engines crawl only a static content from .html, which is not present in case of a clien-side SPA.

To address this issue I aimed to divide my project into 2 parts:

/ pre-rendered static(SSG) landing page for better SEO
/app actual app, which is a client-based(CSR) SPA

I saw several possible options, how to do this:

Create a separate package for the landing page on a static-site oriented framework, like Astro or React with a Vite plugin vite-react-ssg
Migrate to React Router Framework and specify / as a SSG route, while leave /app as a CSR route.

Starting point

Official migration docs: https://reactrouter.com/upgrading/component-routes

Instead of reiterating the migration guide, I'll focus on the specific challenges I encountered that were not covered.

PnP and RR Framework (isbot not found)

After following first part of migration guide i faced with dependency issue:

Cannot find module 'isbot' imported from 'MYPROJECT/.yarn/__virtual__/@react-router-dev-virtual-86a2f80477/4/.yarn/berry/cache/@react-router-dev-npm-7.2.0-2cf33a3d6a-10c0.zip/node_modules/@react-router/dev/dist/config/defaults/entry.server.node.tsx'

It appeared that Yarn PnP was not including isbot due to the absence of an entry.server.tsx (which was not explicitely mentioned in migration guide).
To create default entry.server.tsx I called yarn run react-router reveal and this resolved problem with dependency.

SSL and RR Framework (":method" is an invalid header name)

After creating entry.server.tsx I got another issue:

[vite] Internal server error: Headers.set: ":method" is an invalid header name.
      at Object.webidl.errors.exception (node:internal/deps/undici/undici:3564:14)
      at Object.webidl.errors.invalidArgument (node:internal/deps/undici/undici:3575:28)
      at _Headers.set (node:internal/deps/undici/undici:8814:31)
      at fromNodeHeaders (MYPROJECT.yarn/__virtual__/@react-router-dev-virtual-86a2f80477/4/.yarn/berry/cache/@react-router-dev-npm-7.2.0-2cf33a3d6a-10c0.zip/node_modules/@react-router/dev/dist/vite.js:879:17)
      at fromNodeRequest (MYPROJECT/.yarn/__virtual__/@react-router-dev-virtual-86a2f80477/4/.yarn/berry/cache/@react-router-dev-npm-7.2.0-2cf33a3d6a-10c0.zip/node_modules/@react-router/dev/dist/vite.js:895:14)
      at nodeHandler (MYPROJECT/.yarn/__virtual__/@react-router-dev-virtual-86a2f80477/4/.yarn/berry/cache/@react-router-dev-npm-7.2.0-2cf33a3d6a-10c0.zip/node_modules/@react-router/dev/dist/vite.js:2768:30)
      at MYPROJECT/.yarn/__virtual__/@react-router-dev-virtual-86a2f80477/4/.yarn/berry/cache/@react-router-dev-npm-7.2.0-2cf33a3d6a-10c0.zip/node_modules/@react-router/dev/dist/vite.js:2775:23
      at processTicksAndRejections (node:internal/process/task_queues:105:5)

This was traced back to the Vite SSL plugin used for authentication testing. The issue was resolved by either disabling SSL during development or adding proxy parameters to the Vite configuration:

// vite.config.ts

export default defineConfig({
  plugins: [
    reactRouter(),
    basicSsl({ // this is the cause of error
      name: "test",
      domains: ["*.custom.com"],
      certDir: "/Users/.../.devServer/cert",
    }),
  ],
 ...
  server: {
    proxy: {}, // this is solution
  },
});

Further information on this issue can be found here: https://github.com/remix-run/remix/issues/10445

Client side logic issues

After including my <App /> into catchall.tsx (following migration guide) and running react-router dev I encountered an ERR_UNHANDLED_REJECTION in the client component:

node:internal/process/promises:392
      new UnhandledPromiseRejection(reason);
      ^

Debugging with VS Code revealed a problem with Dexie, specifically a DexieError. This client-side code, used for accessing IndexedDB, was unexpectedly running on the server.
This occurred because the RR framework pre-renders even in spa-mode when ssr: false:

It's important to note that setting ssr:false only disables runtime server rendering. React Router will still server render your root route at build time to generate the index.html file. This is why your project still needs a dependency on @react-router/node and your routes need to be SSR-safe.
https://reactrouter.com/how-to/spa

// react-router.config.ts

export default {
  appDirectory: "src",
  ssr: false,
} satisfies Config;

To resolve this I made my routes to be SSR-safe as mentioned in RR docs. In my case I just added if statement to function which is accessing IndexedDB
This was a part of my Redux store initialization logic.

// store.ts
if (typeof window !== "undefined" && !import.meta.env.SSR) {
  storeInitialize(store); // Function access indexedDB under the hood
}

Setting routes (move away from catchAll.tsx)

With the migration guide completed, I had a functioning SPA with a single route (catchall.tsx).
To achieve my intended structure, I migrated my routes from the RR library:

// App.tsx
// Legacy config for Library mode
<BrowserRouter>
  <Routes>
    <Route path="/" element={<AppRootLayout />}>
      <Route path="book" element={<BookContainerLayout />}>
        <Route path="page/:uuid" element={<MainContainerLayout />} />
      </Route>
    </Route>
  </Routes>
</BrowserRouter>

And configured the framework routes like this:

// routes.ts
// config for Framework mode
export default [
  route("/", "./features/landing-page/components/LandingPage.tsx"),
  route("/app", "./pages/AppRootLayout.tsx", [
    route("book", "./layouts/BookContainerLayout/BookContainerLayout.tsx", [
      route(
        "page/:uuid",
        "./layouts/MainContainerLayout/MainContainerLayout.tsx"
      ),
    ]),
  ]),

// react-router.config.ts

export default {
  appDirectory: "src",
  ssr: false,
  async prerender() {
    return ["/"];
  },
} satisfies Config;

Moving providers

After configuring my routes, I encountered errors related to my providers, such as:

Error: Error: could not find react-redux context value; please ensure the component is wrapped in a <Provider>
    at onShellError (MYAPP/src/entry.server.tsx:57:18)

The question arose: where should these providers be placed?
Initially, they were defined within App.tsx:

function App() {
  return (
    <Auth0Provider
        ...
        authorizationParams={{
        redirect_uri: window.location.href, // notice client code here
      }}
    >
      <ReduxProvider store={store}>
        <AuthProvider>
            <AppRootLayout />
...

Through trial and error, it was discovered that the providers functioned correctly
when placed within the component rendered on the /app route, which in my case was AppRootLayout.tsx.
To accommodate client-side code within the <Auth0Provider> props, an empty page was returned during server-side rendering
(though a loading state could be implemented for a better user experience):

// AppRootLayout.tsx

const [isClient, setIsClient] = useState<boolean>(false);
  useEffect(() => {
    setIsClient(true);
  }, []);

  if (!isClient) return null;

  return (
    <Auth0Provider
    ...
      authorizationParams={{
        redirect_uri: window.location.href,
      }}
    >
      <AuthProvider>
        <Provider store={store}>
          // AppRootLayout original content

Applying css

Finally, I realized that CSS styles were missing in new files. To apply styling, the CSS files previously used in main.tsx needed to be imported into the newly created root.tsx:

// root.tsx

import "./index.css"; // these css where previously used in my `main.tsx`
import "./App.css";
...

Serving Issues After Build: No Matching Routes Found

At this stage, the app functioned correctly during development with react-router dev.
Aafter building with react-router build, the following files were generated:

build/
    client/
        assets/
        __spa-fallback.html
        index.html
        multiple *.png

Serving these files with sirv-cli build/client --single __spa-fallback.html, as recommended in the documentation (https://reactrouter.com/how-to/pre-rendering), resulted in the / route working as expected, but accessing /app/* produced the following console error:

No routes matched location "/app"

This error originated from useRoutesImpl() in chunk-SYFQ2XB5-D-Hkp_oB.js:

warning(
  parentRoute || matches != null,
  `No routes matched location "${location.pathname}${location.search}${location.hash}"`
);

The app displayed a fatal error message with no descriptive context:

After extensive troubleshooting, updating Vite and React Router resolved the issue:

yarn up vite
yarn up react-router

Afterword

Migrating to the RR framework proved to be a time-consuming and challenging process. Had I known the extent of the effort required, I might have opted to create a separate project for the landing page.
I hope this article provides valuable insights and facilitates a smoother migration process for others.

Happy coding!

originally posted on my blog: https://philrich.dev

Master JavaScript “this” keyword to pass job interview

Philipp Rich — Tue, 25 Jun 2024 18:00:00 +0000

Glossary

Lexical scope aka lexical context or scope.

Determines which variables and functions can be accessed by a part of a code. For example, const variable, defined inside a code block can’t be accessed outside that block.

{  
  const blockScopedVar = 1  
}  
console.log(blockScopedVar) // Error. blockScopedVar is not defined

In this example, lexical scope of console.log() does not contain blockScopedVar.

Under the hood, lexical scope is defined by lexical Environment chain.

Execution context
In simplified terms, it is an environment, in which the current function is running. JavaScript code is executed by dividing the code into ‘pieces’ and running them sequentially. These ‘pieces’ are execution contexts. Execution context created for global context and per each function call. When a function being invoked, execution context is created. Execution context contains a value of this, lexical scope, and other internal stuff required to run this function.

"this" keyword
this keyword is usually used in methods or classes, making it easy to point the function to an object’s properties we want to use. this in JS is just a reference to an object. This reference can be set:

implicitly (when a new execution context is being created)
explicitly (with call(), apply(), bind() methods).

The implicit value of this is determined by where in the code this is being used (in what context). This is causing most confusion and the way to sort this out is to know what this contexts exist and how they affect the value of this.

Implicit contexts

At the creation phase of execution context, the value of this is assigned automatically, based on where this in code is being used. Sometimes this is called this context (not to be confused with execution context or lexical context)

function executionContext1 () {  
  console.log(this.a) // `this` is used in globally invoked function context  
}  
const obj1 = {  
  a: 1,  
  executionContext2() {console.log(this.a)} // `this` is used in method context  
};  

executionContext1() // execution context with `this` pointing to global object being created to execute this function  
executionContext2() // execution context with `this` pointing to `obj1` being created to execute this function

this contexts, determining its value:

Global context (when this placed outside of functions or classes): this -> global object
Function context (when this placed inside the function)
- Globally invoked function: this -> global object
- Method: this -> object, on which method being called
- Constructor function: this -> instance object
- Arrow function: Exception. Do not have this. this -> inherited from outer function scope
Event handler context
Class context

Global context

If this is used outside of functions or classes, it will be pointing to the global environment (window in a browser or global in NodeJS)

console.log(this) // [object Window]

Function context

this is determined by how the function is called, not how it is declared.

Except for an arrow function, when a value of this is determined by where an arrow function is declared.

Globally invoked function

If a function is called In a global context, this refers to the global object.

function printThis() {  
  console.log(this)  
}  

printThis() // Window // or undefined in strict mode

Notice that the value of this in a globally invoked function can be altered by the "use strict" directive.

Method

If a function is called as a method of an object, this will refer to that object (on the left side of the dot before a method). For a.b.c.func() this will be c

const obj1 = {  
  a: 1,  
  log() {console.log(this.a)}  
};  
const obj2 = {  
  a: 2,  
  log: obj1.log  
};  

obj2.log(); // 2, because method is being called on `obj2`

Constructor Function

If this is used inside a constructor function, it points to the created instance of this constructor.

function Person(name, birthYear) {  
  this.name = name // `this` will reference the instanse, so `name` will be added to `beatrix`  
  this.birthYear = birthYear // `this` will reference the instanse, so `birthYear` will be added to `beatrix`  

  this.describe = function() { // `describe()` will be added to `beatrix`  
    console.log(`${this.name} was born in ${this.birthYear}.`)   
    // `this` will be pointing to the object on which `describe` will be called (method context)  
  }  
}  
const beatrix = new Person('Beatrix', 2005)  

beatrix.describe() // "Beatrix was born in 2005."  
console.log(beatrix.name) // "Beatrix"

Arrow Function

Arrow functions are a special case, which makes this more tricky. They do not have their own this and inherit this value from the closest enclosing function scope. this value depends on how a function is declared, not how it is called (like with “normal” functions). In other words, this in arrow functions will point to the ‘owner’ of a function, despite where this function is being invoked. It means, that calling arrow functions as methods might result in an unexpected behavior:

const obj = {  
  a: 1,  
  arrow: () => console.log(this.a), // there is no enclosing function, so this will point to global object  
  arrowNested:  
    function() {  
      return () => console.log(this.a) // will inherit the value of this from arrowNested() function, so it will point to `obj`  
  }  
}  

obj.arrow() // undefined  
obj.arrowNested()() // 1  
// value of `this` in arrow function is determined by where function being declared

In some cases, such a behavior of arrow functions might be handy, i.e. when used in event handlers.

Event Handler

In the browser, there is a special this context for event handlers. In an event handler called by addEventListener, this will refer to the element, on which a listener is placed. In other words, this is pointing to event.currentTarget

const button = document.createElement('button')  
button.textContent = 'Click me'  
document.body.append(button)  

button.addEventListener('click', function(event) {  
  console.log(this) // <button>Click me</button>  
})

Sometimes it is not convenient and arrow functions being used to ‘preserve’ this value, no matter what ‘caller’ is:

const person = {  
  name: "Beatrix",  
  sayHello: function() {  
    document.getElementById("myButton").addEventListener("click", () => {  
      console.log("Hello, " + this.name); // `this` inherited from `sayHello` and always will point to `person`, no matter where it will be invoked (arrow function context)  
    });  
  }  
};  

person.sayHello(); // "Hello, Beatrix"

Class

When this is used inside a class, its value depends on what type of methods and field initializer it’s being used in:

In public and private methods and field initializers this behaves like in constructor functions: pointing to an instance
Static methods cannot be accessed via instance’s this. It must be called on class itself

class C {  
  instanceField = this;  
  static staticField = this;  
}  

const instance = new C();  

console.log(instance.instanceField === instance); // true  
console.log(instance.staticField); // undefined because static methods cannot be accessed via instance's `this`   
console.log(C.staticField === C); // true

Explicit Context of this

The value of this can be set manually by using special function methods. Note, that Arrow functions do not have their own this, so these methods can’t be used with them.

.call() and .apply() are used to call the function with a specified value of this:

const obj1 = {  
    a: 1,  
    log() {console.log(this.a)}  
};  
const obj2 = {  
    a: 2,  
};  

obj1.log.apply(obj2); // 2, because `this` explicitely set to `obj2`  
obj1.log() // 1

.bind() is used to create a constant binding of this to a specified object:

const obj1 = {  
    a: 1,  
    log() {console.log(this.a)}  
};  
const obj2 = {  
    a: 2,  
};  
const getObj2Var = obj1.log.bind(obj2);  

getObj2Var() // 2, because getObj2Var `this` binded to obj2

Self-check

const obj = {  
  a: 1,  
  b: function() {  
    console.log(this.a)  
  },  
  c: () => {  
    console.log(this.a)  
  },  
  d: function() {  
    return () => {  
      console.log(this.a);  
    }  
  }  
}  

// what the output will be?  

console.log(obj.a)  

obj.b()  
const b = obj.b  
b()  
obj.b.apply({a: 2})  

obj.c()  
obj.c.apply({a:2})  

obj.d()()  
obj.d.call({a:2})()  
obj.d().call({a:2})

Answer

console.log(obj.a)  // 1  

obj.b()             // 1           // method context  
const b = obj.b  
b()                 // undefined   // This is globally invoked function, not a method, so `this` is pointing to global object  
obj.b.apply({a: 2}) // 2  

obj.c()             // undefined   // Arrow function do not have outer function, so `this` reference global object  
obj.c.apply({a:2})  // undefined   // Arrow functions can't use .call() .apply() or .bind()  

obj.d()()           // 1           // first obj.d() being executed (method context)   
                                   // and returned arrow function. Then arrow function being executed in global context,   
                                   // but `this` in arrow function always points to the `this` of the encapsulating function.   
                                   // In this case `this` of `d()` pointing to `obj`, so `this` in arrow function   
                                   // will always reference `obj`, no matter where it called  

obj.d.call({a:2})() // 2           // same as above, but here `this` of `d()` was explicitely set   
obj.d().call({a:2}) // 1           // `call()` method was applied to arrow function, which is not making any sense.

References

Happy coding! Feedback is appreciated.

Authentication in monorepo(NextJs, Astro) with Lucia and MongoDB

Philipp Rich — Thu, 06 Jun 2024 17:00:00 +0000

This guide will walk you through setting up a simple authentication in a monorepo environment. It covers the common scenario when multiple applications (e.g. landing page and web app), built with different frameworks need to share the same authentication mechanism.

Create a monorepo mockup (with turborepo)
Create a shared package to work with MongoDB database (with mongoose)
Create a shared package to manage auth across monorepo (with lucia-auth)
Set up user validation in Astro.js
Set up user validation in Next.js

For all NPM packages, I explicitly specified the latest versions by the moment of writing (instead of @latest) so this guide can be reproduced in a future. It is recommended to use @latest version of packages since they should be more secure and stable.

Project overview

mysite.com – landing page built with Astro
Publicly available
Provides login/signup page
Redirects authenticated users to app.mysite.com
app.mysite.com – web application built with NextJs (app Router)
Available only for authenticated users
Provides sign-out feature
Redirects unauthenticated users to mysite.com

Stack

Astro js
Next.js (app router)
Lucia-auth
Mongoose
TurboRepo
npm
dotenv

Source code

GitHub - skorphil/monorepo-auth

Prerequisites

MongoDB atlas(free account will do)

Part 1. Create monorepo mockup

For simplicity starter packages of TurboRepo(with NextJs) and Astro will be used.

Monorepo structure

db-utils - provides simple db methods to work with MongoDB: createUser(), getUser(). These methods are used by auth-utils.
auth-utils - provides methods to create users and user sessions. Used by web and landing
web - web application, accessible only for authenticated users. Provides log-out function
landing - public landing page. Provides logout and login form. Inaccessible for authenticated users

Install Turborepo

Install Turborepo starter package:

npx create-turbo@1.13.3

# ? Where would you like to create your turborepo? ./monorepo-auth
# ? Which package manager do you want to use? npm workspaces

Create landing page (@monorepo-auth/landing)

Install Astro starter package inside {monorepo}/apps/landing

npm create astro@4.8.0

# Where should we create your new project? ./apps/landing
# How would you like to start your new project? Include sample files
# Do you plan to write TypeScript? Yes
# How strict should TypeScript be? Strict
# Install dependencies? Yes
# Initialize a new git repository? No

Rename the package to maintain consistency:

// apps/landing/package.json

- "name": "monorepo-auth-apps-landing",
+ "name": "@monorepo-auth/landing",

Create web app (@monorepo-auth/web)

Next.js starter package is already being created with a turborepo, so just rename it:

// apps/web/package.json

- "name": "web",
+ "name": "@monorepo-auth/web",

Delete {monorepo}/apps/docs package, so there is only 2 packages left in apps directory:

# Monorepo structure so far

monorepo-auth/
└── apps/
    ├── web # @monorepo-auth/web
    └── landing # @monorepo-auth/landing

Test run npm run dev to make sure everything works as expected. In my case landing runs at localhost:4321 and web runs at localhost:3000.
If everything is working it's time to set up an authentication.

Part 2. Create database utilities (@monorepo-auth/db-utils)

Database methods are usually used among multiple packages inside the project, this is why it is better to create them in a separate package. Only a few methods are needed for now: createUser() method for the sign-up form and getUser() for the login form. Also, lucia mongodb adapter needs dbConnect() method.

Create a db-utils package. I created it in {monorepo}/packages

mkdir packages/db-utils && touch packages/db-utils/package.json && touch packages/db-utils/.env

Get connection string(URI) for your ModgoDB Atlas: Connection Strings - MongoDB Manual v7.0

Add URI to the created .env file.

# monorepo-auth/packages/db-utils/.env

MONGO_URI="mongodb_uri_here"

Set up Turborepo to use created .env. I used dotenv-cli to make global .env file accessible by all packages. Install it to the monorepo root:

npm install dotenv-cli@7.4.2

Add globalDotEnv to turbo.json config:

// monorepo-auth/turbo.json

{
  "$schema": "https://turbo.build/schema.json",
  "globalDependencies": ["**/.env.*local"],
+ "globalDotEnv": [".env"],

Edit global package.json to run turbo with dotenv

// monorepo-auth/package.json

"scripts": {
    "build": "turbo build",
+   "dev": "dotenv -- turbo dev",

Continue creating db-utils. Edit db-utils package.json:

// monorepo-auth/packages/db-utils/package.json

{
    "name": "@monorepo-auth/db-utils",
    "type": "module",
    "exports": "./index.js",
    "version": "0.0.1"
}

Install necessary packages to @monorepo-auth/db-utils

npm install mongoose@8.4.0 @lucia-auth/adapter-mongodb@1.0.3 --workspace="@monorepo-auth/db-utils"

Create `dbConnect()` method is used to connect to a specified mongo database.

// monorepo-auth/packages/db-utils/lib/dbConnect.js

import { connect } from "mongoose";

export async function dbConnect() {
  try {
    await connect(process.env.MONGO_URI);
    console.debug("Database connected");
  } catch (error) {
    throw error;
  }
}

Create `User` and `Session` models.

I followed recommendations from Lucia docs and expanded userSchema to include username and hashed_password along with _id:

// monorepo-auth/packages/db-utils/user.model.js

import { Schema, model, models } from "mongoose";

const userSchema = new Schema(
  {
    _id: {
      type: String,
      required: true,
    },
    username: {
      type: String,
      required: true,
    },
    password_hash: {
      type: String,
      required: true,
    },
  },
  { _id: false } // default mongodb _id will be replaced by custom _id, which is being generated from entropy as Lucia docs suggesting
);

export default models.User || model("User", userSchema);

// monorepo-auth/packages/db-utils/lib/session.model.js

import { Schema, model, models } from "mongoose";

const sessionSchema = new Schema(
  {
    _id: {
      type: String,
      required: true,
    },
    user_id: {
      type: String,
      required: true,
    },
    expires_at: {
      type: Date,
      required: true,
    },
  },
  { _id: false }
);

export default models.Record || model("Session", sessionSchema);

Create `createUser()` and `getUser()` methods.

// monorepo-auth/packages/db-utils/lib/createUser.js

import { dbConnect } from "./dbConnect";
import User from "../models/user.model";

export async function createUser(userData) {
  const user = await new User(userData);
  try {
    await dbConnect();
    await user.save();
    console.debug("User saved to db");
  } catch (error) {
    throw error;
  }
}

// monorepo-auth/packages/db-utils/lib/createUser.js

import User from "../models/user.model";

export async function getUser(userData) {
  const user = await User.findOne(userData, {
    _id: 1,
    password_hash: 1,
    username: 1,
  });
  if (user) {
    return user;
  } else return false;
}

Create Lucia `adapter`

// monorepo-auth/packages/db-utils/lib/adapter.js

import { dbConnect } from "./dbConnect";
import { MongodbAdapter } from "@lucia-auth/adapter-mongodb";
import mongoose from "mongoose";

await dbConnect();

export const adapter = new MongodbAdapter(
  mongoose.connection.collection("sessions"),
  mongoose.connection.collection("users")
);

Create interface for `db-utils`

To export created methods, create index.js in the root of db-utils package:

// monorepo-auth/packages/db-utils/index.js

import { dbConnect } from "./lib/dbConnect";
import { createUser } from "./lib/createUser";
import { getUser } from "./lib/checkUser";
import { adapter } from "./lib/adapter";

export { createUser, adapter, dbConnect, getUser };

db-utils package ready and can be used by auth-utils.

# db-utils package structure

db-utils/
├── lib/
│   ├── dbConnect.js
│   ├── createUser.js
│   └── getUser.js
├── models/
│   ├── session.model.js
│   └── user.model.js
├── package.json
└── index.js

Part 3. Setup Lucia-auth (@monorepo-auth/auth-utils)

Since both apps will use auth, it is better to define auth methods in a separate package.

Create an auth-utils package. I created it in {monorepo}/packages:

mkdir packages/auth-utils && touch packages/auth-utils/package.json && touch packages/auth-utils/tsconfig.json

Edit created package.json and tsconfig.json

// monorepo-auth/packages/auth-utils/package.json

{
    "name": "@monorepo-auth/auth-utils",
    "type": "module",
    "exports": "./index.js",
    "version": "0.0.1"
}

// monorepo-auth/packages/auth-utils/tsconfig.json

{
    "compilerOptions": {
        "noImplicitAny": false, // i specified this to allow imports of undeclared js modules (db-utils)
        "module": "ESNext",
        "target": "ESNext",
        "moduleResolution":"Bundler"
    }
}

Install necessary packages to @monorepo-auth/auth-utils

npm install lucia@3.2.0 --workspace="@monorepo-auth/auth-utils"

Create `lucia` module

I've followed Lucia docs here, performing some decomposition.

// monorepo-auth/packages/auth-utils/auth.ts

import { adapter } from "@monorepo-auth/db-utils";
import { Lucia } from "lucia";

export const lucia = new Lucia(adapter, {
  sessionCookie: {
    attributes: {
      secure: /* import.meta.env.PROD */ false,
    },
  },
  getUserAttributes: (attributes) => {
    return {
      username: attributes.username,
    };
  },
});

declare module "lucia" {
  interface Register {
    Lucia: typeof lucia;
    DatabaseUserAttributes: DatabaseUserAttributes;
  }
}

interface DatabaseUserAttributes {
  username: string;
}

Create auth-utils interface

There is only a single export needed so far.

// monorepo-auth/packages/auth-utils/index.ts

export { lucia } from "./auth";

auth-utils package is ready and it is time to implement auth in web and landing packages.

# auth-utils package structure

auth-utils/
├── tsconfig.json
├── package.json
├── index.ts
└── auth.ts

Part 4. Implement auth in @monorepo-auth/landing

Create middleware

Astro middleware use lucia to manage user sessions. It defines session and user in context.locals making it accessible by other parts of an app.

// monorepo-auth/landing/src/middleware.ts

import { lucia, verifyRequestOrigin } from "@monorepo-auth/auth-utils";
import { defineMiddleware } from "astro:middleware";

export const onRequest = defineMiddleware(async (context, next) => {
  if (context.request.method !== "GET") {
    const originHeader = context.request.headers.get("Origin");
    const hostHeader = context.request.headers.get("Host");
    if (
      !originHeader ||
      !hostHeader ||
      !verifyRequestOrigin(originHeader, [hostHeader])
    ) {
      return new Response(null, {
        status: 403,
      });
    }
  }

  const sessionId = context.cookies.get(lucia.sessionCookieName)?.value ?? null;
  if (!sessionId) {
    context.locals.user = null;
    context.locals.session = null;
    return next();
  }

  const { session, user } = await lucia.validateSession(sessionId);
  if (session && session.fresh) {
    const sessionCookie = lucia.createSessionCookie(session.id);
    context.cookies.set(
      sessionCookie.name,
      sessionCookie.value,
      sessionCookie.attributes
    );
  }
  if (!session) {
    const sessionCookie = lucia.createBlankSessionCookie();
    context.cookies.set(
      sessionCookie.name,
      sessionCookie.value,
      sessionCookie.attributes
    );
  }
  context.locals.session = session;
  context.locals.user = user;
  return next();
});

Declare session and user types

// monorepo-auth/landing/src/env.d.ts

/// <reference types="astro/client" />

declare namespace App {
  interface Locals {
    session: import("lucia").Session | null;
    user: import("lucia").User | null;
  }
}

Lucia works only in Astro server mode, so edit astro.config.mjs:

// monorepo-auth/landing/astro.config.mjs

import { defineConfig } from "astro/config";
import node from "@astrojs/node";

export default defineConfig({
  output: "server",
  adapter: node({
    mode: "standalone",
  }),
});

Enabling server mode requires to install @astrojs/node adapter

npm install @astrojs/node@8.2.5 --workspace="@monorepo-auth/landing"

Create signup form and API

I strictly followed lucia docs to make it more simple, so I created login and signup pages in landing package. However, to achieve modular and flexible architecture they can be created as a part of separate auth package with respective redirects.
API and signup form are copies from lucia docs, but imports shared db-utils and auth-utils:

// monorepo-auth/landing/src/pages/api/signup.ts

import { lucia } from "@monorepo-auth/auth-utils";
import { createUser } from "@monorepo-auth/db-utils";

import { hash } from "@node-rs/argon2";
import { generateIdFromEntropySize } from "lucia";

import type { APIContext } from "astro";

export async function POST(context: APIContext): Promise<Response> {
  const formData = await context.request.formData();
  const username = formData.get("username");
  // username must be between 4 ~ 31 characters, and only consists of lowercase letters, 0-9, -, and _
  // keep in mind some database (e.g. mysql) are case insensitive
  if (
    typeof username !== "string" ||
    username.length < 3 ||
    username.length > 31 ||
    !/^[a-z0-9_-]+$/.test(username)
  ) {
    return new Response("Invalid username", {
      status: 400,
    });
  }
  const password = formData.get("password");
  if (
    typeof password !== "string" ||
    password.length < 6 ||
    password.length > 255
  ) {
    return new Response("Invalid password", {
      status: 400,
    });
  }

  const userId = generateIdFromEntropySize(10); // 16 characters long
  const passwordHash = await hash(password, {
    // recommended minimum parameters
    memoryCost: 19456,
    timeCost: 2,
    outputLen: 32,
    parallelism: 1,
  });

  // TODO: check if username is already used
  await createUser({
    _id: userId,
    username: username,
    password_hash: passwordHash,
  });

  const session = await lucia.createSession(userId, {});
  const sessionCookie = lucia.createSessionCookie(session.id);
  context.cookies.set(
    sessionCookie.name,
    sessionCookie.value,
    sessionCookie.attributes
  );

  return context.redirect("/");
}

Create signup form:

<!--monorepo-auth/landing/src/pages/signup.astro-->

<html lang="en">
    <body>
        <h1>Signup Page</h1>
        <form method="post" action="/api/signup">
            <label for="username">Username</label>
            <input id="username" name="username" />
            <label for="password">Password</label>
            <input id="password" name="password" />
            <button>Continue</button>
        </form>
    </body>
</html>

Add signup form link to index.astro to simplify navigation. I deleted original content of index.astro to make it simpler:

// monorepo-auth/landing/src/pages/index.astro

<Layout title="Welcome to Astro.">
  <main>
    <h1>Landing page</h1>
+   <a href="/signup">Signup</a>
  </main>
</Layout>

To check if sign up feature is working:

Launch project npm run dev
Create new user on http://localhost:4321/signup In MongoDB atlas there should be a new user in users collection as well as a corresponding session in sessions collection.

In browser there should be auth_session cookie

Create login form and API

// monorepo-auth/landing/src/pages/api/login.ts

import { lucia } from "@monorepo-auth/auth-utils";
import { getUser } from "@monorepo-auth/db-utils";

import { verify } from "@node-rs/argon2";
import type { APIContext } from "astro";

interface UserDocument extends Document {
  _id: string;
  username: string;
  password_hash: string;
}

export async function POST(context: APIContext): Promise<Response> {
  const formData = await context.request.formData();
  const username = formData.get("username");
  if (
    typeof username !== "string" ||
    username.length < 3 ||
    username.length > 31 ||
    !/^[a-z0-9_-]+$/.test(username)
  ) {
    return new Response("Invalid username", {
      status: 400,
    });
  }
  const password = formData.get("password");
  if (
    typeof password !== "string" ||
    password.length < 6 ||
    password.length > 255
  ) {
    return new Response("Invalid password", {
      status: 400,
    });
  }

  const existingUser = await getUser({ username: username });
  console.log(existingUser);
  if (!existingUser) {
    // NOTE:
    // Returning immediately allows malicious actors to figure out valid usernames from response times,
    // allowing them to only focus on guessing passwords in brute-force attacks.
    // As a preventive measure, you may want to hash passwords even for invalid usernames.
    // However, valid usernames can be already be revealed with the signup page among other methods.
    // It will also be much more resource intensive.
    // Since protecting against this is non-trivial,
    // it is crucial your implementation is protected against brute-force attacks with login throttling etc.
    // If usernames are public, you may outright tell the user that the username is invalid.
    return new Response("Incorrect username or password", {
      status: 400,
    });
  }

  const validPassword = await verify(existingUser.password_hash, password, {
    memoryCost: 19456,
    timeCost: 2,
    outputLen: 32,
    parallelism: 1,
  });
  if (!validPassword) {
    return new Response("Incorrect username or password", {
      status: 400,
    });
  }

  const session = await lucia.createSession(existingUser._id, {});
  const sessionCookie = lucia.createSessionCookie(session.id);
  context.cookies.set(
    sessionCookie.name,
    sessionCookie.value,
    sessionCookie.attributes
  );

  return context.redirect("/");
}

<!--monorepo-auth/landing/src/pages/login.astro-->

<html lang="en">
    <body>
        <h1>Login Page</h1>
        <form method="post" action="/api/login">
            <label for="username">Username</label>
            <input id="username" name="username" />
            <label for="password">Password</label>
            <input id="password" name="password" />
            <button>Continue</button>
        </form>
    </body>
</html>

Add login form link to index.astro:

// landing/src/pages/index.astro

<Layout title="Welcome to Astro.">
  <main>
    <h1>Landing page</h1>
    <a href="/signup">Signup</a>
+   <a href="/login">Login</a>
  </main>
</Layout>

Redirect authenticated user to web app

For convenience create environment variables in root .env file with urls on which they run. In my case:

# monorepo-auth/packages/db-utils/.env

MONGO_URI="mongodb_uri_here"
+ WEB_URL="http://localhost:3000"
+ LANDING_URL="http://localhost:4321"

After middleware created user in context.locals, it can be checked in astro pages within frontmatter:

---
const user = Astro.locals.user;
if (user) {
  return Astro.redirect(process.env.WEB_URL);
}
---

Now if the user is authenticated it will be redirected to web.

Part 5. Implement auth in @monorepo-auth/web

The last part of this guide covers setting up web package to redirect unauthenticated users to the landing page and provide log-out feature.

Validate users in server components

Create validateRequest() function in auth.ts. It is a copy from Lucia documentation with a different lucia import.

// web/utils/auth.ts

import { cookies } from "next/headers";
import { cache } from "react";
import { lucia } from "@monorepo-auth/auth-utils"; // lucia instance from shared auth-utils

import type { Session, User } from "lucia";

export const validateRequest = cache(
  async (): Promise<
    { user: User; session: Session } | { user: null; session: null }
  > => {
    const sessionId = cookies().get(lucia.sessionCookieName)?.value ?? null;
    if (!sessionId) {
      return {
        user: null,
        session: null,
      };
    }

    const result = await lucia.validateSession(sessionId);
    // next.js throws when you attempt to set cookie when rendering page
    try {
      if (result.session && result.session.fresh) {
        const sessionCookie = lucia.createSessionCookie(result.session.id);
        cookies().set(
          sessionCookie.name,
          sessionCookie.value,
          sessionCookie.attributes
        );
      }
      if (!result.session) {
        const sessionCookie = lucia.createBlankSessionCookie();
        cookies().set(
          sessionCookie.name,
          sessionCookie.value,
          sessionCookie.attributes
        );
      }
    } catch {}
    return result;
  }
);

validateRequest() can be used on server components to check if a user is authenticated. Setting up validation in client component requires setting up API or context, which is not covered in this guide.
Add redirect to landing for unauthenticated users:

// monorepo/web/app/page.tsx

import { validateRequest } from "../utils/auth";
import type { ActionResult } from "next/dist/server/app-render/types";
import { redirect } from "next/navigation"


export default async function ProtectedPage() {
  const { user } = await validateRequest();
  if (!user) {
    return redirect(process.env.LANDING_URL);
  }
  return (
    <>
      <h1>Web-app</h1>
      <h2>Hi, {user.username}!</h2>
    </>
  );
}

Create logout button in Next.js

Since authenticated users don't have access to landing page (it redirects them to web), logout feature should be implemented in web package:

// monorepo/web/app/page.tsx

import { validateRequest } from "../utils/auth";
import { lucia } from "@monorepo-auth/auth-utils";
import { cookies } from "next/headers";
import { redirect } from "next/navigation";

import type { ActionResult } from "next/dist/server/app-render/types";


export default async function ProtectedPage() {
  const { user } = await validateRequest();
  if (!user) {
    return redirect(process.env.LANDING_URL as string);
  }
  return (
    <>
      <h1>Web-app</h1>
      <h2>Hi, {user.username}!</h2>
      <form action={logout}>
        <button>Sign out</button>
      </form>
    </>
  );
}

async function logout(): Promise<ActionResult> {
  "use server";
  const { session } = await validateRequest();
  if (!session) {
    return {
      error: "Unauthorized",
    };
  }

  await lucia.invalidateSession(session.id);

  const sessionCookie = lucia.createBlankSessionCookie();
  cookies().set(
    sessionCookie.name,
    sessionCookie.value,
    sessionCookie.attributes
  );
  return redirect(process.env.LANDING_URL as string);
}

Outcome

Both packages in a monorepo can access user session and validate if user is authenticated.
db-utils and auth-utils can be used by other packages that might be added to monorepo in the future.
project source code: GitHub - skorphil/monorepo-auth

DEV Community: Philipp Rich

Feature sliced design vs clean architecture

Introduction

Feature-Sliced Design Summary

Flow of Development

Layer Isolation

Implementation

Afterword

References

How to apply clean architecture in React app

Introduction

Prerequisites

Summary of Clean Architecture

Layers

Flow of control

Scenario description

Project structure

Domain model

Application layer

Adapters

Controller

Bringing all together

The result

References

I built open-source app to stop micromanaging my finance

From Spreadsheet to App

Tauri File Management on Android

Introduction

Tauri Overview

Setting Up a Project

Tauri File Management Plugins

Tauri Capabilities

Silently Managing Files

Android Limitations

Capabilities

Explicitly Managing Files

Migrating to React Router Framework: Challenges Beyond the Official Guide

Motivation and tech stack

Starting point

PnP and RR Framework (isbot not found)

SSL and RR Framework (":method" is an invalid header name)

Client side logic issues

Setting routes (move away from catchAll.tsx)

Moving providers

Applying css

Serving Issues After Build: No Matching Routes Found

Afterword

Master JavaScript “this” keyword to pass job interview

Glossary

Implicit contexts

Global context

Function context

Globally invoked function

Method

Constructor Function

Arrow Function

Event Handler

Class

Explicit Context of this

Self-check

Answer

References

Authentication in monorepo(NextJs, Astro) with Lucia and MongoDB

Project overview

Stack

Source code

Prerequisites

Part 1. Create monorepo mockup

Monorepo structure

Install Turborepo

Create landing page (@monorepo-auth/landing)

Create web app (@monorepo-auth/web)

Part 2. Create database utilities (@monorepo-auth/db-utils)

Create dbConnect() method is used to connect to a specified mongo database.

Create User and Session models.

Create createUser() and getUser() methods.

Create Lucia adapter

Create interface for db-utils

Part 3. Setup Lucia-auth (@monorepo-auth/auth-utils)

Create lucia module

Create `dbConnect()` method is used to connect to a specified mongo database.

Create `User` and `Session` models.

Create `createUser()` and `getUser()` methods.

Create Lucia `adapter`

Create interface for `db-utils`

Create `lucia` module