Getting Started

What are Patches?

Patches are JavaScript programs anyone can create and share on the Sup platform. Each patch is structured around a main() function and globally available sup object, providing access to various chat features and APIs.

---

Your First Patch

Let’s create a simple patch that welcomes users by their username:

function main() {
  return `sup, ${sup.user.username}!`;
}

Copy this code into the code editor and click “Preview” to see it in action. Clicking Save will publish the patch so anyone else on Sup can immediately start using it.

---

Understanding the Basics

The main() Function

Every patch must have a main() function. This is the entry point of your patch and determines what gets displayed in the chat. Your main() function can return:

• A simple string
• Images, audio, or video
• Buttons for user interaction
• An array with multiple elements

Learn more about main()

Working with User Input

Patches can process user input in various ways. Here’s a simple example that echoes back what the user types:

function main() {
  if (!sup.input.text) return "Type something and I'll echo it back!";
  return `You said: ${sup.input.text}`;
}

Learn more about sup.input

Creating Interactive Elements

You can make your patches interactive using buttons:

function main() {
  const isButtonClicked = sup.message.get("clicked") || false;

  if (isButtonClicked) return "Clicked!";
  else return sup.button("Click me!", handleClick);
}

function handleClick(e) {
  sup.message.set("clicked", true);
}

Learn more about adding interactivity

Simplifying Configuration

It’s a best practice to define configurable values as constants at the top of your file. These will automatically become editable with simple UIs in the code editor, so other users can easily customize the patch:

// Configurable values
const GREETING_MESSAGE = "Sup";
const SHOW_USERNAME = true;
const EMOJI = "👋";

function main() {
  if (SHOW_USERNAME) return `${GREETING_MESSAGE} ${sup.user.username} ${EMOJI}`;
  else return `${GREETING_MESSAGE} ${EMOJI}`;
}

Storing and Retrieving State

Patches can maintain state across interactions:

function main() {
  // Get current count
  const count = sup.user.get("click_count") || 0;

  // Return the count and a button
  return [
    `The button has been clicked ${count} times`,
    sup.button("Add Click", handleClick),
  ];
}

function handleClick(e) {
  // Increment count
  let count = sup.user.get("click_count") || 0;
  count++;
  sup.user.set("click_count", count);
}

State can be scoped in a number ways:

• Chat state: sup.set / sup.get
• Message state: sup.message.set / sup.message.get
• User state: sup.user.set / sup.user.get
• Global state: sup.global.set / sup.global.get

Learn more about working with state

Using AI Features

Patches can leverage AI capabilities for various tasks:

function main() {
  if (!sup.input.text)
    return "Share some text and I'll write a haiku about it!";
  return sup.ai.promptWithContext("Write a haiku about this.");
}

Learn more about integrating AI

---

Best Practices

1. Input Validation: Always check if required input exists before processing
2. Error Handling: Provide friendly messages when something goes wrong
3. Configuration: Place configurable values at the top of the file as constants
4. Documentation: Add comments to explain complex logic or configuration options
5. Modularity: Break down complex patches into smaller functions for better maintainability

---