Skip to content

depatchedmode/simplest-frame

Repository files navigation

poster-animated

A zero-cost, zero-framework, dynamic Farcaster Frame template

This is the "simplest" version of a Frame that can do all of the things a Frame should be able to do. It may be more than you need. It may be less. But it's a great place to start, IMHO. And it is indebted to all the great work by the team over at https://framesjs.org

My needs for starting this were:

  1. 🚱 Zero Framework: Didn't want a framework baked in, and most options default to Next.js/React. No offense, but those seem like overkill.
  2. 🆓 Zero Cost: Frames are for experiments! Experimenting is more fruitful when it's free.
  3. 🧱 Stable: The domain and its attached state should be reasonably stable over the horizon of an experiment. Replit can only give you this at cost (see above)
  4. 🤸 Dynamic: You can get all the above pretty easy with static files, but let's be real: we want dynamism or something! And, as social animals, we want to act and react.
  5. 🤤 Small: and hopefully easy. Nobody to impress here. If my quite smooth brain can write this, your quite prune-like brain can understand it to.
  6. 😎 Cool Tech: We want to be at the 🤬 edge here, people! I admit this is somewhat in tension with "simplest".

Features

  • ⑃ Flow Definition: Define button & input behaviour within each frame file.
  • 🎇 Static & Dynamic Images: Support for both static & dynamic frame images.
  • 🧐 Validate trustedData: Verify the current payload's trustedData via Farcaster Hubs (eg. wield.co), to protect against tomfoolery.
  • ⌨️ Text inputs: Accept that UGC with byte-level protection. Our safeDecode function leverages dompurify to give you a literal, and helpful purity test. The judgement of whether the content meets your standards is still up to you, though.
  • ↗️ Redirect Support: Because frames can't do everything ... yet! And, doggonit, there's a whole world wide web out there for y'all to explore.
  • 🎟️ Mint from frame (COMING SOON): Using Syndicate + Base, this boilerplate gives you what you need to make random interactions with your frame unforgettable. Is that a good idea? That sounds like a you problem.
  • 🔐 Anti-theft: Don't bet the engagement farm! Bind your Frame to a specific cast or account so nobody else can get your likes, follows, recasts ... and respect. Capisci?

Example

simplest-frame https://warpcast.com/depatchedmode/0xecad681e

Getting started

  1. Clone the repo
  2. Install the Netlify CLI
  3. Copy sample.env to .env and add:
    • your Netlify Key, for deploys: NETLIFY_AUTH_TOKEN
    • a Wield Key for reading Farcaster state: WIELD_API_KEY
  4. npm install
  5. netlify dev

Testing

The Frames.js debugger can be run locally for testing by following these instructions: https://framesjs.org/guides/debugger#local-debugger-cli

Defining your Frame

We'll update with a proper docs soon*, but you'll find everything you need in the public and src directories.

To add a new frame, create a {frameName}.js file in /src/frames and add it as an import to /src/frames/index.js. You'll find examples of dynamic (eg. rendered HTML) and static (eg. served from the public folder) frames in that directory.

*Y'all are welcome to help me write them.

Deploying

This should be as simple as watching a git repo for commits.

You may encounter a 502 gateway error after deployment on the /og-image endpoint. This is a known issue with the sharp module this repo relies upon. We'll hopefully have this fixed by default, but for now there are workarounds. Follow this thread for fixes: #3

Caveats

I am a designer larping as a dev. I invite your collaboration and feedback. Please be kind.

And please! Can we make it simpler?