- Notifications
You must be signed in to change notification settings - Fork157
iCalendar (ics) file generator for node.js
License
NotificationsYou must be signed in to change notification settings
adamgibbons/ics
Folders and files
| Name | Name | Last commit message | Last commit date | |
|---|---|---|---|---|
Repository files navigation
TheiCalendar generator
npm install -S ics
- Create an iCalendar event:
constics=require('ics')// or, in ESM: import * as ics from 'ics'constevent={start:[2018,5,30,6,30],duration:{hours:6,minutes:30},title:'Bolder Boulder',description:'Annual 10-kilometer run in Boulder, Colorado',location:'Folsom Field, University of Colorado (finish line)',url:'http://www.bolderboulder.com/',geo:{lat:40.0095,lon:105.2669},categories:['10k races','Memorial Day Weekend','Boulder CO'],status:'CONFIRMED',busyStatus:'BUSY',organizer:{name:'Admin',email:'Race@BolderBOULDER.com'},attendees:[{name:'Adam Gibbons',email:'adam@example.com',rsvp:true,partstat:'ACCEPTED',role:'REQ-PARTICIPANT'},{name:'Brittany Seaton',email:'brittany@example2.org',dir:'https://linkedin.com/in/brittanyseaton',role:'OPT-PARTICIPANT'}]}ics.createEvent(event,(error,value)=>{if(error){console.log(error)return}console.log(value)})// BEGIN:VCALENDAR// VERSION:2.0// CALSCALE:GREGORIAN// PRODID:adamgibbons/ics// METHOD:PUBLISH// X-PUBLISHED-TTL:PT1H// BEGIN:VEVENT// UID:S8h0Vj7mTB74p9vt5pQzJ// SUMMARY:Bolder Boulder// DTSTAMP:20181017T204900Z// DTSTART:20180530T043000Z// DESCRIPTION:Annual 10-kilometer run in Boulder\, Colorado// X-MICROSOFT-CDO-BUSYSTATUS:BUSY// URL:http://www.bolderboulder.com/// GEO:40.0095;105.2669// LOCATION:Folsom Field, University of Colorado (finish line)// STATUS:CONFIRMED// CATEGORIES:10k races,Memorial Day Weekend,Boulder CO// ORGANIZER;CN=Admin:mailto:Race@BolderBOULDER.com// ATTENDEE;RSVP=TRUE;ROLE=REQ-PARTICIPANT;PARTSTAT=ACCEPTED;CN=Adam Gibbons:mailto:adam@example.com// ATTENDEE;RSVP=FALSE;ROLE=OPT-PARTICIPANT;DIR=https://linkedin.com/in/brittanyseaton;CN=Brittany// Seaton:mailto:brittany@example2.org// DURATION:PT6H30M// END:VEVENT// END:VCALENDAR
- Write an iCalendar file:
const{ writeFileSync}=require('fs')constics=require('ics')ics.createEvent({title:'Dinner',description:'Nightly thing I do',busyStatus:'FREE',start:[2018,1,15,6,30],duration:{minutes:50}},(error,value)=>{if(error){console.log(error)}writeFileSync(`${__dirname}/event.ics`,value)/*You cannot use fs in Frontend libraries like React so you rather import a module to save files to the browser as follow [ import { saveAs } from 'file-saver'; // For saving the file in the browser]const blob = new Blob([value], { type: 'text/calendar' }); saveAs(blob, `${title}.ics`);*/})
- Create multiple iCalendar events:
constics=require('./dist')const{ error, value}=ics.createEvents([{title:'Lunch',start:[2018,1,15,12,15],duration:{minutes:45}},{title:'Dinner',start:[2018,1,15,12,15],duration:{hours:1,minutes:30}}])if(error){console.log(error)return}console.log(value)// BEGIN:VCALENDAR// VERSION:2.0// CALSCALE:GREGORIAN// PRODID:adamgibbons/ics// METHOD:PUBLISH// X-PUBLISHED-TTL:PT1H// BEGIN:VEVENT// UID:pP83XzQPo5RlvjDCMIINs// SUMMARY:Lunch// DTSTAMP:20230917T142209Z// DTSTART:20180115T121500Z// DURATION:PT45M// END:VEVENT// BEGIN:VEVENT// UID:gy5vfUVv6wjyBeNkkFmBX// SUMMARY:Dinner// DTSTAMP:20230917T142209Z// DTSTART:20180115T121500Z// DURATION:PT1H30M// END:VEVENT// END:VCALENDAR
- Create iCalendar events with Audio (Mac):
letics=require("ics")letmoment=require("moment")letevents=[]letalarms=[]letstart=moment().format('YYYY-M-D-H-m').split("-").map((a)=>parseInt(a))letend=moment().add({'hours':2,"minutes":30}).format("YYYY-M-D-H-m").split("-").map((a)=>parseInt(a))alarms.push({action:'audio',description:'Reminder',trigger:{hours:2,minutes:30,before:true},repeat:2,attachType:'VALUE=URI',attach:'Glass'})letevent={productId:"myCalendarId",uid:"123"+"@ics.com",startOutputType:"local",start:start,end:end,title:"test here",alarms:alarms}events.push(event)console.log(ics.createEvents(events).value)// BEGIN:VCALENDAR// VERSION:2.0// CALSCALE:GREGORIAN// PRODID:myCalendarId// METHOD:PUBLISH// X-PUBLISHED-TTL:PT1H// BEGIN:VEVENT// UID:123@ics.com// SUMMARY:test here// DTSTAMP:20230917T142621Z// DTSTART:20230917T152600// DTEND:20230917T175600// BEGIN:VALARM// ACTION:AUDIO// REPEAT:2// DESCRIPTION:Reminder// ATTACH;VALUE=URI:Glass// TRIGGER:-PT2H30M\nEND:VALARM// END:VEVENT// END:VCALENDAR
import{createEvent}from'ics';constevent={ ...}asyncfunctionhandleDownload(){constfilename='ExampleEvent.ics'constfile=awaitnewPromise((resolve,reject)=>{createEvent(event,(error,value)=>{if(error){reject(error)}resolve(newFile([value],filename,{type:'text/calendar'}))})})consturl=URL.createObjectURL(file);// trying to assign the file URL to a window could cause cross-site// issues so this is a workaround using HTML5constanchor=document.createElement('a');anchor.href=url;anchor.download=filename;document.body.appendChild(anchor);anchor.click();document.body.removeChild(anchor);URL.revokeObjectURL(url);}
Generates an iCal-compliant VCALENDAR string with one VEVENT.If a callback is not provided, returns an object having the form{ error, value },wherevalue contains an iCal-compliant string if there are no errors.If a callback is provided, returns a Node-style callback.
Object literal containing event information.Only thestart property is required.
Note all date/time fields can be the array form, or a number representing the unix timestamp in milliseconds (e.g.getTime() on aDate).
The following properties are accepted:
| Property | Description | Example |
|---|---|---|
| start | Required. Date and time at which the event begins. | [2000, 1, 5, 10, 0] (January 5, 2000) or anumber |
| startInputType | Type of the date/time data instart:local (default): passed data is in local time.utc: passed data is UTC | |
| startOutputType | Format of the start date/time in the output:utc (default): the start date will be sent in UTC format.local: the start date will be sent as "floating" (form #1 inRFC 5545) | |
| end | Time at which event ends.Eitherend orduration is required, butnot both. | [2000, 1, 5, 13, 5] (January 5, 2000 at 1pm) or anumber |
| endInputType | Type of the date/time data inend:local: passed data is in local time.utc: passed data is UTC.The default is the value of startInputType | |
| endOutputType | Format of the start date/time in the output:utc: the start date will be sent in UTC format.local: the start date will be sent as "floating" (form #1 inRFC 5545).The default is the value of startOutputType | |
| duration | How long the event lasts. Object literal having form{ weeks, days, hours, minutes, seconds }Eitherend orduration is required, butnot both. | { hours: 1, minutes: 45 } (1 hour and 45 minutes) |
| title | Title of event. | 'Code review' |
| description | Description of event. | 'A constructive roasting of those seeking to merge into master branch' |
| location | Intended venue | Mountain Sun Pub and Brewery |
| geo | Geographic coordinates (lat/lon) | { lat: 38.9072, lon: 77.0369 } |
| url | URL associated with event | 'http://www.mountainsunpub.com/' |
| status | Three statuses are allowed:TENTATIVE,CONFIRMED,CANCELLED | CONFIRMED |
| organizer | Person organizing the event | { name: 'Adam Gibbons', email: 'adam@example.com', dir: 'https://linkedin.com/in/adamgibbons', sentBy: 'test@example.com' } |
| attendees | Persons invited to the event | [{ name: 'Mo', email: 'mo@foo.com', rsvp: true }, { name: 'Bo', email: 'bo@bar.biz', dir: 'https://twitter.com/bo1234', partstat: 'ACCEPTED', role: 'REQ-PARTICIPANT' }] |
| categories | Categories associated with the event | ['hacknight', 'stout month'] |
| alarms | Alerts that can be set to trigger before, during, or after the event. The followingattach properties work on Mac OS: Basso, Blow, Bottle, Frog, Funk, Glass, Hero, Morse, Ping, Pop, Purr, Sousumi, Submarine, Tink | { action: 'display', description: 'Reminder', trigger: [2000, 1, 4, 18, 30] } OR{ action: 'display', description: 'Reminder', trigger: { hours: 2, minutes: 30, before: true } } OR{ action: 'display', description: 'Reminder', trigger: { hours: 2, minutes: 30, before: false } OR{ action: 'audio', description: 'Reminder', trigger: { hours: 2, minutes: 30, before: true }, repeat: 2, attachType: 'VALUE=URI', attach: 'Glass' } |
| productId | Product which created ics,PRODID field | 'adamgibbons/ics' |
| uid | Universal unique id for event, produced by default withnanoid.Warning: This value must beglobally unique. It is recommended that it follow theRFC 822 addr-spec (i.e.localpart@domain). Including the@domain half is a good way to ensure uniqueness. | 'LZfXLFzPPR4NNrgjlWDxn' |
| method | This property defines the iCalendar object method associated with the calendar object. When used in a MIME message entity, the value of this property MUST be the same as the Content-Type "method" parameter value. If either the "METHOD" property or the Content-Type "method" parameter is specified, then the other MUST also be specified. | PUBLISH |
| recurrenceRule | A recurrence rule, commonly referred to as an RRULE, defines the repeat pattern or rule for to-dos, journal entries and events. If specified, RRULE can be used to compute the recurrence set (the complete set of recurrence instances in a calendar component). You can use a generator like thisone. | FREQ=DAILY |
| exclusionDates | Array of date-time exceptions for recurring events, to-dos, journal entries, or time zone definitions. | [[2000, 1, 5, 10, 0], [2000, 2, 5, 10, 0]] OR[1694941727477, 1694945327477] |
| sequence | For sending an update for an event (with the same uid), defines the revision sequence number. | 2 |
| busyStatus | Used to specify busy status for Microsoft applications, like Outlook. SeeMicrosoft spec. | 'BUSY' OR'FREE' OR'TENTATIVE' OR'OOF' |
| transp | Used to specify event transparency (does event consume actual time of an individual). Used by Google Calendar to determine if event should change attendees availability to 'Busy' or not. | 'TRANSPARENT' OR'OPAQUE' |
| classification | This property defines the access classification for a calendar component. SeeiCalender spec. | 'PUBLIC' OR'PRIVATE' OR'CONFIDENTIAL' OR any non-standard string |
| created | Date-time representing event's creation date. Provide a date-time in local time | [2000, 1, 5, 10, 0] or anumber |
| lastModified | Date-time representing date when event was last modified. Provide a date-time in local time | [2000, 1, 5, 10, 0] or anumber |
| calName | Specifies thecalendar (not event) name. Used by Apple iCal and Microsoft Outlook; seeOpen Specification | 'Example Calendar' |
| htmlContent | Used to include HTML markup in an event's description. Standard DESCRIPTION tag should contain non-HTML version. | <!DOCTYPE html><html><body><p>This is<br>test<br>html code.</p></body></html> |
To create anall-day event, pass only three values (year,month, anddate) to thestart andend properties.The date of theend property should be the dayafter your all-day event.For example, in order to create an all-day event occuring on October 15, 2018:
consteventAttributes={start:[2018,10,15],end:[2018,10,16],/* rest of attributes */}
Optional.Node-style callback.
function(err,value){if(err){// if iCal generation fails, err is an object containing the reason// if iCal generation succeeds, err is null}console.log(value)// iCal-compliant text string}
Generates an iCal-compliant VCALENDAR string with multiple VEVENTS.
headerParams may be omitted, and in this case they will be read from the first event.
If a callback is not provided, returns an object having the form{ error, value }, where value is an iCal-compliant text stringiferror isnull.
If a callback is provided, returns a Node-style callback.
Array ofattributes objects (as described increateEvent).
Optional.Node-style callback.
function(err,value){if(err){// if iCal generation fails, err is an object containing the reason// if iCal generation succeeds, err is null}console.log(value)// iCal-compliant text string}
Run mocha tests and watch for changes:
npm startRun tests once and exit:
npm testBuild the project, compiling all ES6 files within thesrc directory into vanilla JavaScript in thedist directory.
npm run buildAbout
iCalendar (ics) file generator for node.js
Topics
Resources
License
Stars
Watchers
Forks
Packages0
No packages published