DEV Community: Friedrich WT

My monorepo setup to ship full-stack, end-to-end type-safe apps with TypeScript

Friedrich WT — Mon, 18 May 2026 00:07:07 +0000

During the previous year, I took quite some time to find my perfect tech-stack that would allow me to ship TypeScript apps fast, with end-to-end type safety. That last part was a little bit tricky. I started simple with Next.js and it worked fine for a while. Server components, server actions. Seemed magical, type contracts shared between the frontend and the backend. And everything was in a single Node.js application. Dockerized it and boom, ready to deploy!

But as I said, it worked “for a while”. Usually in a project, we end up having multiple clients that consume the api, not just one frontend. While building Mooncode (an application to track user coding time, programming languages and files), I hit that roadblock. I needed a VSCode extension and a dashboard that would communicate with a backend, and I couldn’t achieve that easily with Next.js. That’s how I shifted from it. So, what does my current tech stack look like?

Nest.js for the api/backend. It is a robust, easy to scale, TypeScript backend framework. Even though it is quite strict, opinionated and takes some time to get comfortable with, the benefits become more visible on the long run. It feels like a Spring Boot for the Node.js ecosystem or an Angular for the backend, but man, I like it. I can also expect a consistent developer experience and file structure between projects too, which is a win, in my opinion
React + Vite + React Router on the frontend for any application that doesn’t require any SEO (Search Engine Optimization) or is hidden behind a login wall. This includes dashboards and admin panels. It is simple to get around and to understand
Astro/Nextjs for frontend apps that need SEO. I use them for landing pages or blogs in general, with static build
Turborepo for a monorepo setup and have all those different applications (frontends, backends) in the same codebase and be able to reuse code between them with shared packages
tRPC in the middle to ensure end-to-end type safety. What I mean by that is, I am able to get the types of any data I fetch from the frontend apps. So, when I update an endpoint parameters or return type, if there is any error, it will immediately be reflected in the frontends that consume that endpoint. And if I forget to fix those errors, the build will fail

My goal in this article is to setup such a monorepo with: a Nest.js api, a React+Vite+React Router frontend and another frontend using Astro, all this with tRPC, of course.

Let’s start by creating a turborepo monorepo with the command:

npx create-turbo@latest

This will generate a bare bones Turborepo monorepo with two applications: a docs and a web folder. Both of them are Next.js applications. Let’s remove them and start fresh by creating the Nest.js api with:

# From the root of the monorepo
cd apps && nest new api

Make sure to add the following fields in the tsconfig.json of the api:

{
  "compilerOptions": {
    "module": "nodenext",
    "composite": true,
    "rootDir": ".",
    "outDir": "./dist",
    "paths": {
      "@/*": ["./src/*"]
    },
    "types": ["node"],
    "strict": true,
    "noImplicitAny": true
  }
}

And also install the latest version of TypeScript:

# From the root of the monorepo
npm i -D typescript --workspace=api

Remove the .git folder of the api. The Nest.js cli generates a git repository by default and we don’t want it because the monorepo has already its own git repository.

# From the root of the monorepo
cd apps/api && rm -rf .git

Let’s continue by creating the Vite + React Router frontend

# From the root of the monorepo
cd apps && npm create vite@latest

And install react-router there (I called that app dashboard):

# From the root of the monorepo
npm i react-router --workspace=dashboard

I put in place some boilerplate code, but since it is not the core of the article, I will not go in the details. Here is the link to the GitHub repository if you want access to the full source code: monorepo-setup, on the initial setup branch.

Now, let’s do the same thing with the Astro application with:

# From the root of the monorepo
cd apps && npm create astro@latest
# recommanded setup, no git repository for the same reasons as the api

Here again I will remove the boilerplate, add some styling and some ESLint and Prettier rules. Formatting and linting are a separate topic that I may touch in a part two of this article, with more details on my linting rules especially.

Anyways, once all that is setup, here is what we have currently:

dashboard (Vite + React Router)

web app (Astro)

OK, now we can start configuring tRPC in the api. Starting by installing @trpc/server.

# In apps/api
npm i @trpc/server --workspace=api

Now let’s create a tRPC resource (module + controller + service):

# From the root of the monorepo
cd apps/api && nest g res trpc

(with no CRUD endpoints for the trpc service). So, at the beginning it looks like this:

import { Injectable } from '@nestjs/common';

@Injectable()
export class TrpcService {}

Let’s define some tRPC concepts before going further. The API endpoints are called procedures. And there are two types of procedures: the queries and the mutations. A query is the equivalent of a GET REST method. It is used to get data. And a mutation is almost everything else: create, update, delete data. So it matches the POST, PATCH, PUT, DELETE REST methods. We also often group REST API endpoints under a controller, for example users will have endpoints to create, read, update, delete a user. tRPC calls such collection of procedures a router. Another concept that is worth explaining is the context which contains the request and the response and can be accessed by procedures. A middleware is a function that runs before or after a procedure and can change the context.

Here is the full code of the TrpcService:

import superjson from "superjson";

import { JWTDto } from "@/common/dto";
import { EnvService } from "@/env/env.service";
import { errorFormatter } from "@/filters/error-formatter";
import { Injectable } from "@nestjs/common";
import { JwtService } from "@nestjs/jwt";
import { initTRPC, TRPCError } from "@trpc/server";
import * as trpcExpress from "@trpc/server/adapters/express";

export type TrpcContext = {
  req: trpcExpress.CreateExpressContextOptions["req"];
  res: trpcExpress.CreateExpressContextOptions["res"];
  user?: {
    sub: string;
  };
};

export const createContext = async (
  opts: trpcExpress.CreateExpressContextOptions,
): Promise<TrpcContext> => {
  return {
    req: opts.req,
    res: opts.res,
  };
};

@Injectable()
export class TrpcService {
  trpc;
  constructor(
    private readonly jwtService: JwtService,
    private readonly envService: EnvService,
  ) {
    this.trpc = initTRPC.context<TrpcContext>().create({
      transformer: superjson,
      errorFormatter: ({ error, shape }) =>
        errorFormatter({
          environment: this.envService.get("NODE_ENV"),
          error,
          shape,
        }),
    });
  }

  // these routes are publicly accessible to everyone
  publicProcedure() {
    return this.trpc.procedure;
  }

  // these routes requires authentication
  protectedProcedure() {
    const procedure = this.trpc.procedure.use(async (opts) => {
      const payload = await this.getPayload(opts.ctx);

      return opts.next({
        ctx: {
          ...opts.ctx,
          user: { sub: payload.sub },
        },
      });
    });

    return procedure;
  }

  async getPayload(ctx: TrpcContext) {
    // get JWT from cookies
    const accessToken = ctx.req.cookies?.auth_token;

    if (!accessToken) {
      throw new TRPCError({
        code: "UNAUTHORIZED",
        message: "Token not found",
      });
    }

    try {
      const rawPayload = await this.jwtService.verifyAsync(accessToken, {
        secret: this.envService.get("JWT_SECRET"),
      });

      const parsedPayload = JWTDto.safeParse(rawPayload);

      if (!parsedPayload.success) {
        throw new TRPCError({
          code: "UNAUTHORIZED",
        });
      }

      const data = parsedPayload.data;

      return data;
    } catch (error) {
      if (error instanceof Error && error.name !== "JsonWebTokenError") {
        console.error("Unexpected Error:", error);
      }

      throw new TRPCError({
        code: "UNAUTHORIZED",
        message: "An error occurred",
      });
    }
  }
}

Let’s explain it piece by piece:

export type TrpcContext = {
  req: trpcExpress.CreateExpressContextOptions["req"];
  res: trpcExpress.CreateExpressContextOptions["res"];
};

export const createContext = async (
  opts: trpcExpress.CreateExpressContextOptions,
): Promise<TrpcContext> => {
  return {
    req: opts.req,
    res: opts.res,
  };
};

As its name suggests, the createContext function is used to define the tRPC context and will be used in the service to create an instance of trpc.

@Injectable()
export class TrpcService {
  trpc;
  constructor(
    private readonly jwtService: JwtService,
    private readonly envService: EnvService,
  ) {
    this.trpc = initTRPC.context<TrpcContext>().create({
      transformer: superjson,
      errorFormatter: ({ error, shape }) =>
        errorFormatter({
          environment: this.envService.get("NODE_ENV"),
          error,
          shape,
        }),
    });
  }

We define and instanciate tprc in the constructor of the TrpcService class. We also inject in the constructor of the class two other services: jwtService to create and decode JWTs and envService to interact with environment variables in a type safe way (it is a wrapper around the provided ConfigService of Nest.js for environment variables). The errorFormatter function is used to format the errors depending of the environment (development or production). I will provide their source codes later in the article. JwtDtoType is the shape of our decoded JWT. And superjson is a package used to easily pass data types like Date, Map, Set (which are not easily json serializable) between client and server without having to recreate them ourselves.

Packages installations:

# From the root of the monorepo
npm i @nestjs/jwt --workspace=api
npm i superjson --workspace=api

In the world of tRPC, endpoints that are protected by authentication are called protected procedures and the remaining, public procedures.

 // these routes are publicly accessible to everyone
  publicProcedure() {
    return this.trpc.procedure;
  }

  // these routes requires authentication
  protectedProcedure() {
    const procedure = this.trpc.procedure.use(async (opts) => {
      const payload = await this.getPayload(opts.ctx);

      return opts.next({
        ctx: {
          ...opts.ctx,
          user: { sub: payload.sub },
        },
      });
    });

    return procedure;
  }

In the case of a public procedure, we just give access to the data of the procedure, but if it is private, we use a tRPC middleware to check the JWT of the user (handled by the getPayload function). If we cannot get the payload, we throw a 401 unauthorized errror, otherwise we add the sub value of our JWT in the tRPC context. About the way we get that payload:

async getPayload(ctx: TrpcContext) {
    // get JWT from cookies
    const accessToken = ctx.req.cookies?.auth_token;

    if (!accessToken) {
      throw new TRPCError({
        code: "UNAUTHORIZED",
        message: "Token not found",
      });
    }

    try {
      const rawPayload = await this.jwtService.verifyAsync(accessToken, {
        secret: this.envService.get("JWT_SECRET"),
      });

      const parsedPayload = JWTDto.safeParse(rawPayload);

      if (!parsedPayload.success) {
        throw new TRPCError({
          code: "UNAUTHORIZED",
        });
      }

      const data = parsedPayload.data;

      return data;
    } catch (error) {
      if (error instanceof Error && error.name !== "JsonWebTokenError") {
        console.error("Unexpected Error:", error);
      }

      throw new TRPCError({
        code: "UNAUTHORIZED",
        message: "An error occurred",
      });
    }
  }

We simply extract the JWT from the cookies (the cookie is named auth_token) and decode it.

The code of:

env.service.ts

Create a env resource with the Nest.js cli:

# From the root of the monorepo
cd apps/api && nest g res env

Then paste this code in the env.service.ts

import { Env } from "@/env";
import { Injectable } from "@nestjs/common";
import { ConfigService } from "@nestjs/config";

@Injectable()
export class EnvService {
  constructor(private configService: ConfigService<Env, true>) {}
  get<T extends keyof Env>(key: T) {
    return this.configService.get(key, { infer: true });
  }
}

The get method of the EnvService will make the environment variables type safe. Also install the @nestjs/config package.

# From the root of the monorepo
npm i @nestjs/config --workspace=api

There is a env.ts file at the root of the src directory of the api, that contains a zod schema of our environment variables.

# From the root of the monorepo
npm i zod --workspace=api

import { z } from "zod";

export const envSchema = z.object({
  NODE_ENV: z.enum(["production", "development"]),

  JWT_SECRET: z.string().trim().min(1),
});

export type Env = z.infer<typeof envSchema>;

common/dto.ts Create a dto.ts file in src/common of the api.

import { z } from "zod";

export const JWTDto = z.object({
  sub: z.string().min(1),
  iat: z.number().int(),
  exp: z.number().int(),
});

export type JWTDtoType = z.infer<typeof JWTDto>;

formatters/error-formatter.ts

import { z, ZodError } from "zod";

import { EnvService } from "@/env/env.service";
import { TRPCError } from "@trpc/server";

type ErrorShape = {
  data: {
    stack?: string | undefined;
    path?: string | undefined;
    zodIssues?: ZodError[] | undefined;
    code: string;
    httpStatus: number;
  };
  message: string;
};

export const errorFormatter = (
  envService: EnvService,
  {
    shape,
    error,
  }: {
    shape: ErrorShape;
    error: unknown;
  },
) => {
  const isDev = envService.get("NODE_ENV") === "development";

  if (error instanceof TRPCError && error.code === "BAD_REQUEST") {
    if (error.cause && isZodError(error.cause)) {
      return {
        ...shape,
        message: z.prettifyError(error.cause),
        data: {
          code: shape.data.code,
          httpStatus: shape.data.httpStatus,
          ...(isDev && {
            stack: shape.data.stack,
            path: shape.data.path,
            zodIssues: error.cause.issues,
          }),
        },
      };
    }
  }

  // Handle direct Zod errors
  if (isZodError(error)) {
    return {
      ...shape,
      message: z.prettifyError(error),
      data: {
        code: shape.data.code,
        httpStatus: shape.data.httpStatus,
        ...(isDev && {
          stack: shape.data.stack,
          path: shape.data.path,
          zodIssues: error.issues,
        }),
      },
    };
  }

  // Other errors
  let cleanMessage = "An error occurred";

  if (error instanceof Error) {
    cleanMessage = error.message;
    try {
      if (error.message.startsWith("[") && error.message.endsWith("]")) {
        const parsedErrors = JSON.parse(error.message);
        if (Array.isArray(parsedErrors)) {
          cleanMessage = parsedErrors
            .map((err) => `${err.path?.join(".") || "field"}: ${err.message}`)
            .join("; ");
        }
      }
    } catch {
      // Keep original message if parsing fails
    }
  }

  return {
    ...shape,
    message: cleanMessage,
    data: {
      code: shape.data.code,
      httpStatus: shape.data.httpStatus,
      ...(isDev && {
        stack: shape.data.stack,
        path: shape.data.path,
      }),
    },
  };
};

const isZodError = (error: unknown) => {
  return error instanceof ZodError;
};

Let’s fix some Nest.js dependency injection issues. In the trpc.module.ts, add the JwtService and EnvService to the list of providers:

import { EnvService } from "@/env/env.service";
import { Module } from "@nestjs/common";
import { JwtService } from "@nestjs/jwt";

import { TrpcController } from "./trpc.controller";
import { TrpcService } from "./trpc.service";

@Module({
  controllers: [TrpcController],
  providers: [TrpcService, JwtService, EnvService],
})
export class TrpcModule {}

In the app.module.ts, let’s add the ConfigModule to the list of imports and make it prevent the app from bootstrapping if we don’t have all the required environment variables:

import { Module } from "@nestjs/common";
import { ConfigModule } from "@nestjs/config";

import { AppController } from "./app.controller";
import { AppService } from "./app.service";
import { envSchema } from "./env";
import { EnvModule } from "./env/env.module";
import { TrpcModule } from "./trpc/trpc.module";

@Module({
  imports: [
    ConfigModule.forRoot({
      isGlobal: true,
      validate: (env) => envSchema.parse(env), // this will prevent the app from starting if the environment variables are not valid
    }),
    TrpcModule,
    EnvModule,
  ],
  controllers: [AppController],
  providers: [AppService],
})
export class AppModule {}

Validating our environment variables and having a type safe EnvService that wraps the ConfigService provided out of the box by Nest.js is not necessary. I just find those measures to be a good safety net: we get type safety on our environment variables and the app will fail to start of they are not valid. Better to get the error at the beginning than weird issues (due to misconfigured environment variables) when the app is already running.

Now the api folder structure should like this:

And let’s not forget to create a .env with proper environment variables

NODE_ENV=development
JWT_SECRET=...

You can generate a JWT_SECRET with the command:

openssl rand -hex 32

And the api should bootstrap without any issues.

Next step is to define the main router of our api. Let’s first delete the trpc.controller.ts and replace it with a trpc.router.ts.

import { INestApplication, Injectable } from "@nestjs/common";
import * as trpcExpress from "@trpc/server/adapters/express";

import { createContext, TrpcService } from "./trpc.service";

@Injectable()
export class TrpcRouter {
  constructor(private readonly trpcService: TrpcService) {}

  appRouter = this.trpcService.trpc.router({}); // here we will define our procedures that will be called by our client
  // we can also create different routers per module and pass them here

  async applyMiddleware(app: INestApplication) {
    app.use(
      "/trpc", // all the procedures that we define will be under the /trpc prefix (eg: http://api/trpc/...)
      trpcExpress.createExpressMiddleware({
        router: this.appRouter,
        createContext,
      }),
    );
  }
}

export type AppRouter = TrpcRouter["appRouter"]; // we export this type! Necessary to get the type safety in the clients (web app and dashboard)

Let’s also declare it as a provider in the trpc.module.ts.

import { EnvService } from "@/env/env.service";
import { Module } from "@nestjs/common";
import { JwtService } from "@nestjs/jwt";

import { TrpcRouter } from "./trpc.router";
import { TrpcService } from "./trpc.service";

@Module({
  providers: [TrpcService, TrpcRouter, JwtService, EnvService],
})
export class TrpcModule {}

Now that we defined the main router, let’s use it at the Nest.js application level by updating the main.ts root file of the api. But we need to install the cookie-parser package which is required to work with cookies when using Nest.js with express.

# From the root of the monorepo
npm i cookie-parser --workspace=api
npm i -D @types/cookie-parser --workspace=api

and

import cookieParser from "cookie-parser";

import { NestFactory } from "@nestjs/core";

import { AppModule } from "./app.module";
import { TrpcRouter } from "./trpc/trpc.router";

const bootstrap = async () => {
  const app = await NestFactory.create(AppModule);
  app.use(cookieParser());

  const trpc = app.get(TrpcRouter);
  trpc.applyMiddleware(app);

  await app.listen(process.env.PORT ?? 3010);
};
bootstrap();

Let’s test this setup by quickly defining a procedure directly in the trpc.router.ts. And we will try to call it from the clients.

import { z } from "zod";

import { INestApplication, Injectable } from "@nestjs/common";
import * as trpcExpress from "@trpc/server/adapters/express";

import { createContext, TrpcService } from "./trpc.service";

@Injectable()
export class TrpcRouter {
  constructor(private readonly trpcService: TrpcService) {}

  appRouter = this.trpcService.trpc.router({
    getHello: this.trpcService
      .publicProcedure()
      .input(
        z.object({
          name: z.string().min(1),
        }),
      )
      .query(({ input }) => `Hello, ${input.name} from trpc server`),
  });

  async applyMiddleware(app: INestApplication) {
    app.use(
      "/trpc",
      trpcExpress.createExpressMiddleware({
        router: this.appRouter,
        createContext,
      }),
    );
  }
}

export type AppRouter = TrpcRouter["appRouter"];

Before going to the clients there is one step in between: create a trpc package in the monorepo. The sole purpose of this package is to re-export the AppRouter type. So the clients will import from @repo/trpc instead of importing directly from the api. The files of that package:

package.json:

{
  "name": "@repo/trpc",
  "version": "0.0.0",
  "private": true,
  "license": "MIT",
  "exports": {
    "./router": "./src/router.ts"
  },
  "scripts": {
    "dev": "tsc --watch",
    "lint": "eslint . --fix",
    "format": "prettier --write \"**/*.ts\"",
    "build": "tsc"
  }
}

tsconfig.json:

{
  "extends": "@repo/typescript-config/base.json",
  "references": [{ "path": "../../apps/api/tsconfig.json" }],

  "compilerOptions": {
    "outDir": "dist",
    "rootDir": "src",
    "composite": true,
    "incremental": true
  },
  "include": ["src"],
  "exclude": ["node_modules", "dist"]
}

src/router.ts:

export type { AppRouter } from "api/src/trpc/trpc.router";

Now the clients:

dashboard (React + Vite)

We are going to use @tanstack/react-query to make our lives easier. It works great with tRPC.

First step is to install the following packages:

npm install @trpc/server @trpc/client @trpc/tanstack-react-query @tanstack/react-query

After we need to create a TRPCProvider to wrap our entire application:

// src/utils/trpc.ts
import type { AppRouter } from "@repo/trpc/router";
import { TRPCClientError } from "@trpc/client";
import type { inferRouterInputs, inferRouterOutputs } from "@trpc/server";
import { createTRPCContext } from "@trpc/tanstack-react-query";

export const { TRPCProvider, useTRPC, useTRPCClient } =
  createTRPCContext<AppRouter>();

export const isTRPCClientError = (
  error: unknown,
): error is TRPCClientError<AppRouter> => {
  return error instanceof TRPCClientError;
};

export type Inputs = inferRouterInputs<AppRouter>;
export type Outputs = inferRouterOutputs<AppRouter>;

And in the app.tsx file of the dashboard, we create our queryClient then the trpcClient that we pass to the TRPCProvider:

import { useState } from "react";
import { Outlet } from "react-router";
import superjson from "superjson";

import { ThemeProvider } from "@/providers/theme-provider";
import { isTRPCClientError, TRPCProvider } from "@/utils/trpc";
import type { AppRouter } from "@repo/trpc/router";
import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
import { createTRPCClient, httpBatchLink } from "@trpc/client";

// we define our tanstack query QueryClient
const makeQueryClient = () => {
  return new QueryClient({
    defaultOptions: {
      queries: {
        staleTime: 60 * 1000,
        refetchOnWindowFocus: true,
        refetchInterval: 60 * 1000,
        retry: (failureCount, error) => {
          if (isTRPCClientError(error)) {
            return failureCount < 1;
          }

          return failureCount < 3;
        },
      },
    },
  });
};

let browserQueryClient: QueryClient | undefined = undefined;

const getQueryClient = () => {
  // if we are on the server, always make a new query client
  if (typeof window === "undefined") {
    return makeQueryClient();
  } else {
    // browser: make a query client if we don't already have one
    if (!browserQueryClient) {
      browserQueryClient = makeQueryClient();
    }
    return browserQueryClient;
  }
};

export const App = () => {
  const queryClient = getQueryClient();
  const [trpcClient] = useState(() =>
    createTRPCClient<AppRouter>({
      links: [
        httpBatchLink({
          // the url of the api, we define it as an environment variable
          url: import.meta.env.VITE_API_URL,
          fetch(url, options) {
            return fetch(url, {
              ...options,
              credentials: "include",
            });
          },
          transformer: superjson,
        }),
      ],
    }),
  );

  return (
    <ThemeProvider defaultTheme="dark">
      <QueryClientProvider client={queryClient}>
        {/* we wrap the entire app in the TRPCProvider */}
        <TRPCProvider trpcClient={trpcClient} queryClient={queryClient}>
          <Outlet />
        </TRPCProvider>
      </QueryClientProvider>
    </ThemeProvider>
  );
};

We don’t forget to define the environment variable that specifies the api url to the trpcClient:

# .env.development in the dashboard
VITE_API_URL=http://localhost:3010/trpc

And enable type safety with that environment variable using a vite-env.d.ts:

interface ViteTypeOptions {
  strictImportMetaEnv: unknown;
}

interface ImportMetaEnv {
  readonly VITE_API_URL: string;
}

interface ImportMeta {
  readonly env: ImportMetaEnv;
}

Before doing to the data fetching itself, let’s add the url of the dashboard to the list of the allowed clients in the api, otherwise it will be blocked by CORS.

Back to the api: definition of the allowed clients in a constants.ts in the src directory:

// src/constants.ts

export const ALLOWED_CLIENTS = [
  process.env.DASHBOARD_URL || "http://localhost:5173",
];

We add it as an environment variable:

NODE_ENV=development
JWT_SECRET=...
DASHBOARD_URL=http://localhost:5175

And update our schema:

import { z } from "zod";

export const envSchema = z.object({
  NODE_ENV: z.enum(["production", "development"]),

  JWT_SECRET: z.string().trim().min(1),

  DASHBOARD_URL: z.url(),
});

export type Env = z.infer<typeof envSchema>;

To finally enable the CORS in the entrypoint of the api:

import cookieParser from "cookie-parser";

import { NestFactory } from "@nestjs/core";

import { AppModule } from "./app.module";
import { ALLOWED_CLIENTS } from "./constants";
import { TrpcRouter } from "./trpc/trpc.router";

const bootstrap = async () => {
  const app = await NestFactory.create(AppModule);
  app.enableCors({
    origin: ALLOWED_CLIENTS, // pass the allowed clients here
    credentials: true,
  });

  app.use(cookieParser());

  const trpc = app.get(TrpcRouter);
  trpc.applyMiddleware(app);

  await app.listen(process.env.PORT ?? 3010);
};
bootstrap();

We should be OK with the CORS.
Now, the long awaited moment: data fetching:

//src/app/pages/root.tsx
import { ModeToggle } from "@/components/mode-toggle";
import { useTRPC } from "@/utils/trpc";
import { Button } from "@repo/ui/components/ui/button";
import { useSuspenseQuery } from "@tanstack/react-query";

export const Root = () => {
  const trpc = useTRPC();

  const { data } = useSuspenseQuery(
    trpc.getHello.queryOptions({ name: "Friedrich" }),
  );

  return (
    <main>
      <div className="flex justify-between items-center p-4">
        <h1 className="text-4xl">Root</h1>
        <ModeToggle />
      </div>
      <p>Some text here</p>
      <Button>Shadcn button</Button>
      <p>Data fetched from the server: {data}</p>
    </main>
  );
};

And boom! We get the data:

web app (Astro)

Here too, we create a trpc client instance:

// src/utils/trpc.ts
import superjson from "superjson";

import type { AppRouter } from "@repo/trpc/router";
import { createTRPCProxyClient, httpBatchLink } from "@trpc/client";
import type { inferRouterInputs, inferRouterOutputs } from "@trpc/server";

export const trpc = createTRPCProxyClient<AppRouter>({
  links: [
    httpBatchLink({
      url: import.meta.env.PUBLIC_API_URL,
      transformer: superjson,
    }),
  ],
});

export type Inputs = inferRouterInputs<AppRouter>;
export type Outputs = inferRouterOutputs<AppRouter>;

Then define the url of the api in as an environment variable:

# .env.development in the web app
PUBLIC_API_URL=http://localhost:3010/trpc

And of course type safety enabled using a env.d.ts file:

interface ViteTypeOptions {
  strictImportMetaEnv: unknown;
}

interface ImportMetaEnv {
  readonly PUBLIC_API_URL: string;
}

interface ImportMeta {
  readonly env: ImportMetaEnv;
}

Similarly to the dashboard, we need to update the allowed clients to not be blocked by the CORS.

// src/constants.ts

export const ALLOWED_CLIENTS = [
  process.env.DASHBOARD_URL || "http://localhost:5173",
  process.env.WEB_APP_URL || "http://localhost:4321",
];

NODE_ENV=development
JWT_SECRET=...
DASHBOARD_URL=http://localhost:5175
WEB_APP_URL=http://localhost:4321

and

import { z } from "zod";

export const envSchema = z.object({
  NODE_ENV: z.enum(["production", "development"]),

  JWT_SECRET: z.string().trim().min(1),

  DASHBOARD_URL: z.url(),
  WEB_APP_URL: z.url(),
});

export type Env = z.infer<typeof envSchema>;

Good for data fetching:

---
import { ModeToggle } from "@/components/mode-toggle";
import Layout from "@/layouts/layout.Astro";
import { trpc } from "@/utils/trpc";
import { Button } from "@repo/ui/components/ui/button";

const data = await trpc.getHello.query({ name: "Friedrich" });
---

<Layout>
  <div class="flex items-center justify-between p-4">
    <h1 class="text-4xl">Web app</h1>
    <ModeToggle client:load />
  </div>
  <p>A text paragraph</p>
  <Button className="w-32">Shadcn button</Button>
  <p>Data fetched from the server: {data}</p>
</Layout>

Perfect!

We were able to setup a public procedure and call it from the clients, and it is type safe. We get auto-completion for our queries.

dashboard

web app

If I change the shape of the data returned on the backend for example, we will get immediate feedback on the frontend side.

I could try and do the same for a private procedure, but this would make this article way too long. I will stop here and continue in a part two. There, we will add private procedures and a PostgreSQL database if possible.

I really like this monorepo setup. On one hand, we get fully typed queries on our frontends, no way to make mistakes. The feedback is immediate if we change the entry or return type of a procedure in the backend. We can define procedures to get exactly what we need from the server: no under or over fetching. It works great with @tanstack/react-query which is almost a standard for data fetching in React applications. But on the other hand, it requires a bit of setup, especially with tsconfigs. Also tRPC doesn’t integrate well with REST and OpenAPI. There is a plugin to bridge that gap, but it has been archived. A solution I have considered to fix that issue is oRPC, but for the moment tRPC gets the job done.

Thanks you for reading and happy coding!

How to Set Up Prisma and MongoDB with Docker Compose for Development

Friedrich WT — Mon, 13 Apr 2026 15:52:02 +0000

Note: If you are here because you have this issue currently and you just want to copy and paste the code, click to jump directly there.

About two years ago, I wanted to use Prisma in a project but with MongoDB as database. Don’t ask me why, it was one of my first projects and from the fresh tutorial I just watched, the guy used MongoDB, then it was my choice without really understanding why. And in my case, I had a well structured schema for the database, so a relational database like PostgreSQL would have been a better choice. Also, my TypeScript orm of choice is now Drizzle, still I want to share about what was done.

The problem I had was to connect Prisma and MongoDB running in a docker container (local database). Even now, the recommended way according to Prisma docs to do it is to use MongoDB Atlas. This is because the MongoDB Prisma connector requires a replica set deployment for its transactions, and MongoDB Atlas provides such an environment out of the box. But what if you want everything locally (for development or testing for example), or if you want to be able to replicate that infrastructure without any external provider? This is exactly what we are going to do, using Docker Compose. We will use a Next.js application, but any other web framework would be fine.

Let’s start by defining what a replica set is. It appears more in Kubernetes jargon, but basically a replica set is a group of instances (database in our case) that maintain the same dataset. We replicate our data across multiple nodes to guarantee their availability. Instead of having one single database instance we will have for example three of them and if one goes down, the others will still work. In the case of MongoDB, the three base nodes are:

the primary: all writes to the database happen here
one or many secondary(ies): they replicate the data of the primary node and in case the primary node goes down, a secondary node will be elected to become the new primary node, and the system can still work as expected
the arbiter that will be an mediator when a secondary node is chosen as primary. It doesn’t provide data redundancy

A quick excalidraw draft of our replica set:

This is a very simplified description of how the MongoDB replica set works and if you want more details about MongoDB replication system, you can check their docs.

OK, now that we have an overview of the system that is required by Prisma to handle those transactions, it is time to write some code. Let’s start by creating a new Next.js application:

npx create-next-app@latest prisma-mongodb --yes

Then cd in:

cd prisma-mongodb

And start the development server:

npm run dev

I have setup a basic Nextjs to illustrate all this. This is just some markup and it doesn’t really matter.

You can find the exact state of the repo here : Initial setup

Next step is to install Prisma itself. Currently, the version 7 doesn’t support MongoDB. We need to use the version 6.19 which is the latest version with proper support for MongoDB.

We first install it as a dev dependency with the command:

npm install -D prisma@6.19

After, we also install the Prisma client (for database querying) and dotenv (to load the environment variables from a .env file)

Configure Nextjs for ESM compatibility. Make sure the following options are present in your tsconfig.json:

{
  "compilerOptions": {
    "module": "ESNext",
    "moduleResolution": "bundler",
    "strict": true,
    "esModuleInterop": true,
  }
}

And enable ESM in the package.json:

"type": module

We will now proceed to the initialization of Prisma ORM with:

npx prisma && npx prisma init --datasource-provider mongodb --output ../generated/prisma

Those commands will allow us to generate a prisma folder with a schema.prisma file to configure the database connection and a prisma.config.ts (configuration file).

Now comes the fun part: craft the DATABASE_URL. Currently with the commands we just ran, Prisma provides us a .env file with a dummy value for this environment variable.

DATABASE_URL="mongodb+srv://root:randompassword@cluster0.ab1cd.mongodb.net/mydb?retryWrites=true&w=majority"

It is composed of some key elements:

Protocol (Here mongodb+srv)
Base URL (root:randompassword@cluster0.ab1cd.mongodb.net) formed of the username of the database and its password then the host (which can also be something like localhost:27017)
The database (mydb)
Additional parameters (retryWrites=true&w=majority)

We are going to create our own replica set with Docker Compose and update the DATABASE_URL accordingly. Let’s start by creating a compose.yaml file (or docker-compose.yml):

Compose code

# compose.yaml or docker-compose.yml

services:
  mongodb-primary:
    image: bitnami/mongodb@${MONGODB_DIGEST}
    container_name: mongodb-primary
    env_file:
      - .env
      - db/.env.mongo.primary
    ports:
      - 127.0.0.1:27017:27017
    volumes:
      - demo-prisma-db:/bitnami
    networks:
      - app-network

  mongodb-secondary:
    image: bitnami/mongodb@${MONGODB_DIGEST}
    container_name: mongodb-secondary
    depends_on:
      - mongodb-primary
    env_file:
      - .env
      - db/.env.mongo.secondary
    ports:
      - 127.0.0.1:27018:27017
    networks:
      - app-network

  mongodb-arbiter:
    image: bitnami/mongodb@${MONGODB_DIGEST}
    container_name: mongodb-arbiter
    depends_on:
      - mongodb-primary
    env_file:
      - .env
      - db/.env.mongo.arbiter
    ports:
      - 127.0.0.1:27019:27017
    networks:
      - app-network

volumes:
  demo-prisma-db:
    driver: local

networks:
  app-network:
    driver: bridge

And the proper .env files:

The root .env:

MONGODB_DIGEST=sha256:4ff25cfca3d44751416fffcde9fc3847dcf49ace2998f244a3bf319d9e216125 # I pinned the version of the image to a specific one
MONGODB_REPLICA_SET_NAME=rs0 # The name of the replica set
MONGODB_REPLICA_SET_KEY=replicasetkey123 # The replica set key, required for all our nodes. The current value is just an example

A db folder at the root of the repository, with three .env files, each for one of the nodes:

.env.mongo.primary:

 MONGODB_REPLICA_SET_MODE=primary # The replication mode   (the type of node)
 MONGODB_ADVERTISED_HOSTNAME=mongodb-primary # It will  make the primary node configured with a hostname instead of an ip address. The other nodes will refer to him as  "mongodb-primary"
 MONGODB_ROOT_PASSWORD=password # The root password of the database, the current value is just an example

.env.mongo.secondary:

MONGODB_REPLICA_SET_MODE=secondary # The replication mode (the type of node)
MONGODB_INITIAL_PRIMARY_HOST=mongodb-primary # The hostname of our primary node
MONGODB_ADVERTISED_HOSTNAME=mongodb-secondary # The hostname of the secondary node
MONGODB_INITIAL_PRIMARY_ROOT_PASSWORD=password # The root password of the database

.env.mongo.arbiter:

 MONGODB_REPLICA_SET_MODE=arbiter # The replication mode (the type of node)
 MONGODB_INITIAL_PRIMARY_HOST=mongodb-primary # The hostname of our primary node
 MONGODB_ADVERTISED_HOSTNAME=mongodb-arbiter # The hostname of the arbiter node
 MONGODB_INITIAL_PRIMARY_ROOT_PASSWORD=password # The root password of the database

Now we should be able to start the replica set with:

docker compose up -d

Let’s check that it has properly started. For the primary node:

exec in it:

  docker exec -it mongo-primary bash

enter in mongosh with the proper authentication credentials:

   > mongosh -u root -p password 
   # The root user is the default user of the db and can be  changed by setting `MONGODB_ROOT_USER`
   # The password is the one we defined with  `MONGODB_ROOT_PASSWORD`

check:

  > db.isMaster().ismaster

It should output true.

For the secondary or arbitrary nodes we can repeat the same steps (exec and enter in mongosh) then check the content of our replica set:

rs.status().members

And see an output like:

[
  {
    _id: 0,
    name: 'mongodb-primary:27017',
    health: 1,
    state: 1,
    stateStr: 'PRIMARY',
      ...
  },
  {
    _id: 1,
    name: 'mongodb-secondary:27017',
    health: 1,
    state: 2,
    stateStr: 'SECONDARY',
      ...
  },
  {
    _id: 2,
    name: 'mongodb-arbiter:27017',
    health: 1,
    state: 7,
    stateStr: 'ARBITER',
    ...
  }
]

Finally we can set our DATABASE_URL in the root .env file:

DATABASE_URL=mongodb://root:password@localhost:27017/db-dev?replicaSet=rs0&authSource=admin

We use localhost:27017 for the host because we exposed the container of the primary node on our machine on 127.0.0.1:27017.

To test that everything works, let’s add some dummy models to our schema.prisma:

generator client {
  provider = "prisma-client"
  output   = "../generated/prisma"
}

datasource db {
  provider = "mongodb"
  url      = env("DATABASE_URL")
}

model User {
  id        String   @id @default(auto()) @map("_id") @db.ObjectId
  email     String   @unique
  posts     Post[]
  createdAt DateTime @default(now()) @db.Timestamp()
  updatedAt DateTime @default(now()) @updatedAt @db.Timestamp()
}

model Post {
  id        String   @id @default(auto()) @map("_id") @db.ObjectId
  title     String
  slug      String
  content   String
  published Boolean  @default(false)
  authorId  String   @db.ObjectId
  createdAt DateTime @default(now()) @db.Timestamp()
  updatedAt DateTime @default(now()) @updatedAt @db.Timestamp()

  author User @relation(fields: [authorId], references: [id])
}

After that we can sync the schema with:

npx prisma db push

which will generate the Prisma client and create the collections in MongoDB (we don’t use migrate because it doesn’t support migrations like relational databases). And to have a visual of all those changes, we can run the Prisma studio:

npx prisma studio

And open localhost:5555 where our two collections should display, even if they are currently empty.

Let’s instantiate the Prisma Client we will use in the application. I created a prisma.ts file in the lib folder of the app:

// lib/prisma.ts
import { PrismaClient } from "../../generated/prisma/client";

const globalForPrisma = global as unknown as { prisma: PrismaClient };

export const prisma = globalForPrisma.prisma || new PrismaClient();

if (process.env.NODE_ENV !== "production") globalForPrisma.prisma = prisma;

We make sure to create one single instance of the Prisma Client by using a global variable. And a seed script to put some dummy data in the database:

// lib/seed.ts
import { prisma } from "./prisma";

async function main() {
  // Create a new user with some posts
  await prisma.user.create({
    data: {
      email: "alice@test.test",

      posts: {
        createMany: {
          data: [
            {
              title: "First Post",
              slug: "first-post",
              content: "This is my first post!",
              published: true,
            },
            {
              title: "His mother had always taught him",
              slug: "his-mother-had-always-taught-him",
              content:
                "His mother had always taught him not to ever think of himself as better than others. He'd tried to live by this motto. He never looked down on those who were less fortunate or who had less money than him. But the stupidity of the group of people he was talking to made him change his mind.",
            },
            {
              title: "He was an expert but not in a discipline",
              slug: "he-was-an-expert-but-not-in-a-discipline",
              content:
                "He was an expert but not in a discipline that anyone could fully appreciate. He knew how to hold the cone just right so that the soft server ice-cream fell into it at the precise angle to form a perfect cone each and every time. It had taken years to perfect and he could now do it without even putting any thought behind it.",
              published: true,
            },
            {
              title: "Dave watched as the forest burned up on the hill",
              slug: "dave-watched-as-the-forest-burned-up-on-the-hill",
              content:
                "Dave watched as the forest burned up on the hill, only a few miles from her house. The car had been hastily packed and Marta was inside trying to round up the last of the pets. Dave went through his mental list of the most important papers and documents that they couldn't leave behind. He scolded himself for not having prepared these better in advance and hoped that he had remembered everything that was needed. He continued to wait for Marta to appear with the pets, but she still was nowhere to be seen.",
            },
          ],
        },
      },
    },
    include: {
      posts: true,
    },
  });
}

main()
  .then(async () => {
    await prisma.$disconnect();
  })
  .catch(async (e) => {
    console.error(e);
    await prisma.$disconnect();
    process.exit(1);
  });

Attach the seed script to the config in the prisma.config.ts (install tsx as a dev dependency)

import "dotenv/config";
import { defineConfig, env } from "prisma/config";

export default defineConfig({
  schema: "prisma/schema.prisma",
  migrations: {
    path: "prisma/migrations",
    seed: "tsx src/lib/seed.ts",
  },
  engine: "classic",
  datasource: {
    url: env("DATABASE_URL"),
  },
});

Then, run it with:

npx prisma db seed

And we should now seed those entries in the database through the Prisma Studio.

Let’s fetch that data in our application to properly display it:

Each post can be viewed individually:

And we can also create a new posts:

Which will appear

That’s it. We were able to create our replica set locally using Docker Compose, and connect to it in our application with Prisma. This setup is ideal for development and testing or when you don’t want to use MongoDB Atlas. Thanks you for reading and happy coding !

Introducing MoonCode: an application that monitors you coding activity, powered by a VS Code extension with offline support

Friedrich WT — Tue, 17 Mar 2026 16:48:28 +0000

During the last months, I have being building an application called MoonCode to track my coding time, languages and projects I was working on. And let me visualize all that on a modern looking dashboard. In this article, I want to write about it, the features it currently has, how it works, why I built it and what I learned along the way.

Presentation

MoonCode is a platform tracking and giving you a summary of your coding activity: coding time, languages, files, all in one single place. To use it, you just need to install the VS Code extension, login, then everything is handled for you. Currently the project only supports VS Code as code editor.

Website link: mooncode.cc

MoonCode’s Features

summary of your coding time, languages and projects per day, week, month, year, or any custom period
support for most programming languages and files extensions. The extension automatically detects the language you are using
the dashboard to visualize your data is local. It comes out of the box when you install the VS Code extension
real-time sync dashboard (every minute). The stats always stay fresh and up to date with the data collected by the extension
the extension works offline and synchronize to the API once you’re back online. So no data loss if you lose your internet connexion
it also keeps your stats up to date automatically

Some screenshots of the dashboard and the extension:

Link on the VS Code marketplace if you want to try it: MoonCode VS Code extension. And the GitHub repository: MoonCode.

Architecture

The main parts of MoonCode are:

a VS Code extension that collect all the relevant metrics (files data and programming languages)
an API that manages all requests, built using NestJS. This choice was made because of the modular architecture of the framework
a Vite+React Router dashboard that comes with the extension and allow you to visualize all the data in a user-friendly way
a PostgreSQL database: a battle tested and robust option for an SQL database, used to store all the data needed: user and analytics data in one single place
a Turborepo monorepo to keep all the parts and shared packages in a single, unified TypeScript codebase
trpc between the API, the dashboard and the VS Code extension to allow end-to-end type-safety within the monorepo
a website, built using NextJS. It is not really a core part, but more like the landing page of the project

So, in on excalidraw diagram it looks like this:

Why I wanted to build it

Why building a productivity coding time tracker when there are already plenty of them out there? Especially when there is already WakaTime doing the same thing, is more established, battle-tested and very feature-rich?

I found the free-tier of Wakatime a little bit limiting (as a cheap developer 😏). Don’t get me wrong, it is an awesome project and product and my goal is not to discredit it. I just decided to build my own, that does exactly what I need and give me full control over the data. About the data control, more on that later.

This project didn’t have to be feature complete, it didn’t have to be the perfect app, it just needed to solve that specific issue I had: track and monitor my coding statistics on any period I want.

And honestly this seemed as a very exciting side-project to work on. Because not only I would build something that could solve a problem I had, but it was very exciting to me personally. I already knew to build frontend web apps, but didn’t know enough about backend but the most interesting part was definitely the extension. How would it work and its life-cycle in general. I decided to focus only on VS Code for the moment because it is the code editor I use on the day to day.

What I learned/lessons

While building MoonCode I learned quite a few things about how VS Code extensions work, backend and APIs in general and Nest.js in particular. I also taught me some tips and tricks about TypeScript monorepos. I will try to be short here because some of the points deserve their own detailed blog post.

VS Code extensions: they were intimidating for me at the beginning, especially because not too much is said about them. We usually build frontend apps and backend systems, not vscode plugins. But the extensions are just Node.js applications with an entrypoint that is the extension.js (built from extension.ts) file, and it can be changed anyways. They have a package.json like any other Node.js app. The main difference with the other apps, is that you can use the VS Code API to create and execute VS Code commands, show notifications, subscribe to events happening in the code editor,… Two approaches are mostly used to build VS Code extensions: Functional Programming (FP) and Oriented Object Programming (OOP) approaches. I chose the FP approach since it is the one I was the most comfortable with.
Nest.js: before building MoonCode, I didn’t do a lot of backend, I had mostly worked with Next.js and even though it offers some backend functionalities, it is not a full fleshed backend framework. In my case the API I will build would be consumed by the extension itself, the dashboard and maybe other applications/packages later. So a separate backend was necessary. As I said earlier, I chose Nest.js for it scalability and opinionated nature (in fact, I wanted to try something new that was stricter, stable and battle-tested so I could really learn the backend side of applications). And I can say without any doubt that it is an, awesome framework, everything is organised in modules and properly separated. Even though Nest.js uses Oriented Object Programming, I didn’t need to be a master at it to be productive. The mental model was a little bit odd at the beginning but I started to click as I was using it.
TypeScript monorepos and trpc: Turborepo is a simple yet very powerful tool to manage TypeScript monorepos, but it took me a very long time (many weeks/months) to really take advantages of its features: the cli, the cache,… I also used trpc to make everything typesafe from the backend to the frontend apps. It is so beautiful how the typesafety flows like water in the different applications. But it was very tricky to setup. I messed a lot with tsconfigs across the monorepo to get what I wanted. Some apps used ES Modules, others like Nest were still on CommonJS… It was a real chaos to make everybody share a typesafe contract, but it ended up being wired properly. What I also really like about monorepos is the ability to share common code/utility functions between all the apps in packages.
Docker in monorepos: this one is also tricky but I can just have one single docker compose file with all my apps. Each of them has its own dockerfile. Or (this one is my favorite approach) deploy each app individually using its Dockerfile.

Building MoonCode was a real journey, I learned a lot. Some days it got very tricky due to the nature of what I was building (a VS Code extension was something new, but working with time in programming is, well, very tricky). But one thing I would 100% avoid if I had to start again is over-engineering. I wasted so many hours, days and even weeks trying to perfect the folder structure of the apps, get the ESLint rules right, …. It was useful in some cases like the VS Code extension and otherwise I would have ended with a real mess. But some days I felt like it was more like an excuse to not continue building, a fake productivity.

I still fall in that trap and I’m learning to detect when I start over-engineering and stop it if so. I have shipped the extension way earlier but I spent a lot of time fixing small issues, not getting anything really serious done for a long time. This is something I needed to hammer down in my head: avoid over-engineering at all costs. Perfection is the enemy, it kills momentum. Ship something that works. It doesn’t mean produce bad quality code, but just get it done. And move on with your day.

About the data ownership, one of initial goals of this project was to make it in a way to allow the user(s) to self-host the API and the database. This can be accomplished with Docker for sure. And since the dashboard is bundled with the VS Code extension, it doesn’t have to be self-hosted. The pain point I hit was to wire the VS Code extension and the API, so the user could update the API URL in the VS Code extension to their self-hosted version. I might find a good solution and ship it soon.

So, yes, that’s it. Thanks you if you made if so far in the article and happy coding !