https://github.com/stephancill/frames-v2-template
Opinionated Frames v2 template with built-in auth and farcaster utils
https://github.com/stephancill/frames-v2-template
frames frames-v2
Last synced: 9 months ago
JSON representation
Opinionated Frames v2 template with built-in auth and farcaster utils
- Host: GitHub
- URL: https://github.com/stephancill/frames-v2-template
- Owner: stephancill
- Created: 2025-01-13T21:32:07.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2025-02-22T10:26:44.000Z (11 months ago)
- Last Synced: 2025-04-23T20:16:16.793Z (9 months ago)
- Topics: frames, frames-v2
- Language: TypeScript
- Homepage:
- Size: 126 KB
- Stars: 22
- Watchers: 1
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# Stephan's Frames v2 Starter
This is an opinionated starter for building v2 frames
## Stack
- Next.js
- PostgreSQL (with Kysely)
- Redis
- Lucia Auth
- BullMQ
- shadcn/ui
## Features
- Sign in with Farcaster
- Customizable db schema
- Authenticated endpoints
- Notification utils
- Farcaster social graph helpers
## Getting Started
### Database
First, start the database and run the migrations
```
docker-compose up -d
```
```
pnpm run migrate
```
### Environment Variables
Copy the `.env.sample` file to `.env` and fill in the values.
> **Note:** The `APP_URL` environment variable is used to configure the frame. It should be the URL of your local dev server.
### Frame
To start your local dev server, run the following command:
```
pnpm run dev
```
This should start the dev server at `http://localhost:3000`.
To debug the frame locally, you can use the frames.js debugger, which you can run with the following command:
```
npx @frames.js/debugger@latest
```
Once the debugger is running, you can load the frame in the debugger by entering the URL of your local dev server in the debugger.
> **Note:** Make sure to select the Farcaster v2 option in the debugger next to the "Debug" button and ensure that you are signed in with your Farcaster account and not impersonating another account.
### Debugging on other URLs
If you want to test the frame on a different URL such as ngrok or a production URL, you can update the `accountAssociations` in `src/app/.well-known/farcaster.json/route.ts` to include the URL you want to test. You can generate account associations in the frames.js debugger or in the Warpcast app (Settings -> Developer -> Domains).
Then update the `APP_URL` environment variable in your `.env` file to the URL you want to test to ensure the correct associations are used.
## Authentication
This project uses Lucia Auth for authentication. You can learn more about it [here](https://lucia-auth.com/).
You can create new authorized endpoints by using the `withAuth` exported from `src/lib/auth.ts`. See the `src/app/api/user/route.ts` file for an example of how to use it.
## Farcaster data
There are some helpers for fetching farcaster data in `src/lib/farcaster.ts`. Wrap these calls with `withCache` to cache the results in Redis.
```ts
const mutuals = await withCache(`fc:mutuals:${user.fid}`, () =>
getMutuals(user.fid)
);
```
## Custommization
### Database
To make a change to the database, create a migration file in `src/migrations` and run the following command:
```
pnpm run migrate
```
And update the `src/types/db.ts` file to reflect the new schema. (Kysely camelcase plugin is enabled so you can use camelcase in your types)
## Workers
This project uses a redis queue for dispatching notification jobs.
There is no build step. Just run the workers file
```
pnpm run workers
```
This project uses Bullboard for monitoring the queue. You can access it at `http://localhost:3005/`. In production you can protect this endpoint with a password by setting the `BULL_BOARD_USERNAME` and `BULL_BOARD_PASSWORD` environment variables.