πŸš€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 clone https://github.com/Airstack-xyz/farcaster-cast-actions-starter.git

Manual Installation

Step 1: Install Dependencies & Environment Variables

To get started, simply install all the necessary dependencies:

npm 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:

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:

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


app.hono.post("/gm", async (c) => {
  const body = await c.req.json();

  // validate the POST body
  const { isValid, message } = await validateFramesMessage(body);
  const interactorFid = message?.data?.fid;
  const castFid = message?.data.frameActionBody.castId?.fid as number;
  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 run dev

Then, you can access the cast actions by making POST request to the http://localhost:5173/api/gm.

πŸ₯³ 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 i @vercel/kv

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

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);
}

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 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 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.

KeyValue

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:

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

Last updated