DEV Community: Zntb

I Built a Drag-and-Drop GitHub Profile README Builder with Next.js 16 & React 19

Zntb — Tue, 31 Mar 2026 05:34:11 +0000

A deep-dive into building a fully visual, self-hosted README builder — covering architecture decisions, the self-hosted stats API, drag-and-drop with dnd-kit, and how the block system works.

Your GitHub profile README is often the first thing a recruiter, collaborator, or open-source maintainer sees. It's prime real estate — yet most developers either leave it blank or spend an afternoon wrestling with raw Markdown, hunting for widget URLs, and tweaking layouts by trial and error.

I wanted to fix that. So I built GitHub Profile README Builder: a fully visual, drag-and-drop editor where you configure your profile in a live preview canvas and export a production-ready README.md in one click.

🔗 Live Demo

⭐ GitHub Repo

What It Does

Drag-and-drop canvas — reorder blocks effortlessly with smooth dnd-kit animations
25+ block types — headings, paragraphs, skill icons, social badges, typing animations, collapsibles, code blocks, GitHub stats cards, activity graphs, trophies, visitor counters, quotes, and more
65+ themes — Tokyo Night, Dracula, Catppuccin Mocha, Nord, Gruvbox, GitHub Dark, and many others
11 starter templates — Animated Developer, Full Stack Engineer, Data Scientist, DevOps / Cloud, Student, Cybersecurity Researcher, Game Developer, and more
Live preview — renders as close to GitHub's actual display as possible
Self-hosted GitHub Stats API — your own Next.js route handlers generate stat SVGs, so no third-party rate limits
One-click export — copy to clipboard or download README.md
Fully responsive — a dedicated layout for desktop, tablet, and mobile

Tech Stack

Frontend     Next.js 16 (App Router) · React 19 · TypeScript 5
Styling      Tailwind CSS v4 · tw-animate-css · shadcn/ui (radix-nova)
State        Zustand 5
DnD          dnd-kit (sortable)
Icons        Lucide React
Theming      next-themes
Toasts       Sonner
API          Next.js Route Handlers · GitHub REST & GraphQL APIs
Fonts        Outfit · JetBrains Mono

Architecture: The Block System

The entire editor is built around a simple, composable block model. Every element on the canvas is a Block:

export interface Block {
  id: string;
  type: BlockType;
  props: Record<string, unknown>;
  children?: Block[];
}

BlockType is a union of all supported block types — from layout primitives like 'container' and 'spacer' to GitHub-specific widgets like 'stats-card' and 'activity-graph'. The children field enables nested blocks (collapsible sections, containers, stats rows).

Adding a New Block

The pattern is deliberate and consistent. Adding a new block type takes about 10 minutes:

Add the type to the BlockType union in lib/types.ts
Define defaultProps in BLOCK_CATEGORIES (used by the sidebar)
Add a canvas preview in components/builder/block-preview.tsx
Add config fields in components/builder/config/block-config-fields.tsx
Add a live preview render in components/builder/live-preview.tsx
Add a Markdown render case in lib/markdown.ts

This separation of concerns keeps each concern focused and testable.

The Self-Hosted Stats API

Most README stat widgets depend on external services with rate limits. Instead, the builder ships its own route handlers that generate stat SVGs server-side using your GITHUB_TOKEN:

GET /api/stats      → GitHub stats card SVG
GET /api/streak     → Streak stats SVG
GET /api/top-langs  → Top languages SVG
GET /api/activity   → 30-day contribution graph SVG
GET /api/trophies   → Trophy grid SVG
GET /api/quotes     → Random dev quote SVG

All routes hit the GitHub GraphQL API, apply theme colors, and return inline SVGs. A simple in-memory cache (5-minute TTL) prevents hammering the API on every preview refresh:

class GitHubCache {
  private cache = new Map<string, CacheEntry<unknown>>();
  private readonly ttl: number;

  get<T>(key: string): T | null {
    const entry = this.cache.get(key);
    if (!entry) return null;
    if (Date.now() - entry.timestamp > this.ttl) {
      this.cache.delete(key);
      return null;
    }
    return entry.data as T;
  }
}

When you export your README, URLs point to your deployed instance — so the stat images are always live and under your control.

Drag and Drop with dnd-kit

The canvas uses @dnd-kit/sortable for block reordering. Blocks are wrapped in a useSortable hook, giving each one a stable drag handle and smooth CSS transforms during drag:

const { attributes, listeners, setNodeRef, transform, transition, isDragging } =
  useSortable({
    id: block.id,
  });

const style: React.CSSProperties = {
  transform: CSS.Transform.toString(transform),
  transition,
};

The PointerSensor has an activation constraint of 8px to prevent accidental drags when clicking to select a block:

useSensor(PointerSensor, {
  activationConstraint: { distance: 8 },
}),

Markdown Rendering

The renderMarkdown function in lib/markdown.ts walks the block array and converts each block to its Markdown equivalent. The interesting case is adjacent half-width stats cards — these need to be grouped into a single <div align="center"> row:

if (imageTag && isHalfWidthCard(block)) {
  const nextBlock = blocks[i + 1];
  const nextImageTag =
    nextBlock && isHalfWidthCard(nextBlock)
      ? getHalfWidthCardImageTag(nextBlock, origin)
      : null;

  if (nextImageTag) {
    rendered.push(
      `<div align="center">\n` +
        `  <img src="..." width="50%" alt="GitHub Stats" />\n` +
        `  <img src="..." width="50%" alt="Top Languages" />\n` +
        `</div>`,
    );
    i += 1; // skip the next block — it's already rendered
    continue;
  }
}

This produces clean, side-by-side stat cards in the exported Markdown without any wrapper framework.

State Management with Zustand

The builder state lives in a single Zustand store. Only the username field is persisted to localStorage — the block canvas resets on refresh by design (to keep things simple and avoid stale state bugs):

export const useBuilderStore = create<BuilderState>()(
  persist(
    (set, get) => ({
      blocks: [],
      selectedBlockId: null,
      username: '',
      // ...actions
    }),
    {
      name: 'github-readme-builder-storage',
      partialize: (state) => ({ username: state.username }),
    },
  ),
);

Store actions handle deeply nested operations like removeBlock and updateBlock, which recursively walk the children tree to find and update the target block.

Testing

The project uses Jest with ts-jest for unit tests covering:

lib/markdown.ts — every block type's Markdown output, including complex scenarios like adjacent half-width cards and stats-row children
lib/github.ts — calculateStreakStats, calculateRank, fetchUserStats, fetchLanguageStats, and more
lib/store.ts — all store actions including nested block operations
lib/themes.ts — theme resolution and alias handling

A pre-commit hook runs the full test suite, ESLint, Prettier format check, and TypeScript type-check before every commit.

Responsive Layout

The builder uses three distinct layouts:

Desktop (lg+): fixed left sidebar (block library) + scrollable canvas + fixed right panel (config or preview)
Tablet (md–lg): canvas fills the screen, sidebar and config panel open as Sheet overlays triggered by floating buttons
Mobile: a bottom tab bar switches between Blocks, Canvas, and Preview views; the config panel slides up as a bottom sheet

What's Next

A few things on the roadmap:

Undo/redo — the block array is already serializable, so it's a natural fit for a history stack
Custom block templates — save your own configured blocks for reuse
More block types — GitHub language badges, contribution heatmaps, Spotify now-playing, etc.
Custom Theme Builder - Allow users to create custom themes beyond the 65+ pre-built options with a visual color picker for stats cards, borders, and backgrounds.

Try It

🔗 Live demo: github-profile-maker.vercel.app

⭐ Star the repo: github.com/zntb/github-profile-maker

The project is MIT-licensed and contributions are welcome. If you add a new block type or template, open a PR — I'd love to include it.

Questions, feedback, or ideas? Drop them in the comments. 👇

Adding 2FA to OAuth Logins in Next.js 16 with Better Auth

Zntb — Tue, 27 Jan 2026 07:17:59 +0000

OAuth providers like Google and GitHub are excellent for reducing friction during onboarding. They handle the identity verification so you don't have to. The challenge arises when you want to add an extra layer of security, like Two-Factor Authentication (2FA), to these accounts.

Most standard 2FA implementations rely on a password confirmation step to enable or disable settings. OAuth users don't have a local password. This creates a gap in the security flow.

I recently implemented a solution using better-auth in a Next.js 16 application that bridges this gap. It allows OAuth users to enable TOTP (Time-based One-Time Password) and manage trusted devices without needing a password fallback.

Here is how I structured the architecture.

The Core Concept

We need to treat OAuth 2FA differently from standard email/password 2FA. Since we cannot validate a password, we validate the active OAuth session. The flow relies on three main parts:

A custom API route to handle TOTP logic.
A modified OAuth callback to intercept logins.
Client components to handle the verification UX.

The Backend Logic

The heavy lifting happens in a custom route handler. I created src/app/api/auth/oauth-two-factor/route.ts. This endpoint acts as a dispatcher for 2FA actions specifically for social login users.

It handles enabling 2FA, verifying the code, and generating backup codes.

// src/app/api/auth/oauth-two-factor/route.ts

// Enabling 2FA
const result = await enableTwoFactorForOAuthUser(userId, issuer);

// Verifying a code
const isValid = await verifyTotpForOAuthUser(userId, code);

// Generating backup codes
const backupCodes = await generateBackupCodesForOAuthUser(userId);

These functions, located in src/lib/two-factor.ts, interact directly with the database. They store secrets in an encrypted format and ensure backup codes are generated securely.

Intercepting the Login

When a user logs in via Google, better-auth handles the callback. We need to hook into this process. I modified src/app/api/auth/oauth-callback/route.ts.

We check the user's profile immediately after authentication. If twoFactorEnabled is true, we pause. We check if the current device is "trusted" via a cookie.

// src/app/api/auth/oauth-callback/route.ts

if (user?.twoFactorEnabled && user?.trustedDeviceEnabled) {
  // If trusted, set the verification cookie and let them in
  response.cookies.set('two-factor-verified', 'true', {...});
} else {
    // If not trusted or no cookie, redirect to verification page
}

This logic ensures that a user with 2FA enabled cannot bypass the second step unless they have previously verified the specific device.

The Verification UI

The user gets redirected to src/app/auth/verify-2fa/page.tsx if a check is required. This page is a server component that validates the session exists before loading the client form.

The client component, verify-2fa-client.tsx, handles the user input. It sends the TOTP code to our custom API route.

// src/components/two-factor-verify-form.tsx

const response = await fetch('/api/auth/oauth-two-factor', {
  method: 'POST',
  body: JSON.stringify({
    action: 'verify',
    code: verificationCode,
  }),
});

If the API returns success, we set a two-factor-verified cookie. This cookie acts as the "proof" that the second factor was passed. The user is then redirected to their dashboard.

Enabling 2FA on the Profile

We also need a way for users to turn this feature on. Inside the user profile, I added a component that generates a QR code.

Since we don't ask for a password, we rely on the active session. When the user clicks "Enable", we hit the API.

// src/components/two-factor-enable-form.tsx

const response = await fetch('/api/auth/oauth-two-factor', {
  method: 'POST',
  body: JSON.stringify({
    action: 'enable',
    issuer: 'Next.js Better Auth',
  }),
});

The server returns a secret and a QR code URL. The user scans it, enters a code to confirm, and the database updates to reflect that 2FA is now active.

Trusted Devices

Repeatedly entering codes is annoying. To solve this, we implemented a toggle for "Trusted Devices".

When verification is successful, the user can choose to trust the device. This sets a long-lived cookie (usually 30 days). The OAuth callback looks for this cookie on subsequent logins. If present and valid, it bypasses the manual code entry.

// src/components/trusted-device-toggle.tsx

const response = await fetch('/api/auth/oauth-two-factor', {
  method: 'POST',
  body: JSON.stringify({
    action: 'toggleTrustedDevice',
    enable: newValue,
  }),
});

Security Considerations

This flow maintains high security standards. All API routes require an active session. You cannot hit the 2FA endpoints without being logged in first.

Secrets are stored encrypted. Backup codes are single-use; they are regenerated whenever a user requests new ones. The cookies used for trusted devices are HTTP-only and Secure, preventing client-side script access.

Summary

By decoupling the 2FA logic from password validation, we allow OAuth users to enjoy the same security benefits as email/password users. The combination of custom route handlers and session checks in Next.js 16 provides a robust solution.

nextjs #authentication #typescript #websecurity

Developer Toolkit Pro

Zntb — Tue, 06 Jan 2026 12:34:52 +0000

🚀 Introducing Developer Toolkit Pro: A Comprehensive Suite of Developer Utilities

Website
X
Email

Hey dev community! 👋

I've been working on a project that I think many of you will find useful: Next.js Dev Tools – a collection of 50+ developer utilities built with Next.js 16, React 19, and Tailwind CSS.

What's Inside?

The platform includes tools for virtually every development workflow:

🔧 Code & Development Tools

API Client – Test and debug APIs with a clean interface
Code Playground – Write and execute code snippets
Code Diff Checker – Compare code changes visually
Regex Tester – Test and debug regular expressions
JSON Formatter/Validator – Format, validate, and prettify JSON
SQL Formatter – Beautify your SQL queries

🎨 CSS & Design Tools

CSS Animations Generator – Create smooth animations with preview
Box Shadow Generator – Generate perfect box shadows
Neumorphism Generator – Create neumorphic UI elements
Flexbox Generator – Visual flexbox layout builder
Grid Generator – CSS Grid layout generator
Gradient Generator – Beautiful gradient creator
Color Palette – Generate and manage color schemes
Clip Path Generator – Create complex CSS clip-paths
CSS to Tailwind Converter – Convert CSS to Tailwind classes

🔐 Security & Encoding Tools

Hash Generator – Generate MD5, SHA-1, SHA-256, SHA-512 hashes
Base64 Encoder/Decoder – Encode and decode Base64
URL Encoder – URL-safe encoding/decoding
JWT Decoder – Decode and analyze JWT tokens
BCRYPT Generator – Generate secure password hashes

🔢 Conversion & Calculation Tools

Number Base Converter – Convert between binary, decimal, hex, octal
PX to REM Converter – Convert pixel values to REM
CSV to JSON Converter – Convert CSV data to JSON
JSON to TypeScript – Generate TypeScript interfaces from JSON
YAML to JSON Converter – Convert YAML to JSON
Unix Timestamp Converter – Convert timestamps

🖼️ Image Tools

Image Resizer – Resize images easily
Image Format Converter – Convert between formats
SVG to JSX – Convert SVG to React JSX
SVG Optimizer – Optimize SVG files
Favicon Generator – Generate favicons for all platforms
QR Generator – Create QR codes
Placeholder Generator – Generate placeholder images
JSX to Image – Convert JSX to images

📊 Analysis & Debugging Tools

SEO Audit – Analyze pages for SEO issues
Web Vitals Calculator – Calculate Core Web Vitals scores
Tech Stack Detector – Detect technologies used by websites
HTTP Status Lookup – Quick reference for HTTP status codes
WCAG Contrast Checker – Check color contrast for accessibility
Hex Compare – Compare hex colors

🔄 Version Control & DevOps Tools

Git Command Generator – Generate Git commands from UI
Docker Compose Builder – Visual Docker Compose editor
GitHub Repo Analyzer – Analyze GitHub repositories
Cron Calculator – Understand and test cron expressions

📝 Content & Documentation Tools

Markdown Editor – Full-featured markdown editor
Mermaid Diagram Generator – Create flowcharts and diagrams
README Generator – Generate professional README files
Lorem Ipsum Generator – Generate placeholder text
Data Generator – Generate mock data

🌐 GraphQL & API Tools

GraphQL Generator – Generate GraphQL schemas and queries
WebSocket Tester – Test WebSocket connections
Case Converter – Convert text case (camel, snake, kebab, etc.)

💾 Storage & Data Tools

Storage Inspector – Inspect browser storage
Text Difference – Compare text differences

Tech Stack

Framework: Next.js 15 (App Router)
UI Library: React 19
Styling: Tailwind CSS
State Management: Zustand
Code Editor: Monaco Editor
Charts: Recharts
Theme: Dark/Light mode support
Components: Radix UI primitives
Animations: Framer Motion

Try It Out! 🧪

I'm launching this project and would love your help to make it better!

How You Can Help:

Test the tools – Try out any of the 50+ utilities
Report bugs – Found something broken? Let me know!
Suggest features – What tools would you like to see?
Share feedback – UI/UX improvements, performance tips

Access the Application

🌐 Next.js Dev Tools – Start exploring now!

What's Next?

This is just the beginning. I have plans to:

Add more tools based on community feedback
Improve performance and accessibility
Add keyboard shortcuts for power users
Implement tool favorites and history
Create tool collections/workflows

Let's Connect!

Have ideas for new tools or found a bug? Drop a comment below or reach out!

#WebDev #NextJS #DeveloperTools #OpenSource #React

Note: This project is currently in active development. Your feedback and suggestions are invaluable in shaping its future!