Getting Started

Prerequisites

Bun or Node.js 18+
A NestJS application (backend)
A React 18/19 application (frontend)
PostgreSQL (recommended) or any database supported by Prisma

Installation

Backend

bun add @roomkit/nestjs

Peer dependencies (install as needed):

bun add @nestjs/common @nestjs/core
bun add @prisma/client   # Required for Prisma adapter

Frontend

bun add @roomkit/react

Peer dependencies:

bun add react react-dom  # React 18 or 19

Database Setup

Add the RoomKit models to your schema.prisma. See the Prisma Adapter page for the full schema reference.

Run your migrations after adding the models:

bunx prisma migrate dev --name add-roomkit-models

Backend Setup

1. Register the Module

import { Module } from '@nestjs/common';
import { RoomKitModule, PrismaRoomKitAdapter } from '@roomkit/nestjs';
import { PrismaClient } from '@prisma/client';

const prisma = new PrismaClient();

@Module({
    imports: [
        RoomKitModule.register({
            storage: new PrismaRoomKitAdapter(prisma),
            priorities: [
                { name: 'LECTURE', weight: 100 },
                { name: 'SEMINAR', weight: 75 },
                { name: 'STUDY_GROUP', weight: 50 },
                { name: 'OPEN', weight: 25 },
            ],
            events: {
                BookingRequested: (event) => {
                    console.log('New booking requested:', event.payload.title);
                },
                ConflictDetected: (event) => {
                    console.log('Conflict detected:', event.payload);
                },
            },
        }),
    ],
})
export class AppModule {}

2. Create a Booking Controller

import { Controller, Get, Post, Body, Query } from '@nestjs/common';
import { BookingService, AvailabilityService } from '@roomkit/nestjs';

@Controller('roomkit')
export class BookingController {
    constructor(
        private readonly bookings: BookingService,
        private readonly availability: AvailabilityService,
    ) {}

    @Post('bookings')
    async createBooking(@Body() body: {
        roomId: string;
        requesterId: string;
        title: string;
        startsAt: string;
        endsAt: string;
        purposeType: string;
    }) {
        return this.bookings.create({
            ...body,
            startsAt: new Date(body.startsAt),
            endsAt: new Date(body.endsAt),
        });
    }

    @Get('availability')
    async searchAvailability(
        @Query('startsAt') startsAt: string,
        @Query('endsAt') endsAt: string,
        @Query('minCapacity') minCapacity?: string,
    ) {
        return this.availability.search(
            {
                timeRange: {
                    startsAt: new Date(startsAt),
                    endsAt: new Date(endsAt),
                },
                minCapacity: minCapacity ? parseInt(minCapacity, 10) : undefined,
            },
            { limit: 20 },
        );
    }
}

Frontend Setup

1. Add the Provider

import { RoomKitProvider } from '@roomkit/react';

function App() {
    return (
        <RoomKitProvider config={{ apiUrl: '/api/roomkit' }}>
            <YourApp />
        </RoomKitProvider>
    );
}

2. Search for Available Rooms

import { useAvailability, AvailabilitySearch, RoomCard } from '@roomkit/react';

function RoomFinder() {
    const [filters, setFilters] = useState(null);
    const { data, isLoading } = useAvailability({
        filters: filters ?? {
            timeRange: {
                startsAt: new Date(),
                endsAt: new Date(Date.now() + 2 * 60 * 60 * 1000),
            },
        },
    });

    return (
        <div>
            <AvailabilitySearch onChange={setFilters} />
            {isLoading && <p>Searching...</p>}
            {data?.items.map((item) => (
                <RoomCard key={item.room.id} room={item.room} score={item.score} />
            ))}
        </div>
    );
}

3. Create a Booking

import { useCreateBooking, BookingForm } from '@roomkit/react';

function NewBooking({ roomId }: { roomId: string }) {
    const { mutate, isLoading, error } = useCreateBooking({
        onSuccess: (booking) => console.log('Booked:', booking.id),
    });

    return (
        <BookingForm
            roomId={roomId}
            onSubmit={(data) => mutate(data)}
            isSubmitting={isLoading}
        />
    );
}

Getting Started

On this page