🚀Quickstart

Learn how to quickly build your first Farcaster Cast Actions using Airstack Frog Recipes in Node.js.

In this tutorial, you will learn how to create a simple upthumbed-like cast action called GM, where with each click you "GM" a person.

You have the option to directly clone the project through automatic installation or manually follow it step-by-step through manual installation.

Automatic Installation

You can find the Airstack Farcaster Cast Actions Starter Code using Airstack Frog Recipes in our GitHub here.

To clone the repository, run the following command:

Git (HTTPS)

git clone https://github.com/Airstack-xyz/farcaster-cast-actions-starter.git

Git (SSH)

git clone [e-mail]:Airstack-xyz/farcaster-cast-actions-starter.git

GitHub CLI

gh repo clone Airstack-xyz/farcaster-cast-actions-starter

Manual Installation

Step 1: Install Dependencies & Environment Variables

To get started, simply install all the necessary dependencies:

npm

npm install @airstack/frog hono dotenv

yarn

yarn add @airstack/frog hono dotenv

pnpm

pnpm install @airstack/frog hono dotenv

bun

bun install @airstack/frog hono dotenv

Then, get your Airstack API key and add it as an environment variable:

.env.local

AIRSTACK_API_KEY=YOUR_API_KEY

Step 2: Build Your 1st Cast Actions

To create your 1st Farcaster cast actions, create a new file index.tsx under api folder and add the following code to create a new Frog instance from @airstack/frog:

TypeScript

index.tsx

import { Frog } from "@airstack/frog";
import { devtools } from "@airstack/frog/dev";
import { serveStatic } from "@airstack/frog/serve-static";
import { handle } from "@airstack/frog/vercel";
import { config } from "dotenv";

config();

export const app = new Frog({
  apiKey: process.env.AIRSTACK_API_KEY as string,
  basePath: "/api",
});

devtools(app, { serveStatic });

export const GET = handle(app);
export const POST = handle(app);

Once you have the Frog instance instantiated, define a POST route /gm that will be the post_url of your cast actions. For the cast action, you only need to return the message text in the 1st response (in JSON format) with the response status code in the 2nd response:

TypeScript

index.tsx

import {
  getFarcasterUserDetails,
  validateFramesMessage,
} from "@airstack/frog";

app.hono.post("/gm", async (c) => {
  // validate the POST body
  const { isValid, message } =
    process.env.NODE_ENV === "development"
      ? { isValid: true, message: {} }
      : await validateFramesMessage(await c.req.json?.());
  const interactorFid = message?.data?.fid ?? 0;
  const castFid = message?.data?.frameActionBody?.castId?.fid ?? 1;
  if (isValid) {
    // Check if trying to `GM` themselves
    if (interactorFid === castFid) {
      return c.json({ message: "Nice try." }, 400);
    }

    // Fetch user profile name
    const { data, error } = await getFarcasterUserDetails({
      fid: castFid,
    });

    if (error) {
      return c.json({ message: "Error. Try Again." }, 500);
    }

    let message = `GM ${data?.profileName}!`;
    if (message.length > 30) {
      message = "GM!";
    }

    return c.json({ message });
  } else {
    return c.json({ message: "Unauthorized" }, 401);
  }
});

Step 3: Configure TSConfig

Add the following fields into your tsconfig.json:

{
  "compilerOptions": {
    // Other configurations
    "jsx": "react-jsx",
    "jsxImportSource": "@airstack/frog/jsx",
  }
}

If you don't have tsconfig.json in your project, then run the following command first:

npx tsc --init

Run Development Server

Add dev script to your package.json as shown below:

package.json

{
  "scripts": { 
    "dev": "npx @airstack/frog dev",
  },
}

To start the development server, simply run one of the following command to run the dev script:

npm

npm run dev

yarn

yarn dev

pnpm

pnpm dev

bun

bun run dev

Then, you can access the cast actions by making POST request to the http://localhost:5173/api/gm. You can do this either by making a CURL POST request:

curl -X POST http://localhost:5173/api/gm

Or tunnel your local server through ngrok:

ngrok http 5173

and test your cast action with the Farcaster official cast action playground.

🥳 Congratulations, you've just built your 1st Farcaster Cast Actions using Airstack Frog Recipes!

Bonus: Deployment & Add Database

To keep track the number of time user GM someone, you can add a simple Redis DB to store the number. For this, Vercel provide Vercel KV that you can easily use in your project.

To use Vercel KV in your cast actions, install @vercel/kv as a dependency:

npm

npm i @vercel/kv

yarn

yarn add @vercel/kv

pnpm

pnpm install @vercel/kv

bun

bun install @vercel/kv

Then, add this gm function code to your project and import it to api/index.tsx:

lib/gm.ts

lib/gm.ts

import { createClient } from "@vercel/kv";
import { config } from "dotenv";

config();

export async function gm(fid: number) {
  const redis = createClient({
    url: process.env.KV_REST_API_URL as string,
    token: process.env.KV_REST_API_TOKEN as string,
  });
  const id = fid.toString();
  await redis.zincrby("gm", 1, id);
}

api/index.tsx

api/index.tsx

import { gm } from "../lib/gm.js";

app.hono.post("/gm", async (c) => {
  // same as code in previous steps
  if (isValid) {
    if (interactorFid === castFid) {
      return c.json({ message: "Nice try." }, 400);
    }

    await gm(castFid); // add this line
    // same as code in previous steps
    return c.json({ message });
  } else {
    return c.json({ message: "Unauthorized" }, 401);
  }
}

Once the code is added, you can have the database setup for your project. To setup a new KV database, you will first need to setup and deploy your project on Vercel.

To deploy, first add some of the following additional scripts to your package.json:

package.json

{
  "scripts": { 
    "build": "npx @airstack/frog vercel-build",
    "deploy": "vercel --prod",
    "deploy:preview": "vercel",
  },
}

Then, compile the poject by running the following command:

npm

npm run build

yarn

yarn build

pnpm

pnpm build

bun

bun run build

If run successfully, you should have a new .vercel folder generated. With this you can deploy the compiled build into Vercel by running:

Before running the command, make sure that you have vercel CLI within your machine and have it connected to your account by running vercel auth.

npm

npm run deploy

yarn

yarn deploy

pnpm

pnpm deploy

bun

bun run deploy

Once deployed successfully, you can go to the Vercel Dashboard to create a new Vercel KV database (follow steps here) have your Airstack API key added to your environment variables.

Key	Value
AIRSTACK_API_KEY	Your Airstack API key

Then, access the live Farcaster cast actions from a custom vercel link with the following format https://<CAST_ACTIONS_VERCEL_PROJECT>.vercel.app/api/gm, which you can use to test with the Farcaster official cast action playground.

🥳 Congratulations, you've just deployed your 1st Farcaster cast actions built usng Airstack Frog Recipes into Vercel!

Next Steps

Now that you have your 1st Farcaster cast actions running, you can also learn more on how to use Airstack Frog Recipes to build your 1st Farcaster Frame here to company your cast actions.

In addition, you can also check out all the Airstack features available in Airstack Frog Recipes to enrich your Farcaster cast actions or Farcaster Frames with various onchain data offered:

• Onchain Data

• Farcaster Hubs

• Allow List

Developer Support

If you have any questions or need help regarding integrating onchain data to your Farcaster cast actions using the Airstack Frog Recipe, please join our Airstack's Telegram group.

More Resources

• Farcaster Frames Quickstart

• Airstack Frog Recipes & Middleware

• Frog Framework