Skip to content

Frog

Frog API Reference

Import

import { Frog } from 'frog'

Usage

import { Frog } from 'frog'
 
const app = new Frog({ title: 'Frog Frame' })

Constructor Parameters

basePath

  • Type: string

The base path for the server instance.

For instance, if you are deploying your server to Vercel Serverless, you probably want to specify /api.

import { Frog } from 'frog'
 
const app = new Frog({
  basePath: '/api',
  title: 'Frog Frame',
})

browserLocation

  • Type: string

Location (URL or path relative to basePath) to redirect to when the user is coming to the page via a browser.

For instance, a user may reach the frame page in their browser by clicking on the link beneath the frame on Warpcast. We may want to redirect them to a different page (ie. a mint page, etc) when they arrive via their browser.

Read more.

import { Frog } from 'frog'
 
const app = new Frog({
  basePath: '/api',
  browserLocation: '/:path',
  title: 'Frog Frame',
})

headers

  • Type: Record<string, string>

Default HTTP response headers to set for frames.

import { Frog } from 'frog'
 
const app = new Frog({
  headers: {
    'cache-control': 'max-age=0',
  },
  title: 'Frog Frame',
})

honoOptions

  • Type: HonoOptions

Options to forward to the Hono instance.

import { Frog } from 'frog'
 
const app = new Frog({
  honoOptions: {
    getPath: (req) => '/' + req.headers.get('host') + req.url.replace(/^https?:\/\/[^/]+(\/[^?]*)/, '$1'),
  },
  title: 'Frog Frame',
})

hub

  • Type: { apiUrl: string, fetchOptions?: RequestInit }

Farcaster Hub configuration.

import { Frog } from 'frog'
 
const app = new Frog({
  hub: {
    apiUrl: 'https://api.hub.wevm.dev'
  },
  title: 'Frog Frame',
})

Can also supply a built-in Hub configuration such as neynar.

import { Frog } from 'frog'
import { neynar } from 'frog/hubs'
 
const app = new Frog({
  hub: neynar({ apiKey: 'NEYNAR_FROG_FM' }),
  title: 'Frog Frame',
})

imageAspectRatio

  • Type: '1.91:1' | '1:1'

Aspect ratio clients should use to display images in frames.

import { Frog } from 'frog'
 
const app = new Frog({
  imageAspectRatio: '1:1',
  title: 'Frog Frame',
})

imageOptions

Image options to apply to frames.

Read more.

import { Frog } from 'frog'
 
const app = new Frog({
  imageOptions: {
    height: 600,
    width: 600,
  },
  title: 'Frog Frame',
})

initialState

Initial state for the frames.

import { Frog } from 'frog'
 
type State = {
  index: number
  todos: string[]
}
 
const app = new Frog<{ State: State }>({
  initialState: {
    index: 0,
    todos: []
  }
})
## Errors were thrown in the sample, but not included in an error tag These errors were not marked as being expected: 2345. Expected: // @errors: 2345 Compiler Errors: index.tsx [2345] 120 - Argument of type '{ initialState: { index: number; todos: never[]; }; }' is not assignable to parameter of type 'FrogConstructorParameters<{ State: State; }, "/", State>'. Property 'title' is missing in type '{ initialState: { index: number; todos: never[]; }; }' but required in type 'Required<Pick<FrameResponse, "title">>'.

origin

  • Type: string

Origin URL for the server instance.

import { Frog } from 'frog'
 
const app = new Frog({
  origin: 'https://sweetframe.com',
  title: 'Frog Frame',
})

secret

  • Type: string

Key used to sign secret data.

It is used for:

  • Signing frame state, and
  • Signing auth session cookies in the devtools.
src/index.ts
import { Frog } from 'frog'
 
const app = new Frog({
  secret: process.env.FROG_SECRET,
  title: 'Frog Frame',
})

verify

  • Type: boolean | "silent" | undefined
  • Default: true

Whether or not to verify frame data via the Farcaster Hub's validateMessage API.

  • When true, the frame will go through verification and throw an error if it fails.
  • When "silent", the frame will go through verification, but not throw an error if it fails. Instead, the frame will receive verified: false in its context.
  • When false, the frame will not go through verification.
import { Frog } from 'frog'
 
const app = new Frog({
  verify: 'silent',
  title: 'Frog Frame',
})

Return Type

A Frog instance containing:

basePath

  • Type: string

The base path for the server instance.

browserLocation

  • Type: string

URL to redirect to when the user is coming to the page via a browser.

frame

  • Type: Frog['frame']

The .frame method.

hono

  • Type: Hono

The Hono instance.

hub

  • Type: Hub

Farcaster Hub configuration.

fetch

  • Type: Hono['fetch']

Hono's fetch method.

get

  • Type: Hono['get']

Hono's get method.

post

  • Type: Hono['post']

Hono's post method.

use

  • Type: Hono['use']

Hono's use method.

verify

  • Type: boolean

Whether or not frames should be verified.