nuxt-calendar-module

A modern and customizable calendar package for Vue 3 / Nuxt 3, born from the need to simplify complex scheduling components. This is a community package, not officially maintained by the Nuxt team.

The Story Behind This Module

I originally built an admin dashboard for sports coaching sessions, and the calendar component I created manually was quite complex for me to maintain. That's when I decided to create my first Nuxt module to make this reusable and easier to manage. This module is the result of that journey - a clean, modular calendar solution that can be easily integrated into any Nuxt 3 project.

Features

• ✨ Easy imports - Import components and composables directly
• 🎨 Themes - Light, dark and automatic theme support
• 🌍 Internationalization - Complete locale support
• 📱 Responsive - Adapted for mobile and tablets
• ⚡ Performance - Optimized with Vue 3 and Composition API
• 🎯 TypeScript - Complete TypeScript support
• 🔧 Configurable - Flexible configuration options
• 📅 Events - Complete event management
• 🏃‍♂️ Sports Coaching Ready - Perfect for scheduling sports sessions
• 📊 Admin Dashboard - Built with admin interfaces in mind

Quick Installation

1. Add nuxt-calendar-module to your project dependencies:

# npm
npm install nuxt-calendar-module

# pnpm
pnpm add nuxt-calendar-module

# yarn
yarn add nuxt-calendar-module

2. Add the CSS (recommended)

Nuxt 3 (nuxt.config.ts):

export default defineNuxtConfig({
  css: ['nuxt-calendar-module/runtime/assets/calendar.css']
})

ou import global (ex. app.vue):

// app.vue or a global entry
import 'nuxt-calendar-module/runtime/assets/calendar.css'

That's it! You can now import and use the Calendar components in your application ✨

Status

🚧 Community Module - This module is maintained by the community and is not officially supported by the Nuxt team. Use at your own discretion.

Development

Local Development

1. Clone the repository

git clone https://github.com/yourusername/nuxt-module-calendar.git
cd nuxt-module-calendar

2. Install dependencies

npm install

3. Start the playground

cd playground
npm run dev

4. Run tests

npm run test

Testing the Package

You can test the module locally before publishing:

# Build the module
npm run build

# Pack it locally
npm pack

# Install in a test project
npm install ../path/to/nuxt-calendar-module-1.0.1.tgz

Usage

Quick usage with CalendarComponent

<template>
  <div>
    <CalendarComponent 
      :locale="'fr-FR'"
      :timezone="'Europe/Paris'"
      :theme="'auto'"
      :reservations="reservations"
      @new-reservation="handleNewReservation"
      @reservation-click="handleClick"
    />
  </div>
</template>

<script setup lang="ts">
import { ref } from 'vue'
import 'nuxt-calendar-module/runtime/assets/calendar.css'
import CalendarComponent from 'nuxt-calendar-module/runtime/components/CalendarComponent.vue'

const reservations = ref([
  {
    id: '1',
    title: 'Client Session',
    start_date: '2024-01-15T09:00:00.000Z',
    end_date: '2024-01-15T10:00:00.000Z',
    duration: 60
  }
])

function handleNewReservation(reservation: any) {
  reservations.value.push(reservation)
}

function handleClick(reservation: any) {
  console.log('Reservation clicked:', reservation)
}
</script>

Calendar component usage (direct import)

<template>
  <div>
    <Calendar 
      :reservations="reservations"
      :working-hours="workingHours"
      locale="fr-FR"
      timezone="Europe/Paris"
      theme="auto"
      @reservation-click="onReservationClick"
      @view-change="onViewChange"
    />
  </div>
</template>

<script setup lang="ts">
import 'nuxt-calendar-module/runtime/assets/calendar.css'
import Calendar from 'nuxt-calendar-module/runtime/components/Calendar.vue'

const reservations: any[] = []
const workingHours = {
  morning: [9, 10, 11, 12],
  afternoon: [14, 15, 16, 17]
}

function onReservationClick(reservation: any) {
  console.log('Reservation clicked:', reservation)
}

function onViewChange(view: 'day' | 'week', date: Date) {
  console.log('View changed:', view, date)
}
</script>

Simple calendar with events (direct import)

<template>
  <div>
    <SimpleCalendar 
      :events="events"
      :locale="'fr-FR'"
      :theme="'auto'"
      @date-select="onDateSelect"
      @event-click="onEventClick"
    />
  </div>
</template>

<script setup lang="ts">
import { ref } from 'vue'
import 'nuxt-calendar-module/runtime/assets/calendar.css'
import SimpleCalendar from 'nuxt-calendar-module/runtime/components/SimpleCalendar.vue'

const events = ref([
  { id: 1, title: 'Team Meeting', date: new Date(), color: '#3b82f6' },
  { id: 2, title: 'Client Presentation', date: new Date(Date.now() + 86400000), color: '#ef4444' }
])

function onDateSelect(date: Date) {
  console.log('Date selected:', date)
}

function onEventClick(event: any) {
  console.log('Event clicked:', event)
}
</script>

With composables (direct import)

<template>
  <div>
    <h2>{{ monthName }} {{ currentYear }}</h2>
    <button @click="goToPreviousMonth">← Previous</button>
    <button @click="goToNextMonth">Next →</button>
    <p>Selected date: {{ selectedDate?.toLocaleDateString() }}</p>
    <div class="custom-calendar"></div>
  </div>
  </template>

<script setup lang="ts">
import 'nuxt-calendar-module/runtime/assets/calendar.css'
import { useCalendar } from 'nuxt-calendar-module/runtime/composables/useCalendar'
import { useReservationCalendar } from 'nuxt-calendar-module/runtime/composables/useReservationCalendar'

const {
  currentYear,
  monthName,
  selectedDate,
  calendarDates,
  goToNextMonth,
  goToPreviousMonth,
  addEvent
} = useCalendar({ locale: 'fr-FR' })

const reservationCalendar = useReservationCalendar({
  locale: 'fr-FR',
  timezone: 'Europe/Paris'
})

addEvent({ id: 1, title: 'Team Meeting', date: new Date(), color: '#3b82f6' })
</script>

Configuration

No Nuxt module configuration is required. Optionally, add the CSS in nuxt.config.ts:

export default defineNuxtConfig({
  css: ['nuxt-calendar-module/runtime/assets/calendar.css']
})

useCalendar composable options

const calendar = useCalendar({
  locale: 'fr-FR',
  firstDayOfWeek: 1,
  showWeekNumbers: true,
  theme: 'dark',
  minDate: new Date('2023-01-01'),
  maxDate: new Date('2024-12-31'),
  disabledDates: [
    new Date('2024-01-01'), // New Year's Day
    new Date('2024-12-25')  // Christmas
  ]
})

TypeScript Types

The module includes complete TypeScript types:

interface CalendarEvent {
  id: string | number
  title: string
  description?: string
  date: Date
  startTime?: string
  endTime?: string
  color?: string
  category?: string
  allDay?: boolean
}

interface CalendarDate {
  year: number
  month: number
  day: number
  date: Date
  isCurrentMonth: boolean
  isToday: boolean
  isSelected: boolean
  isDisabled?: boolean
  events?: CalendarEvent[]
}

Available Components

CalendarComponent (Recommended)

Main component for reservations with optimized Nuxt integration.

Calendar

Reservation component with all advanced features.

SimpleCalendar

Simple monthly calendar for displaying events.

BaseCalendar

Flexible base component with slots for complete customization.

Component Events

CalendarComponent & Calendar

• reservation-click: Emitted when a reservation is clicked
• view-change: Emitted when the view changes (day/week)
• date-change: Emitted when the navigation date changes
• new-reservation: Emitted for a new reservation
• reservations-updated: Emitted when reservations are updated

SimpleCalendar & BaseCalendar

• date-select: Emitted when a date is selected
• month-change: Emitted when the month changes
• event-click: Emitted when an event is clicked

Advanced Customization

Using BaseCalendar with slots

<template>
  <BaseCalendar 
    :locale="locale"
    :theme="theme"
    :events="events"
    @date-select="onDateSelect"
  >
    <!-- Customize header -->
    <template #header="{ currentDate, navigation }">
      <div class="my-custom-header">
        <button @click="navigation.goToPreviousMonth">◀</button>
        <h3>{{ formatDate(currentDate) }}</h3>
        <button @click="navigation.goToNextMonth">▶</button>
      </div>
    </template>

    <!-- Customize day content -->
    <template #day-content="{ date, events }">
      <div class="my-day-content">
        <div class="my-events">
          <span v-for="event in events" :key="event.id" class="my-event">
            🎉 {{ event.title }}
          </span>
        </div>
      </div>
    </template>
  </BaseCalendar>
</template>

Development

# Install dependencies
npm install

# Generate type files
npm run dev:prepare

# Develop with playground
npm run dev

# Build the module
npm run build

# Run tests
npm run test

Contributing

Contributions are welcome! Please check our contributing guide.

License

MIT License