Pulse App

Pulse App Developer Guide

What Is a Pulse App?

A Pulse App is a module-federated, full-stack React extension that can run standalone or integrate into the Pulse Editor platform. Pulse Editor acts primarily as a hosting environment for these modular apps.

Project Structure

my-pulse-app/
├── pulse.config.ts          # App metadata & Pulse Editor configuration
├── package.json
├── tsconfig.json
├── src/
│   ├── main.tsx             # Frontend entry point (React UI)
│   ├── tailwind.css
│   ├── server-function/     # Backend endpoints (file path = URL path)
│   │   └── echo.ts          # → POST /server-function/echo
│   └── skill/               # Agentic skills (AI-callable actions)
│       └── example-skill/
│           ├── SKILL.md     # Skill definition (Anthropic YAML frontmatter format)
│           └── action.ts    # Action handler (default export function)

Quick Start

1. Create a new Pulse App

pulse create

2. Start development server

npm run dev
# Hosts at http://localhost:3030
# Register in Pulse Editor → Settings

3. Preview in browser (no editor integration)

npm run preview
# Note: Inter-Module-Communication features won't work in preview mode

4. Build

npm run build          # Full build (client + server)
npm run build-client   # Frontend only
npm run build-server   # Backend only

Frontend: src/main.tsx

The single React entry point rendered by Pulse Editor as an extension UI. Uses Tailwind CSS for styling.

Key hooks from @pulse-editor/react-api

import { useLoading, useActionEffect } from "@pulse-editor/react-api";

// useLoading — manage loading states
const { isLoading, setLoading } = useLoading();

// useActionEffect — register a handler for an app action
useActionEffect("mySkillName", {
  beforeAction: (input) => {
    setLoading(true);
    return input; // optionally transform input
  },
  afterAction: (output) => {
    setLoading(false);
    console.log("Action completed:", output);
  },
});

Calling a server function from the frontend

const response = await fetch("/server-function/echo", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ message: "hello" }),
});
const data = await response.json();

Backend: src/server-function/

Files in this directory are automatically mapped to HTTP endpoints:

Example server function

// src/server-function/echo.ts
import { Request, Response } from "express";

export default async function handler(req: Request, res: Response) {
  const { message } = req.body;
  res.json({ echo: message });
}

Skills: src/skill/

Skills are agentic capabilities — actions callable by AI agents, frontend components via useActionEffect, or Pulse Editor's automation platform.

Each skill lives in its own subdirectory with two files:

SKILL.md — Skill definition (Anthropic YAML frontmatter format)

---
name: mySkill
description: Brief description of what this skill does
---

# My Skill

Longer description for the AI agent about when and how to use this skill.

action.ts — Action handler

// src/skill/my-skill/action.ts

type Input = {
  /** The main text to process */
  text: string;
  /** Optional count parameter */
  count?: number;
};

type Output = {
  result: string;
  processedCount: number;
};

/**
 * Default export is the action handler.
 * Input/Output types + JSDoc comments are used for AI agent documentation.
 */
export default function mySkill({ text, count = 1 }: Input): Output {
  return {
    result: text.repeat(count),
    processedCount: count,
  };
}

Create a new skill with the CLI

pulse skill create

App Configuration: pulse.config.ts

import { AppConfig } from "@pulse-editor/shared-utils";
import pkg from "./package.json";

const config: AppConfig = {
  id: pkg.name,           // Must match package name — NO hyphens
  version: pkg.version,
  libVersion: pkg.dependencies["@pulse-editor/react-api"],
  displayName: pkg.displayName,
  description: pkg.description,
  visibility: "unlisted", // or "public"
  recommendedHeight: 640,
  recommendedWidth: 360,
  thumbnail: "./src/assets/thumbnail.png",
};

export default config;

Important: The id field must not contain hyphens. Use underscores or camelCase instead.

Key Concepts

App Actions

App Actions are the primary integration mechanism in Pulse Apps. They:

• Are defined by a skill's action.ts default export
• Are callable by AI agents (via SKILL.md definition)
• Are callable from the frontend UI (via useActionEffect)
• Are callable from external services via a dedicated API endpoint

beforeAction / afterAction Pipeline

These work like middleware around action execution:

• beforeAction(input) — runs before the action; return value becomes the action's input (use for UI state setup, input transformation)
• afterAction(output) — runs after the action completes (use for UI state teardown, handling results)

Common Patterns

Loading state around an action

const { isLoading, setLoading } = useLoading();

useActionEffect("processData", {
  beforeAction: (input) => { setLoading(true); return input; },
  afterAction: (output) => {
    setLoading(false);
    setResult(output.result);
  },
});

Server function with environment variables

// src/server-function/my-api.ts
import "dotenv/config";

export default async function handler(req, res) {
  const apiKey = process.env.MY_API_KEY;
  // ...
}

Limitations

• Single entry point only — multi-page apps are not yet supported
• Inter-Module-Communication (IMC) features require running in Pulse Editor (npm run dev), not preview mode

Resources

• Template repo: https://github.com/claypulse/pulse-app-template
• @pulse-editor/react-api — React hooks for Pulse Editor integration
• @pulse-editor/shared-utils — Shared types including AppConfig
• Pulse Editor CLI: pulse create, pulse skill create