Desktop calendar app for Microsoft 365 Exchange Online built with Electron.
- Microsoft sign-in via
@azure/msal-nodewith encrypted token cache - Multi-account support with calendar selection and custom colors
- Full event CRUD with drag-and-drop move/resize
- Optional physical-location autocomplete and map previews powered by Photon / OpenStreetMap, without an API key
- Meeting responses (accept/tentative/decline)
- Participant free/busy indicators when creating meetings, refreshed as attendees or times change
- Local SQLite cache with configurable periodic sync
- Desktop reminder popup with snooze/dismiss and meeting join
- In-app invitation popups on Windows and macOS, including new invitations synced at startup; popup and system notification preferences are independent in Settings > Notifications
- System tray integration
- React 19 renderer with month/week/day views and mini calendar
- Internationalization (English/Italian)
- Update checks via GitHub Releases (stable/prerelease channels), with automatic installation on Windows and manual DMG installation on macOS
- Electron + electron-vite + TypeScript
- React 19 + FullCalendar + Zustand + TanStack Query
- better-sqlite3 (local cache), MSAL Node (auth), Microsoft Graph API
- Zod (validation), i18next (i18n), electron-updater (auto-updates)
- oxlint + oxfmt for linting/formatting, Vitest for testing, Husky for hooks
- Register a Microsoft Entra application for DefCalendar.
- Point
src/main/auth/app-registration.tsat your public-client app registration, or useMSAL_CLIENT_IDonly as a development override. - Configure the app for accounts in any organizational directory.
- Enable the public client desktop/mobile flow.
- Under
Authentication > Add a platform, addMobile and desktop applicationswith the redirect URIhttp://localhost. - Grant delegated Microsoft Graph permissions:
openid,profile,offline_accessUser.Read,User.ReadBasic.All,Calendars.ReadWrite,MailboxSettings.Read,Contacts.Read,People.Read
- Use
.env.examplefor optional development overrides; packaged end users should use the bundled app registration. - For tenant-specific development, override
MSAL_AUTHORITY.
npm run dev— Start development servernpm run build— Compile main, preload, and renderer intoout/npm run lint— Run oxlintnpm run lint:fix— Apply oxlint autofixesnpm run format— Format code with oxfmtnpm run format:check— Check formatting without changesnpm run test— Run Vitest suitenpm run test:watch— Run tests in watch modenpm run package— Create unpacked distributablenpm run dist— Create installer artifacts with electron-buildernpm run dist:publish— Create installer artifacts and publish a GitHub Release
Pushing a v* tag matching package.json builds Windows and macOS assets in parallel. The workflow checks the installers, blockmaps, and update manifests before uploading them and publishing the GitHub Release with generated notes. Pull requests that change the release workflow or its asset verifier run the packaging checks and attach the verified files to the Actions run.
- Windows: NSIS installer.
- macOS: universal DMG and ZIP containing both Intel (
x64) and Apple Silicon (arm64) binaries, plus update metadata. The workflow checks both architectures in the app executable and the native SQLite module before publishing the release. - To build the macOS artifacts locally on a Mac without a Developer ID certificate, run
npm run dist -- --mac --universal -c.mac.identity=- -c.mac.notarize=false. The ad-hoc signature is required for native notifications. With signing credentials configured, usenpm run dist -- --mac --universal.
For Developer ID signing and notarization, configure the repository Actions secrets MAC_CSC_LINK (base64-encoded .p12 certificate), MAC_CSC_KEY_PASSWORD, APPLE_ID, APPLE_APP_SPECIFIC_PASSWORD, and APPLE_TEAM_ID. Without these credentials, the workflow still builds macOS artifacts, but they are not Developer ID signed or notarized; normal Gatekeeper distribution and macOS auto-updates require signing. See the electron-builder macOS signing documentation.
DefCalendar encrypts its Microsoft sign-in token cache with Electron safeStorage, whose encryption key is protected by the macOS login keychain. On the system access prompt, choose Always Allow (Consenti sempre) to remember permission for the installed app. Allow Once grants access only for that request and can cause another prompt on the next launch. See Apple's Keychain access instructions.
Install DefCalendar in /Applications or ~/Applications and launch that installed copy. Ad-hoc signed releases can require permission again after an update because their signing identity changes. To preserve the app identity across releases, configure the Developer ID signing secrets above and keep using a consistent signing identity. When a certificate is supplied, the release workflow verifies that the built app has an Apple-issued Developer ID Application signature before making the release public. Development, App Store distribution, self-signed, and ad-hoc signatures fail this check. Releases built without a certificate retain the explicit ad-hoc path and warning. See Electron's code-signing requirements for Keychain access and Apple's code-signing requirements.
The app cannot grant itself persistent Keychain permission. If prompts continue after choosing Always Allow, check the login keychain's lock settings and the installed app's access in Keychain Access. Keep the existing Safe Storage keychain item: deleting it makes the saved token cache unreadable and requires signing in again.
The app uses a DMG-based installation flow on macOS. From either the update popup or Settings, the download action retrieves and verifies the detected version's universal DMG, then quits DefCalendar and opens the disk image. Replace the app in /Applications or ~/Applications without deleting application data. A helper waits for the selected version with a valid code signature and relaunches the installed copy after replacement. The changelog link opens the GitHub release page. Older installations showing Code signature ... did not pass validation can recover by downloading the universal DMG from GitHub and replacing the app manually. Configuring Developer ID signing credentials alone does not switch the app to Squirrel.Mac automatic installation; that mode must be enabled and tested separately after migrating existing installations to a compatible signing identity.
- Targets Microsoft 365 work/school accounts only.
- Locations are plain text by default, including online meeting names. Use the icon selector to the left of the location field to switch from Location to Map for address suggestions and a small OpenStreetMap area preview. Hovering or focusing the preview reveals the link icon; clicking opens Google Maps. The physical-location choice and selected coordinates are saved locally for each event and retained through synchronization while the address remains unchanged. Map previews load only the visible tiles through Electron's HTTP cache, with an identifying DefCalendar User-Agent; no API key is required.
- Location suggestions use the public Photon API. Searches send only the typed location to Photon after at least three characters and a 500 ms pause. Requests run in the main process, are limited to one per second, and results are cached in memory for five minutes. Returning to a cached query displays results immediately; switching away from the app preserves the open popup and pending search. Previous suggestions remain visible but cannot be selected while a new search is pending. Italian uses local place names; English requests translated names. Street addresses with house numbers use structured searches and exclude conflicting streets or house numbers. When Photon only knows the street, suggestions retain the entered number and explicitly mark it as unverified. The public service permits moderate usage, may throttle requests, and has no availability guarantee. Manual locations remain available when offline or when no result matches. Map data is attributed to OpenStreetMap contributors.
- Participant profile photos use delegated
User.ReadBasic.Allto read other organizational users' basic profiles, including photos, andContacts.Readfor personal contact photos. See the Microsoft Graph photo permissions. When upgrading an existing Entra app registration, addUser.ReadBasic.Allto its delegated permissions and sign in again to grant the additional consent. Tenant consent policies may require administrator approval. IfGRAPH_SCOPESis overridden, includeUser.ReadBasic.Allthere as well; photos without sufficient permission retain initials. - Participant availability uses Microsoft Graph
getSchedulewith the existing delegatedCalendars.ReadWritepermission; no additional Microsoft 365 consent is required. Exchange calendar sharing and free/busy policies determine which schedules the signed-in account can see. Inaccessible or external mailboxes may show availability as unknown, never as free. Only availability is sent to the UI, without event titles or details. Recurring meetings check the selected time range only. AADSTS500113means the Entra app registration is missing the localhost redirect or public client flows are disabled.- Shared/delegate calendars are not implemented.
- Recurring events and attendee-managed meetings are shown but edited as read-only, with an Outlook handoff.
- Build Windows installers on native Windows or CI (WSL2 is not suitable).
- Updates use GitHub Releases and are user-initiated from the update popup or
Settings > About. - Publishing updates requires a
GH_TOKENwith repository release permissions.