Nuxt Calendar

A powerful, production-ready calendar module for Nuxt 3 & 4 with comprehensive features for building modern calendar applications.

✨ Features

• 🎯 Strongly Typed - Full TypeScript support with comprehensive type definitions
• 🧩 Modular Architecture - Composable API design for maximum flexibility
• 🎨 Highly Customizable - Extensive configuration options for UI and behavior
• 🚀 Best DX - Auto-imported composables and components with full IDE support
• 🌍 Internationalization - Built-in i18n with date-fns locale support
• 🌐 Timezone Support - Full timezone handling with date-fns-tz
• 📅 ICS Export - Generate and download .ics files for calendar events
• 💾 Database Sync - Optional PostgreSQL integration via NuxtHub
• 🎯 Multiple Views - Day, week, and month calendar views
• ⚡ Performance - Optimized rendering with Vue 3 composition API
• 🎨 Nuxt UI Integration - Seamless integration with Nuxt UI components

📦 Installation

npx nuxi module add nuxt-calendar

Or install manually:

npm install nuxt-calendar
# or
pnpm add nuxt-calendar
# or
yarn add nuxt-calendar

🚀 Quick Start

Add the module to your nuxt.config.ts:

export default defineNuxtConfig({
  modules: ['nuxt-calendar'],
  
  NuxtCalendar: {
    // Optional configuration
    timeFormat: '24h',
    i18n: {
      locale: 'en',
      timezone: 'UTC',
      weekStartsOn: 1, // Monday
    },
    enableIcsExport: true,
    enableDatabaseSync: false,
  },
})

Use in your components:

<template>
  <NuxtCalendar 
    :events="events"
    :teams="teams"
    @event-click="handleEventClick"
  />
</template>

<script setup lang="ts">
const events = ref([
  {
    id: '1',
    title: 'Team Meeting',
    start: new Date('2024-01-15T10:00:00'),
    end: new Date('2024-01-15T11:00:00'),
    description: 'Weekly team sync',
    location: 'Conference Room A',
  },
])

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

📖 Configuration

Module Options

interface ModuleOptions {
  // License key for commercial features (optional)
  licenseKey?: string
  
  // Time format for display
  timeFormat?: '12h' | '24h'
  
  // Team/calendar configuration
  teams?: Team[]
  
  // Company branding
  company?: {
    name: string
    logo: string
  }
  
  // Internationalization settings
  i18n?: {
    locale: string           // 'en', 'nl', 'de', 'fr', etc.
    timezone: string         // IANA timezone identifier
    weekStartsOn: 0 | 1 | 2 | 3 | 4 | 5 | 6  // 0 = Sunday, 1 = Monday
  }
  
  // Enable ICS file export functionality
  enableIcsExport?: boolean
  
  // Enable database sync with NuxtHub
  enableDatabaseSync?: boolean
}

Default Configuration

{
  timeFormat: '24h',
  i18n: {
    locale: 'en',
    timezone: 'UTC',
    weekStartsOn: 1,
  },
  enableIcsExport: true,
  enableDatabaseSync: false,
}

🎯 Usage Examples

Basic Calendar

<template>
  <NuxtCalendar :events="events" />
</template>

<script setup lang="ts">
const events = ref([
  {
    id: '1',
    title: 'Meeting',
    start: new Date(),
    end: new Date(Date.now() + 3600000),
  },
])
</script>

With Teams

<template>
  <NuxtCalendar :events="events" :teams="teams" />
</template>

<script setup lang="ts">
const teams = ref([
  {
    id: 'dev-team',
    name: 'Development Team',
    members: [
      {
        id: 'user-1',
        name: 'John Doe',
        email: '[email protected]',
        color: {
          background: '#34D399',
          border: '#10B981',
        },
        visible: true,
      },
    ],
  },
])
</script>

ICS Export

<script setup lang="ts">
import { useCalendarIcs } from '#imports'

const { exportToIcs } = useCalendarIcs()

async function handleExport() {
  const result = await exportToIcs(events.value, 'my-calendar.ics')
  if (result.success) {
    console.log('Calendar exported successfully')
  }
}
</script>

Database Sync

First, enable database sync in your config:

// nuxt.config.ts
export default defineNuxtConfig({
  NuxtCalendar: {
    enableDatabaseSync: true,
  },
})

Then use the composable:

<script setup lang="ts">
import { useCalendarDatabase } from '#imports'

const { fetchEvents, createEvent, updateEvent, deleteEvent } = useCalendarDatabase()

// Fetch events from database
const { events } = await fetchEvents()

// Create a new event
await createEvent({
  id: '1',
  title: 'New Meeting',
  start: new Date(),
  end: new Date(Date.now() + 3600000),
})

// Update an event
await updateEvent('1', {
  title: 'Updated Meeting Title',
})

// Delete an event
await deleteEvent('1')
</script>

Timezone Support

<script setup lang="ts">
import { useCalendarI18n } from '#imports'

const { locale, timezone, formatDate, toLocalTimezone } = useCalendarI18n()

// Format date in configured timezone
const formattedDate = formatDate(new Date(), 'PPpp')

// Convert to local timezone
const localDate = toLocalTimezone(new Date())
</script>

🎨 Composables

useNuxtCalendarConfig()

Access the calendar configuration:

const config = useNuxtCalendarConfig()
console.log(config.timeFormat) // '24h'
console.log(config.i18n.locale) // 'en'

useCalendarIcs()

Export calendar events to ICS format:

const { exportToIcs, exportToIcsServer } = useCalendarIcs()

// Client-side export (downloads file)
await exportToIcs(events, 'calendar.ics')

// Server-side export (returns ICS data)
const { data } = await exportToIcsServer(events)

useCalendarDatabase()

Sync calendar events with database:

const { fetchEvents, createEvent, updateEvent, deleteEvent } = useCalendarDatabase()

const result = await fetchEvents()
if (result.success) {
  console.log(result.events)
}

useCalendarI18n()

Handle internationalization and timezones:

const { locale, timezone, weekStartsOn, formatDate, toLocalTimezone } = useCalendarI18n()

const formatted = formatDate(new Date(), 'yyyy-MM-dd HH:mm')

useCalendarSlotHeight()

Manage calendar grid height:

const { hourHeight, getEventTop, getEventHeight } = useCalendarSlotHeight()

🌍 Supported Locales

The module supports all locales available in date-fns. Configure via:

NuxtCalendar: {
  i18n: {
    locale: 'en', // or 'nl', 'de', 'fr', 'es', 'it', 'pt', 'ja', 'zh', 'ko', 'ru', etc.
  },
}

🌐 Supported Timezones

Full IANA timezone database support including:

• UTC
• America/* (New_York, Los_Angeles, Chicago, etc.)
• Europe/* (London, Paris, Berlin, etc.)
• Asia/* (Tokyo, Shanghai, Dubai, etc.)
• Australia/* (Sydney, Melbourne, etc.)
• And many more...

📅 Event Types

interface CalendarEvent {
  id: string | number
  title: string
  start: Date
  end: Date
  description?: string
  location?: string
  organizer?: {
    name: string
    email: string
  }
  attendees?: Array<{
    name: string
    email: string
    rsvp?: boolean
  }>
  meetLink?: string
  category?: string
  teamMemberIds?: (string | number)[]
}

🔌 API Endpoints

When features are enabled, the module provides these endpoints:

ICS Export (enableIcsExport: true)

• POST /api/nuxt-calendar/export/ics - Generate ICS file from events

Database Sync (enableDatabaseSync: true)

• GET /api/nuxt-calendar/events - Fetch all events
• POST /api/nuxt-calendar/events - Create a new event
• PUT /api/nuxt-calendar/events/:id - Update an event
• DELETE /api/nuxt-calendar/events/:id - Delete an event

🎯 TypeScript Support

The module is fully typed with comprehensive TypeScript definitions. All types are auto-imported:

import type { 
  CalendarEvent,
  Team,
  TeamMember,
  View,
  SlotHeightConfig,
  NuxtCalendarPublicConfig,
} from '#imports'

🤝 Contributing

Contributions are welcome! Please see the repository for more details.

📄 License

MIT License