https://github.com/artlu99/framesv2-remix-cf
an opinionated Farcaster Frames V2 starter built on Remix and CF Pages
https://github.com/artlu99/framesv2-remix-cf
farcaster farcaster-frame farcaster-frames
Last synced: 3 months ago
JSON representation
an opinionated Farcaster Frames V2 starter built on Remix and CF Pages
- Host: GitHub
- URL: https://github.com/artlu99/framesv2-remix-cf
- Owner: artlu99
- License: mit
- Created: 2024-12-25T21:23:42.000Z (5 months ago)
- Default Branch: main
- Last Pushed: 2025-02-10T23:50:29.000Z (4 months ago)
- Last Synced: 2025-02-11T00:28:58.264Z (4 months ago)
- Topics: farcaster, farcaster-frame, farcaster-frames
- Language: TypeScript
- Homepage: https://frames.artlu.xyz/pinned/6546
- Size: 644 KB
- Stars: 2
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
- awesome-farcaster - Farcaster Frames V2 Starter on Remix and Cloudflare
README
# Farcaster Frames V2 Starter on Remix and Cloudflare
## Wat is dis
If you luurve `Next.js` on `Vercel`, check out [Demo](https://github.com/farcasterxyz/frames-v2-demo) by the Warpcast team, or [Stephan](http://warpcast.com/stephancill)'s [Frames v2 Starter](https://github.com/stephancill/frames-v2-template) and [limone.eth](http://warpcast.com/limone.eth)'s [Frames v2 Starter Kit](https://github.com/builders-garden/frames-v2-starter) all on Next.
If not, keep reading! 👇👇👇
This starter is meant for anyone who wants to quickly build a Farcaster Frame V2, with a focus on lightning-fast DX and gtm. It is not meant to showcase bleeding-edge features of the Frames v2 spec, nor to enable devs to re-build common Frames infrastructure such as auth or a notifications service.
## Local Development [~60 seconds to localhost:5173]
```sh
git clone https://github.com/artlu99/framesv2-remix-cf [your-folder-name]
cd [your-folder-name]
pnpm i
pnpm dev
```
[PRO TIP]: develop locally at 400x567, which is viewable window on a Gen 2 iPhone SE. If you use the native button, expect users to need to scroll vertically.
## Deployment [~30 seconds to live]
### "Bish bash bingo bongo", a.k.a. accept the defaults and go
- update project name in `wrangler.toml`
- deploy to Cloudflare Pages using `pnpm run deploy`
- pay attention to the deployment branch name, update in `package.json` as necessary
- [ONE-TIME OPTIONAL, BUT RECOMMENDED]. Assign `Custom domain` via Cloudflare dashboard. Sign manifest in Warpcast, update `/public/.well-known/farcaster.json` and re-deploy
## Optional batteries included
***permissionless install, managed user notifications, auth, redis, postgres***
Click to expand/collapse
### Enable users to install your frame
- update `/public/.well-known/farcaster.json`
- icons can be changed later, but caching can cause issues / delays. *Avoid headaches later; try to get it right before Warpcast scrapes your site.*
### Managed notifications
- set up an app with [Neynar](https://dev.neynar.com/app). Details [[here]](https://docs.neynar.com/docs/send-notifications-to-frame-users)
- for local dev, update environment variable in `.dev.vars` (not checked into git, but follow `dev.vars.example`)
- update `NEYNAR_FRAME_WEBHOOK_URL` env variable as a secret via Cloudflare dashboard (do not use `wrangler.toml` for secrets!)
### Privy seamless Farcaster login
- set up an application with [Privy](https://dashboard.privy.io). Follow Steps 1 and 2 [[here]](https://docs.privy.io/guide/react/recipes/misc/farcaster-frames#build-a-farcaster-frame-with-privy). This starter implements Steps 3 and 4 for you!
- update `/app/config.json` with your Privy `appId`
### Redis
- set up an [Upstash Redis](https://upstash.com) instance via their dashboard
- this starter shares data across dev and prod environments. It does not expose the Redis connection to browsers; only the server-side Remix loader has access to it
Secrets setup
- copy **two (2)** secrets from the `REST API` -> `.env` section. Ensure you have copied the actual token, and not a bunch of asterisks to your clipboard (*don't ask me how I know!*)
- update secrets via Cloudflare dashboard (do not use `wrangler.toml` for secrets!)
- for local dev, update environment variables in `.dev.vars` (not checked into git, but follow `dev.vars.example`)
### Postgres
- set up [Neon Postgres](https://neon.tech) via their dashboard
- this starter shares data across dev and prod environments. It does not expose the Postgres connection to browsers; only the server-side Remix loader has access to it
Secrets setup
- copy **one (1)** secret from the `Connection Details` -> `Connection string` section
- update secrets via Cloudflare dashboard (do not use `wrangler.toml` for secrets!)
- for local dev, update environment variables in `.dev.vars` and `.env` (not checked into git, but follow the example files)
- run `pnpm run migrate` to create the database and tables
## Opinionated Features
This starter emphasizes iteration speed and type-safety.
It postpones scale decisions by leaning on serverless site generation, stateless connections and edge datastores.
It expects zero cost-to-launch, and the first bottleneck is expected to be the Privy plan (at ~150 users). Neynar is currently $9/month until much higher loads, and the plan includes many other useful features for Farcaster devs. Hosting and data should remain performant on the free tiers until much later. YMMV.
Click to expand/collapse a nerd list 🤓
1. `Remix` on `Cloudflare Pages`, for light, fast SSR with familiar `React` mental models. *Serverless that feels like a long-lived server*
2. `Vite` for lightning-fast local development with HMR
3. `Hono Stack` for end-to-end type safety, zero codegen and *de minimis* boilerplate
4. `Kysely` Typescript query builder and migration scripts
5. `shadcn/ui` `TailwindCSS` components, `Framer` motion animations
6. `Upstash Redis` and `Neon Postgres` as edge, scalable datastores on stateless connections
7. Seamless Farcaster login via `Privy` [[details]](https://docs.privy.io/guide/react/recipes/misc/farcaster-frames#build-a-farcaster-frame-with-privy), with easy pathway to providing embedded wallets
8. webhook logging, optionally verified and/or managed via `Neynar` (see [[docs]](https://docs.neynar.com/reference/fetch-notification-tokens)). Send managed notifications [[here]](https://docs.neynar.com/reference/publish-frame-notifications)
9. `Biome` linting at the speed of Rust. `pnpm` because it's 2025.
10. BYO: test suite, CI/CD, local frame debugger
Click to expand/collapse a nerd table 🏓
## comparison with Warpcast Demo Repo
| Feature | artlu Starter | Warpcast Demo Repo |
|-----------------------------|-----------------------------------|----------------------------------|
| Framework | Remix | Next App router |
| Local Development Tool | Vite | Next |
| UI components | shadcn/ui | Radix + TailwindCSS |
| End-to-End Type Safety | Hono Stack | nah, we have Zod at home |
| Datastores | Upstash Redis, Neon Postgres (optional) | Vercel KV (Redis) |
| Notifications | Neynar (optional) | integrated + Neynar Hub verification |
| Authentication | Privy (optional) | SIWF on NextAuth |
| Deployment | Cloudflare Pages | Vercel |
| Dynamic OG Generation | separate microservice | integrated |
| Linting and Formatting | Biome | ESLint, Prettier |
| CI/CD | bring-your-own | Vercel + GitHub Actions (default) |
| testing | bring-your-own | bring-your-own |
| Edge Functions | Yes | Yes |
| Cost Efficiency | Free tiers recommended | Free tiers recommended |
| Philosophy | serverless V8 | long-lived Node server + Edge serverless |
## Some Frames V2 built on this starter
1. (artlu) and (Vitalik)
2. "real-time" International Space Station Urine Tank monitor in a frame
3. Yo dawg, I heard you like frames, so I put a website in your frame, so you can browse while you frame
4. one hundred push up club frame on Farcaster
### Notes
1. dynamic OG image generation is a separate microservice. FOSS and MIT Licensed [[here]](https://github.com/artlu99/cached-dynamic-og-generator-cf).
2. Neon supports painless database branching, which is a great feature for development. Out of scope for this starter.
3. when you need the full Cloudflare environment, first run `pnpm build` and then `pnpm start` *(this should be rare)*.
4. the framework is ready for `TailwindCSS v4`, and some frames built on this starter are already using it. However, some edge cases with `shadcn/ui` and `vite` + `Remix` should get ironed out soon. Suggest upgrading after `shadcn/ui` gets CLI support.
## Thanks
- [@horsefacts](https://github.com/horsefacts), [@deodad](https://github.com/deodad) and [@cmlad](https://github.com/cmlad) for [Demo](https://github.com/farcasterxyz/frames-v2-demo) and
- [jiangsi](https://github.com/jiangsi) for Remix on Cloudflare Pages template
- [Yusuke Wada](https://github.com/yusukebe) for Hono 🔥
## License
MIT