Skip to main content

Quick Start

Apps quick start​

Build your first Kittl app in about 2 minutes. When you want to sync that project with your app on Kittl (manifest, build output, review), use the official Kittl CLI.

What is a Kittl app?​

Kittl apps let developers expand Kittl's core editor functionality.

Apps are small packages users install through the app discovery panel in the editor. They can use the Kittl SDK to interact with the editor and perform actions like updating design content or uploading images on a user's behalf.

Examples of what you can build with Kittl apps:

  • Connectors to third-party systems like Google, Dropbox, and Shopify
  • Editor workflow automations
  • Custom AI image generation features

Local setup​

Install the Kittl CLI globally:

npm install -g @kittl/cli

Sign in from the terminal. Your browser opens; use your usual Kittl account.

kittl auth login

From the folder that will hold your project, initialize the app:

kittl app init

The CLI asks for an app name and which developer organization should own the app. You can pick an existing org or create a new one in the same flow.

When init succeeds, the directory is tied to a Kittl app draft (see .kittl/config.json in the Kittl CLI workflow).

Push manifest.json to your draft so the app shows up in the editor (including Developer apps):

kittl app update

Start the dev server (the Vite starter uses port 5173 by default):

npm run dev

In the editor at app.kittl.com, open Apps in the left sidebar. In the Developer apps tab, find your app, install it, then open it. Use the version control at the top of the panel and choose local development. The UI loads from your dev server with hot reload.

note

Local development uses your machine. The draft on Kittl may not show a working build until you kittl app upload (and run kittl app update again whenever you change manifest.json). See the Kittl CLI workflow.

Developing your app​

Kittl apps are built with HTML and JavaScript. Use any stack or bundler you like.

Project root: Keep manifest.json next to package.json. The layout below is only an example.

manifest.json
package.json
src/
  index.html
  icon.svg
  your-app-script-1.js
  your-app-script-2.js

Build output: Run whatever build step fits your repo so you get a directory of static files your entry HTML can load (scripts, images, and so on). When you sync with Kittl, Kittl CLI kittl app upload sends that directory to your draft. The default path is dist/; use the CLI’s --dist flag if your build writes somewhere else.

Manifest file​

The manifest JSON file lives at the project root and contains metadata for your app. This is where you provide details about the app and its developer, including the app name shown in the editor's app discovery panel.

See more info on manifest files.

note

Use the Kittl CLI: kittl app init ties this folder to a Kittl app (and may add starter files); kittl app update pushes manifest.json to your draft. If package.json already exists, init does not lay down the Vite starter but still ensures manifest.json exists when missing. See App init and starter scaffolding.

Index HTML​

Your index.html file is what loads in the app sandbox. You can build a functional Kittl app with only this file.

<!doctype html>
<html lang="en">
  <body>
    My Kittl app
  </body>
</html>

Using the Kittl SDK​

To interact with Kittl functionality, load the Kittl SDK. With this client-side JavaScript SDK, you can interact with design content, upload images, and connect to third-party OAuth-supported services.

TypeScript​

  • Recommended: Use pnpm add @kittl/sdk for both runtime and types; no need to duplicate types.
  • Script-tag only: Use the remote .d.ts URL. Most modern setups (TypeScript, Vite, esbuild, Deno) support types or /// <reference types="..." /> pointing to that URL.
  • Do not copy type definitions into your source. Use the package or the remote URL: https://static.kittl.com/sdk/staging/v0/sdk.d.ts

For a deeper dive into SDK capabilities, see the explainer and reference docs.

<!doctype html>
<html lang="en">
  <head>
    <script src="https://static.kittl.com/sdk/staging/v0/sdk.js"></script>
  </head>
  <body>
    My Kittl app
    <script src="./script.js"></script>
  </body>
</html>

The SDK script provides access to the global window.kittl variable. You can then use the Design API to interact with editor content.

The optional script.js file is a good place to keep your app logic. The createPredefinedShape method adds a shape to the canvas.

window.kittl.onReady(() => {
  window.kittl.design.shape.createPredefinedShape({
    shapeType: "ellipse",
    position: {
      absolute: {
        left: 100,
        top: 100
      }
    }
  });
});

Apps that need a backend​

Kittl apps follow a bring-your-own-backend model. You are free to build and deploy your backend however you prefer.

The app sandbox includes restrictions on remote requests. See the backend and networking docs for details.

Auth​

The SDK supports integration with popular OAuth-backed services, including Dropbox, Google, and Shopify. Providers you want to connect can be configured in your manifest file.

If your app needs OAuth, define providers in oauthProviders and use kittl.auth. See Authentication.

Previewing and testing​

Use the Kittl CLI to preview your app locally during development.

Distributing your apps​

Once your app is ready, use the Kittl CLI to upload and submit it for review.