📅 Add to Calendar

Create event links to add them to a calendar.

Supported services: Outlook, Office365, Google and Yahoo. You are also able to use ICalendar to create downloadable links to ics files.

🚀 Getting started

Install package:

npm install --save @barinbritva/add-to-calendar

Import entities:

import {Event, Outlook, Google, MultiGenerator} from '@barinbritva/add-to-calendar'

Create an event:

const event = new Event(
  'Meet with friends',
  new Date(2021, 5, 18, 15, 0),
  new Date(2021, 5, 18, 17, 0),
  'It\'s Bill\'s birthday today!',
  'Blue Bottle Coffee, 300 S Broadway, Los Angeles'
)

Create link by link:

const outlookLink = new Outlook().createLink(event)
const googleLink = new Google().createLink(event)

console.log(outlookLink, googleLink)

Create a bunch of links:

// Create generators you are going to use
// Key names doesn't matter, it's up to you
const generators = {
  outlook: new Outlook(),
  office365: new Office365(),
  google: new Google(),
  yahoo: new Yahoo(),
  ics: new ICalendar()
}

const multiGenerator = new MultiGenerator(generators)

// Object of keys/values - key => link
const linksObject = multiGenerator.createLinks(event)
// Array (tuple) of pairs key/link - [key, link][]
const array = multiGenerator.createLinks(event, true)

Create an ics attachment:

Method createLink is designed to create links for anchors:

const icsLink = new ICalendar().createLink(event)
return <a href=`${icsLink}`>Download ics file</a>

To create attachable ics files, use createFile method:

const icsFile = new ICalendar().createFile(event)
// letter is a pseudo variable, read a doc of library you are using to send emails
letter.attach(Buffer.from(icsFile))

💡 Guides

Working with Event

Read Event API to learn how to create, reschedule an event and manage its attendees.

Working with time zones

The best practice to avoid troubles with time zones is to create all dates in UTC time zone. add-to-calendar will convert date\time to UTC anyway and calendar services convert them to user local machine time zone.

Server

If a server works in UTC time zone, create dates as usual:

new Date(2021, 5, 18, 15, 0)

If a server is not set to UTC time zone, use Date.UTC method. Before doing that, calculate date\time relatively to UTC:

// if a server is in GMT+3 time zone,
// add 3 hours to desired date\time
// new Date(2021, 5, 18, 15, 0) -> new Date(2021, 5, 18, 15 + 3, 0)
new Date(Date.UTC(2021, 5, 18, 18, 0))

To calculate date\time in UTC automatically use a library for working with time zones, like date-fns-tz, or use the following approach:

const date = new Date(2021, 5, 18, 15, 0)
new Date(date.getTime() - date.getTimezoneOffset() * 60 * 1000)

Tips:

• To check if a server is set up to UTC time zone run new Date().getTimezoneOffset(). If the result is 0, everything is set up. If no, configure a server.
• To force node.js use UTC time zone without setting up server time, add TZ=UTC environment variable during an app launch, for example: TZ=UTC node index.js.

Client

On a client side, it's an option to use Date as usual:

new Date(2021, 5, 18, 15, 0)

But calendar services use time zone not from user local machine, but from user settings at the service.

For example, if a user is in GMT+3 time zone and uses Google Calendar, which is set up in GMT+3 time zone, everything will be OK. But if Google Calendar is set up in GMT+5, the date\time will be shifted by 2 hours.

To avoid this pitfall, use technics from the section about server side.

🔙 Feedback

Your feedback is really important for the project. Please, use contacts from my profile to send your questions, suggestions, help requests and others. Also, feel free to use issues section to report bugs and problems.

🌟 Credits

• Special thanks for information about calendar APIs to add-event-to-calendar-docs repo.
• The project is bootstrapped using init-typescript-app.

MIT, see LICENSE for the details.