Search…
Building apps
Since Cal.com is open source we encourage developers to create new apps for others to use. This guide is to help you get started.

Structure

All apps can be found under packages/app-store. In this folder is _example which shows the general structure of an app.
1
├──_example
2
|
3
| ├──api
4
| | ├──example.ts
5
| | ├──index.ts
6
|
7
| ├──components
8
| | ├──InstallAppButton.tsx
9
| | ├──index.ts
10
|
11
| ├──lib
12
| | ├──adaptor.ts
13
| | ├──index.ts
14
|
15
| ├──static
16
| | ├──icon.svg
17
|
18
| ├──index.ts
19
| ├──package.json
20
| ├──.env.example
21
| ├──README.mdx
Copied!

Getting Started

In the package.json name your package appropriately and list the dependencies needed for the package.
Next in the .env.example specify the environmental variables (ex. auth token, API secrets) that your app will need. In a comment add a link to instructions on how to obtain the credentials. Create a .env with your the filled in environmental variables.
In index.js fill out the meta data that will be rendered on the app page. Under packages/app-store/index.ts, import your app and add it under appStore. Your app should now appear in the app store.
Under the /api folder, this is where any API calls that are associated with your app will be handled. Since cal.com uses Next.js we use dynamic API routes. In this example if we want to hit /api/example.ts the route would be {BASE_URL}/api/integrations/_example/example. Export your endpoints in an index.ts file under /api folder and import them in your main index.ts file.
Under the /components folder, this is where the install button for your app should live. Follow the template under _example to add your on click action (ex. Redirecting to a log in page or opening a modal).
The /lib folder is where the functions of your app live. For example, when creating a booking with a MS Teams link the function to make the call to grab the link lives in the /lib folder. Export your endpoints in an index.ts file under /lib folder and import them in your main index.ts file.
On the app store page you can customize your apps description by adding a markdown file called README.mdx. If you do not add one then the description from you package.json will be used instead.
The /static folder is where you can store your app icon and any images that your README.mdx may use.

Adding Your App to the App Store

To render your app on the app store page, go to packages/app-store/index.ts. Import your app into the file and add it to the appStore object.
Under packages/app-store/components.tsx, in the InstallAppButtonMap object dynamically import your install button. Your install button should live under {your_app}/components.
If you need any help feel free to join us on Slack