DEV Community: Martin Persson

[Boost]

Martin Persson — Mon, 27 Oct 2025 12:09:37 +0000

Orion Kit: Production-Ready SaaS Template (Next.js 15, TypeScript, Stripe, Drizzle)

Martin Persson ・ Oct 18

#typescript #nextjs #webdev #saas

If you're building SaaS, learning how monorepos work or just want to see how modern TypeScript apps are structured. Orion Kit shows you the full stack: Next.js 15, Drizzle ORM, Stripe payments & JWT auth. Hope it's helpful!

Martin Persson — Tue, 21 Oct 2025 08:14:31 +0000

Martin Persson

Oct 18 '25

Orion Kit: Production-Ready SaaS Template (Next.js 15, TypeScript, Stripe, Drizzle)

#typescript #nextjs #webdev #saas

Comments

4 min read

Orion Kit: Production-Ready SaaS Template (Next.js 15, TypeScript, Stripe, Drizzle)

Martin Persson — Sat, 18 Oct 2025 14:42:31 +0000

TL;DR – Open-source monorepo template with Next.js 15, JWT auth, Stripe payments, PostgreSQL (Neon), Drizzle,complete documentation and much more. Designed to make the initial setup overhead for TypeScript SaaS projects simple while keeping strict end-to-end types.

What This Is

Orion Kit is a TypeScript monorepo template that includes the infrastructure most SaaS applications need: user authentication, payment processing, database with migrations, transactional emails, analytics, and background jobs. These systems are pre-configured and integrated, but the template also makes it easy to add features like AI integration, file uploads, i18n, CMS, real-time updates, or rate limiting.

The architecture demonstrates type-safe full-stack development where database schemas automatically generate TypeScript types used throughout your API and frontend—eliminating type mismatches and keeping your codebase in sync as you evolve your data model.

What’s Inside

Applications (4)

Marketing site – /apps/web (port 3000): Landing page & public marketing.
Dashboard – /apps/app (port 3001): Authenticated UI with tasks, billing, basic analytics.
API – /apps/api (port 3002): REST endpoints with auth middleware and Stripe webhooks.
Documentation – /apps/docs (port 3004): Astro Starlight docs.

Shared Packages (9)

@workspace/auth – JWT authentication & user management.
@workspace/database – Drizzle ORM with Neon PostgreSQL (migrations & schema).
@workspace/types – Shared TypeScript types across apps & packages.
@workspace/ui – shadcn/ui component library.
@workspace/payment – Stripe subscriptions & Billing Portal utilities.
@workspace/email – Resend integration with React Email templates.
@workspace/analytics – PostHog event tracking helpers.
@workspace/observability – Axiom logging & error reporting.
@workspace/jobs – Trigger.dev background job processing.

Technical Architecture

Type Safety Flow

Single Source of Truth: the database schema.

Define tables & columns in Drizzle.
Drizzle generates TypeScript types from PostgreSQL.
Those types flow through @workspace/database → API validation (Zod) → frontend forms (React Hook Form + Zod) → UI components.

Result: If you rename a DB column, TypeScript flags every affected usage across the monorepo. No silent mismatches between layers.

PostgreSQL (Neon) → Drizzle schema → Drizzle types → API handlers → Zod validators → React forms/components

Monorepo Structure

Orchestrated by Turborepo. Apps import from shared packages using the workspace protocol (@workspace/*) for code reuse with clear boundaries.

.
├─ apps/
│  ├─ web/         # marketing (Next.js 15)
│  ├─ app/         # dashboard (Next.js 15)
│  ├─ api/         # REST API (Next.js 15 / Route Handlers)
│  ├─ studio/      # Drizzle Studio to interact with the database
│  └─ docs/        # documentation (Astro Starlight)
├─ packages/
│  ├─ auth/
│  ├─ database/
│  ├─ types/
│  ├─ ui/
│  ├─ payment/
│  ├─ email/
│  ├─ analytics/
│  ├─ observability/
│  └─ jobs/
└─ turbo.json / package.json / tsconfig.json / .env* / etc.

Integrated Features

Authentication

Custom JWT implementation with protected routes.
Sessions managed server-side; token stored client-side (e.g., localStorage).
Middleware auto-protects authenticated routes.

Payments

Stripe Checkout for subscriptions.
Webhook handlers for payment lifecycle events.
Billing Portal integration out of the box.
Centralized pricing configuration & subscription helpers in @workspace/payment.

Database

Serverless PostgreSQL via Neon.
Drizzle ORM for type-safe queries & migrations (version controlled).
Comes with a basic DB Studio config for quick inspection.

Email

Resend for transactional email.
React Email templates with a welcome sequence and extensible template system.

Testing

Vitest for unit tests.
Playwright for end-to-end tests (auth flow & critical navigation paths).

Observability & Analytics

PostHog for product analytics (SDK wired to middleware & app events).
Axiom for logs & error reporting (server + edge).

Background Jobs

Trigger.dev orchestrates background tasks from @workspace/jobs.

Development Workflow

Run all apps concurrently with hot reload; changes in packages are instantly reflected in dependents thanks to Turborepo + workspace linking.

App	Path	Port
Marketing	`/apps/web`	3000
Dashboard	`/apps/app`	3001
API	`/apps/api`	3002
Docs	`/apps/docs`	3004

Required Services (all have generous free tiers)

Neon – PostgreSQL hosting
Stripe – Payments
Resend – Email delivery
PostHog – Analytics
Axiom – Logging & monitoring

Stripe CLI to test payments locally

Configuration examples for each live in the docs and .env.example files.

Getting Started

Prerequisites

Node 20+
pnpm (recommended)
Accounts/keys for: Neon, Stripe, Resend, PostHog, Axiom

1) Clone & install

pnpm i

2) Environment variables

Copy the example and fill in values:

cp .env.example .env
cp apps/api/.env.example apps/api/.env
cp apps/app/.env.example apps/app/.env
cp apps/web/.env.example apps/web/.env
cp apps/docs/.env.example apps/docs/.env

See /apps/docs for service-by-service setup. Stripe requires adding webhook secrets; Neon requires a database URL; etc.

3) Database

pnpm db:generate   # drizzle generate
pnpm db:migrate    # run migrations

4) Dev servers

pnpm dev           # starts web (3000), app (3001), api (3002), docs (3004)

5) Tests

pnpm test          # unit (Vitest)
pnpm test:e2e      # e2e (Playwright)

Documentation

Built with Astro Starlight (Markdown, searchable) at /apps/docs.

Coverage:

Quick start
Architectural decisions & data flow
Package API references
Integration guides (AI, CMS, i18n, file uploads, etc.)
Testing strategies
Deployment instructions

Use Cases

Great as a starting point for:

SaaS with auth & subscriptions
Internal tools with role-based access & analytics
MVPs where infra setup must be minimal
Learning resource for modern TypeScript architecture

Licensed under MIT for unrestricted use & modification.

Deployment (Overview)

Web/App/API → Vercel (or similar). Route Handlers power REST & webhooks.
Database → Neon (serverless Postgres).
Stripe → Set live keys & webhook endpoints.
Resend → Configure domain & production API key.
PostHog/Axiom → Set environment keys; verify event/log flow.

Detailed, step-by-step instructions are in the docs.

Contributing

Contributions & feedback are welcome! Feel free to open Issues and PRs. Please include:

Clear description of the change
Screenshots (for UI)
Tests where applicable

Build something you’re proud of. Launch it into orbit. 🚀

[Boost]

Martin Persson — Mon, 25 Aug 2025 11:04:56 +0000

Martin Persson

Aug 19 '25

How I Use Effect.ts to Orchestrate a Type-Safe GraphQL Backend

#webdev #typescript #graphql #backend

Comments 1

8 min read

How I Use Effect.ts to Orchestrate a Type-Safe GraphQL Backend

Martin Persson — Tue, 19 Aug 2025 09:46:57 +0000

Building a Robust Backend with Effect, GraphQL, and Drizzle

Link to Github repo

Introduction
The Problem
The Solution
- Effect: Functional Effects for Robust Error Handling
- Gradual Migration: Mix Effect and Promises
- Branded Types: Type Safety That Actually Works
Architecture Overview
- Domain Layer
- Repository Layer
Key Features
- Robust Error Handling
- Performance Optimizations
- Circular Relationship Prevention
- Tree Operations
Important Disclaimer: This is a Demo
Benefits
- Compile-Time Safety
- Debugging-Friendly
- Testable Code
- Maintainable
Getting Started
- Available Scripts
- GraphQL API
Key Takeaways
Conclusion

Introduction

This post demonstrates how to build a type-safe, robust backend using Effect, GraphQL, and Drizzle ORM. I built a hierarchical ticket management system to showcase functional programming principles in a real-world application.

The project shows how to handle complex business logic with proper error handling, type safety, and gradual migration from existing codebases. It's designed to be educational rather than production-optimized.

The Problem

Most backend applications suffer from:

Silent failures: Errors get swallowed by generic catch blocks
Type safety theater: TypeScript types that don't actually prevent runtime errors
Tight coupling: Business logic mixed with infrastructure concerns
Poor error handling: Generic error messages that don't help debugging
Difficult testing: Business logic entangled with side effects
Hard to reason about: Complex async flows that are hard to follow

The Solution

A ticket management system that handles hierarchical data with proper error handling and type safety. The system supports:

Hierarchical ticket structures (parent-child relationships)
Cascade operations (toggle, delete entire subtrees)
Circular relationship prevention
Parallel processing for performance
Comprehensive error handling with specific error types

1. Effect: Functional Effects for Robust Error Handling

Effect is a TypeScript library that brings functional programming principles to the real world. Instead of throwing errors or returning null, Effect forces you to handle all possible outcomes explicitly.

// Traditional approach - fragile
const findTicket = (id: number) => {
  const ticket = database.find(id);
  if (!ticket) throw new Error("Not found");
  return ticket;
}

// Effect approach - robust
const findTicket = (id: TicketId) =>
  Effect.gen(function* () {
    const ticket = yield* repository.findById(id);
    return yield* Effect.flatMap(
      ticket,
      Option.match({
        onNone: () => Effect.fail(new TicketNotFoundError(`Failed to find ticket with ID ${id}`)),
        onSome: Effect.succeed,
      })
    );
  });

Effect provides several benefits:

Explicit error handling: All possible failure cases must be handled
Composable operations: Chain operations together safely
Dependency injection: Services are injected through layers
Type safety: Compile-time guarantees about error handling

2. Gradual Migration: Mix Effect and Promises

You don't need to rewrite everything at once. The adapter allows mixing Effect-based and Promise-based resolvers:

export const enableEffectResolvers = (schema: GraphQLSchema) => {
  return mapSchema(schema, {
    [MapperKind.ROOT_FIELD]: (fieldConfig) => {
      const originalResolver = fieldConfig.resolve
      if (!originalResolver) {
        return fieldConfig
      }
      return {
        ...fieldConfig,
        async resolve(parent, args, context, info) {
          const result = originalResolver(parent, args, context, info)

          if (Effect.isEffect(result)) {
            return await Effect.runPromise(result.pipe(Effect.provide(AppLayer)))
          }

          // This adapter allows mixing Effect and Promise-based resolvers in the same codebase.
          // If the resolver returns a Promise instead of an Effect, it will be executed as-is.
          // This enables incremental migration from Promise-based to Effect-based code without
          // requiring a complete rewrite of all resolvers at once.
        },
      }
    },
  })
}

This approach enables:

Incremental adoption: Start with new features using Effect
Risk mitigation: Keep existing code working while migrating
Team learning: Gradually introduce functional concepts
Proof of concept: Demonstrate benefits before full migration

3. Branded Types: Type Safety That Actually Works

Instead of using plain numbers for IDs, branded types prevent mixing up different kinds of IDs:

export type TicketId = number & Brand.Brand<"TicketId">

export const TicketIdSchema = Schema.NumberFromString.pipe(
  Schema.int(),
  Schema.nonNegative(),
  Schema.brand("TicketId")
)

This means you can't accidentally pass a UserId where a TicketId is expected - TypeScript will catch it at compile time.

Benefits of branded types:

Prevent bugs: TypeScript catches ID mixing at compile time
Self-documenting: Code clearly shows what type of ID is expected
Refactoring safety: Changes to ID types are caught immediately
Better IDE support: Autocomplete and error detection work correctly

Architecture Overview

The project follows a clean architecture pattern with clear separation of concerns:

domain/           # Business logic, models, schemas
├── ticket/
│   ├── model.ts      # Drizzle table definitions
│   ├── schema.ts     # Input validation & branded types
│   ├── service.ts    # Business logic
│   ├── repository.ts # Database access
│   └── helpers.ts    # Tree manipulation utilities
graphql/          # API layer
├── resolvers/    # GraphQL resolvers with error handling
└── schema/       # GraphQL type definitions
lib/              # Infrastructure
├── db.ts         # Database setup
└── utils.ts      # Response helpers
adapter/          # Integration layer
└── effectAdapter.ts # Effect integration with GraphQL

Domain Layer

The domain layer contains all business logic and is completely independent of infrastructure concerns:

export class TicketService extends Effect.Service<TicketService>()("Ticket/Service", {
  effect: Effect.gen(function* () {
    const repository = yield* TicketRepository
    const helper = yield* HelperService

    const toggleTicket = (input: typeof ToggleTicketInput.Type) =>
      Effect.gen(function* () {
        // Business logic here
      })

    return {
      findById,
      createTicket,
      findAll,
      deleteTicket,
      toggleTicket,
      removeParentFromTicket,
      setParentOfTicket,
      addChildrenToTicket,
    } as const
  }),
  dependencies: [TicketRepository.Default, HelperService.Default],
})

Repository Layer

The repository layer handles database operations with proper error handling:

export class TicketRepository extends Effect.Service<TicketRepository>()("Ticket/Repo", {
  effect: Effect.gen(function* () {
    const db = yield* SqliteDrizzle.SqliteDrizzle

    const findById = (id: TicketId) => {
      return Effect.gen(function* () {
        const rowsResult = yield* db.select().from(tickets).where(eq(tickets.id, id))
        return Option.fromNullable(rowsResult[0])
      })
    }

    return {
      findById,
      createTicket,
      deleteTicket,
      findAll,
      toggleTicket,
      findChildren,
      removeParent,
      setParent,
    } as const
  }),
  dependencies: [DatabaseLive],
})

Key Features

Robust Error Handling

Every operation has comprehensive error handling with specific error types:

Effect.catchTags({
  ParseError: (error) => Effect.gen(function* () {
    yield* Effect.logError(`❌ Invalid input format: ${error.message}`);
    return yield* errorResponse(`Invalid parameters. Please check your input.`);
  }),
  TicketNotFoundError: (error) => Effect.gen(function* () {
    yield* Effect.logError(`🔍 Ticket not found: ${error.message}`);
    return yield* errorResponse(`Ticket not found. Cannot perform operation on non-existent ticket.`);
  }),
  CircularRelationshipError: (error) => Effect.gen(function* () {
    yield* Effect.logError(`🔄 Circular relationship detected: ${error.message}`);
    return yield* errorResponse(`Cannot create circular parent-child relationship.`);
  }),
  TimeoutException: (error) => Effect.gen(function* () {
    yield* Effect.logError(`⏰ Operation timeout: ${error.message}`);
    return yield* errorResponse(`Operation took too long. Please try again.`);
  }),
  SqlError: (error) => Effect.gen(function* () {
    yield* Effect.logError(`�� Database error: ${error.message}`);
    return yield* errorResponse(`Database connection issue. Please try again later.`);
  }),
});

Performance Optimizations

Parallel processing for operations that affect multiple tickets:

yield* Effect.forEach(
  allTickets,
  (ticket) => repository.toggleTicket({ id: ticket.id as TicketId, isCompleted: input.isCompleted }),
  { concurrency: 5 }
);

Circular Relationship Prevention

The system prevents circular relationships in the ticket hierarchy:

const checkCircularRelationships = (childId: TicketId, parentId: TicketId) =>
  Effect.gen(function* () {
    const visited = new Set<TicketId>([childId])
    let currentId = parentId

    while (true) {
      if (visited.has(currentId)) {
        return yield* Effect.fail(
          new CircularRelationshipError(
            `Circular relationship detected: setting ticket ${childId} as parent of ${parentId} would create a cycle`
          )
        )
      }
      visited.add(currentId)

      const current = yield* repository.findById(currentId)
      const result = Option.match(current, {
        onNone: () => false,
        onSome: (ticket) => {
          if (ticket.parentId === null) {
            return false
          }
          currentId = ticket.parentId as TicketId
          return true
        },
      })

      if (!result) {
        return yield* Effect.void
      }
    }
  })

Tree Operations

The system supports complex tree operations like cascade toggle and delete:

const enrichTicketTree = (rootTicket: Ticket, maxDepth = 10) =>
  Effect.gen(function* () {
    const queue = yield* Queue.unbounded<TicketWithChildren>()
    const withChildren = yield* getMaybeChildren(rootTicket)
    yield* Queue.offer(queue, withChildren)

    let depth = 0

    while (depth++ < maxDepth) {
      const currentLevel = yield* Queue.takeUpTo(queue, 100)

      for (const ticket of currentLevel) {
        if (ticket.children.length > 0) {
          for (const child of ticket.children) {
            const enriched = yield* getMaybeChildren(child)
            yield* Queue.offer(queue, enriched)
            ticket.children = ticket.children.map((child) => (child.id === enriched.id ? enriched : child))
          }
        }
      }

      if (currentLevel.length === 0) {
        break
      }
    }

    return withChildren
  })

Important Disclaimer: This is a Demo

This ticket system is designed to showcase Effect and functional programming principles, not to be the most efficient ticket management system.

For example, I'm doing recursive tree traversal and multiple database calls where a few well-crafted SQL queries could do the same job more efficiently. But that would defeat the purpose of demonstrating Effect's capabilities.

The goal is to show how Effect can handle complex business logic with proper error handling, not to optimize for database performance.

Benefits

1. Compile-Time Safety

TypeScript catches most errors before runtime, and Effect ensures all error cases are handled:

Type safety: Branded types prevent ID mixing
Error handling: All failure cases must be explicitly handled
Dependency injection: Services are properly injected and typed
Composition: Operations can be safely composed

2. Debugging-Friendly

Specific error types and comprehensive logging:

🔄 Starting cascade toggle for ticket ID: 1 to true
 Toggling 6 tickets to true
✅ Cascade toggle completed: 6 tickets updated

The logging system provides:

Structured logs: Each operation is clearly logged
Error context: Specific error types with meaningful messages
Operation tracking: Easy to follow the flow of operations
Performance insights: Timing and concurrency information

3. Testable Code

The functional approach makes testing straightforward:

describe("TicketService", () => {
  describe("findById", () => {
    it("should find a ticket by id", async () => {
      const TicketServiceMock = new TicketService({
        ...DefaultServiceMockImplementation,
        findById: vi.fn().mockReturnValue(
          Effect.succeed({
            id: 1 as TicketId,
            title: "Test Ticket",
            description: "Test Description",
            parentId: null,
            completed: false,
            createdAt: new Date(),
            updatedAt: new Date(),
          })
        ),
      })

      const result = await Effect.runPromise(
        Effect.gen(function* () {
          const ticketService = yield* TicketService
          const ticket = yield* ticketService.findById(1 as TicketId)
          return ticket
        }).pipe(Effect.provide(Layer.succeed(TicketService, TicketServiceMock)))
      )

      expect(result.title).toBe("Test Ticket")
      expect(TicketServiceMock.findById).toHaveBeenCalledWith(1)
    })
  })
})

Benefits of this testing approach:

Pure functions: Easy to test business logic in isolation
Mockable dependencies: Services can be easily mocked
Type safety: Tests benefit from the same type safety as production code
Comprehensive coverage: All error cases can be tested

4. Maintainable

Clear separation of concerns and explicit error handling make the codebase easy to understand and modify:

Separation of concerns: Business logic, data access, and API layers are separate
Explicit dependencies: All dependencies are clearly declared
Consistent patterns: Effect patterns are used consistently throughout
Documentation: Code is self-documenting through types and structure

Getting Started

git clone <repository>
npm install
npm run db:seed
npm run dev

The system comes with a comprehensive GraphQL API at http://localhost:4000.

Available Scripts

npm start: Start the production server
npm run dev: Start the development server with hot reload
npm run db:seed: Seed the database with sample data
npm run db:drop: Delete the database file
npm run db:reset: Reset the database (drop + seed)
npm test: Run tests
npm run test:watch: Run tests in watch mode
npm run test:coverage: Run tests with coverage

GraphQL API

The API provides the following operations:

Queries:

findAll: Get root tickets with pagination
findById: Get a specific ticket with its complete tree

Mutations:

createTicket: Create a new root ticket
toggleTicket: Toggle completion status (cascade)
deleteTicket: Delete a ticket and all descendants
removeParentFromTicket: Convert child to root ticket
setParentOfTicket: Move ticket to new parent
addChildrenToTicket: Add multiple children to a parent

Key Takeaways

Functional programming solves real problems in production code
Gradual migration is possible - you don't need to rewrite everything at once
Type safety matters - branded types prevent entire classes of bugs
Error handling should be explicit - don't let errors slip through the cracks
Effect works great with existing tools - Apollo GraphQL Server, Drizzle ORM, etc.
Testing becomes easier with pure functions and explicit dependencies
Code is more maintainable with clear separation of concerns
Debugging is improved with structured logging and specific error types

Conclusion

Effect, combined with GraphQL and Drizzle, creates a development experience that's both productive and reliable. The functional approach forces you to handle errors explicitly while maintaining type safety throughout the application.

The gradual migration approach makes it practical to adopt these patterns in existing codebases, while the comprehensive error handling and testing capabilities make the resulting code more robust and maintainable.

This approach isn't just about using trendy functional programming concepts - it's about building software that's easier to reason about, test, and maintain in the long run.

Building a Real-Time Chat App with Firebase and Next.js

Martin Persson — Wed, 23 Apr 2025 17:46:29 +0000

Introduction
Tech Stack
Project Overview
Firebase Setup
Message Schema with Zod
Real-Time Messaging with Firestore
Pagination and Lazy Loading
Scroll Behavior
UI with shadcn/ui and Tailwind
Handling Edge Cases
Conclusion

Introduction

This post walks through the process of building a modern real-time chat application using Next.js, Firebase Firestore, and Tailwind CSS. The app allows users to enter a display name and join a live chat where messages are synced instantly across clients. It supports lazy loading of older messages, smooth scroll behavior, and a clean, responsive UI built with minimal dependencies.

View the repository on GitHub

Tech Stack

Next.js for the React framework
Firebase Firestore for real-time database
Tailwind CSS for styling
shadcn/ui for prebuilt UI components
Zod for runtime validation of messages

Project Overview

The chat app begins with a simple prompt asking for your display name. Once submitted, you're taken to the main chat interface. It displays the 25 most recent messages by default and anchors the view to the bottom. As users scroll up, older messages are fetched and added seamlessly. All messages are updated in real-time using Firestore subscriptions, ensuring that new content appears instantly across all clients.

Firebase Setup

To get started with Firebase and Firestore:

1. Create a Firebase project:

Go to Firebase Console.
Click “Add project” and follow the setup wizard (you can skip Google Analytics).

2. Add Firestore to your project:

In the Firebase Console, navigate to Build > Firestore Database.
Click “Create database”, select Start in test mode, and choose your region.

3. Create a Web App in Firebase:

Go to Project Settings > General.
Scroll down to “Your apps” and click the </> icon to add a new web app.
Register your app and Firebase will generate your configuration object.

4. Set up environment variables:

In your project root, create a file named .env.local and add the following using your config values:

NEXT_PUBLIC_FIREBASE_API_KEY=your_api_key
NEXT_PUBLIC_FIREBASE_AUTH_DOMAIN=your_auth_domain
NEXT_PUBLIC_FIREBASE_PROJECT_ID=your_project_id
NEXT_PUBLIC_FIREBASE_STORAGE_BUCKET=your_storage_bucket
NEXT_PUBLIC_FIREBASE_MESSAGING_SENDER_ID=your_sender_id
NEXT_PUBLIC_FIREBASE_APP_ID=your_app_id
NEXT_PUBLIC_FIREBASE_COLLECTION=your_unique_collection_name

5. Initialize Firebase in your app:

Create a file like lib/firebase.ts:

import { initializeApp } from "firebase/app"
import { getFirestore } from "firebase/firestore"

const firebaseConfig = {
  apiKey: process.env.NEXT_PUBLIC_FIREBASE_API_KEY,
  authDomain: process.env.NEXT_PUBLIC_FIREBASE_AUTH_DOMAIN,
  projectId: process.env.NEXT_PUBLIC_FIREBASE_PROJECT_ID,
  storageBucket: process.env.NEXT_PUBLIC_FIREBASE_STORAGE_BUCKET,
  messagingSenderId: process.env.NEXT_PUBLIC_FIREBASE_MESSAGING_SENDER_ID,
  appId: process.env.NEXT_PUBLIC_FIREBASE_APP_ID,
}

const app = initializeApp(firebaseConfig)
export const db = getFirestore(app)

You're now ready to use Firestore to store and retrieve chat messages in real time.

Message Schema with Zod

In this project, we take a code-first approach when working with Firestore. Instead of relying on Firestore rules or ad-hoc validation, we define the shape and structure of a valid message directly in our application code using Zod.

Zod is a TypeScript-first schema declaration and validation library. It allows us to describe the expected structure of a message object and ensure that any data coming from or going to Firestore matches this schema.

This improves data consistency and safety. For example, it prevents malformed data from being saved or rendered, and avoids bugs caused by missing or invalid fields.

Here’s the schema definition:

import { z } from "zod"
import { Timestamp } from "firebase/firestore"

export const messageSchema = z.object({
  id: z.string(),
  text: z.string().min(1),
  sender: z.string(),
  timestamp: z.instanceof(Timestamp),
})

export type Message = z.infer<typeof messageSchema>

We use this schema in three main places:

When sending messages – to ensure the message has the right shape before adding it to Firestore.
When fetching messages – to validate all messages returned from Firestore queries.
When listening to new messages in real time – to discard or warn about any data that doesn’t match the schema.

This helps enforce strict typing and protects your frontend from unexpected data issues, especially in real-time applications.

Real-Time Messaging with Firestore

To enable real-time chat functionality, the app leverages Firestore’s onSnapshot() method. This sets up a listener on the collection that receives updates whenever new documents (messages) are added that match the query criteria.

In our implementation, we subscribe only to messages with a timestamp greater than the most recent message already displayed. This prevents re-fetching old messages. Every new message is parsed and validated with zod before it's added to the UI, ensuring both real-time updates and schema safety.

Pagination and Lazy Loading

The chat is optimized for performance and user experience using a lazy loading strategy. On initial load, the app fetches only the 25 most recent messages using a descending order query. These are then reversed to maintain chronological order.

When the user scrolls upwards, additional older messages are fetched using startAfter(lastDoc) to avoid duplicates. This paginated approach ensures scalability and smooth UX without overloading the UI with too many messages at once.

Scroll Behavior

The scroll behavior is intelligently managed:

On first load or when a new message is sent/received, the chat automatically scrolls to the bottom.
When loading older messages, the app maintains the user's current scroll position to avoid disorienting jumps.

This logic provides a seamless experience, especially in long conversations, and mimics the behavior of popular chat apps.

UI with shadcn/ui and Tailwind

The user interface is built using components from shadcn/ui, a utility-focused library that integrates seamlessly with Tailwind CSS. For example, we use Textarea for message input and Button for actions like sending messages. These components provide a clean foundation with minimal styling, allowing us to maintain design consistency while focusing on function.

Tailwind CSS is used throughout for layout and spacing. It ensures that the chat UI is responsive and visually balanced across different screen sizes without the need for custom CSS.

Handling Edge Cases

To provide a smooth and robust user experience, several edge cases are considered and handled:

Empty Chats: If there are no messages yet, the app handles the empty state gracefully without crashing or rendering errors.
Realtime Handling of Own Sent Message: Messages sent by the current user appear instantly and are not duplicated when received via the real-time listener.
Debouncing Scroll Fetches: Scroll-triggered fetching of older messages is debounced to avoid spamming the backend with requests.
Avoiding Duplicate Message Entries: Before adding any new message to the list, the app checks for existing message IDs to prevent duplicates in the UI.

Conclusion

This project demonstrates how to build a full-featured real-time chat app using Firebase Firestore, Next.js, and modern UI tools like Tailwind CSS and shadcn/ui.

It showcases best practices such as:

Code-first schema validation with Zod
Real-time data updates using Firestore subscriptions
Efficient lazy loading and scroll handling
Clean and minimal UI with reusable components

The architecture is intentionally kept simple and readable to emphasize clarity over complexity. Whether you're testing this for a coding challenge or building on top of it for a larger project, this foundation provides a strong starting point.

Feel free to reach out with questions, feedback, or suggestions. I'd love to hear what you think!

Discriminated Unions in C# with OneOf – Azure Functions

Martin Persson — Mon, 24 Mar 2025 22:03:48 +0000

🧠 What Are Discriminated Unions?

A discriminated union is a type that can represent one of several distinct outcomes, but never more than one at a time. They are native to F#, Rust, TypeScript, and other functional languages.

In C#, we simulate this using the excellent OneOf library.

🧼 Why Classic C# Fails Here

Pattern	Why it's bad
`null`	No context — what went wrong?
`bool TryX(out T)`	Hard to read, hard to test
`try/catch` as logic	Expensive, messy, and often misused
Exception everywhere	Breaks flow, pollutes logic

✅ Why OneOf Is Better

Type-safe return values
Explicit control over outcomes
Functional-style .Match(...)
Easier to test, reason about, and maintain
Avoids throwing exceptions for flow control

🛠 Setup

dotnet new azure-functions -n OneOfDemo --worker-runtime dotnetIsolated
cd OneOfDemo
dotnet add package OneOf

📦 Define Your Result Types

public record User(int Id, string Name);
public record NotFoundError(string Message);
public record TimeoutError(string Message);
public record ValidationError(string Message);
public record UnknownError(string Message);

🔧 Build the Service Layer

public class UserService
{
    private readonly HttpClient _http = new()
    {
        BaseAddress = new Uri("https://jsonplaceholder.typicode.com")
    };

    public async Task<OneOf<User, NotFoundError, TimeoutError, UnknownError, ValidationError>> GetUserByIdAsync(int id)
    {
        if (id <= 0)
            return new ValidationError("Id must be greater than 0.");
        if (id == 99)
            return new TimeoutError("Simulated timeout.");
        if (id == 42)
            return new UnknownError("Simulated crash.");

        try
        {
            var response = await _http.GetAsync($"/users/{id}");
            if (!response.IsSuccessStatusCode)
                return new NotFoundError("User not found.");

            var user = await response.Content.ReadFromJsonAsync<User>();
            return user ?? new NotFoundError("User not found.");
        }
        catch (Exception ex)
        {
            return new UnknownError($"Unexpected error: {ex.Message}");
        }
    }
}

🚀 Azure Function Using Match

[Function("GetUserById")]
public async Task<HttpResponseData> Run(
  [HttpTrigger(AuthorizationLevel.Anonymous, "get", Route = "users/{id:int}")] HttpRequestData req,
  int id)
{
    var result = await _service.GetUserByIdAsync(id);

    return await result.Match<Task<HttpResponseData>>(
        async user => req.CreateJsonResponse(HttpStatusCode.OK, user),
        async notFound => req.CreateJsonResponse(HttpStatusCode.NotFound, new { error = notFound.Message }),
        async timeout => req.CreateJsonResponse(HttpStatusCode.RequestTimeout, new { error = timeout.Message }),
        async unknown => req.CreateJsonResponse(HttpStatusCode.InternalServerError, new { error = unknown.Message }),
        async validation => req.CreateJsonResponse(HttpStatusCode.BadRequest, new { error = validation.Message })
    );
}

🧼 Extension Method

public static class HttpResponseExtensions
{
    public static async Task<HttpResponseData> CreateJsonResponse<T>(this HttpRequestData req, HttpStatusCode status, T body)
    {
        var response = req.CreateResponse(status);
        await response.WriteAsJsonAsync(body);
        return response;
    }
}

🧪 Unit Testing With OneOf

[Fact]
public async Task Returns_ValidationError_When_Id_Is_Zero()
{
    var service = new UserService();
    var result = await service.GetUserByIdAsync(0);

    Assert.True(result.IsT4); // ValidationError
    Assert.Equal("Id must be greater than 0.", result.AsT4.Message);
}

You can test any path: .IsT0, .IsT1, .IsT2... depending on position in OneOf.

🧠 Benefits of This Approach

No need for null checks
No exception-based flow
Clear separation of responsibilities
Total control over error behavior
Greatly improved testability

🧨 Common Mistakes

Mistake	What to do instead
Returning null	Return a specific error type
Throwing errors everywhere	Return values like `TimeoutError`
Using try/catch for flow	Use `.Match(...)` and OneOf types
Skipping tests for errors	Test each OneOf case with `.IsTn`

📐 Architecture Tips

Put all error types in an Errors/ folder
Use record for immutability and clarity
Use OneOf everywhere instead of throwing
Keep Azure Function logic lean — let services do the work

🔚 Final Thoughts

This pattern is not just syntactic sugar — it changes how you think about control flow, responsibility, and correctness.

Using OneOf + Azure Functions:

You get full control of your return paths
You write less error-prone code
You make every function explicit and testable

And it still feels like C#.

📚 Resources

OneOf GitHub: https://github.com/mcintyre321/OneOf
Example code: https://github.com/Mumma6/azure-function-oneof

Building Robust Typescript APIs with the Effect Ecosystem

Martin Persson — Tue, 02 Jul 2024 13:22:13 +0000

Introduction

In this post, we will explore how to create a complete API using the Effect ecosystem. Although the Effect documentation is excellent, there are not many examples of full applications.

If you have never heard of Effect, I suggest you take a look at the website: https://effect.website/

Effect is not just another framework but instead acts as the missing standard library for TypeScript. Because of this, I believe Effect is truly the future for TypeScript, especially when considering the challenges associated with writing production-ready applications in "plain" TypeScript. To understand more about these challenges and how Effect addresses them, watch this insightful video by Johannes Schickling, the founder of Prisma: https://www.youtube.com/watch?v=PxIBWjiv3og&ab_channel=Effect%7CTypeScriptatScale.

The purpose of this post is to demonstrate how to use the different components of the Effect ecosystem to build a modern API:

Effect: The core module for handling and creating effects.
Effect Schema: Use schemas to validate and transform data.
Effect SQL: A toolkit for integration with SQL databases. We will use PostgreSQL in our example.
Effect Platform/Node: Allows us to use the Node.js platform. We will use this to create our server, router, and handle external API calls.
Effect opentelemetry: Lets us get tracing and metrics for our app. We integrate it to our console but its really easy to setup in honeycomb for example

By utilizing these modules from Effect, we gain massive benefits. Everything is type-safe, we have robust error handling, and there's no need to reach out to NPM for specific packages. Everything is included in Effect.

Make sure you clone the GitHub repo to see the complete code.
Link to repo: https://github.com/Mumma6/effect-node-server

Overview of the Project

This project involves building a straightforward application that allows you to create user profiles and add movies to these profiles. It incorporates basic CRUD (Create, Read, Update, Delete) operations, external API calls with movie details fetched from the OMDb API. All data, including user profiles and associated movie information, is stored in a PostgreSQL database.

The system's design is inspired by Domain-Driven Design (DDD), where "User" and "Movie" are treated as distinct domains. This approach facilitates managing complex functionalities and maintaining clear boundaries between different areas of concern within the application making it an excellent starting point and foundation to build upon.

Design

Domain Layer

The domain layer is divided into user and movie domains, each containing the following sub-layers:

Models: Define the data structures and schemas.
Repositories: Handle data access and database operations.
Infrastructure: Handle external API calls (movie only).
Services: Implement business logic and orchestrate calls to repositories and external APIs (for the movie domain).

Routes Layer

The routes layer defines the HTTP routes for the API. Each domain has its own set of routes:

User Routes: Handles user-related operations (create, read, update, delete).
Movie Routes: Handles movie-related operations (create, read, update, delete) and integrates with the OMDb API.

Lib Layer

The lib layer contains configuration and setup for the database:

Database: Contains configuration and initialization logic for connecting to PostgreSQL using the Effect library.

Entry Point

index.ts: The main entry point of the application. It initializes the application by setting up routes and starting the server.

Code

Rather than guiding you through a step-by-step coding tutorial, I'll highlight crucial code snippets from our project. This approach will focus on explaining the concepts and the architecture behind the implementation, offering insights into how the Effect ecosystem seamlessly integrates into our application.

Dependencies

The project uses these dependencies

"dependencies": {
    "@effect/opentelemetry": "^0.34.29",
    "@effect/platform": "^0.58.16",
    "@effect/platform-node": "^0.53.15",
    "@effect/schema": "^0.68.14",
    "@effect/sql": "^0.4.16",
    "@effect/sql-pg": "^0.4.16",
    "@opentelemetry/sdk-metrics": "^1.25.1",
    "@opentelemetry/sdk-trace-base": "^1.25.1",
    "@opentelemetry/sdk-trace-node": "^1.25.1",
    "dotenv": "^16.4.5",
    "effect": "^3.4.5",
    "ts-node-dev": "^2.0.0",
    "typescript": "^5.5.2"
  }

Entry point

In our index.ts, we initialize the server and the router. We provide all the necessary Layers for the project, similar to "dependency injection." This setup ensures that each component has access to the resources it needs to function correctly.

We also have the ability to add our custom middleware. Notably, the NodeRuntime.runMain function acts as the starting point of our entire application. This function boots up the server, ensuring that all configurations and services are loaded and ready to handle requests.

import { HttpMiddleware, HttpRouter, HttpServer, HttpServerResponse } from "@effect/platform"
import { NodeHttpServer, NodeRuntime } from "@effect/platform-node"
import { Effect, Layer } from "effect"
import { createServer } from "http"
import { DatabaseInitialisation, SqlLive } from "./lib/database"
import { AppRouter } from "./routes/routes"

import { UserService } from "./domain/user/service/user.service"
import { MovieService } from "./domain/movies/service/movie.service"
import { TracingConsole } from "./lib/tracing"

const myLogger = HttpMiddleware.make((app) =>
  Effect.gen(function* () {
    console.log("LOGGED")
    return yield* app
  })
)
const ServerLive = NodeHttpServer.layer(createServer, { port: 5000, host: "localhost" })

const HttpLive = HttpRouter.Default.unwrap(HttpServer.serve(myLogger)).pipe(
  Layer.provide(AppRouter),
  Layer.provide(ServerLive),
  Layer.provide(UserService.Live),
  Layer.provide(MovieService.Live),
  Layer.provide(DatabaseInitialisation.Live),
  Layer.provide(SqlLive),
  Layer.provide(TracingConsole)
)

NodeRuntime.runMain(Layer.launch(HttpLive))

Lib folder

In the lib directory, we define the structure of our database by creating tables and setting up the connection details for our PostgreSQL client. Typically, you would retrieve these connection details from environment variables specified in your .env file to enhance security and flexibility. However, for simplicity in this demonstration, I have hardcoded them directly into the configuration files.

import { PgClient } from "@effect/sql-pg"
import { Config, Context, Effect, Layer, Redacted } from "effect"

const make = Effect.gen(function* () {
  const sql = yield* PgClient.PgClient

  // Suppress NOTICE messages
  yield* sql`SET client_min_messages TO WARNING;`

  // Create users table if it does not exist
  yield* sql`CREATE TABLE IF NOT EXISTS users (
    id SERIAL PRIMARY KEY,
    name VARCHAR(255) NOT NULL,
    email VARCHAR(255) NOT NULL,
    created_at TIMESTAMP NOT NULL DEFAULT NOW(),
    updated_at TIMESTAMP NOT NULL DEFAULT NOW()
  );`

  // Create movies table if it does not exist
  yield* sql`CREATE TABLE IF NOT EXISTS movies (
    id SERIAL PRIMARY KEY,
    user_id INTEGER NOT NULL REFERENCES users(id) ON DELETE CASCADE,
    title VARCHAR(255) NOT NULL,
    year VARCHAR(4),
    genre VARCHAR(255),
    plot TEXT,
    imdb_id VARCHAR(255),
    created_at TIMESTAMP NOT NULL DEFAULT NOW(),
    updated_at TIMESTAMP NOT NULL DEFAULT NOW()
  );`
})

export class DatabaseInitialisation extends Context.Tag("DatabaseInitialisation")<DatabaseInitialisation, Effect.Effect.Success<typeof make>>() {
  static readonly Live = Layer.effect(this, make)
}

export const SqlLive = PgClient.layer({
  database: Config.succeed("effect"),
  host: Config.succeed("localhost"),
  username: Config.succeed("postgres"),
  port: Config.succeed(5432),
  password: Config.succeed(Redacted.make("123")),
})

In addition to database configurations, our lib directory also sets up tracing to monitor and diagnose application performance. For details on integrating with alternative tracing services like Honeycomb, refer to the GitHub repository.

import * as NodeSdk from "@effect/opentelemetry/NodeSdk"
import { BatchSpanProcessor, ConsoleSpanExporter } from "@opentelemetry/sdk-trace-base"

export const TracingConsole = NodeSdk.layer(() => ({
  resource: { serviceName: "example" },
  spanProcessor: new BatchSpanProcessor(new ConsoleSpanExporter()),
}))

Routing

The routes.ts file plays a crucial role in our application by organizing and managing all the routing configurations. Currently, it handles two primary routes: one for movies and another for users. However, the structure is designed to be extensible, allowing for the easy addition of more routes as the application grows.

Each route is grouped within its respective module, and specific route implementations are equipped with necessary dependencies using the Layer.provide method. This setup ensures that each route has access to the services and data layers it requires to function correctly.

import { HttpRouter } from "@effect/platform"
import { Effect, Layer } from "effect"
import { UserRoutes, UsersRouter } from "./users/users.routes"
import { MoviesRouter, MovieRoutes } from "./movies/movies.routes"

export const AppRouter = HttpRouter.Default.use((router) =>
  Effect.gen(function* () {
    yield* router.mount("/users", yield* UsersRouter.router)
    yield* router.mount("/movies", yield* MoviesRouter.router)
  })
).pipe(Layer.provide(UserRoutes), Layer.provide(MovieRoutes))

The MoviesRouter handles routing for movie-related requests. It's defined as a specialized router with a unique tag, which helps in organizing and isolating movie-related routes within the larger application. Here’s how we define and organize these routes:

export class MoviesRouter extends HttpRouter.Tag("MoviesRouter")<MoviesRouter>() {}

export const MovieRoutes = Layer.mergeAll(GetMovies, CreateMovie, UpdateMovie, GetMovieById, GetMoviesForUserId, DeleteMovieById).pipe(
  Layer.provideMerge(MoviesRouter.Live)
)

In this setup, we use Layer.mergeAll to combine various movie-related route handlers like GetMovies, CreateMovie, and others into a single layer. This layer is then provided to the MoviesRouter using Layer.provideMerge, ensuring that all route handlers have access to the necessary dependencies and configurations.

The GetMovies route demonstrates how we handle a typical GET request to fetch all movies. This route uses services from the domain layer to perform its operations and includes robust error handling to manage potential issues during execution:

import { HttpRouter, HttpServerRequest, HttpServerResponse } from "@effect/platform"
import { Effect, Layer, pipe } from "effect"
import { Schema } from "@effect/schema"
import { MovieService } from "../../domain/movies/service/movie.service"

const GetMovies = MoviesRouter.use((router) =>
  pipe(
    MovieService,
    Effect.flatMap((service) =>
      router.get(
        Routes.All,
        Effect.gen(function* () {
          const movies = yield* service.getAllMovies()
          return yield* HttpServerResponse.json(movies)
        }).pipe(
          Effect.catchTags({
            ParseError: (error) =>
              HttpServerResponse.json({ message: "Invalid request data for fetching all movies", details: error.message }, { status: 400 }),
            SqlError: (error) =>
              HttpServerResponse.json({ message: "Database error while fetching all movies", details: error.message }, { status: 500 }),

            HttpBodyError: (error) =>
              HttpServerResponse.json(
                { message: "Error processing request body while fetching all movies", details: error.reason },
                { status: 400 }
              ),
          }),
          Effect.withSpan("GetAllMoviesRoute")
        )
      )
    )
  )
)

Key Features:

Service Integration: The route integrates with MovieService to fetch all movies, encapsulating business logic and data fetching in a service layer.
Error Handling: Robust error handling is implemented using Effect.catchTags. This method catches and handles different types of errors, allowing the application to respond with appropriate HTTP status codes and error messages:

ParseError: Catches errors related to request data parsing.
SqlError: Handles errors that occur during database operations.
HttpBodyError: Manages errors related to processing the HTTP request body.

Distributed Tracing: Effect.withSpan("GetAllMoviesRoute") is used for adding tracing to monitor the performance and troubleshoot issues in the route execution.

By structuring routes in this manner, we ensure that our application not only efficiently handles operations but also gracefully manages errors, providing clear feedback to the client and maintaining the integrity of the application.

Service

The MovieService is responsible for movie-related functionalities in our application. It acts as an intermediary between the MovieRepository, which handles database operations, and MovieInfrastructure, which deals with external API calls to fetch additional movie details.

Here’s how the service is structured:


const make = Effect.gen(function* () {
  const repository = yield* MovieRepository
  const infrastructure = yield* MovieInfrastructure

  const getAllMovies = () => repository.getAllMovies()

  const getMovieById = (id: string) =>
    pipe(
      repository.GetMovieById(id),
      Effect.map(
        Option.match({
          onNone: () => "Movie not found",
          onSome: (movie) => movie,
        })
      )
    )

  // rest of the service implementations

  return {
    getAllMovies,
    getMovieById,
    createMovie,
    updateMovie,
    deleteMovie,
    getMoviesByUserId,
  } as const
})
export class MovieService extends Context.Tag("MovieService")<MovieService, Effect.Effect.Success<typeof make>>() {
  static readonly Live = Layer.effect(this, make)
}

Infrastructure

The MovieInfrastructure layer in our application is specifically designed to handle all external API interactions. In this example, we focus on fetching movie information from the OMDb API, but the structure is scalable to accommodate multiple external API sources as needed. This modularity ensures that extending our application to integrate with additional services is straightforward.

import { Config, Context, Effect, Layer, pipe } from "effect"
import { HttpClientRequest, HttpClient } from "@effect/platform"
import { ApiMovieSchema } from "../models/movie.model"

const basePath = "http://www.omdbapi.com/"

const make = Effect.gen(function* () {
  const key = yield* Config.string("OMDB_KEY")
  const getMovieInformation = (name: string) =>
    pipe(
      HttpClientRequest.get(`${basePath}?t=${name}&apikey=${key}`),
      HttpClient.fetch,
      ApiMovieSchema.decodeResponse,
      Effect.retry({ times: 3 }),
      Effect.withSpan("GetMovieInformation")
    )

  return {
    getMovieInformation,
  } as const
})

export class MovieInfrastructure extends Context.Tag("MovieInfrastructure")<MovieInfrastructure, Effect.Effect.Success<typeof make>>() {
  static readonly Live = Layer.effect(this, make)
}

In the "models" directory we define the expected structure of the JSON response from the OMDb API. Each field like Title is mapped directly to the corresponding field in the API response.

Decoding Method: decodeResponse is a static method that wraps around the schema to provide a convenient way to parse and validate the JSON body of the HTTP response. It ensures that the incoming data matches our specified schema, which is critical for maintaining the integrity and consistency of the data used within our application.

export class ApiMovieSchema extends Schema.Class<ApiMovieSchema>("ApiMovieSchema")({
  Title: Schema.String,
  // Many more fields here...
}) {
  static decodeResponse = HttpClientResponse.schemaBodyJsonScoped(ApiMovieSchema)
}

Repository

The repository layer in our application is crucial for handling all database interactions. It uses SQL providers to communicate with the database, leveraging schemas to define the data structures expected from the database responses and to format the data sent in queries.

Here’s how we define and structure the MovieRepository:

import { Schema } from "@effect/schema"
import { PgClient } from "@effect/sql-pg"
import { Context, Effect, Layer } from "effect"
import { SqlResolver, SqlSchema } from "@effect/sql"
import { InsertMovieSchema, Movie, UpdateMovieSchema } from "../models/movie.model"

const make = Effect.gen(function* () {
  const sql = yield* PgClient.PgClient

  const AddMovie = yield* SqlResolver.ordered("InsertMovie", {
    Request: InsertMovieSchema,
    Result: Movie,
    execute: (requests) => sql`INSERT INTO movies ${sql.insert(requests)} RETURNING *`,
  }).pipe(Effect.withSpan("AddMovieResolver"))

  // rest of the implementations

  return {
    addMovie: AddMovie.execute,
    GetMovieById: GetMovieById.execute,
    getAllMovies: GetAllMovies,
    updateMovie: UpdateMovie.execute,
    deleteMovie: DeleteMovie.execute,
    getMovieByUserId: GetMovieByUserId,
  } as const
})
export class MovieRepository extends Context.Tag("MovieRepository")<MovieRepository, Effect.Effect.Success<typeof make>>() {
  static readonly Live = Layer.effect(this, make)
}

Conclusion

Throughout this post, we've explored how to build a complete and modern API using the Effect ecosystem. From setting up an organized and efficient routing system to integrating external API services and managing database interactions seamlessly, the Effect library has shown its strength in creating scalable and maintainable backend applications.

The future of Typescript in Production-Grade Applications

Martin Persson — Sat, 30 Mar 2024 11:06:54 +0000

Introduction

Javascript is everywhere and will not be going away anytime soon. I love Javascript, it's the first language I learned, and I use it every day, having done so for the past 7 years. But I think we can all agree that the language has many flaws, especially with error handling, callback hell, type coercion and many more. Alot of improvments have been made over time tho.

Typecript was introduced as a superset of Javascript, aimed at addressing many of Javascript's flaws through the introduction of static typing. These days, pure Javascript applications are becoming increasingly rare. The vast majority of new projects opt for Typescript for its robust typing system that improves code reliability and maintainability.

Popular frameworks like Next.js strongly advocate for Typescript, further solidifying its position as the preferred choice for modern web development. This shift towards Typescript is a positive move towards a future where code is more understandable, easier to refactor, and less prone to runtime errors.

Why is typescript not enough?

We often like to think that Typescript solves all the problems inherent to Javascript, but unfortunately, that's not entirely true.

How many times do we not write an API call like this? I've done it thousands of times, and it seems to work, right?

async function getTodo(id: number): Promise<{ todo: Todo}> {
    const response = await fetch(`/todos/${id}`)
    const todo = await response.json()

    return { todo }
}

So, what's the problem here? At first glance, it looks straightforward and effective. However, several things could go wrong and as developers we need to take care of that. For error handling we can use try-catch.

async function getTodo(
  id: number
): Promise<
  | { ok: true; todo: any }
  | { ok: false; error: "InvalidJson" | "RequestFailed" }
> {
  try {
    const response = await fetch(`/todos/${id}`)
    if (!response.ok) throw new Error("Not OK!")
    try {
      const todo = await response.json()
      return { ok: true, todo }
    } catch (jsonError) {
      return { ok: false, error: "InvalidJson" }
    }
  } catch (error) {
    return { ok: false, error: "RequestFailed" }
  }
}

This is better but we had to add more then 10 lines of code for it and the nested try-catches can be hard to read.

But for a production-grade app, we might still need more features, like retries in case something fails. That would look something like this:

function getTodo(
  id: number
  {
    retries = 3,
    retryBaseDelay = 1000,
  }: { retries?: number; retryBaseDelay?: number },
): Promise<
  | { ok: true; todo: any }
  | { ok: false; error: "InvalidJson" | "RequestFailed" }
> {
  async function execute(
    attempt: number
  ): Promise<
    | { ok: true; todo: any }
    | { ok: false; error: "InvalidJson" | "RequestFailed" }
  > {
    try {
      const response = await fetch(`/todos/${id}`)
      if (!response.ok) throw new Error("Not OK!")
      try {
        const todo = await response.json()
        return { ok: true, todo }
      } catch (jsonError) {
        if (attempt < retries) {
          throw jsonError // jump to retry
        }
        return { ok: false, error: "InvalidJson" }
      }
    } catch (error) {
      if (attempt < retries) {
        const delayMs = retryBaseDelay * 2 ** attempt
        return new Promise((resolve) =>
          setTimeout(
            () => resolve(execute(attempt + 1)),
            delayMs,
          ),
        )
      }
      return { ok: false, error: "RequestFailed" }
    }
  }

  return execute(0)
}

The code is getting out of hand but we are still not done. Often we must introduce a mechanism for interruption to manage and clean up resources effectively. We can use the AbortSignal API for that

function getTodo(
  id: number
  {
    retries = 3,
    retryBaseDelay = 1000,
    signal,
  }: {
    retries?: number
    retryBaseDelay?: number
    signal?: AbortSignal
  },
): Promise<
  | { ok: true; todo: any }
  | {
      ok: false
      error: "InvalidJson" | "RequestFailed" | "Timeout"
    }
> {
  async function execute(attempt: number): Promise<
    | { ok: true; todo: any }
    | {
        ok: false
        error: "InvalidJson" | "RequestFailed" | "Timeout"
      }
  > {
    try {
      const controller = new AbortController()
      setTimeout(() => controller.abort(), 1000)
      signal?.addEventListener("abort", () =>
        controller.abort(),
      )
      const response = await fetch(`/todos/${id}`, {
        signal: controller.signal,
      })
      if (!response.ok) throw new Error("Not OK!")
      try {
        const todo = await response.json()
        return { ok: true, todo }
      } catch (jsonError) {
        if (attempt < retries) {
          throw jsonError // jump to retry
        }
        return { ok: false, error: "InvalidJson" }
      }
    } catch (error) {
      if ((error as Error).name === "AbortError") {
        return { ok: false, error: "Timeout" }
      } else if (attempt < retries) {
        const delayMs = retryBaseDelay * 2 ** attempt
        return new Promise((resolve) =>
          setTimeout(
            () => resolve(execute(attempt + 1)),
            delayMs,
          ),
        )
      }
      return { ok: false, error: "RequestFailed" }
    }
  }

  return execute(0)
}

Now our API is robustly designed, having addressed nearly all the typical issues. However, we find ourselves dealing with over 60 lines of code and the solution lacks modularity. This means we'd need to replicate this for each of our API routes, which is hardly efficient or scalable.

Additionally, another aspect worth considering is the incorporation of a tracer.

const tracer = Otel.trace.getTracer("todos")

function getTodo(
  id: number
  {
    retries = 3,
    retryBaseDelay = 1000,
    signal,
  }: {
    retries?: number
    retryBaseDelay?: number
    signal?: AbortSignal
  },
): Promise<
  | { ok: true; todo: any }
  | {
      ok: false
      error: "InvalidJson" | "RequestFailed" | "Timeout"
    }
> {
  return tracer.startActiveSpan(
    "getTodo",
    { attributes: { id } },
    async (span) => {
      try {
        const result = await execute(0)
        if (result.ok) {
          span.setStatus({ code: Otel.SpanStatusCode.OK })
        } else {
          span.setStatus({
            code: Otel.SpanStatusCode.ERROR,
            message: result.error,
          })
        }
        return result
      } finally {
        span.end()
      }
    },
  )

  async function execute(attempt: number): Promise<
    | { ok: true; todo: any }
    | {
        ok: false
        error: "InvalidJson" | "RequestFailed" | "Timeout"
      }
  > {
    try {
      const controller = new AbortController()
      setTimeout(() => controller.abort(), 1000)
      signal?.addEventListener("abort", () =>
        controller.abort(),
      )
      const response = await fetch(`/todos/${id}`, {
        signal: controller.signal,
      })
      if (!response.ok) throw new Error("Not OK!")
      try {
        const todo = await response.json()
        return { ok: true, todo }
      } catch (jsonError) {
        if (attempt < retries) {
          throw jsonError // jump to retry
        }
        return { ok: false, error: "InvalidJson" }
      }
    } catch (error) {
      if ((error as Error).name === "AbortError") {
        return { ok: false, error: "Timeout" }
      } else if (attempt < retries) {
        const delayMs = retryBaseDelay * 2 ** attempt
        return new Promise((resolve) =>
          setTimeout(
            () => resolve(execute(attempt + 1)),
            delayMs,
          ),
        )
      }
      return { ok: false, error: "RequestFailed" }
    }
  }
}

Now all of a sudden we have gone from from 6 lines of code to about 80 lines...

To be honest, I rarely go to these lengths when creating an API endpoint and that's largely due to how cumbersome it is.

Producing production-grade TypeScript is hard.

Challenges include:

No type-safety beyond the happy path
Error handling
Retrying on error
Interruptions
Observability
Schema validation

The last point, schema validation, isn't even covered in our code example, but we'd often turn to tools like Zod for this purpose.

What TypeScript lacks, that other languages offer, is a comprehensive standard library. Instead, we have NPM, which is great because we can find almost everything, but that comes with its own set of problems as well.

So, what should we do then?

Effect

Effect is designed to address the issues inherent in Typescript and to solve the challenges developers face when using it.

It does so using:

Powerful building blocks: Each component of the Effect ecosystem is crafted to be composable.
No more one-off deps:: With Effect, we have all we need, eliminating the necessity to depend on numerous npm packages. It provides tools for data validation and HTTP frameworks, among others.
No more try-catch:: Effect takes a comprehensive approach to error handling, ensuring all errors are type-safe and not just the happy path.

The 2022 State of JS survey highlighted a strong desire among developers for a standard library.

Effect can be utilized wherever Typescript is applicable, positioning itself as the missing standard library for Typescript. However, there's a catch:

Learning curve: Effect heavily relies on functional programming concepts, which can be intimidating for many developers.
Different programming style: The programming style of Effect is quite distinct from traditional Typescript, potentially making it challenging to adapt to.
Extensivve API: Aiming to be a standard library for Typescript, Effect boasts an API for nearly every situation, which can be overwhelming. Yet, mastering just a few of the most common ones can go a long way.

So, how would our production-grade code example look like in Effect?

const getTodo = (id: number): Effect.Effect<
  unknown,
  HttpClientError | TimeoutException
> =>
  Http.request.get(`/todos/${id}`).pipe(
    Http.client.fetchOk(),
    Http.response.json,
    Effect.timeout("1 seconds"),
    Effect.retry(
      Schedule.exponential(1000).pipe(
        Schedule.compose(Schedule.recurs(3)),
      ),
    ),
    Effect.withSpan("getTodo", { attributes: { id } }),
  )

This code is significantly shorter and more modular. Admittedly, it might be challenging to grasp what's happening if you're not familiar with the syntax, but it illustrates the power and potential of adopting Effect for Typescript development.

Conclusion

In this post we did not go into how to use or what effect really is. We talked about the problem it solves.

What does the future of Typescript look like, in your opinion?

Resources

This post is heavily inspired by the insightful talk from Johannes Schickling the founder of Primsa. You can watch his talk here

The effect website. Be sure to read the docs

Join the Discord: https://discord.gg/effect-ts

Learning resources:

Building & Testing React Hooks with NPM

Martin Persson — Tue, 12 Sep 2023 07:46:48 +0000

Introduction
Setting Up the Project
Rollup Configuration
Create Our Hook
Testing
Conclusion

Introduction

This tutorial aims to guide you through setting up an NPM package specifically designed for React projects. You'll learn how to create and test a custom hook as well.

Links:

Previous NPM tutorial

Repo for this tutorial

What you will learn:

NPM Package Setup: Steps to create an NPM package for React projects or custom component libraries.
Custom Form Hook Creation: How to build a simple but extensible custom hook.
Testing in React: Utilize Jest and React Testing Library to test React components and hooks.

This tutorial builds upon a previous guide where we created a basic NPM package. If you haven't checked that out yet, you might want to start there.

Setting up the project

Firstly, ensure you have Node and npm installed. To kickstart your project, clone the starter code from the GitHub repository:

git clone https://github.com/Mumma6/npm-package-tutorial

Navigate into the project directory:

cd npm-package-tutorial/

After you've cloned the starter code, you'll want to set up your own GitHub repository. Here is how to do that:

Create a New Repository on GitHub:
- Go to your GitHub account and create a new repository.
- Do not initialize the new repository with a README, .gitignore, or license. This empty repository will be linked to your local project.
Change the Remote URL:
- Open your terminal and navigate to your local project directory.
- Type git remote -v to list the current configured remote repository for your fork.
- Run git remote set-url origin YOUR-NEW-REPOSITORY-URL.git to change the repository URL to your newly created repository.
Verify the Remote URL:
- Again, run git remote -v to verify that the remote URL has been updated.
Push to New Repository:
- Run git push -u origin main (or git push -u origin master depending on your default branch name) to push your local code to your own GitHub repository.

After these steps, your local repository will be linked to your new GitHub repository, and you can start making commits and pushing changes.

Note: If you plan to publish this package, make sure to change the name in your package.json to avoid conflicts with existing packages.

Install Dependencies

Install React and React DOM. We'll use version 17 to maintain compatibility with React Testing Library:

npm i react@17 react-dom@17 @types/react@17 @types/react-dom@17

Rollup Configuration

Update your Rollup configuration to include React and React DOM as external dependencies:

const typescript = require("rollup-plugin-typescript2")
const pkg = require("./package.json")

module.exports = {
  input: 'src/index.ts',
  output: [
    {
      file: pkg.main,
      format: 'cjs',
      exports: 'named',
      sourcemap: true,
      strict: false
    }
  ],
  plugins: [
    typescript()
  ],
  external: ['react', 'react-dom']
}

Create our hook

Let's create our custom form hook. For simplicity, the hook will be minimal:

In you index.ts file create this.

import { useState } from "react"

export function useForm(formData: any) {
  const [values, setValues] = useState(formData)

  return {
    values,
    setValues,
  }
}

Testing

For testing we are going to use Jest and React Testing Library.

Jest

Jest is a popular testing framework in the JavaScript ecosystem that comes with a lot of features out-of-the-box, like mocking, assertions, and snapshot testing. It's widely used in the React community, partly because create-react-app includes it by default.

React Testing Library

React Testing Library is built on top of Jest and provides a set of utilities to test React components. It encourages better testing practices and makes it easier to find elements and interact with them in a way that resembles how the end-user would.

Testing Hooks with @testing-library/react-hooks

While React Testing Library primarily focuses on React components, @testing-library/react-hooks is an extension that allows us to test React hooks in isolation from the components that use them. This is particularly useful for your tutorial since you're building a hook.

The renderHook and act Functions

In our test example, we use two primary functions: renderHook and act.

renderHook: This function "renders" your hook in a testing environment, much like render does for components. It returns an object that contains the hook's return value, among other things.
act: When you need to interact with your hook (for example, to change a state variable), wrap those interactions in an act function to ensure that all updates related to these actions have been processed and applied to the DOM before you make any assertions.

To test our hook, install the required testing libraries:

npm i @testing-library/react-hooks @testing-library/jest-dom jest-environment-jsdom

Create a file called setupTests.ts and add the following line:

import "@testing-library/jest-dom"

Update your Jest configuration to include the new environment and setup file:

module.exports = {
  preset: 'ts-jest',
  testMatch: ["**/__tests__/**/*.test.ts"],
  testEnvironment: 'jest-environment-jsdom',
  setupFilesAfterEnv: ['./setupTests.ts'],
};

Now, create a folder called __tests__ and add a test file index.test.ts with the following content:

import { renderHook, act } from "@testing-library/react-hooks"
import { useForm } from "../src/index"

describe("useFormHook", () => {
  test("should update form values", () => {
    const { result } = renderHook(() => useForm({ name: "", email: "" }))

    act(() => {
      result.current.setValues({ name: "John", email: "john@example.com" })
    })

    expect(result.current.values).toEqual({ name: "John", email: "john@example.com" })
  })
})

You can now run the test with npm test

Conclusion

Congratulations on making it to the end of this tutorial! You've successfully built an NPM package tailored for React projects, complete with a custom hook. Not only did you develop the hook, but you also ensured its robustness by writing tests using Jest and React Testing Library. This not only amplifies the quality of your package but also provides peace of mind when integrating it into larger, more complex systems.

What's more, your package is now ready for publishing on NPM, opening up the possibility for other developers to make use of your work in their projects. If you're unsure about how to publish your package, you can refer back to my previous guide for a detailed walk-through on publishing it to NPM.

As a next step, you might consider adding more features to your custom hook, or perhaps even expand it into a full-fledged React component library. The possibilities are endless, and the foundations laid in this tutorial will serve you well as you continue on your journey in React development.

React Calendar: A Guide to Building Dynamic Calendars with Events and Todos

Martin Persson — Mon, 28 Aug 2023 13:48:51 +0000

Introduction
Key Features
Setting up the Project
Create the Calendar
Modals
- AddEventModal.tsx
- EventInfoModal
- AddDatePickerEventModal
- AddTodoModal
EventInfo
Conclusion

Introduction

Links:

Live demo

Github repo

This tutorial aims to guide you through the process of building a calendar application using React and Material UI. With features like dynamic event creation, todo integration, and event color-coding, the application serves as a practical example of how to implement complex functionalities in a React app. We will use a variety of libraries and dependencies to achieve this, including Material UI components, React Big Calendar, and the date-fns library for localized date formats.

You can easily add on to this by integrate a database or add more info to your events.

Key Features

Event Management

Enables users to add, view, and manage events on the calendar.
Allows for both slot-based and date-based event creation.

Todo List Integration

Demonstrates how to integrate a todo list with a calendar application.
Features options for creating todos and associating them with events.

Event Color-Coding

Shows how to dynamically color-code events based on associated todos or other criteria.

React Big Calendar

Uses React Big Calendar library for main calendar functionalities.

Locale Support

Includes localized date formatting through the date-fns library.

Setting up the Project

In this section, we'll walk you through the initial setup for building the calendar application. This involves initializing a new Next.js project and installing the necessary dependencies.

To start, let's create a new React project. Open your terminal and run the following command:

npx create-react-app react-calendar --template typescript

This will create a new directory called react-calendar with all the files you need. To navigate into your new app and start it, run:

cd react-calendar
npm run start

Your React application should now be accessible at http://localhost:3000/

Installing Dependencies
To build our calendar application, several packages are required. These include:

Material-UI components (@mui/material and @mui/icons-material) for the UI.
Emotion (@emotion/react and @emotion/styled) for additional styling capabilities.
Date-fns (date-fns) for date manipulations.
React Big Calendar (react-big-calendar) for the main calendar functionalities.
React Colorful (react-colorful) for a color picker.

Install these dependencies by running the following command in your terminal:

MUI and Emotion

npm install @mui/material@5.14.6 @mui/icons-material@5.14.6 @emotion/react@11.11.1 @emotion/styled@11.11.0

Date manipulation, calendar functionality, and a color picker.

npm install date-fns@2.30.0 react-big-calendar@1.8.2 react-colorful@5.6.1 @mui/x-date-pickers@5.0.12 @types/react-big-calendar

After installing these dependencies, your project will have all the required packages to proceed with development. In the following sections, we'll dive into creating the various features for our calendar application.

Create the Calendar

we'll go step by step through creating a calendar in React using Typescript. The calendar will have features for creating events, and todos.

First, you'll need to create a file called EventCalendar.tsx in your src/components directory. This file will contain all the logic for your calendar application.

Note: As we add the code in chunks, you might see some errors initially. Don't worry, these will go away as we add more code.

Your overall folder structure should look like this:

src/components

 AddDatePickerEventModal.tsx
 AddEventModal.tsx
 AddTodoModal.tsx
 EventCalendar.tsx
 EventInfo.tsx
 EventInfoModal.tsx

Importing Dependencies

In your EventCalendar.tsx file, add the following code to import all necessary dependencies:

import { useState, MouseEvent } from "react"
import { Box, Button, ButtonGroup, Card, CardContent, CardHeader, Container, Divider } from "@mui/material"

import { Calendar, type Event, dateFnsLocalizer } from "react-big-calendar"

import format from "date-fns/format"
import parse from "date-fns/parse"
import startOfWeek from "date-fns/startOfWeek"
import getDay from "date-fns/getDay"
import enUS from "date-fns/locale/en-US"

import "react-big-calendar/lib/css/react-big-calendar.css"

import EventInfo from "./EventInfo"
import AddEventModal from "./AddEventModal"
import EventInfoModal from "./EventInfoModal"
import { AddTodoModal } from "./AddTodoModal"
import AddDatePickerEventModal from "./AddDatePickerEventModal"

Here, we're importing everything we'll need for our calendar, including React hooks, material-UI components, and functionalities from react-big-calendar.

Initialize the Localizer

Next, we'll initialize the date-fns localizer to handle date formatting.

const locales = {
  "en-US": enUS,
}

const localizer = dateFnsLocalizer({
  format,
  parse,
  startOfWeek,
  getDay,
  locales,
})

This sets up date-fns to work with react-big-calendar.

Defining Data Models

We define our data models and utility functions like generateId to uniquely identify each todo and event.

export interface ITodo {
  _id: string
  title: string
  color?: string
}

export interface IEventInfo extends Event {
  _id: string
  description: string
  todoId?: string
}

export interface EventFormData {
  description: string
  todoId?: string
}

export interface DatePickerEventFormData {
  description: string
  todoId?: string
  allDay: boolean
  start?: Date
  end?: Date
}

export const generateId = () => (Math.floor(Math.random() * 10000) + 1).toString()

Here, we define different interfaces for Events and Todos, along with some utility types.

Initialize Form Data

// Make this better
We can add events in 2 different ways, the first is that we click and drag in the calender and the other is what we use a datePicker. Lets create the initial formData for both options

const initialEventFormState: EventFormData = {
  description: "",
  todoId: undefined,
}

const initialDatePickerEventFormData: DatePickerEventFormData = {
  description: "",
  todoId: undefined,
  allDay: false,
  start: undefined,
  end: undefined,
}

Managing States

Next, let's declare all the state variables we'll be using:

const [openSlot, setOpenSlot] = useState(false)
  const [openDatepickerModal, setOpenDatepickerModal] = useState(false)
  const [openTodoModal, setOpenTodoModal] = useState(false)
  const [currentEvent, setCurrentEvent] = useState<Event | IEventInfo | null>(null)

  const [eventInfoModal, setEventInfoModal] = useState(false)

  const [events, setEvents] = useState<IEventInfo[]>([])
  const [todos, setTodos] = useState<ITodo[]>([])

  const [eventFormData, setEventFormData] = useState<EventFormData>(initialEventFormState)

  const [datePickerEventFormData, setDatePickerEventFormData] =
    useState<DatePickerEventFormData>(initialDatePickerEventFormData)

These states help us control modals, hold the current events, and keep track of todos.

Next up we can add our handlerFunctions,

Handling Events and Modals

We define several handler functions for handling slots, closing modals, and more.

 const handleSelectSlot = (event: Event) => {
    setOpenSlot(true)
    setCurrentEvent(event)
  }

  const handleSelectEvent = (event: IEventInfo) => {
    setCurrentEvent(event)
    setEventInfoModal(true)
  }

  const handleClose = () => {
    setEventFormData(initialEventFormState)
    setOpenSlot(false)
  }

  const handleDatePickerClose = () => {
    setDatePickerEventFormData(initialDatePickerEventFormData)
    setOpenDatepickerModal(false)
  }

These functions are called when certain actions are taken in our application, like selecting an event or a time slot in the calendar.

Creating Events

Here is the core logic for adding new events to our calendar:

const onAddEvent = (e: MouseEvent<HTMLButtonElement>) => {
    e.preventDefault()

    const data: IEventInfo = {
      ...eventFormData,
      _id: generateId(),
      start: currentEvent?.start,
      end: currentEvent?.end,
    }

    const newEvents = [...events, data]

    setEvents(newEvents)
    handleClose()
  }

  const onAddEventFromDatePicker = (e: MouseEvent<HTMLButtonElement>) => {
    e.preventDefault()

    const addHours = (date: Date | undefined, hours: number) => {
      return date ? date.setHours(date.getHours() + hours) : undefined
    }

    const setMinToZero = (date: any) => {
      date.setSeconds(0)

      return date
    }

    const data: IEventInfo = {
      ...datePickerEventFormData,
      _id: generateId(),
      start: setMinToZero(datePickerEventFormData.start),
      end: datePickerEventFormData.allDay
        ? addHours(datePickerEventFormData.start, 12)
        : setMinToZero(datePickerEventFormData.end),
    }

    const newEvents = [...events, data]

    setEvents(newEvents)
    setDatePickerEventFormData(initialDatePickerEventFormData)
  }

  const onDeleteEvent = () => {
    setEvents(() => [...events].filter((e) => e._id !== (currentEvent as IEventInfo)._id!))
    setEventInfoModal(false)
  }

These functions add and delete events to our state, whether they're created by dragging on the calendar or via the date picker.

Putting It All Together

Finally, we render our UI components and tie everything together:

return (
    <Box
      mt={2}
      mb={2}
      component="main"
      sx={{
        flexGrow: 1,
        py: 8,
      }}
    >
      <Container maxWidth={false}>
        <Card>
          <CardHeader title="Calendar" subheader="Create Events and Todos and manage them easily" />
          <Divider />
          <CardContent>
            <Box sx={{ display: "flex", justifyContent: "space-between" }}>
              <ButtonGroup size="large" variant="contained" aria-label="outlined primary button group">
                <Button onClick={() => setOpenDatepickerModal(true)} size="small" variant="contained">
                  Add event
                </Button>
                <Button onClick={() => setOpenTodoModal(true)} size="small" variant="contained">
                  Create todo
                </Button>
              </ButtonGroup>
            </Box>
            <Divider style={{ margin: 10 }} />
            <AddEventModal
              open={openSlot}
              handleClose={handleClose}
              eventFormData={eventFormData}
              setEventFormData={setEventFormData}
              onAddEvent={onAddEvent}
              todos={todos}
            />
            <AddDatePickerEventModal
              open={openDatepickerModal}
              handleClose={handleDatePickerClose}
              datePickerEventFormData={datePickerEventFormData}
              setDatePickerEventFormData={setDatePickerEventFormData}
              onAddEvent={onAddEventFromDatePicker}
              todos={todos}
            />
            <EventInfoModal
              open={eventInfoModal}
              handleClose={() => setEventInfoModal(false)}
              onDeleteEvent={onDeleteEvent}
              currentEvent={currentEvent as IEventInfo}
            />
            <AddTodoModal
              open={openTodoModal}
              handleClose={() => setOpenTodoModal(false)}
              todos={todos}
              setTodos={setTodos}
            />
            <Calendar
              localizer={localizer}
              events={events}
              onSelectEvent={handleSelectEvent}
              onSelectSlot={handleSelectSlot}
              selectable
              startAccessor="start"
              components={{ event: EventInfo }}
              endAccessor="end"
              defaultView="week"
              eventPropGetter={(event) => {
                const hasTodo = todos.find((todo) => todo._id === event.todoId)
                return {
                  style: {
                    backgroundColor: hasTodo ? hasTodo.color : "#b64fc8",
                    borderColor: hasTodo ? hasTodo.color : "#b64fc8",
                  },
                }
              }}
              style={{
                height: 900,
              }}
            />
          </CardContent>
        </Card>
      </Container>
    </Box>
  )

Modals

Creating Different Modals for Events and Todos
Let's dive into the various modals that allow us to add new events and todos within our calendar application.

EventInfoModal: This modal serves as an information panel that displays details about selected events. It provides users with a quick glance at the event description and offers an option to delete the event if necessary.
AddDatePickerEventModal: This modal is specifically designed for adding new events to the calendar. It comes equipped with date and time pickers for specifying the event's start and end times and also allows the user to mark the event as an all-day event. A related todo can also be associated with the event for better task management.
AddEventModal: This modal allows users to create new events with essential information such as event description, time, and date. It acts as a simplified version of AddDatePickerEventModal, designed for quick event creation.
AddTodoModal: Beyond events, the application also supports the addition of 'todos'. This modal allows users to create new todos, complete with a title and a color code for easy identification. Users can also delete existing todos from within this modal.

AddEventModal.tsx

We start with AddEventModal.tsx. This modal gets triggered when you click and drag on a specific time range in the calendar UI. Place this file in the same folder (src/components) where you have EventCalendar.tsx.

Importing Dependencies

First, we import various modules that we will be using, such as the Material UI components and the custom types for our application.

import { ChangeEvent, Dispatch, MouseEvent, SetStateAction } from "react"
import {
  TextField,
  Dialog,
  DialogActions,
  DialogContent,
  DialogContentText,
  DialogTitle,
  Button,
  Autocomplete,
  Box,
} from "@mui/material"
import { EventFormData, ITodo } from "./EventCalendar"

Component Props

We define the properties that this modal component expects using TypeScript's interface system. These props include booleans to control the modal's open state, functions to handle changes, and an array of Todo items.

interface IProps {
  open: boolean
  handleClose: Dispatch<SetStateAction<void>>
  eventFormData: EventFormData
  setEventFormData: Dispatch<SetStateAction<EventFormData>>
  onAddEvent: (e: MouseEvent<HTMLButtonElement>) => void
  todos: ITodo[]
}

Component Functionality

Within the functional component, we define the actual behavior of the modal:

onClose: A function that calls the handleClose prop to close the modal.
onChange: A function that handles changes in the text fields, updating the eventFormData state.
handleTodoChange: A function that handles the selection of Todo items from the dropdown and updates the eventFormData.

The main return block of the component uses Material-UI components to render the modal's UI. It includes text fields for the event description and an autocomplete dropdown for Todo selection.

const AddEventModal = ({ open, handleClose, eventFormData, setEventFormData, onAddEvent, todos }: IProps) => {
  const { description } = eventFormData

  const onClose = () => handleClose()

  const onChange = (event: ChangeEvent<HTMLInputElement>) => {
    setEventFormData((prevState) => ({
      ...prevState,
      [event.target.name]: event.target.value,
    }))
  }

  const handleTodoChange = (e: React.SyntheticEvent, value: ITodo | null) => {
    setEventFormData((prevState) => ({
      ...prevState,
      todoId: value?._id,
    }))
  }

  return (
    <Dialog open={open} onClose={onClose}>
      <DialogTitle>Add event</DialogTitle>
      <DialogContent>
        <DialogContentText>To add a event, please fill in the information below.</DialogContentText>
        <Box component="form">
          <TextField
            name="description"
            value={description}
            margin="dense"
            id="description"
            label="Description"
            type="text"
            fullWidth
            variant="outlined"
            onChange={onChange}
          />
          <Autocomplete
            onChange={handleTodoChange}
            disablePortal
            id="combo-box-demo"
            options={todos}
            sx={{ marginTop: 4 }}
            getOptionLabel={(option) => option.title}
            renderInput={(params) => <TextField {...params} label="Todo" />}
          />
        </Box>
      </DialogContent>
      <DialogActions>
        <Button color="error" onClick={onClose}>
          Cancel
        </Button>
        <Button disabled={description === ""} color="success" onClick={onAddEvent}>
          Add
        </Button>
      </DialogActions>
    </Dialog>
  )
}

export default AddEventModal

EventInfoModal

The EventInfoModal.tsx component serves as an informational pop-up that appears when a user clicks on an existing event within the calendar. This modal allows users to view the details of the selected event and provides an option to delete it. Like the AddEventModal.tsx, this file should also be placed in the src/components folder.

At the beginning of the file, you'll find a series of imports for React, Material UI components, and custom types.

The IProps interface defines the properties that this component expects. It includes a boolean flag to indicate whether the modal is open or not, a handleClose function to close the modal, a onDeleteEvent function to delete the current event, and the data for the current event.

import { SetStateAction, MouseEvent, Dispatch } from "react"
import { Dialog, DialogActions, DialogContent, DialogContentText, DialogTitle, Button, Box, Typography } from "@mui/material"
import { IEventInfo } from "./EventCalendar"

interface IProps {
  open: boolean
  handleClose: Dispatch<SetStateAction<void>>
  onDeleteEvent: (e: MouseEvent<HTMLButtonElement>) => void
  currentEvent: IEventInfo | null
}

const EventInfoModal = ({ open, handleClose, onDeleteEvent, currentEvent }: IProps) => {
  const onClose = () => {
    handleClose()
  }

  return (
    <Dialog open={open} onClose={onClose}>
      <DialogTitle>Event Info</DialogTitle>
      <DialogContent>
        <DialogContentText>
          <Typography sx={{ fontSize: 14, marginTop: 3 }} color="text.secondary" gutterBottom>
            {currentEvent?.description}
          </Typography>
        </DialogContentText>
        <Box component="form"></Box>
      </DialogContent>
      <DialogActions>
        <Button color="error" onClick={onClose}>
          Cancel
        </Button>
        <Button color="info" onClick={onDeleteEvent}>
          Delete Event
        </Button>
      </DialogActions>
    </Dialog>
  )
}

export default EventInfoModal

And that concludes our EventInfoModal.tsx. This component serves as a crucial piece in providing a user-friendly calendar application by allowing users to quickly view and manage their events.

AddDatePickerEventModal

The AddDatePickerEventModal.tsx component is a specialized modal for adding events with date and time selections. This modal comes into play when you want to add an event that requires precise start and end times. It also features a checkbox to indicate if the event spans the entire day. Like the other modal components, place this file in the src/components directory.

Importing Dependencies

The top part of the file imports required modules from React, Material UI, and your custom types.

import React, { Dispatch, MouseEvent, SetStateAction, ChangeEvent } from "react"
import {
  TextField,
  Dialog,
  DialogActions,
  DialogContent,
  DialogContentText,
  DialogTitle,
  Button,
  Autocomplete,
  Box,
  Checkbox,
  Typography,
} from "@mui/material"
import { LocalizationProvider, DateTimePicker } from "@mui/x-date-pickers"
import { AdapterDateFns } from "@mui/x-date-pickers/AdapterDateFns"
import { DatePickerEventFormData, ITodo } from "./EventCalendar"

Component Props

We define the expected properties in the IProps interface. These props include:

open: Boolean flag indicating if the modal is open.
handleClose: Function to close the modal.
datePickerEventFormData: Object containing form data for the event.
setDatePickerEventFormData: Function to update the form data.
onAddEvent: Function to add a new event.
todos: Array of Todo items.

interface IProps {
  open: boolean
  handleClose: Dispatch<SetStateAction<void>>
  datePickerEventFormData: DatePickerEventFormData
  setDatePickerEventFormData: Dispatch<SetStateAction<DatePickerEventFormData>>
  onAddEvent: (e: MouseEvent<HTMLButtonElement>) => void
  todos: ITodo[]
}

Component Functionality

Within AddDatePickerEventModal, several key functions are defined:

onClose: Closes the modal by calling handleClose.
onChange: Handles text input changes and updates the form data.
handleCheckboxChange: Updates the allDay flag in the form data.
handleTodoChange: Handles the Todo selection.
isDisabled: Function to check if the "Add" button should be disabled based on the form data.

The main rendering block uses Material-UI components to render the UI, including date and time pickers.

const AddDatePickerEventModal = ({
  open,
  handleClose,
  datePickerEventFormData,
  setDatePickerEventFormData,
  onAddEvent,
  todos,
}: IProps) => {
  const { description, start, end, allDay } = datePickerEventFormData

  const onClose = () => {
    handleClose()
  }

  const onChange = (event: ChangeEvent<HTMLInputElement>) => {
    setDatePickerEventFormData((prevState) => ({
      ...prevState,
      [event.target.name]: event.target.value,
    }))
  }

  const handleCheckboxChange = (event: ChangeEvent<HTMLInputElement>) => {
    setDatePickerEventFormData((prevState) => ({
      ...prevState,
      allDay: event.target.checked,
    }))
  }

  const handleTodoChange = (e: React.SyntheticEvent, value: ITodo | null) => {
    setDatePickerEventFormData((prevState) => ({
      ...prevState,
      todoId: value?._id,
    }))
  }

  const isDisabled = () => {
    const checkend = () => {
      if (!allDay && end === null) {
        return true
      }
    }
    if (description === "" || start === null || checkend()) {
      return true
    }
    return false
  }

  return (
    <Dialog open={open} onClose={onClose}>
      <DialogTitle>Add event</DialogTitle>
      <DialogContent>
        <DialogContentText>To add a event, please fill in the information below.</DialogContentText>
        <Box component="form">
          <TextField
            name="description"
            value={description}
            margin="dense"
            id="description"
            label="Description"
            type="text"
            fullWidth
            variant="outlined"
            onChange={onChange}
          />
          <LocalizationProvider dateAdapter={AdapterDateFns}>
            <Box mb={2} mt={5}>
              <DateTimePicker
                label="Start date"
                value={start}
                ampm={true}
                minutesStep={30}
                onChange={(newValue) =>
                  setDatePickerEventFormData((prevState) => ({
                    ...prevState,
                    start: new Date(newValue!),
                  }))
                }
                renderInput={(params) => <TextField {...params} />}
              />
            </Box>

            <Box>
              <Typography variant="caption" color="text" component={"span"}>
                All day?
              </Typography>
              <Checkbox onChange={handleCheckboxChange} value={allDay} />
            </Box>

            <DateTimePicker
              label="End date"
              disabled={allDay}
              minDate={start}
              minutesStep={30}
              ampm={true}
              value={allDay ? null : end}
              onChange={(newValue) =>
                setDatePickerEventFormData((prevState) => ({
                  ...prevState,
                  end: new Date(newValue!),
                }))
              }
              renderInput={(params) => <TextField {...params} />}
            />
          </LocalizationProvider>
          <Autocomplete
            onChange={handleTodoChange}
            disablePortal
            id="combo-box-demo"
            options={todos}
            sx={{ marginTop: 4 }}
            getOptionLabel={(option) => option.title}
            renderInput={(params) => <TextField {...params} label="Todo" />}
          />
        </Box>
      </DialogContent>
      <DialogActions>
        <Button color="error" onClick={onClose}>
          Cancel
        </Button>
        <Button disabled={isDisabled()} color="success" onClick={onAddEvent}>
          Add
        </Button>
      </DialogActions>
    </Dialog>
  )
}

export default AddDatePickerEventModal

AddDatePickerEventModal.tsx is an essential component that brings enhanced functionality to the calendar application. It provides a way to input more detailed events with start and end times or mark them as all-day events.

AddTodoModal

AddTodoModal.tsx is another crucial component in your calendar application, serving as the interface for users to add new "Todo" items. It integrates various UI components and logic to facilitate adding new Todos, deleting existing ones, and customizing the color of each Todo.

Importing Dependencies

The component imports a mixture of built-in React hooks, Material UI components, and your custom types to build its functionality:

import { useState, Dispatch, SetStateAction } from "react"
import {
  Dialog,
  DialogActions,
  DialogContent,
  DialogContentText,
  DialogTitle,
  Box,
  Button,
  Divider,
  IconButton,
  List,
  ListItem,
  ListItemText,
  TextField,
} from "@mui/material"
import DeleteIcon from "@mui/icons-material/Delete"

import { HexColorPicker } from "react-colorful"
import { ITodo, generateId } from "./EventCalendar"

Component Props
The props for this modal include:

open: Boolean flag to control the visibility of the modal.
handleClose: Function to close the modal.
todos: Array of existing Todos.
setTodos: Function to set the new list of Todos.

interface IProps {
  open: boolean
  handleClose: Dispatch<SetStateAction<void>>
  todos: ITodo[]
  setTodos: Dispatch<SetStateAction<ITodo[]>>
}

Rendering and Layout

The component leverages Material UI components for layout and styling. Notable features include:

A color picker (HexColorPicker) for choosing the color of a Todo.
A TextField for entering the title of the Todo.
A List of existing Todos with delete buttons.
Cancel and Add buttons in the Dialog actions.

Event Handling

Event handlers are attached to the form field for updating the title (setTitle) and the color picker (setColor), along with click handlers for adding (onAddTodo) and deleting (onDeleteTodo) Todos. The Add button is disabled if either the title or color is empty.

export const AddTodoModal = ({ open, handleClose, todos, setTodos }: IProps) => {
  const [color, setColor] = useState("#b32aa9")
  const [title, setTitle] = useState("")

  const onAddTodo = () => {
    setTitle("")
    setTodos([
      ...todos,
      {
        _id: generateId(),
        color,
        title,
      },
    ])
  }

  const onDeletetodo = (_id: string) => setTodos(todos.filter((todo) => todo._id !== _id))

  const onClose = () => handleClose()

  return (
    <Dialog open={open} onClose={onClose}>
      <DialogTitle>Add todo</DialogTitle>
      <DialogContent>
        <DialogContentText>Create todos to add to your Calendar.</DialogContentText>
        <Box>
          <TextField
            name="title"
            autoFocus
            margin="dense"
            id="title"
            label="Title"
            type="text"
            fullWidth
            sx={{ mb: 6 }}
            required
            variant="outlined"
            onChange={(e) => {
              setTitle(e.target.value)
            }}
            value={title}
          />
          <Box sx={{ display: "flex", justifyContent: "space-around" }}>
            <HexColorPicker color={color} onChange={setColor} />
            <Box sx={{ height: 80, width: 80, borderRadius: 1 }} className="value" style={{ backgroundColor: color }}></Box>
          </Box>
          <Box>
            <List sx={{ marginTop: 3 }}>
              {todos.map((todo) => (
                <ListItem
                  key={todo.title}
                  secondaryAction={
                    <IconButton onClick={() => onDeletetodo(todo._id)} color="error" edge="end">
                      <DeleteIcon />
                    </IconButton>
                  }
                >
                  <Box
                    sx={{ height: 40, width: 40, borderRadius: 1, marginRight: 1 }}
                    className="value"
                    style={{ backgroundColor: todo.color }}
                  ></Box>
                  <ListItemText primary={todo.title} />
                </ListItem>
              ))}
            </List>
          </Box>
        </Box>
      </DialogContent>
      <Divider />
      <DialogActions sx={{ marginTop: 2 }}>
        <Button sx={{ marginRight: 2 }} variant="contained" color="error" onClick={onClose}>
          Cancel
        </Button>
        <Button
          onClick={() => onAddTodo()}
          disabled={title === "" || color === ""}
          sx={{ marginRight: 2 }}
          variant="contained"
          color="success"
        >
          Add
        </Button>
      </DialogActions>
    </Dialog>
  )
}

EventInfo

EventInfo.tsx is a straightforward yet essential component within your calendar application. It displays information about individual events. Right now we only show the description but you could add more things if you like.

import { Typography } from "@mui/material"
import { IEventInfo } from "./EventCalendar"

interface IProps {
  event: IEventInfo
}

const EventInfo = ({ event }: IProps) => {
  return (
    <>
      <Typography>{event.description}</Typography>
    </>
  )
}

export default EventInfo

Conclusion

Congratulations! You've successfully built a dynamic calendar application using React, Material UI, and Typescript. We started from scratch, setting up our project environment and installing the necessary dependencies. Then, we dived into the core functionalities, covering everything from event management and todo integration to color coding and localization.

The application you've built is robust and feature-rich, thanks to the various libraries and components we've employed. You now have the skills to:

Create and manage events on a calendar.
Integrate a todo list within a calendar application.
Color-code events based on associated todos or other criteria.
Utilize the React Big Calendar library for additional functionalities.
Apply localized date formats with the date-fns library.

Not only does this application serve as a practical tool, but it's also a great foundation for any future projects requiring calendar or scheduling functionalities. Feel free to expand upon this by adding more features or tweaking the existing ones to better suit your needs.

Thank you for following along, and happy coding!

Next.js Auth and Dashboard Boilerplate: Building a Full-Stack Web App

Martin Persson — Wed, 23 Aug 2023 09:02:36 +0000

Introduction
Technology Overview
Architecture and Code Structure
- Serverless API Structure with Next.js
- Type Safety with Zod
- Authentication Flow
Data Management
- MongoDB
- Data Fetching with SWR and Fetcher
- Fetcher Explanation
- SWR Explained
- Unified Response Interface
- Server-Side Handlers
- Client-Side Usage
E2E Testing with Cypress
Setting up the Project
- Deployment Process

Introduction

Next.js Auth Boilerplate Project

Welcome to the Next.js Auth Boilerplate Project. This is a full-stack application, built on the Next.js framework, equipped with a comprehensive authentication system. Designed to serve as a solid starting point, it integrates essential technologies to facilitate a smooth development process for modern web applications. Whether you're initiating a new project or seeking a robust foundation, this boilerplate provides the groundwork for swift and efficient web development.

For hands-on experience, you can explore the live demo and delve into the GitHub repository. Further into this post, you'll find detailed explanations on each component and feature.

Live demo: https://next-boilerplate-umber.vercel.app/

Github repo

Main Features

User Authentication: Utilizing Passport, this boilerplate offers a robust login and registration system, complete with persistent sessions. The use of local strategies ensures flexibility and security in handling user authentication.
Mail support: With the integration of nodemailer and brevo, the system can handle email verification and password resets, ensuring a complete and user-friendly authentication process.
Styling: Utilizes Emotion and Material-UI for responsive and aesthetic design.
Data Management: The combination of SWR, Axios, and MongoDB offers efficient data handling. SWR's caching strategy works with Axios's fetching capabilities to provide a seamless user experience, while MongoDB serves as a robust database solution.
Form Handling: The integration of Formik and Zod allows for concise form validations. Formik's intuitive API, along with Zod's schema validation, ensures that the data is handled correctly, providing a more reliable user experience.
Testing: Cypress is used for end-to-end testing, ensuring that the application functions as intended across different scenarios. Its interactive test runner and real browser environment make it a preferred choice for comprehensive testing.
Deployment: Hosted on Vercel, the application benefits from a seamless deployment process. Vercel's continuous deployment and serverless functions align well with the Next.js architecture, making it an ideal choice for this project.

For an in-depth look, you can explore the GitHub repository or see the live demo. In the following sections, we will delve into each aspect of the project, providing insights into the technologies used and how they are configured.

Technology Overview

Here's a brief look at some key technologies used in this project:

🌐 Next.js: The foundational framework for building the React application.
💅 Emotion and Material-UI: These libraries are used to style the components, ensuring responsive and aesthetically pleasing design.
🔐 Passport: Manages user authentication with various strategies, including local.
📝 Formik & Zod: Handle and validate forms, making sure the data is correct.
📊 SWR & Axios: Deal with data fetching and state management.
🔒 bcryptjs: Secures user passwords by hashing them.
📧 nodemailer: Sends emails for things like verification and password resets.
⚙️ next-connect: A small Express/Connect-style middleware framework for Next.js, facilitating efficient handling of server-side routes and middleware.
🗄️ MongoDB: The chosen database for this project, utilized for storing user information and managing sessions.
📚 TypeScript: Adds static typing to JavaScript, enhancing code quality.
🧪 Cypress: Provides end-to-end testing capabilities, ensuring that the application works as intended.
🚀 Vercel: The platform for hosting the application, providing a seamless deployment process.

These tools are chosen based on their functionality and fit for the project. Feel free to explore the code to see how they are implemented and how they work together.

Architecture and Code Structure

The architecture of the Next.js Auth Boilerplate project is designed to be modular and scalable, following industry best practices. Here's an overview:

Frontend (Client-side): Built with Next.js, the frontend uses React components for UI, styled with Emotion and Material-UI, and handles forms via Formik and Zod.
Backend (Server-side): Utilizes a combination of Next.js API routes, Passport for authentication, and MongoDB for data storage. Axios and SWR assist in data fetching and state management.
Testing: Cypress is integrated into the workflow to facilitate end-to-end testing.
Deployment: Vercel is the preferred choice for hosting, providing a smooth deployment process.

Serverless API Structure with Next.js

In the Next.js Auth Boilerplate project, the backend architecture leverages Next.js's built-in support for serverless functions to create a streamlined and scalable API structure. This approach offers various benefits, such as automatic scaling, isolation of functions, and a simplified development experience. Here's an overview of the core components:

Next.js API Routes

API routes in Next.js allow you to build your API within the same project as your Next.js application. These routes are automatically treated as serverless functions and are found in the pages/api directory. Each file within this directory corresponds to an endpoint, and the exported function defines the behavior of that endpoint. This leads to a clear and concise structure that aligns with modern serverless practices.

Next-Connect

To enhance the creation and management of API routes, the project utilizes the next-connect library. Next-connect provides a lightweight layer to work with middleware and handle HTTP methods within Next.js API routes more efficiently.

Here's an example of using next-connect to create a route:

import nextConnect from 'next-connect';

const handler = nextConnect();

handler.get((req, res) => {
  // Handle GET request
});

handler.post((req, res) => {
  // Handle POST request
});

export default handler;

Next-connect simplifies the process of defining various HTTP methods and integrating middleware, leading to cleaner and more maintainable code.

Serverless Benefits

Embracing a serverless architecture with Next.js API routes and next-connect offers several advantages:

Automatic Scaling: The serverless functions scale automatically with demand, providing efficient resource utilization.
Isolation: Each API route functions independently, reducing the risk of one route affecting others, improving stability and security.
Ease of Deployment: By integrating the API within the Next.js project, the deployment process is unified, leveraging platforms like Vercel for a seamless experience.
Rapid Development: The straightforward structure and tools like next-connect facilitate a faster development cycle, allowing for iterative enhancements and flexible adaptations.

Type Safety with Zod

One of the key aspects of the architecture in the Next.js Auth Boilerplate project is the use of Zod to enforce type safety across both the backend and frontend. This approach promotes consistency and robustness in the codebase. Here's how it's done:

Schema Definition: Zod allows you to define a schema for your data, describing the shape, structure, and validation rules. This schema acts as a blueprint for the data, ensuring that it adheres to the expected format.
Type Inference: Zod's powerful type inference capabilities enable you to automatically derive TypeScript types from the defined schema. This means that the same schema used for validation can also be used to generate the corresponding types. Here's an example:

const userSchema = z.object({
  name: z.string(),
  email: z.string().email(),
  age: z.number().positive(),
});

type User = z.infer<typeof userSchema>;

In this example, the User type is automatically inferred from the userSchema, creating a strongly typed representation of the user data.

Backend and Frontend Consistency: By using the same schema and inferred types across both the backend and frontend, you ensure that the data is handled consistently throughout the application. This alignment minimizes the risk of mismatches or errors when transmitting data between different parts of the system.
Validation and Parsing: Zod not only validates the data against the schema but also provides parsed and typed results. This feature simplifies the validation process and enhances the reliability of the code.
Integration with Other Tools: Zod's schemas can be easily integrated with other libraries, such as Formik for form handling, allowing for a seamless and type-safe user experience.

The use of Zod in the Next.js Auth Boilerplate project exemplifies a modern approach to type safety and data validation. By creating a shared understanding of the data structure across different layers of the application, Zod enhances maintainability and robustness. Its ability to define, validate, and infer types fosters a cohesive and efficient development process, contributing to the overall quality and reliability of the application.

Authentication Flow

The authentication flow is managed through Passport, using the Local strategy. Here's how it works:

Registration: Users can register with an email and password, which are stored in MongoDB after hashing with bcryptjs, the user is logged in directly.
Login: Users can log in with their credentials. Passport validates the credentials and creates a session.
Session Management: Express-session and connect-mongo handle sessions, maintaining user authentication status across requests.
Password Reset: If a user forgets their password, they can request a reset link sent to their email.

Email System

The email system plays a vital role in the Next.js Auth Boilerplate project by facilitating user interactions such as email verification and password resets. Below, we explore the technologies and methodologies used to implement this functionality.

Email Verification

Nodemailer: For email verification, the project uses Nodemailer, a widely-adopted module for sending emails in Node.js applications. Here's how it works:

Verification Endpoint: When the user clicks on the verification link, a request is made to a designated endpoint, validating the token and marking the email as verified.

Requesting Reset: Users can request a password reset by submitting their email address. The system generates a reset token through Brevo and sends it to the user's email address.

Resetting Password: When the user accesses the link with the reset token, they are directed to a page to reset their password. The token is validated, and the password is updated.

The project includes customizable email templates for the verification and password reset emails. These templates can be modified to align with the branding and design of your application, providing a consistent user experience.

Configuration
Both Nodemailer and Brevo are configurable, providing flexibility in setting up the email system according to your specific requirements. This includes the choice of email service provider, authentication credentials, and other settings. Here's a brief overview of the key configuration steps:

Nodemailer Configuration: Nodemailer requires an SMTP (Simple Mail Transfer Protocol) service to send emails. You can choose a provider like Gmail, SendGrid, or any other that supports SMTP. The credentials for this service will need to be included in your .env file.
Brevo Configuration: To use Brevo for generating and handling tokens (e.g., for email verification and password reset), you will need to set up an SMTP service on Brevo. This is where your chosen email service provider comes into play. Follow the instructions in the Brevo documentation or your chosen provider's documentation to set up the SMTP service.
Environment Variables: To keep sensitive information like API keys and email credentials secure, you should store them in environment variables. Make sure to update the .env file in your project with the correct credentials for both Nodemailer and Brevo. This may include SMTP server details, API keys, email addresses, and other authentication information.

MAIL_PASSWORD=""
MAIL_USER=""

Security Considerations
The email system is designed with security in mind. By utilizing secure tokens, HTTPS connections, and best practices for handling sensitive information, the project ensures that email-related operations are carried out securely.

The integration of Nodemailer and Brevo, along with the well-designed workflows for email verification and password resets, establishes a robust and user-friendly email system within the Next.js Auth Boilerplate project. This system not only enhances security but also adds convenience and functionality, contributing to a positive user experience.

Data Management

Data management is a crucial aspect of any application, ensuring the effective handling, validation, and storage of data. It involves managing the flow of data through the entire lifecycle, including data collection, processing, storage, and retrieval. This section will delve into the specific methods and technologies used in this application for data management.

MongoDB

We are using MongoDB and MongoDB Atlas for our database. MongoDB is a popular NoSQL database that offers high performance, scalability, and flexibility. The following explains the implementation:

MongoDB Connection

The connection to the MongoDB server is handled through the MongoClient from the MongoDB library. We've created a reusable function getMongoClient to manage the connection and another function getMongoDb to get access to the specific database:

import { MongoClient } from "mongodb"

if (!process.env.MONGODB_URI) {
  throw new Error('Invalid/Missing environment variable: "MONGODB_URI"')
}

const uri = process.env.MONGODB_URI
const options = {}

let indexesCreated = false
async function createIndexes(client: MongoClient) {
  if (indexesCreated) return client
  const db = client.db("dev")
  await Promise.all([db.collection("users").createIndexes([{ key: { email: 1 }, unique: true }])])
  indexesCreated = true
  return client
}

export async function getMongoClient() {
  // Global is used here to maintain a cached connection across hot reloads in development.
  if (!global._mongoClientPromise) {
    const client = new MongoClient(uri)
    global._mongoClientPromise = client.connect().then(async (client) => await createIndexes(client))
  }
  return await global._mongoClientPromise
}

export async function getMongoDb() {
  const mongoClient = await getMongoClient()
  return mongoClient.db("dev")
}

Serverless Connection Handling

This implementation is tailored for a serverless environment. By caching the MongoDB client, the connection can be reused across different function invocations, preventing a new connection from being established every time. This avoids exponentially growing connections during API Route usage, which is vital for a serverless architecture.

Creating Indexes

The createIndexes function ensures that specific indexes are created on the collections when the application starts. In this example, a unique index is created on the email field of the users collection, ensuring that no two users can have the same email address.

By leveraging MongoDB and MongoDB Atlas, the application benefits from a robust and scalable data storage solution. The serverless architecture, combined with efficient connection handling and indexing, provides an effective way to manage the data within the application.

Data Fetching with SWR and Fetcher

Fetcher Explanation

The fetcher function acts as a utility for making HTTP requests using Axios. It is designed to handle requests with a consistent response format and handle errors in a standardized way.

Here's a breakdown of the function:

Generics: The function utilizes TypeScript generics where R is the expected response type, and T is the expected request body type. This ensures that both the input and the response are type-checked according to the specific usage of the fetcher.
Options Interface: An Options interface is defined to describe the method, data, and headers of the HTTP request.

export type HTTPMethod = "GET" | "POST" | "PUT" | "DELETE" | "PATCH"

export interface Options<T> {
  method: HTTPMethod
  data: T
  headers: {}
}

Handling Response: The handleResponse function checks if the response status code is between 200 and 300, indicating success. If successful, it returns the data; otherwise, it returns a predefined error structure.
Handling Error: The handleError function handles specific error scenarios. For example, a 401 status code returns an unauthorized error. Any other errors return the error message.
Axios Request: The fetcher uses Axios to make the HTTP request with the provided URL and options. It then utilizes handleResponse and handleError functions to process the response.

// Generic R is the response type and T is the request body type.
export const fetcher = async <R, T>(url: string, options?: Options<T>): Promise<Response<R>> =>
  await axios
    .request({ url, ...options })
    .then(handleResponse<R>)
    .catch(handleError<R>);

In a usage scenario, you would replace R and T with specific types according to what the request and response should contain.

export const useUser = () =>
  useSWRImmutable("/api/user", async (url) => await fetcher<Omit<UserModelSchemaType, "password"> | null, undefined>(url))

The fetcher offers a flexible and type-safe way to make HTTP requests within your application.

Another example using the fetcher with Options

const registerUser = async (data: UserRegistrationSchemaType) => {
  setStatus("loading")

  const responseData = await fetcher<UserModelSchemaType, UserRegistrationSchemaType>("/api/users", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    data,
  })

  // Handling response
  // ...
}

SWR explained

SWR (stale-while-revalidate) is a library used for data fetching that allows you to keep data up to date with background updates and revalidation. This boilerplate takes advantage of SWR's useSWRImmutable hook to provide immutable data fetching. The provided fetcher function is used in conjunction with SWR to standardize how requests are made.

Here's how the user data is retrieved using a custom hook:

export const useUser = () =>
  useSWRImmutable("/api/user", async (url) => await fetcher<Omit<UserModelSchemaType, "password"> | null, undefined>(url))

Unified Response Interface

We have defined a common Response<R> interface that represents the structure of the response both on the client and server sides. This interface ensures that all responses have a consistent shape, containing a payload, an error message, and a general message string.

export interface Response<R> {
  payload: R | null;
  error: string | null;
  message: string;
}

This pattern allows the application to handle responses uniformly, whether they represent success or failure.

Server-Side Handlers

We are using Zod to help parse the request data, ensuring that the data received matches the expected structure. This adds a layer of validation and type safety to the request handling process:

 const parsedFormInput = UserRegistrationSchema.safeParse(req.body)

Once the data is parsed, two utility functions, handleAPIResponse and handleAPIError, are utilized to send consistent responses to the client.

handleAPIResponse: This function accepts a payload, a message, and a status code, and sends a JSON response that aligns with the Response interface. It's used to send successful responses.

export const handleAPIResponse = <T>(
  res: NextApiResponse<Response<T>>,
  payload: T,
  message: string,
  statusCode = 200
): void => {
  res.statusCode = statusCode;
  res.json({ payload, error: null, message });
};

handleAPIError: This function is designed to send error responses, again aligning with the Response interface. It accepts an error string and a status code, ensuring that error responses are structured consistently.

export const handleAPIError = (res: NextApiResponse, error: string, statusCode = 400): void => {
  res.statusCode = statusCode;
  res.json({ payload: null, error: error, message: "An error occurred" });
};

By using Zod for parsing and these utility functions for handling responses, the server-side code maintains a clear and consistent structure, easing both development and maintenance.

Client-Side Usage

On the front-end, the fetcher function is aware of this response structure, as it expects a Promise<Response<R>>. This alignment ensures that both the server and client handle responses in the same way, reducing the likelihood of misunderstandings between the two.

Benefits

Type Safety: Using TypeScript's typing system, this approach guarantees that the server sends and the client expects the same response structure, catching potential issues at compile-time.
Maintainability: By using the same interface across the whole codebase, any changes to the response structure only need to be made in one place. It's a pattern that promotes maintainable and scalable code.
Clarity and Consistency: This approach makes the code more readable and helps new team members or contributors understand how data flows through the application.

By leveraging the power of TypeScript and consistent patterns, this approach streamlines development and can significantly enhance the robustness and efficiency of the application.

Conclusion

Data management is central to the functionality and performance of the application. By utilizing MongoDB with optimized connection handling and indexing, along with standardized fetching using SWR and a fetcher function, the application ensures scalability, maintainability, and type safety. The use of TypeScript and consistent response handling further enhances the robustness and clarity of the code. This comprehensive approach to data management lays a solid foundation for the development and expansion of the application, meeting the demands of modern software development.

E2E Testing with Cypress

End-to-End (E2E) testing is a crucial part of ensuring the stability and reliability of any web application. In this project, we utilize Cypress, a popular testing tool designed for modern web applications.

Why Cypress?

Cypress offers a rich set of features and an easy-to-use interface, which makes writing and running tests a breeze. Some of the reasons why we chose Cypress include:

Interactive Test Runner: Cypress comes with an interactive test runner that allows you to see commands as they execute while viewing the application under test.
Real-Time Reloads: It automatically reloads your tests when changes are made, facilitating a smooth development workflow.
Debuggability: With built-in tools to help you understand what's happening inside your tests, debugging is made more accessible.
Cross-Browser Testing: You can run tests in various browsers to ensure compatibility.
Rich Ecosystem: A thriving community and a plethora of plugins and integrations enhance Cypress's capabilities.

Setting Up Cypress

Setting Up the Test Environment
Before you start testing with Cypress, ensure that you have the development server running locally. This will allow Cypress to access the application and perform the end-to-end tests.

You can start the development server with: npm run dev

Creating a Test User

Before running the tests, you must create a test user with the following credentials:

Email: cypress@test.com
Password: cypress@test.com

This user will be utilized in various authentication-related tests.

Running Tests
Once the test user is created, you can run the automated test suite by executing the following command:

npm run cypress-e2e

This command will start Cypress, and the tests will run in the selected browser. You can see the results in real-time and interact with the test runner to get more insights into the tests' execution.

Writing Your Own Tests

Cypress makes it easy to write your own tests. With its intuitive API and robust documentation, you can quickly start creating tests tailored to your application's specific needs.

To learn more about Cypress and explore its features, visit the official Cypress documentation.

By integrating Cypress into our testing workflow, we ensure that our application behaves as intended, providing confidence in the code's quality and performance. With its straightforward setup and ease of use, Cypress stands as an invaluable tool for developers striving to maintain a high standard of quality in their projects.

Setting up the project

Deployment Process

Deploying the Next.js Auth Boilerplate project to Vercel is a streamlined process, aimed at providing a hassle-free experience even for those new to web deployment. The following step-by-step guide outlines the deployment process, ensuring that you can get your project live in no time:

Create an Account on Vercel (if you don't have one): Visit Vercel's website and sign up or log in.
Create a New Project: Once logged in, click on "New Project" and select "Import Git Repository."
Import the GitHub Repository: Connect your GitHub account and select the repository containing the Next.js Auth Boilerplate project. Follow the on-screen instructions to set up the project on Vercel.
Configure MongoDB Atlas Integration: You'll need to link the project to your MongoDB Atlas database. On the project settings page, navigate to "Integrations" and search for the MongoDB Atlas integration. Follow the instructions to connect your database.
Update Environment Variables: Modify the WEB_URI variable in your .env file to match the domain where your application will be hosted. Additionally, ensure that all the necessary environment variables are configured in the Vercel dashboard. You can refer to the provided .env.example file for a complete list of required variables.
Automatic Deployment: Whenever you push changes to the main branch of your GitHub repository, Vercel will automatically trigger a deployment. The deployment process takes care of building, optimizing, and hosting your application, making it accessible to users around the world.
Verify and Test: Once deployed, visit the provided URL to verify that the application is running correctly. You may want to conduct additional tests to ensure that all functionalities, including authentication and email systems, are operational.

By following this guide, you should have a working instance of the Next.js Auth Boilerplate project. Feel free to explore the additional configuration options available on Vercel to tailor the hosting environment to your specific needs.

Given the scale and complexity of this project, there might be occasional oversights or areas in the guide that could be clearer. If you encounter any issues or need further assistance, please consult the official Vercel documentation or reach out through the comments.

Thank you for taking the time to go through this guide, and happy coding!

DEV Community: Martin Persson

[Boost]

Orion Kit: Production-Ready SaaS Template (Next.js 15, TypeScript, Stripe, Drizzle)

Martin Persson ・ Oct 18

If you're building SaaS, learning how monorepos work or just want to see how modern TypeScript apps are structured. Orion Kit shows you the full stack: Next.js 15, Drizzle ORM, Stripe payments & JWT auth. Hope it's helpful!

Orion Kit: Production-Ready SaaS Template (Next.js 15, TypeScript, Stripe, Drizzle)

Orion Kit: Production-Ready SaaS Template (Next.js 15, TypeScript, Stripe, Drizzle)

Links

What This Is

What’s Inside

Applications (4)

Shared Packages (9)

Technical Architecture

Type Safety Flow

Monorepo Structure

Integrated Features

Authentication

Payments

Database

Email

Testing

Observability & Analytics

Background Jobs

Development Workflow

Required Services (all have generous free tiers)

Getting Started

Prerequisites

1) Clone & install

2) Environment variables

3) Database

4) Dev servers

5) Tests

Documentation

Use Cases

Deployment (Overview)

Contributing

[Boost]

How I Use Effect.ts to Orchestrate a Type-Safe GraphQL Backend

How I Use Effect.ts to Orchestrate a Type-Safe GraphQL Backend

Building a Robust Backend with Effect, GraphQL, and Drizzle

Table of Contents

Introduction

The Problem

The Solution

1. Effect: Functional Effects for Robust Error Handling

2. Gradual Migration: Mix Effect and Promises

3. Branded Types: Type Safety That Actually Works

Architecture Overview

Domain Layer

Repository Layer

Key Features

Robust Error Handling

Performance Optimizations

Circular Relationship Prevention

Tree Operations

Important Disclaimer: This is a Demo

Benefits

1. Compile-Time Safety

2. Debugging-Friendly

3. Testable Code

4. Maintainable

Getting Started

Available Scripts

GraphQL API

Key Takeaways

Conclusion

Building a Real-Time Chat App with Firebase and Next.js

Table of Contents

Introduction

Tech Stack

Project Overview

Firebase Setup

1. Create a Firebase project:

2. Add Firestore to your project:

3. Create a Web App in Firebase:

4. Set up environment variables:

5. Initialize Firebase in your app:

Message Schema with Zod

Real-Time Messaging with Firestore

Pagination and Lazy Loading