Skeleton

What is Skeleton

Skeleton is a command line interface (CLI) designed to facilitate the development of widgets on the Kommo platform. Automates the configuration, deployment and documentation process, generating a basic project structure (skeleton) with React, TypeScript, and other modern technologies.

• It allows you to create custom widgets quickly
• Includes typing, documentation and localization options
• It improves the developer experience by reducing bugs and development time

Why to use?

Skeleton solves the main problems that developers face when working with widgets in Kommo:

• Difficulty setting up development environments and deploying widgets
• Need for customization and scalability

Advantages:

• It accelerates development
• It improves the quality of the code
• Reduces errors
• Reduces the burden on the support team

Logic of work

These interactive prompts ensure your widget’s configuration and manifest are correctly set up.

List of locations

This table lists every location where a widget can live inside Kommo:

The locations array in manifest.json determines where—and how—users will see your widget.

Extra properties for the Manifest

This table maps each special location to the JSON block you must add in manifest.json:

❗️

Include only the blocks that match the locations you selected—otherwise Kommo will reject the manifest

Project Structure

TypeScript Typing:

• Widget lifecycle methods (init(), render(), settings()...)
• Internal methods (get_settings(), etc.)
• APP variable for interacting with Kommo’s API

Minimum structure

Enabling Development Mode After Uploading the Widget Archive

Step 1: Configure Environment

Before starting development or building the production widget, fill in the required environment variables. The project includes two predefined environment files:

• .dev.env — used in development
• .prod.env — used during the production build

Update these files with appropriate values.

🚧

Never commit these files with real secrets to version control. Use environment-specific secret management in CI/CD for deployment.

Step 2: Development

Option A: With Docker & Make

Generate a production-ready ZIP bundle:

make build

Option B: Locally with yarn

You can also build without Docker:

yarn install
yarn run build

This will create a dist folder with your build script, manifest etc. and zip archive.

Step 3: Build

Option A: With Docker

Bring up the dev server with one command:

make run-dev

Option B: Locally with yarn

You can also run the dev server without Docker:

yarn install
yarn run dev

Step 4: Enabling Development Mode After Uploading the Widget Archive

To enable dev mode after uploading the widget.zip archive, follow these steps:

1. Ensure the correct port and widget code are set in your environment variables. In your .dev.env and .prod.env file, make sure the following are properly configured:
   1. LOCALHOST_PORT — This should match the port your local development server is running on (e.g., 9000).
   2. INTEGRATION_CODE — This should be the code specific to your widget. You can find it in the Key and Scopes tab after creating an integration.
2. Enable dev mode by adding the following to localStorage in the client's browser. You can do this by opening the browser's developer console and entering the following command:

localStorage.setItem('your_widget_code_is_dev', '9000');

Use the same port as LOCALHOST_PORT and the same widget code as INTEGRATION_CODE in .env files.

Alternatively, you can manually add the localStorage entry in the browser's storage if needed.

Once done, the widget will load resources from your local dev server when in dev mode, allowing you to test without having to re-upload the widget archive every time.

Links