How to build an app

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.

You can create an app by simply running the following command. It creates a new directory under packages/app-store/``

yarn app-store create

You just need to provide a few inputs and then you will have your app created within a few seconds. See, how you can build a very simple app that greets your users.

Steps in creating an app

• Create the app using the create command
• The app can be installed now. But at this moment it isn't doing anything. It is just installed and ready to do what you want it to do.
• There is pretty much no restriction on what an App can do. Some of the examples are:
  • Hooking into existing functionalities to enhance them - In all these cases you need to first check if the app is installed or not. There is _useApp(appSlug)_ react hook to do that. It gives you the app details if the app is installed.
• Apps that need to connect with third parties like Google Calendar, Apple Calendar, Google Meet.
• A super powerful app that has its own data and pages - Routing Forms App is a great example of this.
• There are so many powerful apps already in the App Store for time. You can get an idea of what the apps can do from it.

Structure

All apps can be found under packages/app-store. In this folder is _baseApp which shows the general structure of an app.

├──_example
| ├──config.json -> Autogenerated by cli. You are free to edit it.
| ├──api
| | ├──add.ts -> Autogenerated by cli. You would want to edit it if your app needs to connect with a third party
|
| ├──components
|
| ├──static -> Add all static assets here
| | ├──icon.svg -> This is used as the logo for your App.

| ├──index.ts
| ├──package.json
| ├──.env.example -> Specify the environmental variables (ex. auth token, API secrets) that your app will need if it's applicable
| ├──README.mdx -> Customize your app description. You can add an image slider as well.

Other Commands

Deleting an app:

yarn app-store delete --slug APP_NAME

Editing an app:

yarn app-store edit --slug APP_NAME

Important Points

• Make sure to have yarn app-store:watch command running when developing an app so that autogenerated files are always up to date.

• If app-store cli fails at this step, try to run this command manually first. Solve that problem and then re-run cli. The command can fail because there are Prisma migrations that can't be applied automatically.

A sample failure in create command

• When you edit an app following things aren't updated.

  • README.mdx - It would still have the old description. Feel free to edit it manually.

Publishing Your App to the Cal.com App Store

Once your app is working in your environment, you can publish it to Cal.com App Store by opening a PR here.

If you need any help feel free to join us on Slack.