DEV Community: uratmangun

Building a Next.js Template Clone Generator: A Complete Guide to Streamlining Your Development Workflow with Kiro

uratmangun — Sat, 29 Nov 2025 22:42:31 +0000

// Detect dark theme var iframe = document.getElementById('tweet-1994902367335313863-486'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1994902367335313863&theme=dark" }

Introduction

Have you ever found yourself repeatedly setting up the same Next.js project structure over and over again? Creating new repositories, configuring TypeScript, setting up Tailwind CSS, and establishing your preferred folder structure can be tedious and time-consuming. What if there was a better way?

In this comprehensive guide, I'll walk you through a project I built that solves this exact problem: a Next.js Template Clone Generator. This interactive web application allows developers to quickly create new repositories from a pre-configured template using the GitHub CLI, all with a beautiful, user-friendly interface.

The Problem We're Solving

As developers, we often face these challenges when starting new projects:

Repetitive Setup: Manually creating the same folder structure, configuration files, and boilerplate code for every new project
Inconsistent Standards: Different projects end up with slightly different configurations, making it harder to maintain consistency across your portfolio
Time Waste: Precious development time spent on setup instead of actual feature development
Human Error: Forgetting to include important configurations or making typos in setup commands

The solution? A template repository combined with an intuitive generator interface that makes cloning and customizing new projects a breeze.

Project Overview

The kiro-nextjs template is a carefully crafted Next.js starter that includes:

Next.js 16 with App Router
TypeScript for type safety
Tailwind CSS for styling
Biome for linting and formatting
Kiro Configuration for AI-assisted development
pnpm as the preferred package manager

But the real magic happens in the landing page itself — it's not just a static "getting started" page. It's an interactive tool that generates the exact command you need to clone the template.

Deep Dive into the Code

Let's break down the main component that powers this generator:

The Component Structure

"use client";

import { useState } from "react";

export default function Home() {
  const [repoName, setRepoName] = useState("my-new-repo");
  const [visibility, setVisibility] = useState<"public" | "private">("public");
  const [copied, setCopied] = useState(false);

  const hasSpaces = repoName.includes(" ");
  const command = `gh repo create ${repoName || "my-new-repo"} --template uratmangun/kiro-nextjs --${visibility} --clone`;
  // ...
}

The component uses React's useState hook to manage three pieces of state:

repoName: The name of the new repository the user wants to create
visibility: Whether the repository should be public or private
copied: A boolean to track whether the command has been copied to clipboard

Input Validation

One of the key features is real-time input validation:

const hasSpaces = repoName.includes(" ");

GitHub repository names cannot contain spaces, so we check for this and provide immediate feedback to the user. This prevents frustration from failed commands and teaches users about GitHub's naming conventions.

Dynamic Command Generation

The command is dynamically generated based on user input:

const command = `gh repo create ${repoName || "my-new-repo"} --template uratmangun/kiro-nextjs --${visibility} --clone`;

This uses template literals to construct the GitHub CLI command with:

The user's chosen repository name (with a fallback to "my-new-repo")
The template repository reference
The visibility flag (public or private)
The --clone flag to automatically clone the new repository locally

Copy to Clipboard Functionality

const copyToClipboard = async () => {
  await navigator.clipboard.writeText(command);
  setCopied(true);
  setTimeout(() => setCopied(false), 2000);
};

This async function uses the modern Clipboard API to copy the command. It also provides visual feedback by:

Setting copied to true immediately
Resetting it to false after 2 seconds

This creates a smooth user experience where the copy button icon changes to a checkmark temporarily.

The User Interface

Responsive Design

The interface is built with a mobile-first approach using Tailwind CSS:

<div className="flex min-h-screen items-center justify-center bg-zinc-50 font-sans dark:bg-zinc-950">
  <main className="flex w-full max-w-2xl flex-col gap-6 px-6">

Key design decisions:

Centered layout: The content is vertically and horizontally centered for a clean, focused experience
Maximum width constraint: max-w-2xl ensures readability on large screens
Dark mode support: Every color class includes a dark: variant for seamless dark mode

Input Field with Validation Feedback

<input
  type="text"
  value={repoName}
  onChange={(e) => setRepoName(e.target.value)}
  placeholder="Repository name"
  className={`w-full rounded-lg border bg-white px-3 py-2 text-sm text-zinc-900 placeholder:text-zinc-400 focus:outline-none focus:ring-1 dark:bg-zinc-900 dark:text-zinc-100 dark:placeholder:text-zinc-500 ${hasSpaces
    ? "border-amber-500 focus:border-amber-500 focus:ring-amber-500"
    : "border-zinc-300 focus:border-emerald-500 focus:ring-emerald-500 dark:border-zinc-700 dark:focus:border-emerald-500"
  }`}
/>

The input field dynamically changes its border color:

Amber/Yellow: When the input contains spaces (warning state)
Emerald/Green: When the input is valid (success state)

This provides immediate visual feedback without being intrusive.

The Command Display

<div className="relative rounded-lg bg-zinc-900 p-4 dark:bg-zinc-800">
  <code className="block pr-10 text-sm text-emerald-400">
    {command}
  </code>
  <button
    type="button"
    onClick={copyToClipboard}
    className="absolute right-2 top-2 rounded p-1.5 text-zinc-400 hover:bg-zinc-700 hover:text-zinc-200"
    aria-label="Copy command"
  >
    {/* Icon changes based on copied state */}
  </button>
</div>

The command is displayed in a code block with:

A dark background that contrasts with the page
Emerald-colored text for that classic terminal feel
An absolutely positioned copy button in the top-right corner
Proper padding to prevent text from overlapping with the button

Kiro Integration

One of the most exciting aspects of this project is its integration with Kiro, an AI-powered development assistant. The template includes a .kiro directory with several configuration files:

Steering Rules

Steering rules are markdown files that guide Kiro's behavior:

Package Manager Preference: Enforces pnpm as the primary package manager with yarn as fallback
UI Color Guidelines: Prefers non-purple primary colors for consistency
Shell Preferences: Configures fish shell syntax for terminal commands
Development Server Policy: Prevents automatic server startup for better resource control

Agent Hooks

The template includes an auto-commit-push hook that automates the git workflow:

Stages all changes
Generates conventional commit messages with emojis
Pushes to the remote repository
Creates pull requests when on feature branches

This automation significantly speeds up the development workflow while maintaining consistent commit standards.

How to Use the Template

Prerequisites

Before using the template generator, ensure you have:

GitHub CLI (gh) installed and authenticated
Node.js (version 18 or higher recommended)
pnpm installed globally

Step-by-Step Guide

Visit the Template Page: Navigate to the deployed application
Enter Repository Name: Type your desired repository name (no spaces allowed)
Select Visibility: Choose between public or private
Copy the Command: Click the copy button
Run in Terminal: Paste and execute the command in your terminal

gh repo create my-awesome-project --template uratmangun/kiro-nextjs --public --clone

Start Developing: Navigate to your new project and start coding!

cd my-awesome-project
pnpm install
pnpm dev

Technical Decisions and Trade-offs

Why GitHub CLI Instead of a Web API?

Using the GitHub CLI (gh) instead of the GitHub API offers several advantages:

Authentication: Users are already authenticated through gh auth login
Simplicity: No need to handle OAuth flows or API tokens in the frontend
Local Cloning: The --clone flag automatically clones the repository
Familiarity: Developers are comfortable with CLI tools

Why Client-Side Rendering?

The component uses "use client" directive because:

Interactivity: The form requires real-time state updates
Clipboard API: Requires client-side JavaScript
No SEO Requirements: This is a tool, not content that needs indexing

Color Palette Choices

The design uses a carefully selected color palette:

Zinc: Neutral grays for backgrounds and text
Emerald: Success states and the command text
Amber: Warning states (like spaces in repo names)

This follows the steering rule of avoiding purple as a primary color while maintaining excellent contrast and accessibility.

Extending the Template

Adding More Options

You could extend the generator to include additional GitHub CLI options:

const [description, setDescription] = useState("");
const [homepage, setHomepage] = useState("");

const command = `gh repo create ${repoName} --template uratmangun/kiro-nextjs --${visibility} ${description ? `--description "${description}"` : ""} ${homepage ? `--homepage "${homepage}"` : ""} --clone`;

Supporting Multiple Templates

For organizations with multiple templates:

const [template, setTemplate] = useState("kiro-nextjs");

const templates = [
  { value: "kiro-nextjs", label: "Next.js Starter" },
  { value: "kiro-react", label: "React Starter" },
  { value: "kiro-node", label: "Node.js API Starter" },
];

Adding Analytics

Track which options are most popular:

const copyToClipboard = async () => {
  await navigator.clipboard.writeText(command);
  // Track the event
  analytics.track("command_copied", {
    repoName,
    visibility,
    timestamp: new Date().toISOString(),
  });
  setCopied(true);
  setTimeout(() => setCopied(false), 2000);
};

Best Practices Demonstrated

1. Accessibility

The component includes proper accessibility features:

<button
  type="button"
  onClick={copyToClipboard}
  aria-label="Copy command"
>

The aria-label ensures screen readers can announce the button's purpose.

2. Type Safety

TypeScript is used throughout:

const [visibility, setVisibility] = useState<"public" | "private">("public");

This ensures only valid visibility values can be set.

3. User Feedback

Multiple feedback mechanisms:

Visual border color changes for validation
Warning messages for invalid input
Icon changes for copy confirmation
Hover states for interactive elements

4. Dark Mode Support

Every visual element has dark mode variants:

className="bg-zinc-50 dark:bg-zinc-950"
className="text-zinc-900 dark:text-zinc-100"

Conclusion

Building a template clone generator might seem like a small project, but it demonstrates several important concepts:

Developer Experience Matters: Tools that save time and reduce friction are invaluable
Interactive Documentation: Instead of static instructions, provide interactive tools
Validation and Feedback: Help users succeed by preventing errors before they happen
Modern React Patterns: Hooks, controlled components, and async operations
Thoughtful Design: Accessibility, dark mode, and responsive layouts

The kiro-nextjs template and its generator represent a modern approach to project scaffolding. By combining a well-configured template with an intuitive interface, we've created a tool that makes starting new projects a joy rather than a chore.

Resources

Try It Yourself

Ready to streamline your Next.js development workflow? Visit the template repository and give it a try:

gh repo create my-next-project --template uratmangun/kiro-nextjs --public --clone

Happy coding! 🚀

Build Linera dApps Fast with This Next.js Template

uratmangun — Sat, 29 Nov 2025 07:14:57 +0000

If you're looking to build decentralized applications on Linera blockchain, setting up the development environment from scratch can be tedious. That's why I created Linera Dynamic Template — a production-ready Next.js starter that handles all the boilerplate for you.

What is Linera?

Linera is a next-generation blockchain platform designed for scalability through its unique microchain architecture. Unlike traditional blockchains, Linera enables parallel execution across multiple chains, making it ideal for high-throughput applications.

The Problem

Getting started with Linera development involves:

Configuring SharedArrayBuffer support (COOP/COEP headers)
Setting up WASM smart contract compilation
Integrating wallet authentication
Managing cross-origin policies for browser execution

This template eliminates all that friction.

Features

🔐 Dynamic wallet authentication — Easy login integration
⛓️ Linera blockchain interaction — Pre-configured client adapter
⚡ Next.js 16 + React 19 — Latest framework features
🎨 Tailwind CSS — Modern styling out of the box
📦 Example counter contract — Rust/WASM smart contract included
🛠️ CLI scripts — Wallet and contract management tools

Quick Start

# Clone with GitHub CLI
gh repo create my-linera-app --template uratmangun/linera-dynamic-template --clone
cd my-linera-app
pnpm install

# Configure environment
cp .env.example .env.local
# Add your Dynamic environment ID

# Start developing
pnpm dev

Project Structure

├── src/
│   ├── app/           # Next.js app router pages
│   └── lib/           # Linera adapter and utilities
├── contracts/         # Rust smart contracts (WASM)
├── scripts/           # CLI scripts for wallet/contract management
└── public/            # Static assets

Available Scripts

Command	Description
`pnpm dev`	Start development server
`pnpm wallet:init`	Initialize Linera wallet
`pnpm wallet:show`	Show wallet info
`pnpm contract:build`	Build smart contract
`pnpm contract:deploy`	Deploy smart contract

Tech Stack

Next.js 16 — React framework with app router
Dynamic — Wallet authentication provider
Linera — Blockchain platform
Rust — Smart contract language
Tailwind CSS — Utility-first styling
TypeScript — Type safety throughout

Key Technical Details

The template handles the tricky COOP/COEP headers required for SharedArrayBuffer support in browsers:

// next.config.ts
async headers() {
  return [{
    source: "/(.*)",
    headers: [
      { key: "Cross-Origin-Opener-Policy", value: "same-origin" },
      { key: "Cross-Origin-Embedder-Policy", value: "credentialless" },
      { key: "Cross-Origin-Resource-Policy", value: "cross-origin" },
    ],
  }];
}

This is essential for Linera's WASM client to function properly in the browser.

Get Started

Check out the template on GitHub: uratmangun/linera-dynamic-template

Click "Use this template" to create your own Linera dApp in seconds!

Have questions or feedback? Drop a comment below or open an issue on GitHub. Happy building! 🚀

Demo

Building a Gasless Marketplace on Polygon with x402 Protocol

uratmangun — Wed, 26 Nov 2025 05:43:19 +0000

Have you ever wanted to build a marketplace where users can buy and sell products using stablecoins without worrying about gas fees? In this article, I'll walk you through how I built Polygon x402 Marketplace, a gasless peer-to-peer marketplace using the x402 protocol on Polygon Amoy.

The Problem

Traditional blockchain marketplaces have a major UX problem: users need to hold native tokens (like MATIC) just to pay for gas fees. This creates friction because:

New users need to acquire native tokens from exchanges first
Users must manage multiple token balances
Gas prices fluctuate, making transaction costs unpredictable

The Solution: x402 Protocol

The x402 protocol enables gasless USDC transfers by using EIP-712 signatures and a facilitator network. Users only need USDC in their wallet to participate in the marketplace - no native tokens required!

Tech Stack

Frontend: Next.js 16, React 19, TailwindCSS 4
Web3: RainbowKit, wagmi, viem, x402-axios
Database: PostgreSQL with Drizzle ORM
Blockchain: Polygon Amoy (Testnet), USDC Token
Protocol: x402 Protocol with PayAI Facilitator

Key Features

Gasless USDC Payments

The marketplace uses the x402 protocol to handle payments. When a user makes a purchase, the payment flow works like this:

User clicks "Buy Now"
The API returns a 402 Payment Required response with payment requirements
x402-axios intercepts this and prompts the user to sign an EIP-712 message
The signed payment is sent to the PayAI facilitator for verification and settlement
The transaction is executed on-chain without the user paying gas

Product Listings

Sellers can list items with title, description, price, stock quantity, and images. The marketplace supports:

Creating new listings
Editing existing products
Automatic stock management after purchases
Comments on product listings

Wallet Integration

RainbowKit provides seamless wallet connection supporting MetaMask, WalletConnect, and more. The app automatically handles chain switching to Polygon Amoy.

Implementation Highlights

The Facilitator Proxy

One of the challenges was building a local facilitator proxy that correctly forwards requests to PayAI while maintaining proper CORS headers:

const paymentRequirements = {
  scheme: "exact",
  network: "polygon-amoy",
  maxAmountRequired: atomicAmount,
  payTo: recipientAddress,
  asset: USDC_ADDRESS,
  extra: {
    name: "USDC",
    version: "2",
  },
};

Using x402-axios

The x402-axios library makes it easy to handle the payment flow:

const axiosInstance = withPaymentInterceptor(
  axios.create(),
  walletClient
);

const response = await axiosInstance.post("/api/usdc-pay", {
  to: recipient,
  amount: amount,
});

Live Demo

Check out the live marketplace at: https://polygon-x402.vercel.app/

GitHub Repository: https://github.com/uratmangun/polygon-x402

What's Next

Deploy to Polygon Mainnet
Add order history and transaction tracking
Implement seller profiles with ratings
Support multiple stablecoins (USDT, DAI)
Mobile optimization with PWA features

How We Used Kiro in This Project

This project leverages Kiro's steering rules and MCP (Model Context Protocol) configuration to maintain consistent development practices. The .kiro folder contains:

Steering Rules

Kiro steering rules are markdown files that guide AI assistants during development:

Shell Preferences (shell-preferences.md): Enforces fish shell syntax for all terminal commands, ensuring consistent command execution across the project.
No Auto Start Dev Server (no auto start dev server.md): Prevents AI assistants from automatically starting development servers, giving developers control over resource usage.
UI Color Preferences (ui color prefer non purple primary.md): Establishes cyan/blue as primary colors instead of purple, maintaining consistent visual identity.
Package Manager Standards (use pnpm with yarn fallback for nodejs dependency manager.md): Mandates pnpm as the primary package manager with yarn as fallback, ensuring efficient disk usage and consistent dependency resolution.

MCP Configuration

The .kiro/settings/mcp.json configures Model Context Protocol servers:

chrome-devtools: Enables browser automation for testing and debugging
context7: Provides enhanced context awareness
next-devtools: Integrates Next.js-specific development tools

These Kiro configurations ensure that any AI assistant working on this project follows the same conventions, making collaboration smoother and code more consistent.

If you're interested in building gasless dApps, I highly recommend exploring the x402 protocol. It's a game-changer for blockchain UX!

Happy coding! 🚀

Demo

Freelancing Reimagined: Total Autonomy with Massa Smart Contracts

uratmangun — Mon, 24 Nov 2025 22:09:47 +0000

Introduction

The freelance economy is booming, but it’s still plagued by age-old problems: delayed payments, lack of trust, and the constant need to chase invoices. What if you could work with the certainty that your funds are already secured and will be released automatically as you work?

Enter Massa Freelance, a new decentralized application (dApp) built on the Massa Blockchain. We are redefining the relationship between clients and freelancers by leveraging Autonomous Smart Contracts to guarantee transparency, security, and real-time payments.

Why Massa Freelance?

1. Verified Proof of Funds

Never work for free again. With our platform, clients lock funds into a smart contract before the work begins. As a freelancer, you can verify the contract's balance in real-time, ensuring the money is there and ready for you.

2. Autonomous Payments

Forget about net-30 payment terms. Massa's unique Autonomous Smart Contracts can wake themselves up and execute transactions automatically. This means you can get paid by the hour, the minute, or any interval you choose—without the client needing to manually click "send" every time.

3. Total Flexibility

Whether you are hiring talent or looking for work, our platform offers ultimate flexibility. The interface is built with Next.js and styled with a clean, modern aesthetic (using a fresh green palette instead of the standard crypto-purple!), making it accessible to everyone, not just web3 natives.

Under the Hood

We've built Massa Freelance using a robust modern stack:

Frontend: Next.js 15 with React 19
Blockchain: @massalabs/massa-web3 and AssemblyScript contracts
Database: PostgreSQL with Drizzle ORM
Styling: Tailwind CSS with a custom design system

How We Use @[.kiro]

One of the secret weapons in our development workflow is .kiro. You might have noticed this directory in our project root. It serves as the "steering wheel" and "brain" for our AI coding assistant.

The .kiro directory allows us to define project-specific context and rules that the AI must follow. It contains two key subdirectories:

settings/: This holds configuration files like mcp.json, which defines the Model Context Protocol (MCP) servers our AI uses. This connects our AI to external tools, such as Chrome DevTools or database connectors, giving it superpowers beyond just reading code.
steering/: This is where we keep our "constitution." It contains Markdown files with specific instructions, such as ui color prefer non purple primary.md. These files tell the AI exactly how we want our code written—from UI color preferences (we strictly prefer greens and teals over purple) to coding conventions.

By using .kiro, we ensure that every line of code generated by the AI aligns perfectly with our project's unique style and architectural decisions, effectively "customizing" the AI to be a perfect teammate for Massa Freelance.

🛠️ Developer Guide: Deploying & Interacting with Smart Contracts

Want to run this yourself? Here is how we handle the smart contract lifecycle in Massa Freelance.

1. The Autonomous Smart Contract (`assembly/contracts/autonomous.ts`)

The heart of our system is the autonomous.ts contract. Unlike traditional smart contracts that are passive (waiting for an external transaction to trigger them), this contract is active.

Self-Scheduling: The sendCoinsAutonomously function performs a payment and then immediately schedules its next execution using deferredCallRegister. This creates an infinite loop of payments that runs entirely on-chain without any off-chain "keeper" or cron job.
State Management: We use a simple state machine (RUNNING / STOPPED) to control the flow. The start function kicks off the loop, and stop breaks it.
Safety: The contract checks its own balance before every execution to ensure it can cover both the payment and the storage fees for the next scheduled call.

2. Compiling & Deploying

We use a set of custom scripts defined in our package.json to streamline the process.

Step 1: Compile to WASM
First, we compile our AssemblyScript code into WebAssembly (WASM) bytecode that the Massa blockchain can understand.

npm run build:autonomous
# Runs: asc assembly/contracts/autonomous.ts --outFile build/autonomous.wasm --optimize --runtime stub

Step 2: Deploy to Buildnet
Next, we deploy the compiled WASM to the Massa Buildnet. We use a dedicated deployment script (assembly/deploy_autonomous.ts) that handles the wallet connection and constructor arguments.

npm run deploy:autonomous
# Runs: bun assembly/deploy_autonomous.ts

Note: Make sure you have your WALLET_PRIVATE_KEY set in your .env file!

3. Interacting with the Contract

Once deployed, the contract is in a STOPPED state. To start the autonomous payment stream, we need to call the start function.

We've created a helper script for this:

npm run call:autonomous-start
# Runs: bun scripts/call_autonomous_start.ts

This script:

Connects to the blockchain using your private key.
Targets your specific contract address.
Sends a transaction to execute the start method.
Monitors the execution to ensure it started successfully.

And that's it! Your contract is now alive, waking itself up at every interval to pay your freelancer. 🚀

Demo

Building a Para MCP Server + Next.js Wallet Demo (with Kiro + MCP)

uratmangun — Mon, 17 Nov 2025 22:49:13 +0000

para-mcp-server in one sentence

para-mcp-server is a Para MCP server plus a Next.js demo UI that lets AI tools and humans share the same Para-powered auth and wallet flows.

It’s a small lab for experimenting with:

MCP tools that talk to Para
Next.js UI that shows what the same flows look like in the browser
AI-first workflows (Kiro, ChatGPT, etc.) that can trigger those flows from inside your editor or chat.

What this project gives you

From the typescript/community/mcp-tools/para-mcp-server folder you get:

A Para MCP server
- Managed by xmcp via xmcp.config.ts
- Exposes Para operations to any MCP-capable client (ChatGPT, Kiro, etc.)
A Next.js demo app
- Runs on http://localhost:3012
- Shows end-to-end auth and wallet flows backed by Para
Configurable Web3 infra
- Para API key and environment
- WalletConnect project ID
- Optional Coinbase Developer Platform (CDP) integration for paymaster / gas sponsorship
- Optional Base Sepolia RPC URL

You can treat it as both:

A reference implementation of Para + MCP + Next.js
A playground for your own tools and flows.

Local setup

From the workspace root (where pnpm-workspace.yaml lives):

pnpm install

Then from typescript/community/mcp-tools/para-mcp-server:

cp .env.example .env

Open .env and fill in the values documented in .env.example, especially:

Para SDK
- PARA_API_KEY
- NEXT_PUBLIC_PARA_API_KEY
- NEXT_PUBLIC_PARA_ENVIRONMENT (e.g. BETA or PROD)
WalletConnect
- NEXT_PUBLIC_WALLET_CONNECT_PROJECT_ID
Coinbase Developer Platform (optional)
- CDP_API_KEY_ID
- CDP_API_KEY_SECRET
- NEXT_PUBLIC_PAYMASTER_URL (for sponsored gas, if you use it)
Optional RPC URLs
- NEXT_PUBLIC_BASE_SEPOLIA_RPC_URL
Optional Postgres (for pregenerated wallets)
- DATABASE_URL=postgresql://username:password@host:port/databaseThen run development mode:

pnpm dev

This will start:

xmcp dev – the Para MCP HTTP server
next dev -p 3012 – the Next.js UI at http://localhost:3012

At that point you can connect your MCP-enabled client (Kiro, ChatGPT, etc.) to the running MCP server and also browse the UI directly.

Auth and wallet flows (Next.js side)

On the UI side, the heart of the demo is a reusable ParaAuthComponent that encapsulates all Para auth logic. It’s designed to be dropped into different pages and flows instead of wiring each page manually.

Some highlights:

Email + OTP + passkeys
- Existing users can log in via hosted login links opened in a new tab or popup.
- New users can verify via a 6-digit code sent to email.
- Passkeys / password / PIN flows are supported through Para.
Wallet-aware UI
- After auth completes, the component pulls all wallets associated with the user.
- A dropdown lets you pick whichever wallet you want to use.
- The component can optionally render wallet details (address, id, userId, type, isPregen, etc.).
Pregenerated wallet flows
- The repo also includes pages for claiming pregenerated wallets.
- These can be backed by Postgres via the DATABASE_URL configuration if you enable that feature.
Browser- and AI-friendly auth redirects
- For ChatGPT / MCP environments, the code tries to use window.openai.openExternal when available so auth links open correctly inside native clients.
- It can also fall back to posting messages to a parent window (postMessage) or simply using window.location.assign with clear status messages like:
- "Authentication opened in a new tab. Don't close this page; finish auth there and return here."

The end result is that the same auth + wallet flow can be driven by:

A user clicking buttons in the Next.js UI
An AI tool calling MCP tools that eventually surface these URLs and flows

Why MCP matters here

The MCP layer is what lets this project plug Para directly into AI tooling.

Instead of hard-coding a single frontend or CLI, you expose Para capabilities (auth, wallets, etc.) as MCP tools. Any MCP-aware client can then:

Ask for a Para wallet
Trigger a login or verification
Interact with the Next.js UI and underlying Para SDK indirectly

This creates a neat loop:

You run pnpm dev to bring up the MCP server + Next.js app.
You connect an MCP client (like Kiro or ChatGPT) to the Para MCP server.
The AI tool calls MCP tools to orchestrate Para auth/wallet actions.
Humans can still see and debug everything via the Next.js UI in the browser.

How we use Kiro in this repo

Kiro is the AI development environment for this project, and it’s wired directly into multiple MCP servers via .kiro/settings/mcp.json.

That single JSON file tells Kiro which MCP servers are available when you’re working in this repo. In this project it looks roughly like this:

blockscout
- Configured with "url": "https://mcp.blockscout.com/mcp"
- Used for blockchain querying (token addresses, balances, transfers, etc.).
chrome-devtools
- Configured to run via:
- "command": "npx"
- "args": [ "chrome-devtools-mcp@latest", "--browser-url=http://127.0.0.1:9222" ]
- Lets the AI talk to a running Chrome instance through the DevTools protocol.
coinbase-cdp (currently disabled)
- Points at https://docs.cdp.coinbase.com/mcp.
- Intended for interacting with Coinbase Developer Platform from AI tooling.
context7
- Configured with "command": "npx" and "args": [ "-y", "@upstash/context7-mcp@latest" ].
- Used to fetch up-to-date documentation for libraries (e.g., shadcn, Next.js packages, etc.).
next-devtools
- Configured with "command": "npx" and "args": [ "-y", "next-devtools-mcp@latest" ].
- Helps the AI search and read official Next.js docs and, when applicable, talk to a running Next.js dev server.
para-docs
- Configured with "url": "http://docs.getpara.com/mcp".
- Allows the AI to search Para’s documentation directly from within Kiro.
sequential-thinking (disabled)
- Uses the @modelcontextprotocol/server-sequential-thinking package.
- Intended for more structured, multi-step reasoning on complex tasks.
tiger (disabled)
- Configured with "command": "tiger" and "args": [ "mcp", "start" ].
- Aimed at querying Postgres databases via MCP.

Because .kiro/settings/mcp.json lives alongside the code, anyone opening this repo in Kiro gets the same MCP setup automatically. The assistant knows:

How to talk to Para docs (para-docs)
How to introspect and control the browser (chrome-devtools)
How to pull in Blockscout, Context7, and Next.js-specific knowledge

…all without you manually wiring each tool in your editor.

In other words, Kiro + MCP turns this repo into an AI-first development environment:

The code defines your server and UI.
.kiro/settings/mcp.json defines your tool graph.
Kiro uses both to help you build, debug.

Demo

https://github.com/uratmangun/arbitrum-vibekit/tree/para-integration/typescript/community/mcp-tools/para-mcp-server

https://para-mcp-server.vercel.app/

Resume AI Creator: Building an Intelligent Resume Platform with MCP and Auth0

uratmangun — Sun, 19 Oct 2025 14:52:16 +0000

This is a submission for the Auth0 for AI Agents Challenge

What I Built

I built Resume AI Creator, an intelligent resume management platform that leverages the Model Context Protocol (MCP) to enable AI agents to create, manage, and optimize professional resumes through natural language conversations. The application solves the problem of tedious resume creation by allowing users to interact with AI agents that understand context and can intelligently structure work history, projects, and achievements.

The platform features:

AI-Powered Resume Creation: Natural language interface for building resumes via MCP tools
Structured Data Management: PostgreSQL database with relational tables for resumes, work history, projects, and achievements
Multi-Provider AI Support: Integration with OpenRouter, Google Gemini, and OpenAI for flexible AI capabilities
Secure Authentication: Auth0-based user authentication with session management
API Key Management: Secure storage and validation of API keys for external integrations
Real-time Updates: Modern React 19 UI with Next.js 15 App Router

Demo

Repository: GitHub - resume-ai-creator-mcp

Web demo: https://resume-chatgpt-apps.vercel.app/

The application exposes 6 MCP tools that AI agents can use:

create-resume - Create new resumes with structured data
update-resume - Modify existing resumes
get-resume - Retrieve resume details
list-resumes - List all user resumes
delete-resume - Remove resumes with cascading deletes
draft-create-resume - Preview resumes before creation

Tech Stack:

Next.js 15.3.5 with React 19
xmcp 0.3.4 for MCP server implementation
Drizzle ORM with PostgreSQL (Neon)
TailwindCSS 4.1 for styling
TypeScript 5.9 for type safety
Vercel AI SDK for multi-provider support

How I Used Auth0 for AI Agents

Auth0 plays a critical role in securing both the web application and the MCP server endpoints. Here's how I implemented it:

1. User Authentication Flow

I integrated Auth0's Next.js SDK (@auth0/nextjs-auth0) to handle user authentication:

Users authenticate via Auth0's Universal Login
Sessions are stored in encrypted HTTP-only cookies
The middleware validates sessions on every protected route

2. Protected MCP Endpoints

The MCP server runs as a Next.js API route, and I secured it using Auth0 middleware:

// middleware.ts
export async function middleware(request: NextRequest) {
  const protectedPaths = ['/api/resumes', '/api/api-keys', '/resumes'];
  const isProtected = protectedPaths.some(path => 
    request.nextUrl.pathname.startsWith(path)
  );

  if (isProtected) {
    const session = await auth0.getSession(request);
    if (!session) {
      return NextResponse.redirect(new URL('/api/auth/login', request.url));
    }
  }
}

3. User Context in MCP Tools

Each MCP tool extracts the authenticated user ID from the Auth0 session to ensure data isolation:

// src/tools/create-resume.ts
export async function handler(args: InferSchema<typeof schema>, extra: any) {
  const userId = getUserIdFromExtra(extra);

  const resume = await createResume({
    userId,
    name: args.name,
    title: args.title,
    // ... other fields
  });

  return { success: true, resumeId: resume.id };
}

4. Session Management

Auth0's session handling ensures:

Automatic token refresh for long-running AI agent sessions
Secure cookie storage with encryption
CORS support for cross-origin MCP requests
Graceful error handling with automatic re-authentication

The combination of Auth0's robust authentication and MCP's tool-based architecture creates a secure environment where AI agents can operate on behalf of authenticated users without compromising security.

Lessons Learned and Takeaways

Building this project taught me several valuable lessons about AI agents, authentication, and modern web development:

1. MCP is a Game-Changer for AI Integration

The Model Context Protocol provides a standardized way for AI agents to interact with applications. Instead of building custom APIs for each AI provider, MCP tools are universally accessible. The xmcp library made it incredibly easy to expose Next.js API routes as MCP endpoints with just a config file.

2. Authentication for AI Agents is Different

Traditional user authentication doesn't translate directly to AI agents. I learned to implement a dual authentication system:

User-facing: Auth0 for web UI and session management

3. Database Schema Design Matters

Using Drizzle ORM with a relational schema (resumes → work_history, projects, achievements) made it easy to structure complex resume data. The cascading deletes ensure data integrity, and TypeScript types generated from the schema eliminate runtime errors.

4. Challenges Faced

Session Cookie Issues: Auth0's encrypted cookies initially caused JWE errors. I fixed this by only validating sessions on protected routes, not on every request.
MCP Tool Parameter Validation: Ensuring AI agents pass correctly structured data required careful Zod schema design with descriptive field annotations.
Multi-Provider AI Support: Different AI providers have varying capabilities. Using the Vercel AI SDK abstracted these differences.

5. Key Insights

Fish Shell Syntax: Standardizing on Fish shell for all terminal commands improved consistency across development workflows.
Bun for Performance: Using Bun as the primary package manager significantly reduced install times and improved dev server startup.
Conventional Commits with Emojis: Implementing a structured commit message format (✨ feat, 🔧 fix, etc.) made the Git history much more readable.

6. Advice for Other Developers

Start with a clear database schema before building MCP tools
Use TypeScript everywhere—it catches errors before they reach production
Test MCP tools with multiple AI providers to ensure compatibility
Implement proper error handling in middleware to avoid cryptic authentication failures
Use Drizzle Studio (bun run db:studio) for visual database management during development

This project demonstrated that combining Auth0's enterprise-grade authentication with MCP's AI-native architecture creates powerful, secure applications that feel magical to use. The future of software is conversational, and tools like these are paving the way.

Securing AI Agents with Auth0: Complete MCP Server Implementation

uratmangun — Wed, 15 Oct 2025 13:54:36 +0000

This is a submission for the Auth0 for AI Agents Challenge

What I Built

I built Auth XMCP - Next.js, a secure Next.js application that provides OAuth-protected Model Context Protocol (MCP) endpoints using Auth0 authentication. This project demonstrates how to build a modern MCP server with enterprise-grade security and Next.js integration.

The application solves a critical problem in the AI ecosystem: secure communication between AI agents and external systems. As AI agents become more prevalent, they need secure ways to access resources, tools, and data. My solution provides:

🔐 OAuth Authentication: Secure MCP endpoints with Auth0 integration
🚀 Full MCP Server: Complete Model Context Protocol server with tools, resources, and prompts
⚡ Next.js 15: Built with the latest Next.js features including Turbopack
🛡️ JWT Verification: Robust token validation with JWKS support
🎨 Modern UI: Clean interface with TailwindCSS and dark mode support

Demo

https://github.com/uratmangun/auth-xmcp-nextjs/tree/auth0

https://auth-xmcp-nextjs.vercel.app

Technology Stack:

Next.js 15.5.2 with React 19.2.0
TypeScript 5.9.3 with full type safety
Auth0 NextJS SDK 4.10.0
XMCP 0.3.2 with Next.js adapter
TailwindCSS 4.1.14, Zod 3.24.4, jose 5.10.0

Key Features:

Secure MCP endpoint at /mcp requiring Auth0 JWT tokens
AI agent authentication flow via Auth0
MCP tools with parameter validation
Configuration and user resources
Code review prompts

How I Used Auth0 for AI Agents

Auth0 secures my MCP server through:

🔐 JWT Token Validation

Tokens verified against Auth0's JWKS
Claims validation for issuer and audience
Automatic middleware protection

🚀 OAuth Flow Integration

Client credentials flow for AI agents
Scoped tokens for MCP operations
Automatic token refresh

🛡️ Enterprise Security

RBAC for different agent permissions
Audit logging and rate limiting
Multi-factor authentication support

Lessons Learned and Takeaways

Key Challenges:

JWT integration with XMCP framework required careful middleware design
Ensuring end-to-end TypeScript safety
Working with bleeding-edge Next.js 15 features

Technical Insights:

AI agents need robust authentication from day one
Zod schemas prevent runtime errors in production
Next.js 15 + Turbopack provides excellent developer experience
Auth0's JWKS simplifies key rotation and certificate management

Advice for Developers:

Start with security - don't treat authentication as an afterthought
Use type safety with Zod + TypeScript
Leverage modern tools: Next.js 15, XMCP, and Auth0 work beautifully together
Test thoroughly - AI agent authentication requires comprehensive testing
Document everything for better integration

This project demonstrates that building secure, production-ready AI agent infrastructure is achievable with the right tools. The combination of Auth0 and MCP opens exciting possibilities for secure AI ecosystems.

Built with ❤️ using Next.js, XMCP, and Auth0

Deploy and Host remix-template on Railway

uratmangun — Sun, 10 Aug 2025 12:23:28 +0000

A modern Remix application template with TypeScript, Tailwind CSS, and Vite for fast development and production builds. This template provides a solid foundation for building full-stack React applications with server-side rendering capabilities.

One click deploy url

About Hosting remix-template

This Remix template is designed for seamless deployment on Railway's platform. It includes a production-ready server setup with remix-serve and builds optimized client and server bundles. The application uses Node.js 20+ and includes modern tooling like Vite for fast builds and hot module replacement during development.

Common Use Cases

Full-stack web applications with server-side rendering
Progressive web apps with enhanced user experience
API-driven applications with integrated frontend and backend
E-commerce platforms requiring SEO optimization
Content management systems with dynamic routing

Dependencies for remix-template Hosting

Runtime Requirements:

Node.js 20.0.0 or higher
Package manager: pnpm (preferred) or yarn fallback

Core Dependencies:

@remix-run/node, @remix-run/react, @remix-run/serve
React 18.2.0+ and React DOM
TypeScript for type safety
Tailwind CSS for styling

Deployment Dependencies

Build Process:

pnpm run build - Compiles the application for production
pnpm start - Starts the production server with remix-serve

Environment Variables:

PORT - Railway automatically provides this for server binding
Additional environment variables can be configured in Railway dashboard

Build Output:

build/server - Server-side code
build/client - Client-side assets

Using .kiro Automation (optional)

This template includes .kiro automation workflows for enhanced development experience:

Auto-commit and push workflows for streamlined version control
README generation to keep documentation up-to-date
Project scaffolding tools for rapid development setup
Steering rules for consistent code standards and package management

The .kiro configuration ensures pnpm usage with yarn fallback, maintains shell preferences, and provides automated workflows for common development tasks.

Why Deploy remix-template on Railway?

Seamless Deployment: Railway's git-based deployment automatically builds and deploys your Remix app with zero configuration. Simply connect your repository and Railway handles the rest.

Performance Optimized: Railway's global edge network ensures fast loading times for your server-rendered Remix applications, with automatic scaling based on traffic.

Developer Experience: Built-in environment variable management, automatic HTTPS, custom domains, and integrated monitoring make Railway ideal for Remix applications requiring both development speed and production reliability.

Cost Effective: Pay only for what you use with Railway's usage-based pricing, perfect for Remix apps that benefit from server-side rendering without the overhead of complex infrastructure management.

Github repo

uratmangun / remix-template

Remix SPA – Cloudflare Pages static deployment

Deploy and Host remix-template on Railway

One click deploy url

About Hosting remix-template

Common Use Cases

Full-stack web applications with server-side rendering
Progressive web apps with enhanced user experience
API-driven applications with integrated frontend and backend
E-commerce platforms requiring SEO optimization
Content management systems with dynamic routing

Dependencies for remix-template Hosting

Runtime Requirements:

Node.js 20.0.0 or higher
Package manager: pnpm (preferred) or yarn fallback

Core Dependencies:

@remix-run/node, @remix-run/react, @remix-run/serve
React 18.2.0+ and…

View on GitHub

Building an AI-Powered Repository Search with Redis 8 Vector Similarity

uratmangun — Mon, 04 Aug 2025 01:58:54 +0000

What I Built

I created a modern full-stack web application that combines React, Deno, and Redis 8 to deliver AI-powered semantic search capabilities for GitHub repositories. This isn't just another search tool - it's a smart repository discovery platform that understands the meaning behind your queries using vector embeddings and cosine similarity.

The application features a sleek React frontend with dark mode support, powered by a robust Deno backend that leverages Redis 8's advanced vector search capabilities. Users can add GitHub repositories to their collection and then search through them using natural language queries that go far beyond simple keyword matching.

Demo

🔗 Repository: My Awesome Boilerplate

The project showcases a complete implementation of vector similarity search using Redis 8, with features including:

AI-powered semantic search using nomic embeddings
Real-time repository management with GitHub API integration
Multiple search types (description, repository name, or combined embeddings)
Responsive design with Tailwind CSS and custom UI components
Secure authentication with Clerk

How I Used Redis 8

Redis 8 serves as the backbone of this application, going far beyond traditional caching to function as a primary vector database and search engine. Here's how I leveraged its advanced capabilities:

Vector Storage and Indexing

I used Redis 8's native vector field support to store three types of embeddings for each repository:

Description embeddings: 768-dimensional vectors from repository descriptions
Repository name embeddings: Semantic vectors from repository names
Combined embeddings: Unified vectors combining both description and name data

The Redis index schema supports both FLAT and HNSW algorithms:

// FLAT algorithm for precise similarity on smaller datasets
"$.descriptionEmbeddings" as descriptionEmbeddings VECTOR "FLAT" 6
    "TYPE" FLOAT32
    "DIM" 768
    "DISTANCE_METRIC" "COSINE"

// HNSW for faster approximate search on larger datasets
"$.combinedEmbeddings" as combinedEmbeddings VECTOR "HNSW" 8
    "TYPE" FLOAT32
    "DIM" 768
    "DISTANCE_METRIC" "COSINE"

Semantic Search Implementation

Instead of relying on Redis Search modules that might not be available in all environments, I implemented a custom vector similarity search using Redis 8's core operations:

Vector Generation: Using Google's Gemini embedding model to convert text queries into 768-dimensional vectors
Similarity Calculation: Computing cosine similarity between query vectors and stored repository embeddings
Ranking: Sorting results by similarity scores to surface the most relevant repositories

Multi-Modal Search Capabilities

The application supports three distinct search modes:

Description Search: Matches against repository description embeddings
Repository Search: Focuses on repository name semantics
Combined Search: Uses unified embeddings for comprehensive matching

Real-Time Data Management

Redis 8 handles all CRUD operations for repository data, storing complete JSON documents with embedded vectors. The hash-based storage pattern (item:*) enables efficient scanning and retrieval while maintaining data integrity.

Performance Optimization

By leveraging Redis 8's in-memory architecture, the application delivers sub-second search results even when processing complex vector calculations. The cosine similarity computations happen entirely in-memory, making the search experience incredibly responsive.

This implementation demonstrates Redis 8's evolution from a simple cache to a sophisticated vector database capable of powering modern AI applications. The combination of traditional Redis operations with advanced vector capabilities creates a powerful foundation for semantic search that scales beautifully.

Building a Redis AI Vector Search Boilerplate with Spec-Driven Development

uratmangun — Fri, 01 Aug 2025 03:29:00 +0000

Introduction

In the era of AI-powered applications, traditional keyword search feels increasingly outdated. Users expect search experiences that understand context and meaning, not just exact word matches. That's why I built this Redis AI Vector Search Boilerplate - a modern full-stack application that demonstrates how to implement intelligent semantic search using Redis vector similarity and Google GenAI embeddings.

What is Redis AI Vector Search Boilerplate?

This project is a comprehensive boilerplate that enables developers to quickly implement AI-powered semantic search in their applications. Instead of searching for exact keywords, users can ask natural language questions like "How to implement real-time chat?" and get relevance-ranked results that understand the intent behind their query.

The application combines the power of Redis for high-performance vector storage, Google GenAI for generating text embeddings, and modern web technologies to create a seamless search experience. It's designed as both a functional application and an educational resource for developers wanting to understand vector similarity search.

Tech Stack & Architecture

The project leverages a modern serverless architecture with carefully chosen technologies:

Frontend Technologies

React 19 - Latest React features for modern UI development
TypeScript - Type safety throughout the application
Tailwind CSS - Utility-first styling with dark/light theme support
Vite - Fast build tool and development server
Radix UI - Accessible component primitives

Backend Technologies

Deno - Modern JavaScript/TypeScript runtime for serverless functions
Redis - Vector database for high-performance similarity search
Google GenAI - Text embedding generation for semantic understanding

Development Tools

Kiro AI - Spec-driven development and automation
ESLint - Code quality and consistency
pnpm - Fast package management

Development Methodology: Kiro Specifications

This project follows spec-driven development using Kiro AI specifications, which proved instrumental in maintaining code quality and project coherence. The methodology involves three core components:

Requirements: User stories and acceptance criteria for each feature
Design: Technical architecture and implementation approach
Tasks: Discrete, trackable implementation steps

Specifications Created:

Redis AI Boilerplate - Core application functionality with semantic search interface
Cloudflare-Deno Integration - Seamless deployment pipeline for full-stack serverless architecture
Item Deletion - CRUD operations with proper error handling and user feedback
Deno Server Polish - Performance optimization and production readiness

Each specification follows the EARS (Easy Approach to Requirements Syntax) format, ensuring clear, testable requirements that guide implementation decisions.

Key Features

Semantic Search: Natural language queries powered by 768-dimensional vector embeddings
Real-time CRUD Operations: Add, search, retrieve, and delete items with instant feedback
Vector Similarity Scoring: Cosine similarity calculations for relevance ranking
Multi-platform Deployment: Compatible with Deno Deploy and Cloudflare Pages
Responsive Design: Modern UI with dark/light theme support
Development Automation: 23 Kiro hooks for workflow automation

Demo

uratmangun / redis-boilerplate

Redis AI Vector Search Boilerplate

A modern full-stack application demonstrating AI-powered semantic search using Redis vector similarity, built with React, TypeScript, and Deno. This project showcases how to implement intelligent search functionality with text embeddings and vector databases.

🚀 Features

AI Semantic Search: Natural language queries powered by Google GenAI embeddings
Vector Similarity: Redis-based vector search with cosine similarity
Real-time UI: Modern React interface with dark/light theme support
Serverless Ready: Deno Deploy and Cloudflare Pages compatible
Full CRUD Operations: Add, search, retrieve, and delete items
Responsive Design: Mobile-friendly interface with Tailwind CSS
Type Safety: Full TypeScript implementation across frontend and backend

🛠 Tech Stack

Frontend

React 19 - Modern UI library with latest features
TypeScript - Type-safe development
Tailwind CSS - Utility-first styling
Vite - Fast build tool and dev server
React Router - Client-side routing
Radix UI - Accessible component primitives

Backend

…

View on GitHub

Getting Started

Setting up the project is straightforward with the provided configuration:

# Clone the repository
git clone https://github.com/uratmangun/redis-boilerplate.git
cd redis-boilerplate

# Install dependencies
pnpm install

# Configure environment
cp .env.example .env
# Edit .env with your Redis URL and Google AI API key

# Start development servers
pnpm dev

The application supports various Redis providers including local development, Upstash for serverless deployments, Redis Cloud, and Railway.

Conclusion

Building this Redis AI Vector Search Boilerplate was an enlightening journey into the intersection of AI and modern web development. The combination of vector similarity search, serverless architecture, and spec-driven development created a robust foundation for intelligent applications.

The project demonstrates that implementing AI-powered features doesn't have to be complex - with the right architecture and tools, developers can create sophisticated search experiences that truly understand user intent.

Technical Deep Dive

Project Structure

The codebase is organized for clarity and maintainability:

src/components/ - React UI components with TypeScript
functions/ - Deno serverless functions for API endpoints
utils/ - Shared utilities for Redis operations and text embeddings
.kiro/specs/ - Comprehensive development specifications
.kiro/hooks/ - Automated development workflows

Key Dependencies

@google/generative-ai - Google GenAI for text embeddings
redis - Redis client for Deno
react - UI framework with latest features
tailwindcss - Utility-first CSS framework
@radix-ui/react-slot - Accessible component primitives

Development Workflow

The spec-driven approach with Kiro AI enabled systematic feature development:

Requirements gathering with user stories and acceptance criteria
Technical design with architecture decisions and trade-offs
Implementation through discrete, trackable tasks
Automated documentation and workflow management through hooks

This methodology proved invaluable for maintaining project coherence and ensuring all features met their intended requirements while providing clear progress tracking throughout development.

Building AI-Powered Semantic Search with Redis Vector Similarity and Deno

uratmangun — Fri, 01 Aug 2025 03:27:54 +0000

What I Built

I created a modern full-stack application that demonstrates the power of AI-driven semantic search using Redis vector similarity. This isn't your typical keyword-based search - it understands the meaning behind queries and finds relevant content even when exact words don't match.

The application combines a sleek React frontend with a Deno-powered backend, creating a seamless experience for adding, searching, and managing content. Users can perform natural language queries like "machine learning algorithms" and get relevant results even if the stored content uses terms like "AI models" or "neural networks."

Key features include:

Semantic Search: Natural language queries powered by Google GenAI embeddings
Real-time Interface: Modern React UI with dark/light theme support
Serverless Architecture: Built for Deno Deploy and Cloudflare Pages
Full CRUD Operations: Complete item management with vector-powered search
Multiple Search Types: Search by title, content, or combined embeddings

Demo

🔗 Repository: Redis AI Vector Search Boilerplate

The project showcases a complete implementation with:

React 19 frontend with TypeScript and Tailwind CSS
Deno serverless functions for the API layer
Redis vector database with cosine similarity search
Google GenAI for text embedding generation

How I Used Redis 8

Redis serves as the primary database and search engine in this application, going far beyond traditional caching. Here's how I leveraged Redis 8's advanced capabilities:

Vector Database Implementation

The core innovation lies in using Redis as a vector database. Each piece of content gets converted into 768-dimensional embeddings using Google GenAI, then stored in Redis alongside the original text:

// Store embeddings in Redis hash
await redis.hset(itemKey, {
  title: item.title,
  content: item.content,
  titleEmbeddings: JSON.stringify(titleEmbeddings),
  contentEmbeddings: JSON.stringify(contentEmbeddings),
  combinedEmbeddings: JSON.stringify(combinedEmbeddings)
});

Cosine Similarity Search

Instead of relying on Redis Search modules, I implemented cosine similarity calculations directly in the application layer. This approach ensures compatibility across different Redis deployments while maintaining high performance:

// Calculate cosine similarity between query and stored embeddings
let dotProduct = 0;
let queryMagnitude = 0;
let storedMagnitude = 0;

for (let i = 0; i < queryEmbedding.length; i++) {
  dotProduct += queryEmbedding[i] * storedEmbeddings[i];
  queryMagnitude += queryEmbedding[i] * queryEmbedding[i];
  storedMagnitude += storedEmbeddings[i] * storedEmbeddings[i];
}

const similarity = dotProduct / (Math.sqrt(queryMagnitude) * Math.sqrt(storedMagnitude));

Multi-Modal Search Strategy

The application supports three distinct search modes:

Title Search: Searches only in document titles using title-specific embeddings
Content Search: Searches only in document content using content-specific embeddings
Combined Search: Searches across both title and content using merged embeddings

This flexibility allows users to fine-tune their search strategy based on their needs.

Scalable Data Architecture

Redis handles the complete data lifecycle:

Storage: Items stored as Redis hashes with structured fields
Indexing: Vector embeddings stored as JSON strings for efficient retrieval
Search: Scan operations combined with in-memory similarity calculations
Management: Full CRUD operations with automatic timestamp tracking

Performance Optimizations

The implementation includes several Redis-specific optimizations:

Batch Operations: Using Redis pipelines for bulk operations
Memory Efficiency: Storing embeddings as compressed JSON strings
Connection Pooling: Efficient Redis connection management in serverless functions
Scan Patterns: Using Redis SCAN for memory-efficient key iteration

Beyond Traditional Use Cases

This project demonstrates Redis 8's evolution from a simple cache to a sophisticated data platform:

Primary Database: Redis serves as the main data store, not just a cache layer
Vector Search Engine: Handles complex similarity calculations at scale
Real-time Operations: Supports instant search results with sub-second response times
Serverless Compatibility: Works seamlessly with modern deployment platforms

The result is a powerful, scalable search system that understands context and meaning, making it perfect for applications like documentation search, content discovery, recommendation engines, and knowledge bases.

Built with Redis 8, Deno, React, and Google GenAI - showcasing the future of intelligent search applications.

Cloudflare Pages + Deno Deploy Full-Stack Boilerplate

uratmangun — Tue, 29 Jul 2025 13:43:59 +0000

Introduction

Building modern full-stack applications requires seamless integration between frontend and backend services, especially when targeting edge computing platforms. This project demonstrates a production-ready boilerplate that combines React with Deno serverless functions, optimized for Cloudflare Pages and Deno Deploy.

What is Cloudflare Pages + Deno Deploy Boilerplate?

This is a comprehensive full-stack application template that bridges the gap between modern frontend development and serverless backend architecture. The project provides a complete development environment with React 19 frontend, Deno-powered serverless functions, and automated deployment pipelines to edge computing platforms.

The boilerplate eliminates the complexity of setting up cross-platform integrations by providing pre-configured tooling, automated CI/CD workflows, and a seamless development experience that works both locally and in production.

Tech Stack & Architecture

Frontend Technologies

React 19 - Latest version with modern hooks and concurrent features
TypeScript - Full type safety across the entire application
Vite - Lightning-fast build tool and development server
Tailwind CSS - Utility-first CSS framework for rapid styling
shadcn/ui - Beautiful, accessible, and customizable UI components
Radix UI - Headless UI primitives for accessibility
Lucide React - Beautiful icon library

Backend Technologies

Deno Runtime - Modern JavaScript/TypeScript runtime for serverless functions
Function Router - Automatic routing system for multiple serverless functions
CORS Support - Pre-configured for cross-origin requests

Development & Deployment Tools

pnpm - Efficient package manager with strict dependency resolution
Cloudflare Pages - Global CDN with edge computing capabilities
Deno Deploy - Serverless functions at the edge
GitHub Actions - Automated CI/CD pipeline
Concurrently - Run multiple development servers simultaneously

Development Methodology: Kiro Specifications

This project follows spec-driven development using Kiro specifications, which provide a structured approach to building complex features through three core documents:

Requirements: User stories and acceptance criteria for each feature
Design: Technical architecture and implementation approach
Tasks: Discrete, trackable implementation steps

Specifications Created:

Cloudflare & Deno Integration Specification

This comprehensive specification guided the entire development process:

Requirements Phase: Defined four core user stories covering Cloudflare Pages integration, Deno serverless functions, local development environment, and automated deployment pipeline. Each requirement included specific acceptance criteria using WHEN/THEN format to ensure clear, testable outcomes.

Design Phase: Established the technical architecture with a clear component diagram showing the relationship between React frontend, Deno function router, and deployment platforms. The design emphasized performance optimization, security considerations, and scalability patterns.

Implementation Phase: Broke down development into 11 discrete tasks covering setup, development, deployment, testing, and documentation. All tasks were completed successfully, demonstrating the effectiveness of the spec-driven approach.

The specification methodology ensured systematic development with clear milestones, comprehensive testing, and thorough documentation throughout the project lifecycle.

Key Features

Seamless Full-Stack Integration: React frontend communicates effortlessly with Deno serverless functions through an intelligent endpoint detection system that works in both development and production environments.
Edge-Optimized Deployment: Leverages Cloudflare's global CDN for frontend delivery and Deno Deploy's edge computing for serverless functions, ensuring minimal latency worldwide.
Developer Experience Excellence: Hot-reload development environment with concurrent React and Deno servers, TypeScript throughout the stack, and modern tooling integration.
Production-Ready CI/CD: Automated GitHub Actions workflow that deploys frontend to Cloudflare Pages and backend to Deno Deploy with environment variable synchronization.
Modern UI Components: Built with shadcn/ui and Radix UI primitives, providing accessible, customizable components with dark/light theme support.

Demo

uratmangun / cloudflare-deno-kiro

Cloudflare Pages + Deno Deploy Full-Stack Boilerplate

A modern, production-ready full-stack application combining React frontend with Deno serverless functions, optimized for Cloudflare Pages and Deno Deploy. Features automated CI/CD, Kiro AI assistant integration, and comprehensive development tooling.

✨ Features

Frontend

React 19 - Latest version with modern hooks and concurrent features
TypeScript - Full type safety and better development experience
Vite - Lightning-fast build tool and development server
Tailwind CSS - Utility-first CSS framework for rapid styling
shadcn/ui - Beautiful, accessible, and customizable UI components
Dark/Light Theme - Built-in theme switching with system preference detection

Backend

Deno Runtime - Modern JavaScript/TypeScript runtime for serverless functions
Function Router - Automatic routing system for multiple serverless functions
CORS Support - Pre-configured for cross-origin requests
Hot Reload - Local development with automatic server restart
Edge Functions - Serverless functions deployed at the edge for low latency

Deployment & Automation

Cloudflare Pages - Global…

View on GitHub

Getting Started

Prerequisites

Node.js 18+ for React development
Deno 2.x for serverless functions
pnpm package manager (yarn as fallback)

Quick Setup

# Create from template
gh repo create my-project --template uratmangun/cloudflare-deno-kiro --public --clone
cd my-project

# Install dependencies
pnpm install

# Start development servers
pnpm dev

This starts both the React app at http://localhost:5173 and Deno server at http://localhost:8000.

Available Scripts

pnpm dev - Start both React and Deno servers concurrently
pnpm build - Build React app for production
pnpm lint - Lint code with ESLint
deno task dev - Run Deno server with hot-reload

Conclusion

This project demonstrates how spec-driven development with Kiro can streamline complex full-stack integrations. The systematic approach of defining requirements, designing architecture, and implementing discrete tasks resulted in a robust, production-ready boilerplate.

The combination of modern web technologies with edge computing platforms creates a powerful foundation for building scalable applications. The automated deployment pipeline and comprehensive development environment make it easy for teams to adopt and customize for their specific needs.

Technical Deep Dive

Project Structure

├── src/                     # React frontend
│   ├── components/ui/       # shadcn/ui components
│   ├── contexts/           # React context providers
│   └── App.tsx             # Main application
├── functions/              # Deno serverless functions
│   └── hello.ts           # Example function
├── main.ts                # Deno function router
├── server.ts              # Local development server
└── .github/workflows/     # CI/CD pipeline

Key Dependencies

Frontend: React 19, TypeScript, Vite, Tailwind CSS, shadcn/ui
Backend: Deno runtime with standard library modules
Development: Concurrently, ESLint, TypeScript compiler
Deployment: GitHub Actions, Cloudflare Pages, Deno Deploy

Development Workflow

Local Development: Concurrent React and Deno servers with hot-reload
Function Creation: Add new functions in /functions directory and register in main.ts
API Integration: React app automatically detects and calls appropriate endpoints
Deployment: Push to main branch triggers automated deployment to both platforms
Environment Sync: GitHub Actions automatically configures environment variables

The spec-driven approach ensured each component was thoroughly planned, implemented, and tested, resulting in a cohesive and maintainable codebase ready for production use.

🚀 Ready for production • ⚡ Lightning fast • 🌍 Global deployment • 🔧 Fully customizable

Built with modern web technologies for the edge computing era.

DEV Community: uratmangun

Building a Next.js Template Clone Generator: A Complete Guide to Streamlining Your Development Workflow with Kiro

Introduction

The Problem We're Solving

Project Overview

Deep Dive into the Code

The Component Structure

Input Validation

Dynamic Command Generation

Copy to Clipboard Functionality

The User Interface

Responsive Design

Input Field with Validation Feedback

The Command Display

Kiro Integration

Steering Rules

Agent Hooks

How to Use the Template

Prerequisites

Step-by-Step Guide

Technical Decisions and Trade-offs

Why GitHub CLI Instead of a Web API?

Why Client-Side Rendering?

Color Palette Choices

Extending the Template

Adding More Options

Supporting Multiple Templates

Adding Analytics

Best Practices Demonstrated

1. Accessibility

2. Type Safety

3. User Feedback

4. Dark Mode Support

Conclusion

Resources

Try It Yourself

Build Linera dApps Fast with This Next.js Template

What is Linera?

The Problem

Features

Quick Start

Project Structure

Available Scripts

Tech Stack

Key Technical Details

Get Started

Demo

Building a Gasless Marketplace on Polygon with x402 Protocol

The Problem

The Solution: x402 Protocol

Tech Stack

Key Features

Gasless USDC Payments

Product Listings

Wallet Integration

Implementation Highlights

The Facilitator Proxy

Using x402-axios

Live Demo

What's Next

How We Used Kiro in This Project

Steering Rules

MCP Configuration

Demo

Freelancing Reimagined: Total Autonomy with Massa Smart Contracts

Introduction

Why Massa Freelance?

1. Verified Proof of Funds

2. Autonomous Payments

3. Total Flexibility

Under the Hood

How We Use @[.kiro]

🛠️ Developer Guide: Deploying & Interacting with Smart Contracts

1. The Autonomous Smart Contract (assembly/contracts/autonomous.ts)

2. Compiling & Deploying

3. Interacting with the Contract

Demo

Building a Para MCP Server + Next.js Wallet Demo (with Kiro + MCP)

para-mcp-server in one sentence

What this project gives you

1. The Autonomous Smart Contract (`assembly/contracts/autonomous.ts`)