Home

framehack-farcaster-hackathon.mp4

FrameTrain is a platform that allows you to upload your own Frame Templates and earn points when they are used.

Incentivizing creators is a huge part of FrameTrain, so we want to make it as easy as possible, all while being greatly rewarded.

For this we have prepared a guide for the FrameTrain APIs & Components, and a list of Template suggestions below.

How to Get Started

• Clone the repository
• Create a free Turso account and setup a database.
• Create a free R2 bucket on Cloudflare and make it public. If you're familiar with S3-like storage you can use any provider.
• Add the required .env variables
  • AUTH_SECRET: any string will do
  • NEYNAR_API_KEY: you can use the dummy Frog api key ("NEYNAR_FROG_FM"), get a real key from Neynar, or simply disable validation for your Template if you don't need it.
  • NEXT_PUBLIC_HOST: http://localhost:3000
  • NEXT_PUBLIC_DOMAIN: localhost:3000
  • NEXT_PUBLIC_CDN_HOST: the public url you got from the R2 bucket, in full https format
  • SCRAPER_URL: https://tools.farfetched.digital
  • TURSO_URL: libsql://...
  • TURSO_SECRET: the secret you generated in the Turso dashboard
  • S3_BUCKET: the name of your R2 bucket
  • S3_ENDPOINT: the endpoint of your R2 bucket
  • S3_REGION: auto
  • S3_KEY_ID: the key of your R2 bucket
  • S3_SECRET: the secret of your R2 bucket
• Install dependencies (npm i)
• Migrate the database (npm run db:migrate)
• Start the server (npm run dev)
• Deploy to Vercel using (npm run deploy)

Anatomy of a Template

Templates live in the @/templates folder, and this is where you should add yours too.

Each template follows a predefined folder structure:

• handlers — a collection of 1 or more handlers, used as controllers for displaying the views. Must contain at least an initial handler that displays the first image/slide. In addition to the request body and params, Handlers have access to the Frame's state and config.
• views — a collection of 1 or more React components, rendered as the Frames’ image using satori. Must contain at least a Cover view, the initial view that is displayed when you post a Frame.
• Inspector — a React (NextJS use client) component displayed in the Frame Editor. Used to get input from the user, transforming it as needed and saving it as the Frame’s config. The Inspector has access to the config object, and can modify it. This config will be used by your handlers to properly display the views.
• cover — a cover image for the template, displayed in the template selection screen.

Here's a line-by-line explanation of a template's index.ts file:

// 1. Import the base types
import type { BaseConfig, BaseState, BaseTemplate } from '@/lib/types'

// 2. Import your Inspector component
import Inspector from './Inspector'

// 3. Import your cover image (png, jpg, webp)
import cover from './cover.webp'

// 4. Import your handlers
import handlers from './handlers'

// 5. Define your config type, extending the base config
export interface Config extends BaseConfig {
    images: []
}

// 6. Define your state type, extending the base state
export interface State extends BaseState {}

export default {
	// 7. Set the metadata (name, description, your FID and Farcaster username)
    name: 'PDF Template',
    description: 'Upload and convert your PDF into a Frame with multiple slides.',
    creatorFid: '2',
    creatorName: 'Varun',
	// 8. Marks the template as visible in the UI
    enabled: true,
	// 9. Add your previously imported and declared objects
    Inspector,
    handlers,
    initialConfig: {} as Config,
    cover,
	// 10. Marks the template as requiring validation or not
    requiresValidation: false,
} satisfies BaseTemplate

Everything else is completely up to you. You can have a hooks, types, utils, or an assets folder if you want.

What's the difference between state and config?

In a Poll template, you would use the state to save incoming votes, and the config to store the voting options the user wants to display in the Frame and its buttons. You can see this in action in the current Poll template. In general, if you need to save the incoming input from other users Farcaster you use the state, if you are saving the configuration of the Frame when the owner/user is editing it on FrameTrain, you use the config.

Submitting a Template

To submit your Template, simply open a PR in the repository with your Template code added to the @/templates folder, and details about it.

The pull request should have a title in the [FH-1] YOUR TEMPLATE NAME/USE-CASE format. It should contain a few words about your template, and a link to a Farcaster post showing a working example. Create a Frame using your Template, post it to Warpcast, and paste the link in the PR.

This means you will need to deploy your own instance of FrameTrain to showcase it, but do not worry - it's easy and free! See the How to Get Started section for more details about running and deploying FrameTrain.

Relevant Details

1. You're free to install any dependencies that you need, but check first if something you could use isn't installed already in package.json.
2. Your handlers need to be as small and quick as possible. In general, try to compute/fetch everything in your Inspector and save the result in the config, so you do as little work in your handlers as possible. If you want to display the avatar of a Twitter user, you can just save the avatar URL to the config, instead of saving the Twitter username and then fetching the avatar url in your handler. However, if you need real-time data, for example showing an updated number of Twitter followers or the status of a Sablier stream, you probably need to do it in the handler.
3. The resolution of Frames is set very low at the moment (315x315 and 315x630), this is intended until we optimize the architecture so your handlers don't timeout. This will most likely mean migrating to Frog. Your templates will be upgraded automatically.

Support

If you have any questions or suggestions, then you came to the right place!

You can post any thoughts or questions in the /frametrain channel on Farcaster. I will respond to them in real time.