Architecture

Understanding the architecture and design patterns of React Event Calendar.

Overview

React Event Calendar is built with a modern architecture using Next.js App Router, Zustand for state management, URL state management with nuqs, and PostgreSQL with Drizzle ORM for data persistence. The calendar supports multiple views (day, week, month, year) with customizable configurations.

src/

State Management

The calendar uses a combination of Zustand for global state management and URL state management with nuqs to enable shareable calendar views.

URL State with nuqs

URL parameters are managed with nuqs to enable shareable calendar views and bookmarking:

lib/searchParams.ts

import { CalendarViewType } from '@/types/event';
import {
  createSearchParamsCache,
  parseAsArrayOf,
  parseAsBoolean,
  parseAsInteger,
  parseAsIsoDate,
  parseAsString,
} from 'nuqs/server';

export const searchParamsCache = createSearchParamsCache({
  date: parseAsIsoDate.withDefault(new Date()),
  view: parseAsString.withDefault(CalendarViewType.MONTH),
  title: parseAsString.withDefault(''),
  categories: parseAsArrayOf(parseAsString).withDefault([]),
  daysCount: parseAsInteger.withDefault(7),
  search: parseAsString.withDefault(''),
  colors: parseAsArrayOf(parseAsString).withDefault([]),
  locations: parseAsArrayOf(parseAsString).withDefault([]),
  repeatingTypes: parseAsArrayOf(parseAsString).withDefault([]),
  isRepeating: parseAsBoolean.withDefault(false),
  limit: parseAsInteger.withDefault(50),
  offset: parseAsInteger.withDefault(0),
});

Zustand Store

The core state is managed by a Zustand store that handles view configurations, selected events, and UI states:

hooks/use-event-calendar.tsx

import { create } from 'zustand';
import { persist } from 'zustand/middleware';
import {
  CalendarViewType,
  TimeFormatType,
  ViewModeType,
} from '@/types/event';

const DEFAULT_VIEW_CONFIGS = {
  day: {
    showCurrentTimeIndicator: true,
    showHoverTimeIndicator: true,
    enableTimeSlotClick: true,
  },
  week: {
    highlightToday: true,
    showCurrentTimeIndicator: true,
    showHoverTimeIndicator: true,
    enableTimeSlotClick: true,
    expandMultiDayEvents: true,
  },
  // ... other view configurations
};

export const useEventCalendarStore = create(
  persist(
    (set, get) => ({
      selectedEvent: null,
      currentView: CalendarViewType.DAY,
      viewMode: ViewModeType.CALENDAR,
      timeFormat: TimeFormatType.HOUR_24,
      locale: 'en-US',
      firstDayOfWeek: 0, // sunday
      daysCount: 7,
      viewSettings: DEFAULT_VIEW_CONFIGS,
      // ... other state properties

      setView: (view) => set({ currentView: view }),
      setTimeFormat: (format) => set({ timeFormat: format }),
      // ... other actions
    }),
    {
      name: 'event-calendar',
      partialize: (state) => ({
        currentView: state.currentView,
        viewMode: state.viewMode,
        timeFormat: state.timeFormat,
        locale: state.locale,
        firstDayOfWeek: state.firstDayOfWeek,
        daysCount: state.daysCount,
        viewSettings: state.viewSettings,
      }),
    }
  )
);

Database Structure

The calendar uses PostgreSQL with Drizzle ORM for data persistence. The schema is designed to support various event properties including recurring events.

db/schema.ts

import {
  pgTable,
  timestamp,
  varchar,
  uuid,
  boolean,
  text,
} from 'drizzle-orm/pg-core';

export const events = pgTable('events', {
  id: uuid('id').primaryKey().defaultRandom(),
  title: varchar('title', { length: 256 }).notNull(),
  description: text('description').notNull(),
  startDate: timestamp('start_date', { withTimezone: true }).notNull(),
  endDate: timestamp('end_date', { withTimezone: true }).notNull(),
  startTime: varchar('start_time', { length: 5 }).notNull(),
  endTime: varchar('end_time', { length: 5 }).notNull(),
  isRepeating: boolean('is_repeating').notNull(),
  repeatingType: varchar('repeating_type', {
    length: 10,
    enum: ['daily', 'weekly', 'monthly'],
  }).$type<'daily' | 'weekly' | 'monthly'>(),
  location: varchar('location', { length: 256 }).notNull(),
  category: varchar('category', { length: 100 }).notNull(),
  color: varchar('color', { length: 15 }).notNull(),
  createdAt: timestamp('created_at', { withTimezone: true })
    .defaultNow()
    .notNull(),
  updatedAt: timestamp('updated_at', { withTimezone: true })
    .defaultNow()
    .notNull(),
});

export type EventTypes = typeof events.$inferSelect;
export type newEvent = typeof events.$inferInsert;

Server Actions

Next.js Server Actions are used to interact with the database, providing type-safe data fetching and mutations:

app/actions.ts

'use server';

import { db } from '@/db';
import { events } from '@/db/schema';
import { CalendarViewType } from '@/types/event';
import { and, between, eq, ilike, or, lte, gte } from 'drizzle-orm';
import {
  startOfDay,
  endOfDay,
  startOfWeek,
  endOfWeek,
  startOfMonth,
  endOfMonth,
  startOfYear,
  endOfYear,
} from 'date-fns';
import { z } from 'zod';
import { unstable_cache as cache, revalidatePath } from 'next/cache';

const eventFilterSchema = z.object({
  title: z.string().optional(),
  categories: z.array(z.string()).default([]),
  daysCount: z.number().optional(),
  view: z.enum([
    CalendarViewType.DAY,
    CalendarViewType.DAYS,
    CalendarViewType.WEEK,
    CalendarViewType.MONTH,
    CalendarViewType.YEAR,
  ]).optional(),
  date: z.date(),
  // ... other filter properties
});

export type EventFilter = z.infer<typeof eventFilterSchema>;

export const getEvents = cache(
  async (filterParams: EventFilter) => {
    try {
      const filter = eventFilterSchema.parse(filterParams);

      const currentDate = new Date(filter.date);
      let dateRange: { start: Date; end: Date } = {
        start: startOfMonth(currentDate),
        end: endOfMonth(currentDate),
      };

      if (filter.view) {
        switch (filter.view) {
          case CalendarViewType.DAY:
            dateRange = {
              start: startOfDay(currentDate),
              end: endOfDay(currentDate),
            };
            break;
          case CalendarViewType.WEEK:
            dateRange = {
              start: startOfWeek(currentDate, { weekStartsOn: 0 }),
              end: endOfWeek(currentDate, { weekStartsOn: 0 }),
            };
            break;
          // ... other view cases
        }
      }

      const conditions = [];

      // Add date range condition
      conditions.push(
        or(
          and(
            between(events.startDate, dateRange.start, dateRange.end),
            between(events.endDate, dateRange.start, dateRange.end),
          ),
          // ... other date conditions
        ),
      );

      // Add other filter conditions
      if (filter.title) {
        conditions.push(ilike(events.title, `%${filter.title}%`));
      }

      if (filter.categories.length > 0) {
        const categoryConditions = filter.categories.map((category) =>
          eq(events.category, category),
        );
        conditions.push(or(...categoryConditions));
      }

      // Execute the query with all conditions
      const result = await db
        .select()
        .from(events)
        .where(and(...conditions))
        .execute();

      return {
        events: result,
        success: true,
        timestamp: new Date().toISOString(),
      };
    } catch (error) {
      console.error('Error fetching events:', error);
      return {
        events: [],
        success: false,
        error: error instanceof Error ? error.message : 'Error fetching events',
      };
    }
  },
  ['get-events'],
  {
    revalidate: 3600,
    tags: ['events'],
  }
);

Component Architecture

The calendar is built with a modular component architecture that separates concerns:

Main Components

EventCalendar: The main container component that manages state and renders the appropriate view
CalendarHeader: Navigation controls, view switchers, and date display
CalendarDayView: Single day detailed view with time slots
CalendarWeekView: Week view showing multiple days with time slots
CalendarMonthView: Traditional month grid view
EventItem: Individual event rendering with positioning logic
EventForm: Form for creating and editing events

components/event-calendar/calendar.tsx

import { CalendarHeader } from './calendar-header';
import { CalendarDayView } from './calendar-day-view';
import { CalendarWeekView } from './calendar-week-view';
import { CalendarMonthView } from './calendar-month-view';
import { useEventCalendarStore } from '@/hooks/use-event-calendar';
import { CalendarViewType } from '@/types/event';
import { EventTypes } from '@/db/schema';

interface EventCalendarProps {
  events: EventTypes[];
  initialDate: Date;
}

export function EventCalendar({ events, initialDate }: EventCalendarProps) {
  const currentView = useEventCalendarStore((state) => state.currentView);

  // Render different views based on the current view state
  const renderCalendarView = () => {
    switch (currentView) {
      case CalendarViewType.DAY:
        return <CalendarDayView events={events} date={initialDate} />;
      case CalendarViewType.WEEK:
        return <CalendarWeekView events={events} date={initialDate} />;
      case CalendarViewType.MONTH:
        return <CalendarMonthView events={events} date={initialDate} />;
      default:
        return <CalendarDayView events={events} date={initialDate} />;
    }
  };

  return (
    <div className="flex flex-col h-full">
      <CalendarHeader />
      {renderCalendarView()}
    </div>
  );
}

Data Flow

The calendar follows a unidirectional data flow pattern with Next.js App Router and Server Actions:

URL State: User interactions update URL parameters via nuqs
Server Actions: URL parameters are parsed and used to fetch data from the database
Component Rendering: Data is passed to components for rendering
User Interactions: UI events trigger state updates and Server Actions
Persistence: Changes are saved to the database via Server Actions and the UI is updated

app/page.tsx

import { getEvents, getCategories } from './actions';
import { searchParamsCache } from '@/lib/searchParams';
import { CalendarViewType } from '@/types/event';
import { EventCalendar } from '@/components/event-calendar/calendar';
import { Suspense } from 'react';

export default async function CalendarPage({ searchParams }) {
  // Parse URL parameters using nuqs
  const search = searchParamsCache.parse(searchParams);

  // Fetch data using Server Actions
  const eventsResponse = await getEvents({
    date: search.date,
    view: search.view as CalendarViewType,
    daysCount: Number(search.daysCount),
    categories: search.categories,
    title: search.title,
    colors: search.colors,
    locations: search.locations,
    isRepeating: search.isRepeating,
  });

  // Render the calendar with the fetched data
  return (
    <div className="container mx-auto p-4">
      <Suspense fallback={<div>Loading calendar...</div>}>
        <EventCalendar
          events={eventsResponse.events}
          initialDate={search.date}
        />
      </Suspense>
    </div>
  );
}

Server-Side Rendering and Caching

The calendar uses Next.js Server Components and Server Actions to render content on the server and cache responses. The unstable_cache API is used to cache event data for improved performance.

Event Filtering and Search

The calendar supports advanced filtering and search capabilities:

Date Range Filtering: Events are filtered based on the selected view (day, week, month, year)
Category Filtering: Events can be filtered by category
Color Filtering: Events can be filtered by color
Location Filtering: Events can be filtered by location
Recurring Event Filtering: Events can be filtered by their recurring status
Text Search: Events can be searched by title, description, or location

All filters can be combined to create complex queries, and the results are efficiently fetched from the database using Drizzle ORM's query builder.

Recurring Events

The calendar supports recurring events with different patterns:

Daily: Events that repeat every day
Weekly: Events that repeat on the same day every week
Monthly: Events that repeat on the same day every month

Recurring events are stored in the database with a flag indicating their recurring status and the type of recurrence. The calendar logic handles the expansion of recurring events when displaying them in different views.

Performance Optimizations

The calendar implements several performance optimizations:

Server-Side Rendering: Initial data is rendered on the server for faster page loads
Data Caching: Server Actions use Next.js caching to reduce database queries
Incremental Static Regeneration: Pages are statically generated and revalidated periodically
Optimized Database Queries: Queries are optimized to fetch only the necessary data
Component Memoization: React components use memoization to prevent unnecessary re-renders

Introduction

Core Features

Hooks

Database

Customization