How To Convert Your Website Into A Farcaster Mini-App (Obsidian Digital Garden Example)

#digitalgarden #tutorial
May 14, 2025 3:58 PM
May 14, 2025 8:41 PM

flow channel.png
example of the view for Algorithm For Finding Flow Channels

How to Turn Your Existing Website Into A Farcaster Mini-App

This tutorial is a walk-through on how you can convert an existing website into a mini-app on Farcaster. Regardless of whether you are interested in Farcaster or mini-apps, the tutorial flow will help you understand how you can connect AI coding tools like Google AI Studio with Gemini 2.5 Pro to a coding workflow, even as a non-coder.

Since so many of you are interested in digital gardens, I thought the best way to get going would be to start with my digital garden website (what you're reading right now), as this is the best way I have found to publish my Obsidian notes effectively.

If you've never used Farcaster before and want to check it out, let me know, and I can give you an invite link to cover the sign up cost (~$1 I believe).

Suggested Prerequisites:

The Core Idea: We'll modify your site's templates to include Farcaster-specific meta tags and add a configuration file for Farcaster clients.

Tools Needed

Tools needed/suggested:

  1. GitHub Account
  2. Website Repository
    1. Obsidian
    2. digital garden plugin
      1. 11ty static website builder
    3. hosting provider (netlify, vercel, orbiter)
  3. GitHub Desktop
  4. ngrok
  5. VSCode (or other code editor)
    1. e.g., Cursor AI
  6. Farcaster account
  7. AI LLM coding specialist (I'm using Google AI Studio with Gemini 2.5 Pro)
  8. website & SDK context for the AI
    1. llms-full mini-app.txt
    2. frames-llm-docs-main.zip
    3. digital-garden-without-notes.zip see How I Published My Obsidian Notes Website For Free 🏡 Digital Garden

Step-by-Step Guide:

  1. Branch Your Repository:

    • In GitHub Desktop, create a new branch (e.g., farcaster-mini-app) from your main branch. This keeps changes isolated.

  2. Add Farcaster SDK & Meta Tag:

    • Open your project in VSCode.
    • Locate your note template file (usually src/site/_includes/layouts/note.njk) and your homepage template (src/site/_includes/layouts/index.njk or similar).
    • Just before the closing </head> tag in both files, add:
      <script src="https://cdn.jsdelivr.net/npm/@farcaster/frame-sdk/dist/index.min.js" defer></script>
<meta name="fc:frame" content='{"version":"next","imageUrl":"YOUR_DEFAULT_PREVIEW_IMAGE_URL","button":{"title":"Open Note","action":{"type":"launch_frame","name":"YOUR_APP_NAME","url":"YOUR_LIVE_SITE_URL{{ page.url if page.url != '/' else '' }}","splashImageUrl":"YOUR_SPLASH_IMAGE_URL","splashBackgroundColor":"YOUR_SPLASH_BG_COLOR_HEX"}}}' />
      • Replace placeholders:
        • YOUR_DEFAULT_PREVIEW_IMAGE_URL: A 3:2 aspect ratio image (e.g., https://yourdomain.xyz/img/default-preview.png).
        • YOUR_APP_NAME: E.g., "My Digital Garden Frame".
        • YOUR_LIVE_SITE_URL: Your full site URL (e.g., https://wanderloots.xyz). The {{ page.url if page.url != '/' else '' }} part dynamically adds the specific note path or an empty string for the homepage.
        • YOUR_SPLASH_IMAGE_URL: A 200x200px image.
        • YOUR_SPLASH_BG_COLOR_HEX: E.g., #2a2a2a.
    • Just before the closing </body> tag in both files, add:
      <script>
  document.addEventListener('DOMContentLoaded', async () => {
    if (window.frame && window.frame.sdk) {
      try {
        await window.frame.sdk.actions.ready();
        console.log('Farcaster Frame SDK ready.');
      } catch (error) { console.error('Error SDK ready:', error); }
    }
  });
</script>

  3. Create farcaster.json Manifest:

    • In your project, navigate to src/site/ and create a new folder named .well-known.
    • Inside .well-known, create a file named farcaster.json.
    • Paste the following content, replacing placeholders with your live site URL and app details:
      {
  "accountAssociation": {
    "header": "PLACEHOLDER_WILL_BE_FILLED_LATER",
    "payload": "PLACEHOLDER_WILL_BE_FILLED_LATER",
    "signature": "PLACEHOLDER_WILL_BE_FILLED_LATER"
  },
  "frame": {
    "version": "1",
    "name": "YOUR_APP_NAME",
    "iconUrl": "YOUR_LIVE_SITE_URL/favicon.svg",
    "homeUrl": "YOUR_LIVE_SITE_URL/",
    "imageUrl": "YOUR_LIVE_SITE_URL/img/default-og-image.png",
    "buttonTitle": "View Note",
    "splashImageUrl": "YOUR_LIVE_SITE_URL/img/your-splash-icon.png",
    "splashBackgroundColor": "#YOUR_HEX_COLOR"
  }
}

  4. Update Eleventy Config:

    • Open .eleventy.js in your project root.
    • Inside the module.exports = function(eleventyConfig) { ... } block, add this line (usually before the return statement):
      eleventyConfig.addPassthroughCopy(".well-known");
    • This ensures the .well-known folder (with farcaster.json) is copied to your build output.

  5. Test with ngrok & Replace URL Placeholder Names

    1. start local host by opening a terminal in VS Code
    2. write "npm run start" to start your local host
    3. use ngrok to "tunnel" the local host, creating a URL that makes it available to external platforms like farcaster
    4. copy the ngrok URL and replace your placeholder URLs throughout the the edited notes (note.njk, index.njk, farcaster.json)
    5. Close the local host server (cmd + c or ctrl + c)
    6. Restart the local host server with "npm run start" to run it with the ngrok URLs

  6. Test ngrok URL In Warpcast Debugger

    1. go to https://warpcast.com/~/developers/mini-apps/debug
    2. paste in the ngrok URL from the previous step
    3. test the embed preview and that the app works properly
      1. NOTE: I had to wait about 10 minutes before it worked the first time
    4. test the feed embed preview
    5. if it works, we're ready to merge the mini-app branch with the main branch of the website

  7. Commit, Push, and Deploy:

    • Commit all changes in GitHub Desktop to your farcaster-mini-app branch.
    • Push the branch to GitHub.
    • Merge this branch into your main deployment branch (e.g., main) via a Pull Request on GitHub.
    • Wait for Netlify to build and deploy your site.

  8. Generate Farcaster Signature:

    • Once your site is live with the new farcaster.json (containing your live URLs and placeholders for the signature), go to the Warpcast Farcaster JSON Tool.
    • Enter your live domain (e.g., wanderloots.xyz).
    • Click "Sign Message" and sign with your Farcaster-connected wallet.
    • Copy the generated "accountAssociation": { ... } JSON block.

  9. Add Signature, Replace Test URLS, Redeploy:

    • Open src/site/.well-known/farcaster.json in VSCode again.
    • Replace the placeholder "accountAssociation" block with the one you just copied from the Warpcast tool.
    • Replace all instances of the ngrok URL with your live domain (e.g., https://wanderloots.xyz)
      • replace in farcaster.json, note.njk, & index.njk (or your respective template files)
    • Commit this change, push, merge, and wait for Netlify to redeploy.

Testing:

Congratulations! Your Digital Garden notes are now a Farcaster Mini-App. This basic setup allows any page of your garden to be shared as an interactive frame.

From here, you can explore more advanced features like dynamic images or custom frame actions, which I'll get into more in the next tutorial.