Forem: Miracleio

Meet Zhu Li: The AI Agent That Manages Your Notion Workspace From Any Channel

Miracleio — Sat, 28 Mar 2026 23:06:15 +0000

This is a submission for the Notion MCP Challenge

Here's how a typical interaction looks:

Me: hey, I just deployed a fix for the payment button issue on iOS Safari

Zhu Li: Got it. I found the issue in your Notion workspace — marking it resolved now
        and linking it to your latest commit. Done. Your changelog has been updated
        with a note about the fix. Anything else?

That exchange is the core promise of Zhu Li: an AI project operations assistant that turns plain-language messages into real work inside Notion. You can report a bug, submit a feature idea, ask what is blocking a release, or mention that you just shipped a fix, and Zhu Li updates the right records for you.

I built it because project context is usually scattered across chat apps, commits, dashboards, sticky notes, and half-remembered ideas. Bugs get reported but not triaged. Feature requests get discussed but not tracked. Fixes ship but never make it into release notes. I wanted one place where all of that could live in a structured way, and one assistant that could keep it up to date without constant manual cleanup.

That place is Notion, and Notion MCP is what makes the whole experience practical. Instead of treating Notion like a passive document store, Zhu Li uses MCP to read from and write to a real workspace full of issues, features, insights, commits, changelog entries, and queued events.

iMessage is just one part of a much bigger system.

That iMessage conversation — and the Notion updates it triggered — is the most visible slice of a much deeper system. Under the hood, Zhu Li is a fully featured project management backend with an AI pipeline for intake, triage, deduplication, pattern detection, and changelog generation — all writing to a structured Notion workspace that becomes your single source of truth for everything happening in your project.

The name comes from The Legend of Korra — Zhu Li is the loyal, meticulous assistant who quietly handles everything behind the scenes so you don't have to. That's the whole idea.

Live: zhuli.aevr.space

Home page / landing page of zhuli.aevr.space

The problem: project data lives everywhere except where you can use it

Bugs get reported in five different places in five different ways. Feature ideas land in Slack threads and Figma comments and never get tracked. Commits go in with no link to the issue they fix. Release notes write themselves... never. And recurring problems stay invisible until someone connects enough dots to notice the pattern.

I wanted all of that in one structured place that an AI could read and write. The structured place is Notion. The AI that keeps it current is Zhu Li.

Here's what Zhu Li solves:

Noise reduction — Users report the same bug in five different ways across five different channels. Zhu Li's dedup agent reads related issues from your Notion Issues database and only creates a new record when it's genuinely novel, incrementing an affectedCount counter on duplicates.
Triage fatigue — Manually setting severity, category, and component for every incoming issue is slow. Zhu Li's triage agent does it automatically.
Lost patterns — Recurring issues are invisible until your Insights database surfaces them. Zhu Li's insight agent periodically scans resolved and open issues and writes pattern summaries back to Notion.
Changelog pain — Nobody wants to write release notes on Friday afternoon. The code mapper agent links commits to issues and auto-drafts changelog entries in Notion.
Scattered context — Because everything resolves to Notion, you get one source of truth that any AI assistant, human, or tool can read.

How it's wired together

┌──────────────────────────────────────────────────────────┐
│                     Zhu Li Platform                      │
├──────────┬──────────┬──────────────────┬─────────────────┤
│  Web UI  │ REST API │   MCP Server     │ Telegram / iMsg │
│ Next.js  │  /api/v1 │   /api/mcp       │  Webhooks       │
└────┬─────┴────┬─────┴────────┬─────────┴────────┬────────┘
     │          │              │                  │
     ▼          ▼              ▼                  ▼
┌──────────────────────────────────────────────────────────┐
│                   AI Agent Pipeline                      │
│   Intake → Triage → Dedup → Insight → CodeMapper → CLog │
│          Groq Llama 3.1-8b / 3.3-70b (+ Gateway)        │
└──────────────────────────┬───────────────────────────────┘
                           │
                           ▼
┌──────────────────────────────────────────────────────────┐
│             Notion MCP  (mcp.notion.com)                 │
│       Read / write the user's Notion databases           │
└──────────────────────────┬───────────────────────────────┘
                           │
                           ▼
┌──────────────────────────────────────────────────────────┐
│             User's Notion Workspace                      │
│  Issues · Features · Insights · Changelog · Commits     │
└──────────────────────────────────────────────────────────┘

The stack is a Next.js App Router monorepo deployed on Vercel. Every channel feeds the same AI agent pipeline, which always writes to Notion via MCP.

Layer	Technology
Framework	Next.js · App Router · Turbopack
AI runtime	Vercel AI SDK + Groq (Llama 3.1/3.3)
Notion (primary)	`@ai-sdk/mcp` — Notion MCP SSE transport
Notion (bootstrap)	`@notionhq/client` — create databases on signup
Database	MongoDB Atlas (Mongoose)
Auth	JWT (jose) + bcrypt + Notion OAuth
MCP Server	`@modelcontextprotocol/sdk`
UI	Tailwind CSS v4 + shadcn/ui
Deployment	Vercel

The organizational backbone: six Notion databases

After connecting Notion via OAuth, a one-click bootstrap creates six structured databases that become the persistent state of your project:

Issues — Bug tracking with severity, status, component, and assignee
Features — Feature requests with priority, effort, and status
Insights — AI-generated pattern analysis across recurring issues
Commits — Git commit log with hash, message, and linked issues/features
Changelog — Auto-generated release notes linked to commits
Event Queue — Processing pipeline status (synced from MongoDB)

Everything that comes in — whether a text from iMessage, a GitHub Actions payload, or a direct API call — gets classified and written into these databases. The structure is consistent no matter which channel it came through.

Notion workspace showing the six databases

The AI agent pipeline: from raw input to structured Notion data

Every submission enters a multi-stage pipeline. Each stage is a separate AI agent with a single responsibility:

Agent	Model	What it does
Intake	llama-3.1-8b-instant	Classifies input, extracts title/description/component, creates a Notion page
Triage	llama-3.3-70b-versatile	Sets severity (critical/high/medium/low), category, and component
Dedup	llama-3.3-70b-versatile	Searches Notion Issues for semantic matches; marks duplicates
Insight	llama-3.3-70b-versatile	Detects recurring patterns; upserts Insight pages in Notion
Code Mapper	llama-3.3-70b-versatile	Links commits to open Issues/Features; drafts Changelog entries
Changelog	llama-3.3-70b-versatile	Produces formatted release notes from mapped commits

By the time a bug lands in your Notion workspace it already has a severity, a component, a duplicate check, and links to any related commits. No triage meeting required.

A single submitted issue in Notion — severity, component, and category all set automatically

The chat agent: your Notion workspace, conversational

The part that makes this more than a data pipeline is the chat agent. It's backed by Notion MCP, which means it can read and write your entire workspace in response to plain-language requests.

Ask it questions:

You: "Which component has the most critical open issues right now?"

Zhu Li: "The payments component has 3 critical open issues — two related to iOS Safari checkout and one involving webhook retry logic."

Or give it instructions:

You: "I just merged a fix for the iOS Safari payment bug. Mark it resolved."

Zhu Li: "Got it — I've marked the issue as resolved in Notion and linked your latest commit."

Under the hood, Zhu Li calls notion_query_database to find the matching issue, then notion_update_page to close it. No custom CRUD code anywhere in that path — the model reasons about what tools to call and orchestrates Notion directly through MCP.

This is what makes the multi-channel experience feel natural. Whether you use the web dashboard, Telegram, or iMessage, the outcome is the same: your Notion workspace becomes something you converse with — and it acts.

What you can submit, and how

The same pipeline and chat agent are accessible from whichever interface fits your workflow:

For the demo flow, I focus on web dashboard chat and Telegram, while still supporting iMessage channels.

Web Dashboard — A chat interface with structured views for the backlog, insights, and changelog.

[SCREENSHOT: Dashboard chat interface — the message thread showing a question like "What are our open issues?" and an AI response]

REST API + SDK — External services submit issues or query data via an API key:

import { ZhuLiSDK } from "@untools/zhuli";

const zhuli = new ZhuLiSDK({ apiKey: "zhuli_abc123...", baseUrl: "<https://zhuli.aevr.space>" });

// Report a bug from any service
await zhuli.submitIssue({
  title: "Payment button unresponsive on iOS Safari",
  description: "Tapping checkout does nothing. Network tab is empty.",
  severity: "critical"
});

// Ask a natural language question backed by your Notion data
const answer = await zhuli.chat("What critical issues have been open for more than a week?");

// Fetch structured insight records
const insights = await zhuli.getInsights();

Git Integration — A post-commit hook or GitHub Actions step submits every commit automatically:

# .github/workflows/zhuli.yml
on: [push]
jobs:
  notify:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with: { fetch-depth: 2 }
      - run: |
          curl -sf -X POST <https://zhuli.aevr.space/api/v1/ingest/commit> \\
            -H "Authorization: Bearer ${{ secrets.ZHULI_API_KEY }}" \\
            -H "Content-Type: application/json" \\
            -d "{\\"hash\\":\\"$(git rev-parse HEAD)\\",\\"message\\":\\"$(git log -1 --pretty=%s)\\",\\"branch\\":\\"$GITHUB_REF_NAME\\",\\"author\\":\\"$(git log -1 --pretty='%an')\\",\\"committedAt\\":\\"$(git log -1 --pretty=%cI)\\"}"

GitHub action YAML

Telegram Bot — Users message the bot; Zhu Li replies using the same AI agent backed by Notion MCP tools.

Setting up Telegram is pretty straightforward:

Then you can chat with your agent:

[SCREENSHOT: Telegram conversation — user asks "How many commits do I have?", bot responds with a formatted list pulled from Notion]

iMessage via Blooio — This is the hosted iMessage integration. Blooio sends inbound message.received webhooks to Zhu Li, and Zhu Li routes them in three ways:

Plain text messages go straight to the chat agent
/issue ... creates an issue event and pushes it into the intake pipeline
/feature ... creates a feature request event and queues it for processing

That means you can text Zhu Li from iMessage like you would text a teammate: ask for your current backlog, report a production bug, or submit a feature request from your phone. Because Blooio is hosted, this path does not require running your own Mac server or changing SIP settings.

iMessage thread through Blooio

iMessage via BlueBubbles — I also support BlueBubbles as the self-hosted alternative for teams that want to use their own Mac as the iMessage bridge instead of a hosted provider.

MCP Server — Claude Desktop and any MCP-capable AI assistant can connect directly to Zhu Li's own MCP server at /api/mcp. Six tools are exposed: submit_issue, get_insights, get_backlog, update_status, search_workspace, generate_changelog. Each tool internally calls Notion MCP to fulfil the request.

Public Portal — Each workspace gets a shareable /portal/<id> portal page where anonymous visitors can submit issues and feature requests, see the public backlog, read the published changelog, and find documentation links — all without a Zhu Li account. Here’s an example - https://zhuli.aevr.space/portal/zlp_9428dee93575424a81

Public portal page showing the issue submission form

Public portal page showing the issue submission form, public issue list, and published changelog section

Video Demo

[VIDEO: Walkthrough — register, connect Notion, submit from web dashboard and Telegram, watch events land in Notion with severity + component set]

Show us the code

GitHub: github.com/miracleonyenma/zhuli

npm SDK: @untools/zhuli

Live: zhuli.aevr.space

How I Used Notion MCP

Notion MCP is the centrepiece of Zhu Li — not just an add-on.

Connection flow

When a user signs up with "Continue with Notion", an OAuth flow runs:

Auth page → GET /api/v1/notion/oauth/initiate?mode=login
  → Notion authorisation screen
  → GET /api/v1/notion/oauth/callback
    → Creates / finds account by Notion workspace ID
    → Encrypts access token (AES-256-GCM) → stores on User document
    → Creates session cookie (JWT)
    → Redirects to /dashboard/setup (workspace bootstrap)

The access token is encrypted at rest and decrypted on-demand. The MCP client is created per-user and cached with a 5-minute TTL so tool initialisation latency only hits once per session:

// lib/chat/agent.ts (simplified)
async function getNotionMCPTools(userId: string) {
  const cached = mcpClientCache.get(userId);
  if (cached && Date.now() - cached.createdAt < MCP_CACHE_TTL_MS) {
    return cached.tools;
  }

  const user = await UserModel.findById(userId).select("+notionConnection.accessToken");
  const token = decrypt(user.notionConnection.accessToken); // AES-256-GCM

  const client = new experimental_createMCPClient({
    transport: { type: "sse", url: "<https://mcp.notion.com/sse>" },
    headers: { Authorization: `Bearer ${token}` },
  });

  const tools = await client.tools();
  mcpClientCache.set(userId, { tools, createdAt: Date.now() });
  return tools;
}

How agents use MCP tools

Every AI agent that reads or writes Notion data receives the MCP tool set as part of its generateText() call. The agent decides which tool to call — Zhu Li doesn't wire up explicit logic for "call this specific Notion API endpoint". The model reasons about what it needs and calls the right MCP tool:

// lib/agents/triage.ts (simplified)
const { text } = await generateText({
  model: groq("llama-3.3-70b-versatile"),
  tools: { ...notionMCPTools },          // ← the full Notion MCP tool set
  maxSteps: 5,
  system: `You are a triage agent. Given a new issue, read the Issues database
           to understand conventions, then update the issue's Severity, Category,
           and Component properties.`,
  prompt: `Issue: ${title}\\nDescription: ${description}\\nNotion page ID: ${pageId}`,
});

The model will call notion_query_database to read existing issues, understand the team's severity conventions from real data, then call notion_update_page to write back the triage decision. No hand-coded Notion API logic anywhere in the triage step.

MCP-to-MCP: Zhu Li as a MCP server

Zhu Li also exposes its own MCP server, meaning any MCP-capable AI assistant can use Zhu Li as a tool — and Zhu Li in turn calls Notion MCP to fulfil the request. That's MCP all the way down:

Claude Desktop
  → POST /api/mcp (Zhu Li MCP server)
      tool: get_insights
  → Zhu Li resolves user from API key
  → getNotionMCPTools(userId)
  → AI agent: generateText with Notion MCP tools
      → notion_query_database (Insights database)
  → Returns structured insight list to Claude

The six tools exposed through the Zhu Li MCP server:

server.tool("submit_issue",      submitIssueSchema,     handleSubmitIssue);
server.tool("get_insights",      getInsightsSchema,     handleGetInsights);
server.tool("get_backlog",       getBacklogSchema,      handleGetBacklog);
server.tool("update_status",     updateStatusSchema,    handleUpdateStatus);
server.tool("search_workspace",  searchWorkspaceSchema, handleSearchWorkspace);
server.tool("generate_changelog",changelogSchema,       handleGenerateChangelog);

The chat agent: Notion MCP as a conversational interface

The chat agent (lib/chat/agent.ts) is the most direct use of Notion MCP. For queries, the model calls notion_query_database and reasons over the results. For mutations — like the "mark it resolved" example at the top — it calls notion_update_page. No custom aggregation or CRUD code anywhere in that path.

The Blooio integration brings that same Notion-backed chat to iMessage. Zhu Li verifies the Blooio webhook signature, parses inbound message.received events, and routes them to chat or queues them as pipeline events. The reply goes back through the Blooio REST API:

iMessage user
  → Blooio webhook
  → /api/v1/channels/blooio/webhook
      → verify HMAC signature
      → parse inbound text
      → route to chat() or create EventQueue item
  → Notion MCP tools / agent pipeline
  → reply sent back through Blooio REST API

Blooio dashboard webhook configuration showing the Zhu Li webhook URL

For external channels (Telegram, iMessage), the chat agent routes to the AI Gateway primary model (larger context window, better tool-call reliability) and falls back to Groq on error — important when users send bursts of messages or MCP tool results are large.

What Notion MCP unlocks that wasn't possible before

Without MCP, connecting an AI agent to Notion required manually wrapping every endpoint worth using, writing pagination and filter logic for each database, re-implementing rich text parsing, and maintaining all of it as the API evolved.

With MCP, I describe the intent in plain language. The model figures out which tools to call. The agent code became thinner, more readable, and much easier to extend.

It also meant the chat interface — including the bidirectional action-taking — required almost no hand-coded Notion logic. Queries, mutations, cross-database lookups: the model handles the orchestration. I just write the system prompt.

Built for the Notion MCP Challenge · March 2026

DevFlow - Build Anywhere with GitHub Copilot CLI

Miracleio — Mon, 02 Feb 2026 08:30:00 +0000

This is a submission for the GitHub Copilot CLI Challenge

What I Built

I built DevFlow - a tool that lets me control GitHub Copilot CLI on my development machine from anywhere via Telegram or Slack.

The problem: AI coding tools are getting really capable, but there's a fundamental limit: you need to be physically present. If your development environment is on your local machine and you’re not on it, you can't access your AI tools like Antigravity or Claude Code.

Also, if you SSH into a remote server or VPS, you still need to manually run commands, navigate the codebase, and execute everything yourself.

The solution: Install DevFlow on your PC, VM, or VPS. Send natural language commands from Telegram or Slack. DevFlow spins up Copilot CLI sessions locally and executes your tasks while streaming progress back to your chat.

Why existing tools fall short: I use AI coding tools like Trae, Kiro, Antigravity, and Zed—these have excellent in-editor agents but are confined to the IDE. I've also worked with Gemini CLI and Warp. CLI agents aren't locked to an editor, which is powerful, but you still need terminal access. DevFlow removes that constraint entirely.

Example workflow:

Send this in Telegram:

Update the README to reflect the current state of the project

DevFlow responds:

Task created and dispatched to agent-e4425f98. The agent will pick it up shortly. 🚀

🔄 Update: update README
⏳ Starting feature implementation workflow
[▪▪▪▪▪▪▪▪▪▪] 3%

Meanwhile, on your machine, Copilot CLI analyzes the codebase, updates the README, and commits the changes. You get real-time progress updates in Telegram.

Key Features:

🤖 Copilot CLI Integration: Uses GitHub Copilot CLI and SDK to intelligently execute coding tasks
🔒 Local Execution: Code never leaves your machine—the agent runs locally
📱 ChatOps: Send commands via Telegram or Slack (!fix, !feature, !explain, !review-pr)
⚡ Real-time Updates: Streaming progress back to your chat
🔐 Secure: Encrypted credentials, fine-grained permissions, no code exfiltration

Tech Stack:

GitHub Copilot CLI & SDK (@github/copilot-sdk)
Next.js (web platform), Node.js + TypeScript (agent CLI)
Telegram Bot API, Slack API, GitHub API
Monorepo: apps/web (dashboard) + apps/agent (agent CLI)

Demo

🌐 Live Platform: https://devflow.aevr.space/

📦 NPM Package: @untools/devflow

💻 GitHub Repository: miracleonyenma/devflow

How It Works

1. Set up your account and channels

Visit devflow.aevr.space and create an account (email + magic link/code)

Install the GitHub App on your repositories (for notifications like push, PRs, deployment from enabled repos)

Connect Telegram: Go to Settings → Notification Channels → Add Telegram

- For personal DM: Visit [@thedevflowbot](https://t.me/thedevflowbot)
- For group chat: Add the bot and send `/start channel_[ID]`

2. Install the tools on your machine

# Install GitHub Copilot CLI first
npm install -g @github/copilot

# Authenticate with GitHub
copilot

# Install DevFlow agent CLI
npm install -g @untools/devflow

3. Initialize your agent

Navigate to a project and run:

devflow init

This opens your browser to authenticate and configure the agent:

🚀 DevFlow Agent Initialization

📍 Platform URL: <https://devflow.aevr.space>
⏳ Starting authentication flow...
🌐 Opening browser for authentication...

✓ Authentication successful!
✓ Agent ID: agent-f27953dd-eef2-41fb-9b2a-deba66ecbbe7

📝 GitHub Personal Access Token Required
   Create one at: https://github.com/settings/personal-access-tokens
   Required scopes: copilot, repo

Enter your GitHub Personal Access Token: ****

✓ Saved configuration to ~/.devflow/config.json

📋 Configuration Summary:
   Agent: agent-54c6fe56
   Platform: <https://devflow.aevr.space>

🚀 Next Step: devflow start

Note: Use a fine-grained token with only "Copilot" access. You can also store this in DevFlow's encrypted credentials settings.

4. Start the agent

devflow start

🚀 DevFlow Agent Starting

✓ Connecting to platform...
✓ Agent online: agent-f27953dd-eef2-41fb-9b2a-deba66ecbbe7
✓ Listening for commands...

5. Send commands from Telegram

First, check your connected agents:

/agents

Response:

🤖 Connected Agents (2/2)

🟢 agent-0dc45556 (agent-d8)
   Platform: darwin | v0.1.0
   Last seen: 1/29/2026, 3:53:04 PM

🟢 agent-8ca7ec19 (agent-e4)
   Platform: darwin | v0.1.0
   Last seen: 1/29/2026, 3:55:26 PM

Then send a task:

Update the README to reflect the current state of the project

You'll get real-time updates as Copilot CLI works:

Real-time task execution in Telegram showing progress updates

After the task is complete, you should get a notification as well (forgive the poor formatting):

Now, you can check for changes in your project like I did with git status:

➜  trivia git:(main) ✗ git status
On branch main
Your branch is up to date with 'origin/main'.

Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git restore <file>..." to discard changes in working directory)
        modified:   README.md

Check the dashboard to see task history:

DevFlow dashboard showing task details, agent info, and execution timeline

Example Commands

Update the README to reflect the current state of the project
Fix the navbar overlapping issue on mobile
Add dark mode toggle to settings
Explain the authentication flow in auth.ts
Review PR #42 and suggest improvements

Video Walkthrough

Testing Instructions (For Judges)

We have created a test user for you to easily log in and test the application without needing email verification.

Go to the Login Page - https://devflow.aevr.space/login.
Select "Login with PIN".
Enter the following credentials:
- User:
  - Email: judge@pinga.ai
  - PIN: 1234
You will be logged in and redirected to the dashboard.

My Experience with GitHub Copilot CLI

Why I Built This

I had an existing project called "Pinga" that routed GitHub notifications to Telegram and Slack. When I saw the GitHub Copilot CLI Challenge on DEV.to (January 23, 2026), I thought it'd be nice to build a productivity tool with Copilot CLI that lets me use Copilot CLI remotely to build other stuff. Meta, but useful.

Setting Up the Architecture

I needed a monorepo with:

apps/web: Dashboard for user accounts, GitHub/Telegram/Slack connections
apps/agent: NPM package for the agent CLI

First mistake: I didn't explain the architecture clearly in my prompts. Copilot CLI created a separate Express server (apps/agent-host) and put all the integration logic there. After using it for a bit, and getting silent errors, I realized this was unnecessary. The CLI tool should handle everything directly—poll for tasks, initialize Copilot sessions, execute workflows. So I asked Copilot to fix this. We moved the integration into @untools/devflow .

Lesson: When working with AI agents, be explicit about your system architecture upfront.

After refactoring, I hit another frustrating problem. The agent would:

✅ Poll successfully
✅ Receive tasks
✅ Initialize Copilot CLI
❌ Fail silently

No errors. No logs. Just silent failures. My task queue filled up with pending tasks that weren't completing.

The Fix

After some debugging, I later realized it was an authentication problem, in the Copilot CLI docs, you will find that you can authenticate using a Personal Access Token (PAT). I was using a Classic GitHub PAT instead of a Fine-grained PAT.

Switched to fine-grained tokens with the correct scopes, and everything worked immediately.

This prompted me to add BYOK (Bring Your Own Key) to both the dashboard and CLI. Users can now provide their own GitHub PAT and Groq API key. I recommend using the CLI to add credentials (encrypted storage), but you can also add them through the dashboard.

What Makes Copilot CLI Different

1. Build Verification

I noticed that when working with projects that require builds, Copilot CLI attempts to build your project after making changes before marking a task complete. This means fewer syntax errors and TypeScript issues in the final output. When it says "done," you can trust it.

2. Session Resumption

After a session ends, you get a session ID:

Resume this session with: copilot --resume=6f0af322-662a-4367-bfc6-74cc293c5c28

I love this, you can pick up exactly where you left off after ending a Copilot CLI session.

3. Expanded Mode

Toggle expanded mode with ctrl + o to see:

The agent's thought process
File contents being examined
Real-time command outputs

Great for debugging and understanding what's happening.

4. Actually Completes Tasks

Copilot CLI:

Analyzes codebase architecture
Makes informed decisions about where changes belong
Follows existing patterns
Tests changes when possible
Handles edge cases

It feels like pair programming with someone who knows the codebase.

What's Next

DevFlow is functional and I'm using it daily. Still adding features before the February 15 deadline:

Better error handling
More workflow types (deployment automation, enhanced code reviews)
Improved session management for long-running tasks
Better GitHub Issues/PRs integration

I used Copilot CLI to build a tool that lets me use Copilot CLI on any machine from anywhere. That recursive productivity loop is exactly what makes AI-assisted development exciting.

Built with: GitHub Copilot CLI, GitHub Copilot SDK, Next.js, Node.js, TypeScript, Slack API, Telegram Bot API

Live at: devflow.aevr.space

Source: github.com/miracleonyenma/devflow

Package: @untools/devflow

Building a Flexible Share System in React with the Web Share API

Miracleio — Wed, 29 Jan 2025 17:31:40 +0000

Remember when adding social sharing buttons meant littering your website with a dozen third-party scripts, each one slowing down your page load? Or when "share this" functionality meant copying a URL to your clipboard and hoping for the best? The Web Share API changes all that, offering a native, performant way to tap into your device's sharing capabilities. Let's build a modern sharing system in React that your users will actually want to use.

Setting Up the Project

First, let's create a new React project using Vite. We'll use TypeScript for better developer experience and type safety:

npm create vite@latest my-share-app -- --template react-ts
cd my-share-app

Install the necessary dependencies:

npm install sonner

If you're using Tailwind CSS (optional but recommended for styling):

npm install -D tailwindcss@3 postcss autoprefixer
npx tailwindcss init -p

Add the toast provider to your main App component:

// src/App.tsx
import { Toaster } from 'sonner';

function App() {
  return (
    <>
      <Toaster position="bottom-right" />
      {/* Your app content */}
    </>
  );
}

Understanding the Web Share API

The Web Share API provides a platform-native sharing mechanism that integrates with the device's built-in sharing capabilities. On mobile devices, this means accessing the same sharing menu you use in native apps. On desktop, it typically interfaces with installed applications and system sharing features.

Creating the Share Hook

Let's build a custom hook that encapsulates our sharing logic. Create a new file src/hooks/useShare.ts:

import { toast } from "sonner";

const useShare = () => {
  const copy = async (text: string) => {
    try {
      await navigator.clipboard.writeText(text);
      toast.success(`Successfully copied ${text} to clipboard`);
    } catch (error) {
      console.error("Error copying to clipboard:", error);
      toast.error("Error copying to clipboard");
    }
  };

  const share = async (url: string, title: string, description: string) => {
    if (navigator.share) {
      try {
        await navigator.share({
          title,
          text: description,
          url,
        });
        console.log("Successfully shared");
      } catch (error) {
        console.error("Error sharing:", error);
        toast.error("Error sharing");
        copy(url);
      }
    } else {
      console.error("Web Share API not supported");
      toast.error("Web Share API not supported");
      copy(url);
    }
  };

  return { copy, share };
};

export default useShare;

Breaking Down the Implementation

Our useShare hook provides two main functions:

copy: A fallback function that copies text to the clipboard using the Clipboard API
share: The primary sharing function that attempts to use the Web Share API first

The sharing logic follows a progressive enhancement approach:

Check if the Web Share API is available (navigator.share)
If available, attempt to share using the native sharing mechanism
If sharing fails or isn't supported, fall back to copying the URL to the clipboard

Using the Hook in Components

Here's a practical example of implementing a share button component:

// src/components/ShareButton.tsx
import { FC } from 'react';
import useShare from '../hooks/useShare';

interface ShareButtonProps {
  url: string;
  title: string;
  description: string;
}

const ShareButton: FC<ShareButtonProps> = ({ url, title, description }) => {
  const { share } = useShare();

  const handleShare = () => {
    share(url, title, description);
  };

  return (
    <button 
      onClick={handleShare}
      className="px-4 py-2 bg-blue-500 text-white rounded-lg hover:bg-blue-600 transition-colors"
    >
      Share This Content
    </button>
  );
};

export default ShareButton;

And here's how to use it in a page or component:

// src/App.tsx
import ShareButton from './components/ShareButton';

function App() {
  return (
    <div className="p-4">
      <h1 className="text-2xl font-bold mb-4">My Awesome Content</h1>
      <ShareButton 
        url={window.location.href}
        title="Check out this awesome content!"
        description="I found this really interesting article about the Web Share API..."
      />
    </div>
  );
}

Browser Support and Considerations

The Web Share API is well-supported on:

Mobile browsers (iOS Safari, Chrome for Android)
Desktop browsers (Chrome, Edge, Safari)

However, there are some important considerations:

The API must be called from a secure context (HTTPS)
It requires user interaction (like a button click)
Not all browsers support sharing all types of data

Best Practices

Always provide fallbacks: As demonstrated in our implementation, always have a backup plan when the Web Share API isn't available.
Handle errors gracefully: Use toast notifications or other user feedback mechanisms to keep users informed about the sharing status.
Keep it simple: The sharing interface should be straightforward and intuitive. A simple button with clear messaging is often sufficient.
Test across devices: The sharing experience can vary significantly between desktop and mobile devices, so thorough testing is essential.

Resources

Example Project on GitHub - https://github.com/miracleonyenma/my-share-app

Conclusion

The Web Share API provides a clean, native way to implement sharing functionality without bloating your app with third-party scripts. Combined with React hooks and proper fallback mechanisms, we can create a sharing system that feels natural and works reliably across platforms. The solution we've built is lightweight, maintainable, and most importantly, provides a sharing experience that feels native to each user's device.

For your next project, ditch those clunky social sharing libraries and give the Web Share API a try. Your users (and your bundle size) will thank you.

Project Management Assembly of Agents Built with Agent.ai

Miracleio — Mon, 27 Jan 2025 07:33:23 +0000

This is a submission for the Agent.ai Challenge: Assembly of Agents (See Details)

What I Built

This project is a collection of intelligent agents designed to simplify team and project management. These agents collectively perform a range of functions, including:

Creating projects and adding team members.
Assigning tasks to team members.
Sending task reports to team members via email.
Sending reminders for tasks to ensure deadlines are met.
Generating a detailed project overview document that is accessible to both admins and team members.

Why I Built It

Managing a team can often feel overwhelming, especially if you’re not a professional project manager but still need to organize work efficiently. This tool serves as a productivity booster by automating repetitive tasks and centralizing project management functionalities. The goal is to provide assistance to team leads or members, making collaboration and task management seamless.

How It Works

To enable these functionalities, I built a simple API to store project and task data for later retrieval. This ensures that projects, team members, and tasks persist across sessions and can be revisited or updated as needed. The code for the API is available on GitHub (links provided at the end of the submission).

Demo

About 7 agents were created, here area a few

Orchestrator Agent (The Brains)

This is your entry point to create and manage your projects and tasks. It invokes other agents with specific responsibilities depending on the action you want to perform.
It makes use key actions available in the Agent Builder such as advanced actions like Invoking Another Agent, Calling Web API
You can view the agent here:
https://agent.ai/agent/avengers_assemble

Project Creator Agent

This agent collects key information like the name of the project, the owner name and email address. task list and a project overview document.
It processes all this information and creates a new project
You can find it here - https://agent.ai/agent/avengers_project_creator

Creating A Project

Managing Tasks in existing Project

Generating Task Report in existing Project

Triggering Task Reminders

Agent.ai Experience

My experience with Agent.ai was highly positive. The builder community provided a wealth of resources, including detailed videos, which made it easy to understand how the platform works. Setting up agents was straightforward, and I was able to create functional bots after just one or two tutorial videos.

When I inquired about using APIs to store project and team data, I received clear guidance, which allowed me to proceed with my API-based approach confidently.

While the experience was great overall, I encountered a few challenges:

File Input Issues: The default file input didn’t work initially, but the provided template resolved the issue.
Session/User Context: User context isn’t inherently supported, requiring users to provide their own context manually.
Snippet Variables: When snippet variables populated fields, they sometimes removed other variables, complicating dynamic inputs.
Markdown in Multi-Agent Workflow: Only the first line of markdown text was passed between agents, limiting its utility in multi-line contexts.
POST API Limitations: The POST API didn’t function as expected, leading me to use AWS serverless functions as a workaround.
Google Docs Retrieval: Generating shareable Google Docs URLs directly wasn’t straightforward, requiring manual retrieval from Google Drive.

Solutions

To overcome these challenges, I designed specialized agents for specific tasks:

Email HTML Generator Agent: Converts markdown into formatted email HTML for sending task reports.
Trigger Agent: Updates project documents based on the current task status, ensuring the latest version is emailed to users.

Conclusion

This project showcases the versatility of Agent.ai for solving real-world challenges in team and project management. The experience was enriching, and overcoming challenges pushed me to innovate and create a robust solution.

Team members

Miracle Onyenma - @miracleio
Victory Tuduo - @victorytuduo

Real-Time Authorization in a Chat Application with Permit.io and WebSockets

Miracleio — Thu, 23 Jan 2025 09:13:10 +0000

As modern chat applications evolve, real-time communication requires increasingly granular access controls. Managing dynamic permissions in real-time for various chat rooms and participants, especially in complex or multi-user environments, can quickly become challenging. What if you could easily implement fine-grained authorization for your chat app without compromising on performance?

Permit.io makes integrating robust, real-time access control into your chat application simple. By pairing Permit.io’s advanced authorization models with WebSockets, you can ensure that the right users have access at the right time, all while maintaining the responsiveness needed in chat applications.

In this tutorial, you’ll learn how to implement real-time authorization in a WebSocket-based chat application using Permit.io. By the end, you’ll understand how to enforce role-based and attribute-based access controls dynamically, securing different chat rooms, message visibility, and interactions in real time.

Introduction to Real-Time Authorization in Chat Applications

We all use chat applications in one form or another to stay connected with friends and family, discuss important matters with colleagues, and even conduct business. With the increasing demand for seamless, real-time communication, it’s easy to take for granted the sophisticated security measures that protect these interactions. However, as chat applications become more complex, so do the challenges of securing user data and conversations. Fine-grained access control helps ensure that only authorized users have access to sensitive information and actions.

Why real-time chat apps require fine-grained access control

Fine-grained access control is essential in real-time chat applications to ensure security, user customization, and regulatory compliance.
By setting robust authentication methods and role-based permissions, chat applications prevent unauthorized users from accessing sensitive conversations and allow admins to effectively manage user interactions. This approach also enhances user experience by enabling participation in various chat types—public, private, or group—based on individual roles or preferences, creating more engaging interactions.
Furthermore, fine-grained access control helps organizations meet strict data privacy regulations, like the GDPR, safeguarding confidential data and minimizing legal risks.

The challenges of implementing dynamic authorization in a chat context

The points cover all the main ideas from the paragraphs. Here’s a refined version that includes every detail:

Real-time chat apps require instant permission checks and updates, making dynamic authorization challenging without risking performance impacts, especially when handling large volumes of messages and users.
Chat applications often involve multiple access layers, with permissions that vary based on roles, group memberships, or specific attributes, requiring consistent and efficient enforcement.
Dynamic changes in roles (e.g., admin promotions, group removals, or temporary access) must be recognized and applied immediately across all active sessions without disrupting ongoing conversations.
Achieving this level of flexibility while maintaining a seamless user experience demands an advanced authorization model that integrates closely with real-time protocols like WebSockets.

Overview of how Permit.io’s authorization solutions can streamline this process with WebSockets

Permit.io’s authorization solutions can significantly streamline the implementation of real-time authorization in chat applications, particularly when integrated with WebSockets. Here’s an overview of how this combination enhances dynamic access control:

Seamless Integration: Permit.io offers a robust framework for managing fine-grained access controls that can be easily integrated into chat applications utilizing WebSockets. This integration allows for real-time permission checks and updates, ensuring that users have immediate access to the appropriate chat rooms and functionalities based on their roles and attributes.
Dynamic Permission Management: With Permit.io, developers can implement dynamic authorization models that adapt to changes in user roles or group memberships. For instance, if a user is promoted to an admin role or temporarily granted special access, these changes can be reflected instantly across all active sessions without interrupting ongoing conversations. This capability addresses one of the primary challenges in dynamic authorization by ensuring that permissions are consistently enforced in real-time.
Enhanced Performance: By leveraging WebSockets for communication, Permit.io ensures that real-time authorization processes do not compromise application performance. The architecture supports high volumes of messages and users, allowing for efficient handling of concurrent access requests while maintaining responsiveness—a critical requirement for chat applications.
Role-Based and Attribute-Based Access Control: Permit.io facilitates the enforcement of both role-based and attribute-based access controls within chat environments. This flexibility allows administrators to define specific permissions for different user types, such as moderators or regular users, enhancing security while providing a customizable user experience. Users can participate in various chat types—public, private, or group based on their assigned roles.
Regulatory Compliance: Implementing Permit.io’s solutions helps organizations meet stringent data privacy regulations by ensuring only authorized users can access sensitive information and functionalities within the chat application. This compliance is crucial for safeguarding user data and minimizing legal risks associated with unauthorized access.

Setting Up a WebSocket-Based Chat Application

For our web socket-based application, we’ll be using Next.js and Ably, a service that allows us to easily integrate and manage real-time capabilities in our apps powered by web socket.

In addition to Ably and Next Auth, we can use something like Firebase to handle both authentication and realtime features. There’s an entire tutorial about that on the Permit.io blog.

Without further ado, let’s proceed!

Setting up Next.js

Run the following command and follow the prompts:

npx create-next-app@latest live-chat
Need to install the following packages:
create-next-app@15.1.0
Ok to proceed? (y) y

✔ Would you like to use TypeScript? … No / Yes
✔ Would you like to use ESLint? … No / Yes
✔ Would you like to use Tailwind CSS? … No / Yes
✔ Would you like your code inside a `src/` directory? … No / Yes
✔ Would you like to use App Router? (recommended) … No / Yes
✔ Would you like to use Turbopack for `next dev`? … No / Yes
✔ Would you like to customize the import alias (`@/*` by default)? … No / Yes
Creating a new Next.js app in /Users/miracleio/Documents/writing/permit/real-time-authorization-in-a-chat-application-with-permitio-and-websockets/live-chat.

Using npm.

Initializing project with template: app-tw 


Installing dependencies:
- react
- react-dom
- next

Installing devDependencies:
- typescript
- @types/node
- @types/react
- @types/react-dom
- postcss
- tailwindcss
- eslint
- eslint-config-next
- @eslint/eslintrc


added 371 packages, and audited 372 packages in 1m

141 packages are looking for funding
  run `npm fund` for details

found 0 vulnerabilities
Initialized a git repository.

Success! Created live-chat at /Users/miracleio/Documents/writing/permit/real-time-authorization-in-a-chat-application-with-permitio-and-websockets/live-chat

Navigate to the newly created project folder and install a few more packages we’ll use to build our app:

cd live-chat
npm install -D prettier prettier-plugin-tailwindcss  @tailwindcss/forms

Also, install a few UI compoents fron Radix UI:

npm install @radix-ui/react-scroll-area

Create a new file in the root of the project directory - .prettierrc and enter the following:

{
  "plugins": ["prettier-plugin-tailwindcss"]
}

In the tailwind.config.ts file, enter the following:

// ./tailwind.config.ts
import type { Config } from "tailwindcss";
import tailwindForms from "@tailwindcss/forms";
export default {
  content: [
    "./pages/**/*.{js,ts,jsx,tsx,mdx}",
    "./components/**/*.{js,ts,jsx,tsx,mdx}",
    "./app/**/*.{js,ts,jsx,tsx,mdx}",
  ],
  theme: {
    extend: {
      colors: {
        background: "var(--background)",
        foreground: "var(--foreground)",
      },
    },
  },
  plugins: [tailwindForms],
} satisfies Config;

In the `./next.config.ts`, enter the following:

// ./next.config.ts
import type { NextConfig } from "next";
const nextConfig: NextConfig = {
  /* config options here */
  images: {
    remotePatterns: [
      {
        protocol: "https",
        hostname: "lh3.googleusercontent.com",
      },
      {
        protocol: "https",
        hostname: "www.tapback.co",
      },
    ],
  },
};
export default nextConfig;

Set up global styles

In the ./app/globals.css file, enter the following:

/* ./app/globals.css */
@tailwind base;
@tailwind components;
@tailwind utilities;
@layer base {
  body {
    @apply bg-white text-gray-800 dark:bg-gray-900 dark:text-gray-300;
  }
}
@layer components {
  .btn {
    @apply inline-flex items-center justify-center gap-2 rounded-full bg-gray-100 px-4 py-2 text-sm font-semibold text-gray-500 hover:brightness-95 focus:outline-none focus:ring-2 focus:ring-gray-200 focus:ring-offset-2 dark:bg-gray-800 dark:text-gray-300 dark:brightness-105 dark:hover:bg-gray-700 dark:focus:ring-gray-800 dark:focus:ring-offset-gray-900;
  }
  .btn:has(> .icon:first-child) {
    @apply pl-2;
  }
  .btn:has(> .icon:last-child) {
    @apply pr-2;
  }
  .icon {
    @apply h-5 w-5 text-current;
  }
  .form-input {
    @apply flex grow rounded-full border border-none bg-gray-100 px-4 py-2 text-sm font-semibold text-gray-500 outline-none hover:brightness-95 focus:border-none focus:outline-none focus:ring-2 focus:ring-gray-200 focus:ring-offset-2 dark:bg-gray-800 dark:text-gray-300 dark:brightness-105 dark:hover:bg-gray-700 dark:focus:ring-gray-800 dark:focus:ring-offset-gray-900;
  }
  .site-section {
    @apply py-16 md:py-24;
  }
  .site-section > .wrapper {
    @apply mx-auto max-w-5xl px-4 sm:px-6 lg:px-8;
  }
  .noscroll {
    @apply overflow-auto;
    scrollbar-width: none;
  }
}

Setting up Authentication

We’ll be using Auth.js, an authentication library originally built for Next.js.
Run the following command to install the package:

npm install next-auth@beta

We have to create an AUTH_SECRET environment variable. The library uses this random value to encrypt tokens and email verification hashes. (See Deployment to learn more). You can generate one via the official Auth.js CLI running:

npx auth secret

📝 Created /Users/miracleio/Documents/writing/permit/real-time-authorization-in-a-chat-application-with-permitio-and-websockets/live-chat/.env.local with `AUTH_SECRET`.

Next, create the Auth.js config file and object - ./auth.js:

// ./auth.ts
import NextAuth from "next-auth";
export const { handlers, signIn, signOut, auth } = NextAuth({
  providers: [],
});

Add a Route Handler under ./app/api/auth/[...nextauth]/route.ts:

// ./app/api/auth/[...nextauth]/route.ts

import { handlers } from "@/auth"; // Referring to the auth.ts we just created
export const { GET, POST } = handlers;

Add optional Middleware to keep the session alive; this will update the session expiry every time it is called - ./middleware.ts:

export { auth as middleware } from "@/auth"

Setting up Google OAuth

NextAuth supports multiple OAuth providers for authentication. For this tutorial, we’ll be using Google.

To obtain our Google client ID and secret, we have to set up a new project in Google Cloud Console - https://console.cloud.google.com/projectcreate

Next, in the newly created project, we’ll set up a new consent screen:

Once our consent screen has been created, we can set up credentials. Navigate to Credentials from the sidebar.
Click on the + Create Credentials button and select OAuth client ID from the dropdown.

In the following screen, select Web Application, enter the Authorized JavaScript origins, and redirect URIs: http://localhost:3000 and http://localhost:3000/api/auth/callback/google respectively.

With that we should have our client ID and secret:

Copy the values and enter them into the .env file:

# .env
AUTH_SECRET=secrettop # Added by `npx auth`. Read more: https://cli.authjs.dev
AUTH_GOOGLE_ID=livechat.apps.googleusercontent.com
AUTH_GOOGLE_SECRET=GOCSPX-livechat

Next, enable Google as a sign-in option in our Auth.js configuration. We’ll have to import the Google provider from the package and pass it to the providers array we set earlier in the Auth.js config file:

// ./auth.ts
import NextAuth from "next-auth";
import Google from "next-auth/providers/google";
export const { handlers, signIn, signOut, auth } = NextAuth({
  providers: [Google],
});

Create a Site Header component

Let’s create a header for our app containing the sign-in and sign-out buttons. Create a new file - ./components/Site/Header.tsx:

// ./components/Site/Header.tsx
// Importing necessary modules and functions:
// - `auth`, `signIn`, `signOut`: Authentication-related functions from the custom `auth` module.
// - `Image` from `next/image`: For optimized image rendering.
// - `Link` from `next/link`: For client-side navigation in Next.js.
import { auth, signIn, signOut } from "@/auth";
import Image from "next/image";
import Link from "next/link";
// Define the `SiteHeader` component as an async function since it fetches session data.
const SiteHeader = async () => {
  // Fetch the current user's session using the `auth` function.
  const session = await auth();
  return (
    // Define the header with styling for sticky positioning, background, and padding.
    <header className="noscroll sticky top-0 z-10 overflow-auto bg-white px-4 py-4 sm:px-6 lg:px-8">
      <div className="wrapper mx-auto flex max-w-5xl items-center justify-between gap-4">
        {/* Navigation link to the homepage. */}
        <Link href="/">
          <figure className="flex items-center">
            <span className="truncate text-xl font-bold tracking-tight text-gray-900 dark:text-white">
              Live Chat
            </span>
          </figure>
        </Link>
        {/* Navigation menu */}
        <nav className="site-nav flex">
          <ul className="flex items-center gap-2">
            {/* If the user is signed in, show their profile picture, name, and a sign-out button. */}
            {session?.user ? (
              <>
                <li>
                  <button className="btn">
                    {/* Display the user's avatar using the `Image` component. */}
                    <Image
                      src={session?.user.image as string} // User's profile image URL.
                      alt="session?.user avatar" // Alternative text for accessibility.
                      width={32}
                      height={32}
                      className="icon rounded-full"
                    />
                    <span className="truncate">{session?.user.name}</span>{" "}
                    {/* User's name. */}
                  </button>
                </li>
                <li>
                  <button
                    onClick={async () => {
                      "use server"; // Mark this function for server execution.
                      await signOut(); // Sign the user out when clicked.
                    }}
                    className="btn truncate"
                  >
                    Sign out
                  </button>
                </li>
              </>
            ) : (
              // If no user is signed in, show a sign-in button.
              <li>
                <form
                  action={async () => {
                    "use server"; // Mark this function for server execution.
                    await signIn(); // Sign the user in when submitted.
                  }}
                >
                  <button type="submit" className="btn">
                    Sign in
                  </button>
                </form>
              </li>
            )}
          </ul>
        </nav>
      </div>
    </header>
  );
};
// Export the `SiteHeader` component as the default export of this module.
export default SiteHeader;

Here, a SiteHeader component serves as the main navigation bar.

If a user session exists (session?. user), display the user’s avatar, name, and a “Sign out” button.
Otherwise, display a “Sign in” button, and since we’re using Next.js server actions, we put it inside a form.

The signIn and signOut functions are wrapped in server action markers ("use server") for server-side execution in Next.js.

In our ./app/layout.tsx file import the SiteHeader component:

// ./app/layout.tsx
import type { Metadata } from "next";
import { Geist, Geist_Mono } from "next/font/google";
import "./globals.css";
import SiteHeader from "@/components/Site/Header";
const geistSans = Geist({
  variable: "--font-geist-sans",
  subsets: ["latin"],
});
const geistMono = Geist_Mono({
  variable: "--font-geist-mono",
  subsets: ["latin"],
});
export const metadata: Metadata = {
  title: "Live Chat",
  description: "Live Chat with Next.js, NextAuth, Ably and Permit.io",
};
export default function RootLayout({
  children,
}: Readonly<{
  children: React.ReactNode;
}>) {
  return (
    <html lang="en">
      <body
        className={`${geistSans.variable} ${geistMono.variable} antialiased`}
      >
        <SiteHeader />
        {children}
      </body>
    </html>
  );
}

In the homepage at ./app/page.tsx, enter the following:

// ./app/page.tsx
export default function Home() {
  return (
    <main className="site-main">
      <section className="site-section">
        <div className="wrapper">
          <h1 className="text-center text-4xl font-bold tracking-tight text-gray-900 sm:text-5xl md:text-6xl lg:text-7xl dark:text-white">
            Welcome to Live Chat
          </h1>
        </div>
      </section>
    </main>
  );
}

With that, we should have something like this:

Now that we’ve set up authentication, let’s proceed to add websockets capabilities to our app with Ably.

Set up WebSockets with Ably

To get started, sign-up to Ably then Create a new app with the following options:

App name: Call your app something meaningful
Select your preferred language(s): JavaScript
What type of app are you building? Live Chat

In the next screen, copy your API Key:

Save it in the .env file:

# .env
# ...
ABLY_SECRET_KEY=bOpZEQ.E3l_gw:_tf-HaDekVTN2_vyPXdyjs0PT5NzWpXwPrEFJqBSahA

In our app, install the Ably React SDK and jose library for JWT:

npm install ably jose

Once jose and ably installs, create ./app/api/ably/route.ts:

// ./app/api/ably/route.ts
// Import the `auth` function to authenticate the user.
// Import `SignJWT` from the `jose` library to create JSON Web Tokens (JWT).
import { auth } from "@/auth";
import { SignJWT } from "jose";
// Function to create an Ably-compatible token.
// Parameters:
// - `clientId`: A unique identifier for the client.
// - `apiKey`: The Ably API key, which contains the app ID and signing key.
// - `claim`: An object indicating the user's role (e.g., whether they are a moderator).
// - `capability`: A map of channel permissions for the user.
const createToken = (
  clientId: string,
  apiKey: string,
  claim: { isMod: boolean },
  capability: { [key: string]: string[] | undefined },
) => {
  // Extract the app ID and signing key from the provided Ably API key.
  const [appId, signingKey] = apiKey.split(":", 2);
  // Create a text encoder to encode the signing key for the JWT.
  const enc = new TextEncoder();
  // Create the JWT with Ably-specific claims and headers.
  const token = new SignJWT({
    // Specify the user's capabilities for Ably channels.
    "x-ably-capability": JSON.stringify(capability),
    // Associate the token with the client's unique identifier.
    "x-ably-clientId": clientId,
    // Include custom claims (e.g., moderation status).
    "ably.channel.*": JSON.stringify(claim),
  })
    // Set the protected header with the app ID and algorithm used for signing.
    .setProtectedHeader({ kid: appId, alg: "HS256" })
    // Set the issued-at timestamp to the current time.
    .setIssuedAt()
    // Set the expiration time for the token to 24 hours.
    .setExpirationTime("24h")
    // Sign the token using the encoded signing key.
    .sign(enc.encode(signingKey));
  // Return the signed JWT.
  return token;
};
// Function to generate channel permissions (capabilities) based on the user's role.
// Parameters:
// - `claim`: An object indicating the user's role (e.g., whether they are a moderator).
// Returns:
// - An object specifying the user's capabilities for different channels.
const generateCapability = (claim: { isMod: boolean }) => {
  if (claim.isMod) {
    // Moderators have full access to all channels.
    return { "*": ["*"] };
  } else {
    // Regular users have specific permissions for certain channels.
    return {
      "chat:general": ["subscribe", "publish", "presence", "history"],
      "chat:random": ["subscribe", "publish", "presence", "history"],
      "chat:announcements": ["subscribe", "presence", "history"],
    };
  }
};
// Handler for the GET request to this API route.
// Generates an Ably token for the authenticated user.
export const GET = async () => {
  // Authenticate the user and get their session.
  const session = await auth();
  const user = session?.user;
  // Define the user's role as non-moderator by default.
  const userClaim = {
    isMod: false,
  };
  // Generate the user's channel permissions based on their role.
  const userCapability = generateCapability(userClaim);
  // If the user is authenticated, create a signed token for them.
  const token =
    user?.email &&
    (await createToken(
      user?.email, // Use the user's email as the client ID.
      process.env.ABLY_SECRET_KEY as string, // Use the Ably secret key from environment variables.
      userClaim, // Pass the user's role.
      userCapability, // Pass the generated channel permissions.
    ));
  // Return the generated token or an empty response if the token couldn't be created.
  return Response.json(token || "");
};

Let’s break down what’s happening here:

JWT Token Creation: The createToken function generates a JSON Web Token compatible with Ably, including user capabilities and a client identifier. Here, we encode the claim in the token, meaning that the userClaim will be included in any events published by this client in topics with a name matching *.
Dynamic Capabilities: The generateCapability function assigns permissions to users based on their role (moderator or regular user) for specific channels.
User Authentication: The auth function is used to retrieve the user’s session, ensuring only authenticated users can request tokens.
Environment Variables: The ABLY_SECRET_KEY environment variable securely stores the Ably API secret for token signing.
API Response: The handler processes the request, generates the token, and returns it as a JSON response or an empty string if the user is unauthenticated.

Next, lt’s build out all the components we need for that chat page. We’ll start with the Message Item component that displays a single message sent by a user.

Message Item component

Create a new file - ./components/Message/Item.tsx:

// ./components/Message/Item.tsx
// Import required types and components.
// `InboundMessage` is a type from Ably that represents a message received from a channel.
// `Image` is imported from Next.js for optimized image handling.
import { InboundMessage } from "ably";
import Image from "next/image";
// Define the `MessageItem` component as a functional React component with props.
// Props:
// - `message`: An object representing the message, including data and metadata.
// - `onDelete`: A callback function to handle message deletion, identified by a timeserial.
// - `fromUser`: A boolean indicating whether the message is sent by the current user.
const MessageItem: React.FC<{
  message: InboundMessage;
  onDelete: (timeserial: string) => void;
  fromUser: boolean;
}> = ({ message, onDelete, fromUser }) => {
  // Log the sender of the message and whether it's from the current user (for debugging).
  console.log({ fromUser, user: message.clientId });
  return (
    // The outermost container adjusts its layout based on the sender.
    // If the message is from the current user, it uses `flex-row-reverse` for alignment.
    <div
      className={`group relative flex w-fit items-start gap-2 rounded-3xl bg-gray-50 p-2 dark:bg-gray-800 ${
        fromUser ? "flex-row-reverse" : "!flex-row"
      }`}
    >
      {/* Display the avatar for the sender. */}
      <figure className="shrink-0 p-1">
        <Image
          src={message.data.avatarUrl} // URL for the avatar image.
          alt="avatar" // Alternative text for accessibility.
          className="h-8 w-8 rounded-full" // Styling for a circular avatar.
          width={32}
          height={32}
        />
      </figure>
      {/* Display the message content. */}
      <div
        className={`flex flex-col ${
          fromUser ? "pl-2 text-right" : "pr-2 text-left"
        }`}
      >
        {/* The message text, styled for readability. */}
        <span className={`font-medium text-gray-900 dark:text-white`}>
          {message.data.text}
        </span>
        {/* The message timestamp, formatted as a localized time string. */}
        <span
          className={`truncate text-[0.625rem] text-gray-500 dark:text-gray-400`}
        >
          {new Date(message.timestamp).toLocaleTimeString()}
        </span>
      </div>
      {/* If the message is from the current user, show a delete button. */}
      {fromUser && (
        <button
          onClick={() => onDelete(message.id as string)} // Call the `onDelete` function with the message ID.
          className="btn invisible absolute z-[5] flex group-hover:visible"
        >
          {/* Icon for the delete button, rendered as an SVG. */}
          <svg
            xmlns="http://www.w3.org/2000/svg"
            viewBox="0 0 20 20"
            fill="currentColor"
            className="icon"
          >
            <path
              fillRule="evenodd"
              d="M8.75 1A2.75 2.75 0 0 0 6 3.75v.443c-.795.077-1.584.176-2.365.298a.75.75 0 1 0 .23 1.482l.149-.022.841 10.518A2.75 2.75 0 0 0 7.596 19h4.807a2.75 2.75 0 0 0 2.742-2.53l.841-10.52.149.023a.75.75 0 0 0 .23-1.482A41.03 41.03 0 0 0 14 4.193V3.75A2.75 2.75 0 0 0 11.25 1h-2.5ZM10 4c.84 0 1.673.025 2.5.075V3.75c0-.69-.56-1.25-1.25-1.25h-2.5c-.69 0-1.25.56-1.25 1.25v.325C8.327 4.025 9.16 4 10 4ZM8.58 7.72a.75.75 0 0 0-1.5.06l.3 7.5a.75.75 0 1 0 1.5-.06l-.3-7.5Zm4.34.06a.75.75 0 1 0-1.5-.06l-.3 7.5a.75.75 0 1 0 1.5.06l.3-7.5Z"
              clipRule="evenodd"
            />
          </svg>
        </button>
      )}
    </div>
  );
};
// Export the `MessageItem` component for use in other parts of the application.
export default MessageItem;

This MessageItem component dynamically adjusts its layout based on the fromUser prop, using flex-row-reverse for alignment.
It displays the sender’s avatar sourced from message.data.avatarUrl. The message text (message.data.text) and its timestamp (message.timestamp) are shown, formatted as a localized time string.
For messages sent by the current user, a delete button, rendered with an SVG icon, is conditionally displayed and triggers the onDelete callback with message.id.

Message List component

Create a new file - ./components/Message/List.tsx:

// ./components/Message/List.tsx

// Import required types and components.
// `InboundMessage` is a type from Ably that represents a message object.
// `MessageItem` is a child component that renders individual messages.
// `useSession` is a hook from NextAuth used to access the authenticated user's session data.
import { InboundMessage } from "ably";
import MessageItem from "@/components/Message/Item";
import { useSession } from "next-auth/react";

// Define the `MessageList` component as a functional React component with props.
// Props:
// - `messages`: An array of `InboundMessage` objects representing chat messages.
// - `onDelete`: A callback function to handle message deletion, identified by a timeserial.
const MessageList: React.FC<{
  messages: InboundMessage[];
  onDelete: (timeserial: string) => void;
}> = ({ messages, onDelete }) => {
  // Retrieve the current session data to identify the logged-in user.
  const session = useSession();

  return (
    // Render a list of messages as a vertical column.
    // The container ensures messages are aligned at the bottom of the view and spaced apart.
    <ul className="flex h-full flex-col justify-end gap-2">
      {/* Map over the `messages` array to render each message. */}
      {messages.map((message) => {
        // Determine if the message is from the logged-in user by comparing their email
        // with the message's `clientId` in a case-insensitive manner.
        const fromUser =
          session?.data?.user?.email?.trim().toLowerCase() ===
          message.clientId?.trim().toLowerCase();

        return (
          // Each message is wrapped in a `li` element for semantic HTML.
          // If the message is from the user, apply additional styles (`self-end`) for alignment.
          <li
            className={`flex flex-row items-start gap-2 ${fromUser ? "self-end" : ""}`}
            key={message.id} // Use the message ID as the unique key for React's reconciliation.
          >
            {/* Render the `MessageItem` component for each message.
                Pass the `message`, the `onDelete` callback, and the `fromUser` flag as props. */}
            <MessageItem
              message={message}
              onDelete={onDelete}
              fromUser={fromUser}
            />
          </li>
        );
      })}
    </ul>
  );
};

// Export the `MessageList` component for use in other parts of the application.
export default MessageList;

The MessageList component renders a scrollable list of messages using a messages.map() loop, where each message is displayed through the MessageItem component.
It identifies if a message is sent by the logged-in user by comparing the session email (session.data.user.email) with the message’s clientId, styling user messages with self-end for right alignment.
Each MessageItem receives its message and the onDelete callback.

Message Input component

Create new file - ./components/Message/Input.tsx:

// ./components/Message/Input.tsx

// Import the `useState` hook to manage the input field's state.
import { useState } from "react";

// Define the `MessageInput` component as a functional React component with props.
// Props:
// - `onSubmit`: A callback function triggered when the form is submitted.
// - `disabled`: An optional boolean to enable/disable the input field and submission button.
const MessageInput: React.FC<{
  onSubmit: (message: string) => void;
  disabled?: boolean;
}> = ({ onSubmit, disabled = false }) => {
  // State to store the current value of the input field.
  const [input, setInput] = useState("");

  // Event handler to update the `input` state as the user types.
  const handleChange = (e: React.ChangeEvent<HTMLInputElement>) => {
    setInput(e.target.value);
  };

  // Event handler to handle form submission.
  // Prevents the default browser behavior, invokes the `onSubmit` callback with the input value,
  // and clears the input field.
  const handleSubmit = (e: React.FormEvent<HTMLFormElement>) => {
    e.preventDefault();
    onSubmit(input);
    setInput("");
  };

  return (
    // Form element for submitting a new message.
    // Calls `handleSubmit` on form submission.
    <form
      onSubmit={handleSubmit}
      className="flex items-center justify-between gap-4"
    >
      {/* Input field for entering the message. */}
      <input
        type="text" // Input type is text.
        value={input} // Bind the input field's value to the `input` state.
        onChange={handleChange} // Update the `input` state on change.
        disabled={disabled} // Disable the field if `disabled` is true.
        placeholder={
          disabled ? "This input has been disabled." : "Your message here"
        } // Show a contextual placeholder based on the `disabled` prop.
        className="form-input" // Add styling to the input field.
      />

      {/* Submit button to send the message. */}
      <button className="btn primary" disabled={disabled}>
        {/* SVG icon for an upward arrow, symbolizing submission. */}
        <svg
          xmlns="http://www.w3.org/2000/svg"
          viewBox="0 0 20 20"
          fill="currentColor"
          className="icon"
        >
          <path
            fillRule="evenodd"
            d="M10 17a.75.75 0 0 1-.75-.75V5.612L5.29 9.77a.75.75 0 0 1-1.08-1.04l5.25-5.5a.75.75 0 0 1 1.08 0l5.25 5.5a.75.75 0 1 1-1.08 1.04l-3.96-4.158V16.25A.75.75 0 0 1 10 17Z"
            clipRule="evenodd"
          />
        </svg>
      </button>
    </form>
  );
};

// Export the `MessageInput` component for use in other parts of the application.
export default MessageInput;

The MessageInput component manages user input with useState and submits messages via onSubmit, resetting the field after submission. The input field (<input>) shows contextual placeholders and is disabled when the disabled prop is true.

Chat Channel List component

Create a new file - ./components/Chat/ChannelList.tsx:

// ./components/Chat/ChannelList.tsx
// Imports necessary modules for navigation and routing
import Link from "next/link";
import { usePathname } from "next/navigation";
// Defines the available chat channels with their IDs and display names
export const channels = [
  { id: "general", name: "General" },
  { id: "random", name: "Random" },
  { id: "mod", name: "Moderators" },
];
const ChatChannelList = () => {
  // Retrieves the current path to determine the active channel
  const pathname = usePathname();
  return (
    <ul className="flex flex-col">
      {channels.map((channel) => (
        <li key={channel.id}>
          {/* Creates a link for each channel */}
          <Link
            href={`/chat/${channel.id}`}
            className={`${
              pathname === `/chat/${channel.id}` ? "font-bold" : "" // Highlights the active channel
            }`}
          >
            <span className="truncate">{channel.name}</span>{" "}
            {/* Displays the channel name */}
          </Link>
        </li>
      ))}
    </ul>
  );
};
export default ChatChannelList; // Exports the component for use in other parts of the application

The ChatChannelList component renders a list of channels as links. The active channel is highlighted using the font-bold class based on the current pathname.

Chat component

Create a new file - ./components/Chat/index.tsx:

// ./components/Chat/index.tsx
import { useEffect, useState } from "react";
import { useChannel } from "ably/react";
import { InboundMessage } from "ably";
import { useSession } from "next-auth/react";
import * as ScrollArea from "@radix-ui/react-scroll-area";
import MessageList from "@/components/Message/List";
import MessageInput from "@/components/Message/Input";
// The Chat component handles a chat channel, listens to new messages,
// publishes new messages, and displays them in a scrollable area.
const Chat: React.FC<{ channelName: string }> = ({ channelName }) => {
  const session = useSession(); // Access session data for user info
  const [messages, setMessages] = useState<InboundMessage[]>([]); // Local state to store messages
  // useChannel hook from Ably listens for messages on the provided channel
  // and updates the messages list based on the received action.
  const { channel, publish } = useChannel(channelName, (message) => {
    if (message.name === "ADD" || message.name === "PROMOTE")
      setMessages((messages) => [...messages, message as InboundMessage]);
    if (message.name === "DELETE")
      setMessages((messages) =>
        messages.filter((m) => {
          // Remove the message if it matches the one being deleted.
          const matchingMessage = m.id === message.extras?.ref?.id;
          const isOwnMessage = m.clientId === message.clientId;
          return !(matchingMessage && isOwnMessage);
        }),
      );
    if (message.name === "PROMOTE" || message.name === "DEMOTE") {
      setMessages((messages) => [...messages, message as InboundMessage]);
    }
  });
  // Function to publish a new message to the channel via Ably
  const publishMessage = (text: string) => {
    publish({
      name: "ADD",
      data: {
        text, // Message content
        avatarUrl: session?.data?.user?.image as string, // User avatar URL
      },
    });
  };
  // Function to handle deleting a message by publishing a delete event
  const handleDelete = (id: string) => {
    publish({
      name: "DELETE",
      extras: {
        ref: { id },
      },
    });
  };
  // Fetching message history from the channel when the component mounts
  useEffect(() => {
    let ignore = false; // To prevent state updates after unmount
    const fetchHist = async () => {
      console.log("fetching history");
      const history = await channel.history({
        limit: 100, // Limit to the last 100 messages
        direction: "forwards", // Fetch from earliest to latest
      });
      if (!ignore)
        history.items.forEach((item) => {
          if (item.name === "ADD")
            setMessages((messages) => [...messages, item as InboundMessage]);
          if (item.name === "DELETE")
            setMessages((messages) =>
              messages.filter((m) => {
                const matchingMessage =
                  m.extras?.timeserial === item.extras?.ref?.timeserial;
                const isOwnMessage = m.clientId === item.clientId;
                return !(matchingMessage && isOwnMessage);
              }),
            );
        });
    };
    fetchHist();
    return () => {
      ignore = true; // Cleanup on unmount to avoid memory leaks
    };
  }, [channel]); // Effect runs when the channel changes
  return (
    <>
      {/* Scrollable area for message list */}
      <ScrollArea.Root className="h-full w-full overflow-hidden rounded bg-white dark:bg-gray-900">
        <ScrollArea.Viewport className="flex size-full flex-col justify-end rounded p-4">
          {/* List of messages */}
          <MessageList messages={messages} onDelete={handleDelete} />
        </ScrollArea.Viewport>
        {/* Vertical scrollbar for the message area */}
        <ScrollArea.Scrollbar
          className="flex touch-none select-none p-0.5 transition-colors ease-out data-[orientation=horizontal]:h-2.5 data-[orientation=vertical]:w-2.5 data-[orientation=horizontal]:flex-col"
          orientation="vertical"
        >
          <ScrollArea.Thumb className="relative flex-1 rounded-[10px] bg-gray-200 before:absolute before:left-1/2 before:top-1/2 before:size-full before:min-h-11 before:min-w-11 before:-translate-x-1/2 before:-translate-y-1/2" />
        </ScrollArea.Scrollbar>
        {/* Horizontal scrollbar for the message area */}
        <ScrollArea.Scrollbar
          className="flex touch-none select-none p-0.5 transition-colors ease-out data-[orientation=horizontal]:h-2.5 data-[orientation=vertical]:w-2.5 data-[orientation=horizontal]:flex-col"
          orientation="horizontal"
        >
          <ScrollArea.Thumb className="bg-mauve10 relative flex-1 rounded-[10px] before:absolute before:left-1/2 before:top-1/2 before:size-full before:min-h-[44px] before:min-w-[44px] before:-translate-x-1/2 before:-translate-y-1/2" />
        </ScrollArea.Scrollbar>
        {/* Scroll area corner */}
        <ScrollArea.Corner className="" />
      </ScrollArea.Root>
      {/* Message input field at the bottom */}
      <div className="mt-auto p-5">
        <MessageInput onSubmit={publishMessage} />
      </div>
    </>
  );
};
export default Chat;

In this component, we’re doing a few things:

Message Handling: The component listens for messages (ADD, DELETE, PROMOTE) via useChannel and updates the message list accordingly.
Publishing Messages: Messages are published using the publishMessage function, sending the message text and user avatar.
ScrollArea: Radix UI’s ScrollArea is used for smooth scrolling in both vertical and horizontal directions for the message history.
Message History Fetching: On mount, we fetche the last 100 messages from the channel’s history.

Next, we’ll put everything together in the chat page.

Create Chat Page

Create a new file - ./app/chat/[[...channel]]/page.tsx:

// ./app/chat/[[...channel]]/page.tsx
"use client"; // This ensures the component is rendered client-side, required for Ably and NextAuth.
// Import necessary components and providers
import Chat from "@/components/Chat"; // Chat component to handle chat messages and functionality.
import ChatChannelList from "@/components/Chat/ChannelList"; // Sidebar with a list of available chat channels.
import { Realtime } from "ably"; // Ably Realtime client for managing connections and messaging.
import { AblyProvider, ChannelProvider } from "ably/react"; // Providers for using Ably hooks in React components.
import { SessionProvider } from "next-auth/react"; // Provider for managing authentication state.
import { use } from "react"; // Hook to handle async data like the `params` object.
// The Page component defines the layout and functionality for the chat application.
const Page = ({ params }: { params: Promise<{ channel: string[] }> }) => {
  // 👉 Create an Ably Realtime client instance
  //    - `authUrl`: URL for authorizing the connection using a token-based authentication strategy.
  //    - `autoConnect`: Ensures the client connects only when the app runs in the browser.
  const client = new Realtime({
    authUrl: "/api/ably", // Authorization endpoint to secure the Ably connection.
    autoConnect: typeof window !== "undefined", // Only auto-connect in the browser.
  });
  // Extract the `channel` parameter from the dynamic route.
  // The `params` object is an async promise containing the route parameters.
  const { channel } = use(params);
  // Format the channel name to match the expected format in the application.
  // For example, if `channel` is "general", the `channelName` becomes "chat:general".
  const channelName = `chat:${channel}`;
  return (
    // 👉 Wrap the entire application in providers to manage state and context.
    // `SessionProvider`: Manages the user's authentication session globally.
    <SessionProvider>
      {/* `AblyProvider`: Provides Ably context to child components for accessing the Realtime client. */}
      <AblyProvider client={client}>
        {/* `ChannelProvider`: Supplies the current channel context to components like Chat. */}
        <ChannelProvider channelName={channelName}>
          {/* Main chat application layout */}
          <section className="site-section !p-0">
            <div className="wrapper grid h-[calc(100vh-4.25rem)] grid-cols-4 !p-0">
              {/* Sidebar: Displays the list of available chat channels */}
              <div className="h-full max-h-full rounded-xl bg-gray-50 p-5 dark:bg-gray-800">
                <ChatChannelList />
              </div>
              {/* Main Chat Area: Center column for chat messages and input */}
              <div className="col-span-2 flex h-full flex-col overflow-hidden">
                {/* Pass the current channel name to the Chat component */}
                <Chat channelName={channelName} />
              </div>
              {/* Right Sidebar: Reserved for additional features like a user list */}
              <div className="col-span-1 flex h-full flex-col">
                {/* TODO: Implement a user list or additional features in the right sidebar */}
              </div>
            </div>
          </section>
        </ChannelProvider>
      </AblyProvider>
    </SessionProvider>
  );
};
export default Page; // Export the Page component as the default export.

The Page component wraps the chat app in providers for state and context management. The SessionProvider ensures global access to the user’s session, while the AblyProvider and ChannelProvider enable seamless integration with Ably by sharing a Realtime client (authUrl: "/api/ably") and the current channelName (e.g., chat:general).

The layout uses a grid with three sections: a left sidebar (<ChatChannelList /> for channel navigation), a center area (<Chat channelName={channelName} /> for messages), and a placeholder right sidebar (TODO: Users list) for future features like online users. The autoConnect option ensures Ably connects only in the browser, avoiding SSR issues.

With that, we should have something like this, when we navigate to http://localhost:3000/chat/general:

Now that our cha

Set up Permit.io

Create a new account at https://www.permit.io/:

Create a new project

Enter the name of your project, I’ll be using Live Chat for this example:

Create new resource

To create channels for our chat app, Permit allows us to create resources which are entities that represent what users can have access to, let’s set up our channel as a resource to proceed:

Edit resuorce

Now we can edit the resource and add roles on our channel resource:

View roles

Here are the roles we’ve created. You can view it by going to the Roles tab on the Policy page.

Udpate policies

Now we can update our policies to determine who has access to what on each resource:

Create resource instance

Create resource instances for each channel we want in our chat, here we are creating an instance for the general channel, we can do same for random and mod.

View Instances

Here we can see the created resource instances:

Now that we’ve set up our Permit Dashboard, we can add Permit to our Next.js app.

Adding Permit.io to your Next.js application

Let’s dive in and start integrating Permit.io into our application.

First, we have to install the permitio package:

npm install permitio

We have to obtain our API key from our Permit.io dashboard:

Add the copied key to the .env file:

# .env
# ...
PERMIT_API_KEY=permit_key_0000

Set up local PDP

Next, we’ll have to set up our Policy Decision Point which is a network node responsible for answering authorization queries using policies and contextual data.

Pull the PDP container from Docker Hub (Click here to install Docker):

docker pull permitio/pdp-v2:latest

Run the container & replace the PDP_API_KEY environment variable with your API key.

docker run -it \
  -p 7766:7000 \
  --env PDP_API_KEY=<YOUR_API_KEY> \
  --env PDP_DEBUG=True \
  permitio/pdp-v2:latest

Now that we have our PDP set up, let’s dive in to adding autoriaztion to our app, you can learn more about adding Permit.io to a Next.js app from this step-by-step tutorial on the Permit.io blog.

For this example, we’ll need to set up a few reusable functions and routes, lets start with creating a Permit library function in ./lib/permit.ts:

// ./lib/permit.ts
import { Permit } from "permitio";
const PERMIT_API_KEY = process.env.PERMIT_API_KEY;
// This first line initializes the SDK and connects your Node.js app
// to the Permit.io PDP container you've set up in the previous step.
const permit = new Permit({
  // your API Key
  token: PERMIT_API_KEY,
  // in production, you might need to change this url to fit your deployment
  pdp: "http://localhost:7766",
  // if you want the SDK to emit logs, uncomment this:
  // log: {
  //   level: "debug",
  // },
  // The SDK returns false if you get a timeout / network error
  // if you want it to throw an error instead, and let you handle this, uncomment this:
  // throwOnError: true,
});
export default permit;

We’ll also create ./utils/permit.ts file for all our permit-related utility functions:

// ./utils/permit.ts
import permit from "@/lib/permit";
/**
 * Syncs a user with Permit.io and assigns roles.
  *
  * @param user - User details including id, first name, last name, and email.
  * @param role - Role to be assigned to the user for a specific resource.
  * @param resource_instance - Resource instance for which the role is assigned.
  * @returns Object containing the results of default and specific role assignments.
  */
const handleSyncUser = async ({
  user,
  role,
  resource_instance,
}: {
  user: {
    id: string;
    first_name: string;
    last_name: string;
    email: string;
  };
  role: string;
  resource_instance: string;
}) => {
  try {
    // Synchronize the user with Permit.io using their ID and basic information.
    const syncUser = await permit.api.syncUser({
      key: user.id,
      email: user.email,
      first_name: user.first_name,
      last_name: user.last_name,
      attributes: {}, // Add any custom attributes if needed.
    });
    // Assign a default role ("viewer") to the user for the default tenant.
    const assignDefaultRole = await permit.api.assignRole({
      role: "viewer",
      tenant: "default",
      user: syncUser.id,
    });
    // Assign a specific role to the user for a given resource instance.
    const assignRole = await permit.api.assignRole({
      role: role || "viewer", // Fallback to "viewer" if no role is provided.
      tenant: "default",
      user: syncUser.id,
      resource_instance,
    });
    return { assignRole, assignDefaultRole }; // Return role assignment results.
  } catch (error) {
    console.error("Error syncing user with Permit.io: ", error); // Log error details.
    return error; // Return error for further handling.
  }
};
/**
 * Retrieves a specific user's details from Permit.io using their ID.
  *
  * @param id - Unique identifier of the user.
  * @returns User details retrieved from Permit.io.
  */
const handleGetPermitUser = async (id: string) => {
  return await permit.api.getUser(id);
};
/**
 * Retrieves a list of all users managed by Permit.io.
  *
  * @returns List of users.
  */
const handleGetPermitUsers = async () => {
  return await permit.api.users.list();
};
/**
 * Retrieves a list of all resource instances managed by Permit.io.
  *
  * @returns List of resource instances.
  */
const handleListResourceInstances = async () => {
  return await permit.api.resourceInstances.list();
};
/**
 * Retrieves the roles assigned to a user by their user ID.
  *
  * @param userId - Unique identifier of the user.
  * @returns List of roles assigned to the user.
  */
const getUserRoles = async (userId: string) => {
  try {
    return await permit.api.getAssignedRoles(userId);
  } catch (error) {
    console.error("Error fetching user roles: ", error); // Log error details.
    return []; // Return an empty array for graceful error handling.
  }
};
export {
  handleGetPermitUser,
  handleSyncUser,
  handleGetPermitUsers,
  handleListResourceInstances,
  getUserRoles,
};

User Hook

We’ll have to create a useUser hook which will allow us to easily retrieve the permit user on the frontend. Create a new file ./hooks/useUser.ts:

// ./hooks/useUser.ts
import { PermitUser } from "@/types/user";
import { User } from "next-auth";
import { useSession } from "next-auth/react";
import { useCallback, useEffect, useState } from "react";
/**
 * Custom hook to fetch and manage user data from the Permit.io API.
  *
  * This hook combines Permit.io user data with NextAuth user data, returning a unified
  * user object containing Permit.io attributes alongside NextAuth session properties.
  *
  * @returns An object containing the combined user data or `null` if not available.
  */
const useUser = () => {
  // Extract the user data from the NextAuth session.
  const sessionUser = useSession().data?.user;
  // State to hold the combined user data.
  const [user, setUser] = useState<(PermitUser & Partial<User>) | null>(null);
  // Fetch user details from the Permit.io API and combine with NextAuth session data.
  const getPermitUser = useCallback(async () => {
    try {
      // Make a request to the API endpoint to fetch Permit.io user data.
      const res = await fetch("/api/permit/getUser");
      // Parse the API response and cast it to the PermitUser type.
      const user = (await res.json()).user as PermitUser;
      // Merge Permit.io user data with session data (e.g., image and name from NextAuth).
      setUser({
        ...user,
        image: sessionUser?.image,
        name: sessionUser?.name,
      });
    } catch (error) {
      // Handle errors gracefully and reset the user state to `null`.
      console.error("Error fetching Permit.io user data:", error);
      setUser(null);
    }
  }, [sessionUser]);
  useEffect(() => {
    // Fetch user data only when sessionUser is available.
    getPermitUser();
  }, [sessionUser, getPermitUser]);
  return { user, getPermitUser };
};
export default useUser;

Create Users in Permit During Authentication

To automatically add users to Permit during sign-in, use NextAuth’s signIn callback. During the callback:

Fetch Resource Instances: Retrieve resource instances from Permit (e.g., a default workspace or project).
Sync User Data: Use a utility function (like handleSyncUser) to create or update the user’s information in Permit. This includes their ID, email, name, role (e.g., “participant”), and the relevant resource instance.
Complete Sign-In: The sign-in process will continue by returning true.

Replace the ./auth.ts file with this updated code:

// ./auth.ts
// Import NextAuth for authentication and session management
import NextAuth from "next-auth";
// Import the Google provider for authentication via Google accounts
import Google from "next-auth/providers/google";
// Import utility functions for Permit.io integration
import { handleListResourceInstances, handleSyncUser } from "./utils/permit";
// Export handlers and authentication functions provided by NextAuth
export const { handlers, signIn, signOut, auth } = NextAuth({
  // Define the list of authentication providers (Google in this case)
  providers: [Google],
  // Define custom callback functions for NextAuth
  callbacks: {
    // Custom sign-in callback function
    async signIn(params) {
      // Log the sign-in parameters for debugging
      console.log("🟢🟢🟢🟢🟢 ~ params", params);
      // Fetch the list of resource instances using the Permit.io utility
      const resourceInstances = await handleListResourceInstances();
      // Find the specific resource instance with the key "general"
      const resourceInstance = resourceInstances.find(
        (resourceInstance) => resourceInstance.key === "general",
      );
      // Log the fetched resource instance for debugging
      console.log("🟢🟢🟢🟢🟢 ~ resourceInstance", resourceInstance);
      // Sync the authenticated user's data with Permit.io, assigning them a role and associating them with the resource instance
      handleSyncUser({
        user: {
          id: params.user.email as string, // User's email
          email: params.user.email as string, // User's email
          first_name: params.profile?.given_name as string, // User's first name
          last_name: params.profile?.family_name as string, // User's last name
        },
        role: "participant", // Assign the role of "participant" to the user
        resource_instance: resourceInstance?.id as string, // Associate the user with the "general" resource instance
      });
      // Allow the sign-in process to proceed
      return true;
    },
  },
});

This ensures users are authenticated and seamlessly integrated into Permit for access control.

As we can see below, when the user signs in, their account is being added to our Permit dashboard:

We’ll have to set up a few more things before we can proceed, let’s starts with types to appease TypeScript as we develop our app. Create a new ./types/user.ts file and enter the following:

// ./types/user.ts
// Importing necessary types from the "permitio" package.
// `RoleAssignmentRead` represents the structure of role assignment data,
// and `UserRead` represents the structure of user data.
import { RoleAssignmentRead, UserRead } from "permitio";
// Define a new type `PermitUser` by combining `UserRead` and `RoleAssignmentRead`.
// This represents a user with role assignment information in the context of Permit.io.
type PermitUser = UserRead & RoleAssignmentRead;
// Export the `PermitUser` type for use in other parts of the application.
// This allows consistent typing for users with roles and permissions.
export type { PermitUser };

Next, we’ll create a few API routes to obtain user data and permissions and promote and demote users.

Get Users Data

Create a new file - ./app/api/permit/getUsers/route.ts:

// ./app/api/permit/getUsers/route.ts
import permit from "@/lib/permit"; // Importing the Permit.io instance from the specified library path.
import { getUserRoles } from "@/utils/permit";
// Exported GET handler function for fetching all users and their roles.
export const GET = async () => {
  try {
    // Fetch the list of users using the Permit.io API.
    const res = await permit.api.users.list();
    // Map over the users and fetch their roles asynchronously.
    const users = await Promise.all(
      res.data.map(async (user) => {
        const roles = await getUserRoles(user.id); // Fetch roles for the current user.
        return { ...user, roles }; // Merge user data with their roles.
      }),
    );
    // Return a JSON response containing the list of users and their roles.
    return Response.json({ users });
  } catch (error) {
    // Log any errors that occur during the process.
    console.log("🔴🔴🔴🔴 ~ err: ", error);
    // Return a JSON response with the error information for debugging.
    return Response.json({ error });
  }
};

Get User Data

Create a new file *./app/api/permit/getUser/route.ts*:

// ./app/api/permit/getUser/route.ts
// Import the authentication function to verify and retrieve the authenticated user's information.
import { auth } from "@/auth";
// Import the Permit.io instance to interact with the Permit API.
import permit from "@/lib/permit";
// Import the helper function to fetch a user's assigned roles.
import { getUserRoles } from "@/utils/permit";
// Define the GET handler for the API route.
export const GET = async () => {
  try {
    // Retrieve the authenticated user's email from the `auth` function.
    const userKey = (await auth())?.user?.email;
    // If the user's email is not found, throw an error.
    if (!userKey) throw new Error("User not found");
    // Fetch the user details from the Permit.io API using their email as the unique key.
    const res = await permit.api.users.get(userKey);
    // Fetch the roles assigned to the user using the `getUserRoles` utility function.
    const roles = await getUserRoles(res.id);
    // Merge the user details with their roles into a single object.
    const user = { ...res, roles };
    // Log the user details for debugging purposes.
    console.log("🚀 ~ user: ", user);
    // Return the user data as a JSON response.
    return Response.json({ user });
  } catch (error) {
    // Log any errors that occur during the process for debugging.
    console.log("🔴🔴🔴🔴 ~ err: ", error);
    // Return an error response in JSON format.
    return Response.json({ error });
  }
};

Promote User

Create a new file - ./app/api/permit/promoteUser/route.ts and enter the following:

// ./app/api/permit/promoteUser/route.ts
import { auth } from "@/auth"; // Import the authentication module.
import permit from "@/lib/permit"; // Import the Permit.io instance for API interactions.
import { handleListResourceInstances } from "@/utils/permit"; // Utility function to fetch resource instances.
import { NextRequest } from "next/server"; // Import the Next.js request object type.
/**
 * Promotes a user by assigning roles on specific resource instances.
  * @param data - An object containing userKey, channel, role, and modChannel.
  * @returns An object with the results of each role assignment operation.
  */
const promoteUser = async (data: {
  userKey: string;
  channel: string;
  role: string;
  modChannel: string;
}) => {
  // Retrieve the current user's key (e.g., email or unique identifier).
  const currentUserKey = (await auth())?.user?.email;
  if (!currentUserKey) throw new Error("User not found");
  // Check if the current user has permission to promote other users.
  const canPromoteUser = await permit.check(
    currentUserKey,
    "promote",
    "channel",
  );
  console.log("🟢 Can Promote User:", canPromoteUser);
  if (!canPromoteUser) throw new Error("Cannot promote user");
  // Assign the specified role to the user on the target channel.
  const assignToModRoleOnChannel = await permit.api.assignRole({
    role: data.role || "participant",
    tenant: "default",
    user: data.userKey,
    resource_instance: data.channel,
  });
  // Assign the "participant" role to the user on the moderation channel.
  const assignModChannelRole = await permit.api.assignRole({
    role: "participant",
    tenant: "default",
    user: data.userKey,
    resource_instance: data.modChannel,
  });
  // Assign the "admin" role to the user.
  const assignAdminRole = await permit.api.assignRole({
    role: "admin",
    tenant: "default",
    user: data.userKey,
  });
  // Return the results of each assignment operation.
  return { assignModChannelRole, assignToModRoleOnChannel, assignAdminRole };
};
export const GET = async (request: NextRequest) => {
  try {
    // Extract query parameters from the request.
    const searchParams = request.nextUrl.searchParams;
    const key = searchParams.get("key"); // The user key (email or unique identifier).
    const channel = searchParams.get("channel")?.split(":")[1]; // Extract the channel identifier.
    // Validate that both the user key and channel are provided.
    if (!key || !channel) throw new Error("User key or channel not provided");
    // Fetch the list of resource instances from the Permit.io API.
    const resourceInstances = await handleListResourceInstances();
    // Find the specific resource instance for the given channel and the moderation channel.
    const resourceInstance = resourceInstances.find(
      (resource) => resource.key === channel,
    );
    const modChannel = resourceInstances.find(
      (resource) => resource.key === "mod",
    );
    // Ensure the resource instances for the channel and moderation channel exist.
    if (!resourceInstance?.id || !modChannel?.id) {
      throw new Error("Resource not found");
    }
    // Execute the promotion process.
    const res = await promoteUser({
      channel: resourceInstance.id,
      userKey: key,
      role: "moderator",
      modChannel: modChannel.id,
    });
    console.log("🟢 Promotion Result:", res);
    // Return the result as a JSON response.
    return new Response(JSON.stringify({ data: res }), {
      status: 200,
    });
  } catch (error) {
    // Log any errors that occur during the process.
    console.error("🔴 Error:", error);
    // Return the error message as a JSON response with a 400 status code.
    return new Response(JSON.stringify({ error: (error as Error).message }), {
      status: 400,
    });
  }
};

Here we have a Next.js API route that promotes a user by assigning them specific roles on different resource instances using Permit.io.
The promoteUser function checks if the current user has permission to promote others and assigns roles such as "participant," "moderator," and "admin" to the target user on specified channels.
The GET function handles incoming requests, extracts query parameters, validates them, fetches resource instances, and executes the promotion process. It returns the results as a JSON response or an error message if any issues occur.

Demote User

Create a new file - ./app/api/permit/demoteUser/route.ts and enter the following:

// ./app/api/permit/demoteUser/route.ts
import permit from "@/lib/permit"; // Import the Permit.io instance for API interactions.
import { handleListResourceInstances } from "@/utils/permit"; // Utility function to fetch resource instances.
import { NextRequest } from "next/server"; // Import the Next.js request object type.
/**
 * Demotes a user by unassigning roles on specific resource instances.
  * @param key - The user key (email or unique identifier).
  * @param currentChannel - The channel to unassign the "moderator" role from.
  * @returns An object with the status of each unassignment operation.
  */
const demoteUser = async (key: string, currentChannel: string) => {
  // Unassign the "participant" role on the moderation channel.
  const unassignModChannel = (
    await permit.api.unassignRole({
      role: "participant",
      tenant: "default",
      user: key,
      resource_instance: "channel:mod",
    })
  ).status;
  // Unassign the "moderator" role on the current channel.
  const unassignModRoleOnChannel = (
    await permit.api.unassignRole({
      role: "moderator",
      tenant: "default",
      user: key,
      resource_instance: currentChannel,
    })
  ).status;
  // Unassign the "admin" role from the user.
  const unassignAdminRole = (
    await permit.api.unassignRole({
      role: "admin",
      tenant: "default",
      user: key,
    })
  ).status;
  // Return the status of each unassignment operation.
  return {
    unassignModRoleOnChannel,
    unassignModChannel,
    unassignAdminRole,
  };
};
export const GET = async (request: NextRequest) => {
  try {
    // Extract query parameters from the request.
    const searchParams = request.nextUrl.searchParams;
    const key = searchParams.get("key"); // The user key (email or unique identifier).
    const channel = searchParams.get("channel")?.split(":")[1]; // Extract the channel identifier.
    // Validate that both the user key and channel are provided.
    if (!key || !channel) throw new Error("User key or channel not provided");
    // Fetch the list of resource instances from the Permit.io API.
    const resourceInstances = await handleListResourceInstances();
    // Find the specific resource instance for the given channel and the moderation channel.
    const resourceInstance = resourceInstances.find(
      (resource) => resource.key === channel,
    );
    const modChannel = resourceInstances.find(
      (resource) => resource.key === "mod",
    );
    // Ensure the resource instances for the channel and moderation channel exist.
    if (!resourceInstance?.id || !modChannel?.id) {
      throw new Error("Resource not found");
    }
    // Retrieve the roles currently assigned to the user.
    const assignedRoles = await permit.api.getAssignedRoles(key);
    console.log("🟢 Assigned Roles:", assignedRoles);
    // Construct the current channel identifier in the required format.
    const currentChannel = `channel:${channel}`;
    console.log("🟢 Current Channel:", currentChannel);
    // Ensure the current channel is valid before proceeding.
    if (!currentChannel) throw new Error("Channel not found");
    // Execute the demotion process.
    const res = await demoteUser(key, currentChannel);
    console.log("🟢 Demotion Result:", res);
    // Return the result as a JSON response.
    return new Response(JSON.stringify({ data: res }), {
      status: 200,
    });
  } catch (error) {
    // Log any errors that occur during the process.
    console.error("🔴 Error:", error);
    // Return the error message as a JSON response with a 400 status code.
    return new Response(JSON.stringify({ error: (error as Error).message }), {
      status: 400,
    });
  }
};

Similarly, we have a Next.js API route that demotes a user by unassigning their roles on specific resource instances using Permit.io. The demoteUser function removes roles such as "participant", "moderator", and "admin" from the user on specified channels. The GET function handles incoming requests, extracts query parameters, validates them, fetches resource instances, retrieves the user's assigned roles, and executes the demotion process.

Get Resources

Create a new file - ./app/api/permit/listResourceInstances/route.ts and enter the following:

// ./app/api/permit/listResourceInstances/route.ts

import { handleListResourceInstances } from "@/utils/permit";
export const GET = async () => {
  const resourceInstances = await handleListResourceInstances();
  return Response.json(resourceInstances);
};

Update Ably permissions route

In our file ./app/api/ably/route.ts, replace it with the following updated code:

// ./app/api/ably/route.ts
import { auth } from "@/auth"; // Authentication utility to validate user sessions.
import { SignJWT } from "jose"; // Library for creating JSON Web Tokens (JWT).
import { handleGetPermitUsers } from "@/utils/permit"; // Utility to fetch Permit.io users.
import permit from "@/lib/permit"; // Instance of Permit.io SDK.
import { RoleAssignmentRead } from "permitio"; // Type definition for Permit.io role assignments.
/**
 * Creates an Ably-compatible JWT token.
  * @param clientId - Unique identifier for the client (e.g., user's email).
  * @param apiKey - Ably API key consisting of app ID and signing key.
  * @param claim - User-specific claims (e.g., is the user a moderator?).
  * @param capability - Mapping of channels to permissions for the user.
  * @returns A signed JWT token.
  */
const createToken = (
  clientId: string,
  apiKey: string,
  claim: { isMod: boolean },
  capability: { [key: string]: string[] | undefined },
) => {
  // Extract the Ably app ID and signing key from the API key.
  const [appId, signingKey] = apiKey.split(":", 2);
  // Use TextEncoder to encode the signing key.
  const enc = new TextEncoder();
  // Create and sign a JWT with Ably-specific claims.
  return new SignJWT({
    "x-ably-capability": JSON.stringify(capability), // Specify channel permissions.
    "x-ably-clientId": clientId, // Associate the token with the client.
    "ably.channel.*": JSON.stringify(claim), // Include custom claims (e.g., moderator status).
  })
    .setProtectedHeader({ kid: appId, alg: "HS256" }) // Include app ID and algorithm.
    .setIssuedAt() // Set issued-at timestamp to now.
    .setExpirationTime("24h") // Set expiration to 24 hours.
    .sign(enc.encode(signingKey)); // Sign the token with the encoded key.
};
/**
 * Generates a permissions object based on the user's roles.
  * @param roles - Array of roles assigned to the user.
  * @returns An object mapping channel names to allowed actions.
  */
const generatePermissions = (roles: RoleAssignmentRead[]) => {
  // Define a mapping of roles to their respective permissions.
  const rolePermissions: Record<string, string[]> = {
    moderator: ["subscribe", "publish", "presence", "history"],
    participant: ["subscribe", "publish", "presence"],
    viewer: ["subscribe"],
  };
  // Transform the user's roles into a permissions object.
  return roles.reduce(
    (permissions, role) => {
      const resourceInstance = role.resource_instance?.split(":")[1]; // Extract channel name.
      const rolePerms = rolePermissions[role.role]; // Get permissions for the role.
      if (resourceInstance && rolePerms) {
        permissions[`chat:${resourceInstance}`] = rolePerms; // Map permissions to the channel.
      }
      return permissions;
    },
    {} as Record<string, string[]>,
  );
};
/**
 * API handler for generating an Ably token for the authenticated user.
  * @returns A JSON response containing the Ably token or an empty string.
  */
export const GET = async () => {
  // Authenticate the user and retrieve their session data.
  const session = await auth();
  const user = session?.user;
  // Fetch all users from Permit.io and locate the current user by email.
  const permitUsers = await handleGetPermitUsers();
  const permitUser = permitUsers.data.find(
    (permitUser) => permitUser.email === user?.email,
  );
  // Retrieve the roles assigned to the user from Permit.io.
  const userAssignedRoles = await permit.api.getAssignedRoles(
    permitUser?.id as string,
  );
  // Generate channel permissions based on the user's roles.
  const permissions = generatePermissions(userAssignedRoles);
  // Determine if the user has moderator privileges.
  const userClaim = {
    isMod: !!userAssignedRoles.find(
      (role) => role.resource_instance === "channel:mod",
    ),
  };
  // Define the user's channel capabilities. Moderators have full access.
  const userCapability = userClaim.isMod ? { "*": ["*"] } : permissions;
  // Generate a signed JWT token for the authenticated user.
  const token =
    user?.email &&
    (await createToken(
      user.email, // Use the user's email as the client ID.
      process.env.ABLY_SECRET_KEY as string, // Retrieve the Ably secret key from environment variables.
      userClaim, // Pass the user's role claims.
      userCapability, // Include the generated channel permissions.
    ));
  // Return the token or an empty string if token generation fails.
  return Response.json(token || "");
};

Here we incorporate Permit.io for managing roles and permissions, replacing static configurations with dynamic role-based permissions.
The generatePermissions function uses data from Permit.io to map roles to specific channel capabilities, ensuring permissions are aligned with user roles in real-time. This approach improves flexibility and ensures the system adapts as roles or permissions change, integrating seamlessly with Ably’s JWT-based authentication.

Update Channel List

Now that we’ve added the resources (channels) to our permit dashboard, we can fetch them from there instead of hardcoding them.
In the ./components/Chat/ChannelList.tsx file, make the following changes:

// ./components/Chat/ChannelList.tsx
// Imports necessary modules for navigation and routing
import Link from "next/link";
import { usePathname } from "next/navigation";
import { useEffect, useState } from "react";
// Defines the available chat channels with their IDs and display names
export const getChannelList = async () => {
  const resourceInstances = await fetch("/api/permit/resourceInstances").then(
    (res) => res.json(),
  );
  const channels = resourceInstances.map(
    (resourceInstance: { key: string }) => ({
      id: resourceInstance.key,
    }),
  );
  return channels;
};
const ChatChannelList = () => {
  // Retrieves the current path to determine the active channel
  const pathname = usePathname();
  const [channels, setChannels] = useState<{ id: string }[]>([]);
  useEffect(() => {
    const fetchChannels = async () => {
      const channels = await getChannelList();
      setChannels(channels);
    };
    fetchChannels();
  }, []);
  return (
    <ul className="flex flex-col">
      {channels.map((channel) => (
        <li key={channel.id}>
          {/* Creates a link for each channel */}
          <Link
            href={`/chat/${channel.id}`}
            className={`${
              pathname === `/chat/${channel.id}` ? "font-bold" : "" // Highlights the active channel
            }`}
          >
            <span className="truncate">
              {channel.id == "mod" ? "🔒" : "💬"} {channel.id}
            </span>{" "}
            {/* Displays the channel name */}
          </Link>
        </li>
      ))}
    </ul>
  );
};
export default ChatChannelList; // Exports the component for use in other parts of the application

Create User List component

Let’s create a user list component that fetches all the permit users and display promote or demote buttons next to the user name.
Create a new file - ./components/Chat/UserList.tsx and enter the following:

// ./components/Chat/UserList.tsx
import useUser from "@/hooks/useUser"; // Custom hook to fetch the current user's information.
import { useChannel } from "ably/react"; // Ably hook for real-time channel communication.
import { UserRead } from "permitio"; // Type definition for Permit.io user data.
import { useCallback, useEffect, useState } from "react";
/**
 * Fetches the list of users from the server using the Permit.io API.
  * @returns A JSON object containing the list of users.
  */
const getUserList = async () => {
  const res = await fetch("/api/permit/getUsers");
  return await res.json();
};
/**
 * Component to display and manage a list of chat users with promote/demote actions.
  * @param {Object} props - Component props.
  * @param {string} props.channelName - The name of the chat channel.
  */
const ChatUserList: React.FC<{ channelName: string }> = ({ channelName }) => {
  const { user: currentUser, getPermitUser } = useUser(); // Get the current logged-in user's details.
  const [users, setUsers] = useState<UserRead[]>([]); // State to hold the list of users.
  const [canPromote, setCanPromote] = useState(false); // State to determine if the current user can promote others.
  // Subscribe to the Ably channel for real-time updates.
  const { publish } = useChannel(channelName, (message) => {
    if (message.name === "PROMOTE" || message.name === "DEMOTE") {
      fetchUsers(); // Fetch the updated user list when a promote/demote event occurs.
      getPermitUser(); // Fetch the updated Permit.io user data when a promote/demote event occurs.
    }
  });
  /**
   * Fetches and updates the list of users, excluding the current user.
    */
  const fetchUsers = useCallback(async () => {
    const data = await getUserList();
    setUsers(
      data.users.filter((user: UserRead) => user.id !== currentUser?.id),
    );
  }, [currentUser?.id]);
  /**
   * Handles promoting a user to a moderator role.
    * @param {string} [userKey] - The unique identifier for the user to promote.
    */
  const handlePromoteUser = async (userKey?: string) => {
    try {
      const res = await fetch(
        `/api/permit/promoteUser?key=${userKey}&channel=${channelName}`,
      );
      if (!res.ok) throw new Error("Failed to promote user");
      // Notify other clients about the promotion.
      publish({
        name: "PROMOTE",
        data: {
          id: userKey,
          text: `User ${userKey} has been promoted to moderator`,
          avatarUrl: `https://www.tapback.co/api/avatar/${userKey}`,
          role: "moderator",
        },
      });
    } catch (error) {
      console.error("🔴 Error promoting user:", error);
    }
  };
  /**
   * Handles demoting a user from a moderator role.
    * @param {string} [userKey] - The unique identifier for the user to demote.
    */
  const handleDemoteUser = async (userKey?: string) => {
    try {
      const res = await fetch(
        `/api/permit/demoteUser?key=${userKey}&channel=${channelName}`,
      );
      if (!res.ok) throw new Error("Failed to demote user");
      // Notify other clients about the demotion.
      publish({
        name: "DEMOTE",
        data: {
          id: userKey,
          text: `User ${userKey} has been demoted from moderator`,
          avatarUrl: `https://www.tapback.co/api/avatar/${userKey}`,
          role: "participant",
        },
      });
    } catch (error) {
      console.error("🔴 Error demoting user:", error);
    }
  };
  // Fetch the list of users whenever the current user's ID changes.
  useEffect(() => {
    fetchUsers();
  }, [currentUser?.id, fetchUsers]);
  // Determine if the current user has permission to promote others.
  useEffect(() => {
    setCanPromote(
      !!currentUser?.roles?.find((role) => role.role === "moderator"),
    );
  }, [currentUser]);
  return (
    <ul className="flex h-full flex-col gap-2 rounded-2xl bg-gray-50 p-6 dark:bg-gray-800">
      {users.map((user) => (
        <li key={user.id}>
          <article className="text-sm">
            <div className="flex items-center justify-between gap-2">
              {/* Display user's name if available */}
              {user.first_name && (
                <p>
                  {user.first_name} {user.last_name}
                </p>
              )}
              {canPromote &&
                (!user?.roles?.find((role) => role.role === "moderator") ? (
                  <button
                    className="btn"
                    onClick={() => handlePromoteUser(user?.email)}
                  >
                    Promote
                  </button>
                ) : (
                  <button
                    className="btn"
                    onClick={() => handleDemoteUser(user?.email)}
                  >
                    Demote
                  </button>
                ))}
            </div>
          </article>
        </li>
      ))}
    </ul>
  );
};
export default ChatUserList;

Here, we use a custom hook useUser to fetch the current user's information and the useChannel hook from Ably for real-time channel communication. The getUserList function fetches the list of users from the server using the Permit.io API. The component subscribes to the Ably channel for real-time updates and fetches the updated user list when a promote/demote event occurs. The user list is stored in the component's state, excluding the current user.

Finally, we can add it to our page, in ./app/chat/[[...channel]]/page.tsx :

// ./app/chat/[[...channel]]/page.tsx
"use client"; // This ensures the component is rendered client-side, required for Ably and NextAuth.
// Import necessary components and providers
import Chat from "@/components/Chat"; // Chat component to handle chat messages and functionality.
import ChatChannelList from "@/components/Chat/ChannelList"; // Sidebar with a list of available chat channels.
import ChatUserList from "@/components/Chat/UserList";
import { Realtime } from "ably"; // Ably Realtime client for managing connections and messaging.
import { AblyProvider, ChannelProvider } from "ably/react"; // Providers for using Ably hooks in React components.
import { SessionProvider } from "next-auth/react"; // Provider for managing authentication state.
import { use } from "react"; // Hook to handle async data like the `params` object.
// The Page component defines the layout and functionality for the chat application.
const Page = ({ params }: { params: Promise<{ channel: string[] }> }) => {
  // 👉 Create an Ably Realtime client instance
  //    - `authUrl`: URL for authorizing the connection using a token-based authentication strategy.
  //    - `autoConnect`: Ensures the client connects only when the app runs in the browser.
  const client = new Realtime({
    authUrl: "/api/ably", // Authorization endpoint to secure the Ably connection.
    autoConnect: typeof window !== "undefined", // Only auto-connect in the browser.
  });

  // Extract the `channel` parameter from the dynamic route.
  // The `params` object is an async promise containing the route parameters.
  const { channel } = use(params);
  // Format the channel name to match the expected format in the application.
  // For example, if `channel` is "general", the `channelName` becomes "chat:general".
  const channelName = `chat:${channel}`;
  return (
    // 👉 Wrap the entire application in providers to manage state and context.
    // `SessionProvider`: Manages the user's authentication session globally.
    <SessionProvider>
      {/* `AblyProvider`: Provides Ably context to child components for accessing the Realtime client. */}
      <AblyProvider client={client}>
        {/* `ChannelProvider`: Supplies the current channel context to components like Chat. */}
        <ChannelProvider channelName={channelName}>
          {/* Main chat application layout */}
          <section className="site-section !p-0">
            <div className="wrapper grid h-[calc(100vh-4.25rem)] grid-cols-4 !p-0">
              {/* Sidebar: Displays the list of available chat channels */}
              <div className="h-full max-h-full rounded-xl bg-gray-50 p-5 dark:bg-gray-800">
                <ChatChannelList />
              </div>
              {/* Main Chat Area: Center column for chat messages and input */}
              <div className="col-span-2 flex h-full flex-col overflow-hidden">
                {/* Pass the current channel name to the Chat component */}
                <Chat channelName={channelName} />
              </div>
              {/* Right Sidebar: Reserved for additional features like a user list */}
              <div className="col-span-1 flex h-full flex-col">
                {/* TODO: Implement a user list or additional features in the right sidebar */}
                <ChatUserList channelName={channelName} />
              </div>
            </div>
          </section>
        </ChannelProvider>
      </AblyProvider>
    </SessionProvider>
  );
};
export default Page; // Export the Page component as the default export.

With that we should be able to promote and demote users in real time:

Here’s the demotion in action:

Closing and Conclusion

Building a chat application with real-time authorization is a challenging but rewarding process. By integrating powerful tools like Permit.io and WebSockets, you can create a seamless experience that ensures secure and fine-grained access control. In this article, we explored the importance of dynamic authorization in chat applications, set up a WebSocket-based architecture with Ably, and integrated Permit.io for authorization management.

This workflow demonstrates how modern tools simplify what was once a complex implementation, enabling developers to focus more on user experience and scalability rather than the underlying infrastructure. With the right approach, you can ensure your chat application is both dynamic and secure.

Next Steps

With the foundational setup complete, you can explore simple and advanced features like:

Allowing moderators to delete participants messages
Adding AI-powered moderation tools to detect and prevent abusive content in chat. You can learn more about Building AI Applications with Permit
Implementing analytics dashboards to track user activity and message trends.

How to use multiple versions of Node on your machine

Miracleio — Tue, 26 Apr 2022 10:31:07 +0000

The best way I’ve tried to do this on my Linux machine is with nvm.

What's NVM

nvm allows you to quickly install and use different versions of Node via the command line. You can read more about it and how to install it on the README. nvm was originally developed for Linux systems, however it can be installed separately for Windows.

Install on Linux

To install on Linux run:

    curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.1/install.sh | bash

    #or
    wget -q0- https://raw.githubusercontent.com/nvm-sh/nvm/v0.38.0/install.sh | bash

Then close and reopen the terminal for the system to recognize the changes or run the command:

source ~/.bashrc

Install on Windows

nvm can be installed on the windows system using the following steps:

Go to this site
Install and unzip the nvm-setup.zip file

Install on MacOS

No hard feelings Mac users, just jejely follow the instructions here to install nvm with homebrew.

To verify that it was successful, run:

nvm --version

Output of nvm --version in terminal

Great! Now, you’re ready to rumble.

You can do a lot with nvm here are some examples:

$ nvm use 16
Now using node v16.9.1 (npm v7.21.1)

$ node -v
v16.9.1

$ nvm use 14
Now using node v14.18.0 (npm v6.14.15)

$ node -v
v14.18.0

$ nvm install 12
Now using node v12.22.6 (npm v6.14.5)

$ node -v
v12.22.6

Simple as that!

Install and use the LTS version of Node

This is recommended for most users. To do this run:

nvm install --lts

Output of nvm --install in terminal

Hermoso ✨, now you can go and install that stubborn package.

Make the new version default

Now, if you close your current terminal and run node -v you might notice that it still shows your old node version.

You can try to set a the new version as default:

nvm alias default v16.14.2

Close your terminal and open again to run node -v again to check. You should see the new version.

Make sure to exit open terminals that still show old Node versions

If you’re using VSCode’s terminal for example, you might notice that even if you close the terminal by clicking on the trash can icon, when you open it again, and run node -v, it still shows you the old node version.

You’ll have to exit the terminal by running:

exit

When you open it again and check the terminal, you should see the new node version.

How to use Custom events in Vue 3

Miracleio — Tue, 26 Oct 2021 07:08:39 +0000

As someone who has been using Vue 2 for a while now, switching over to Vue 3 with its new composition API and other cool features is exciting but comes with its little hiccups.

One of the hiccups or issues I faced while writing Vue 3 applications was using custom events in the new Composition API instead of the good Ol' Options API.

I tried checking out the Vue docs, but I wasn't getting exactly what I wanted. Then I set out on a googling spree, desperate to find a way to use custom events with the Composition API in my project.

And I finally found the way(s) 😋.

So here, I'll discuss how to emit custom events from our components using the Composition API.

Define Custom events inline

Before I dive right into how to use Custom events with the Composition API in Vue 3, here's how we normally use custom events inline. To emit custom events inline, maybe in an input field or button, we can define events using the v-on or @ directive:

<button @click="$emit('btn-click')">Click me</button>

Then, in our parent component, we can listen for the event like so:

<child @btn-click="doSomething()" />

Custom events using the Options API

With the Options API to emit custom events we also use the $emit method. We can access this method within our <script> with this. We'll set up the event emit from the doSomething method of the component.

<script>
export default {
    // define your emits via the emits option
    emits: ['btn-click'],
    ...
    methods: {
        doSomething(){
          this.$emit('btn-click')  
        },
    }

};
</script>

We still listen to this event from the parent component the same way we did when the emit was defined inline previously.

Custom events using Composition API

Unlike the Options API, the setup Component option is executed before the component is created, so we basically do not have to this.

The setup function accepts two arguments: props and context. We can access the component emit method from context.

We can create a function where we call the emit method and run the function when the button is clicked.

<script>
export default {
    // define your emits via the emits option
    emits: ['btn-click'],

    ...
    setup(props, context){
        const doSomething = () => {
            context.emit('btn-click')
        }
    },
};
</script>

OR, using destructuring,

...

// here we're getting the emit method by destructuring the context argument
setup(props, { emit }){
    const doSomething = () => {
        emit('btn-click')
    }
}

...

And there you have it! That's how we can use custom events in the Composition API.

Thanks for reading 💖. Let me know if you have any questions or suggestions ✨

How I implemented TailwindCSS dark mode in my Nuxt blog

Miracleio — Sat, 18 Sep 2021 10:37:00 +0000

I've always been in love with this dark mode functionality of a thing. So when I learnt that TailwindCSS - A Utility-first CSS Framework supports dark mode out of the box, I was excited. That's probably one of the top reasons I fell in love with Tailwind.

I've been working on a redesign of my portfolio and blog in my free time and I just had to add this feature to my site, it just wouldn't be complete without it.

Although it's a well known fact that dark mode offers a ton of benefits to site visitors, like it:

helps their device consume less battery on OLED screens,
keeps them from squeezing their eyelids and trying to block the excess light while browsing in dark places by just turning on dark mode
also prevents them from cranking their brightness 🔆 all the way up because they are trying to read what's on the page while outdoors
is just plain cool 😎

My new site runs on Nuxt which is basically a server side rendering framework like Next.js (which is for React) but for Vue. I'm not going to cover how I set up the site with Nuxt Content and Tailwind in this article but here's a link to that here.

Approaching The Problem

If you look at the Tailwind docs on dark mode, there's an example of a common approach for dark mode and respecting user preference and that approach is what I was looking for.

What I want for my site is that:

The system theme preference is respected by first time users - this is where prefers-color-scheme comes in.
This preference is now cached in localStorageand upon the user's next visit, the cached theme will be used
The user can also toggle theme mode and that will be saved to localStorage for their next visit

Now, the thing with Tailwind's example is that it's very basic and you have to figure out how to implement it.

Prerequisites

Before we jump into how I transformed that basic example into a feature that works, there's a few things I did beforehand.

Enable Manual Dark Mode

According to Tailwind's docs

If you want to support toggling dark mode manually instead of relying on the operating system preference, use the class strategy instead of the media strategy

It's important to note that we'll have to add the .darkclass to our HTML document (so that it'll be applied throughout the app ) in order to apply any dark:{class} class to elements. That's why we need to be able to control this class manually.

To do this, just change media to class in the darkMode property in tailwind.config.js file

// tailwind.config.js
module.exports = {
  darkMode: 'class',
  // ...
}

Now, when dark mode is enabled, <html> should have a class of dark. Then, all dark:{class} classes will be applied

<!-- Dark mode enabled -->
<html class="dark">
  <body>
    <!-- dark:bg-black Will be applied -->
    <div class="bg-white dark:bg-black">
      <!-- ... -->
    </div>
  </body>
</html>

🆒

Enable Dark Mode Variant For Other Utilities

By default, dark mode is only enabled for color-related utilities/classes, so something like this will work:

<p class="text-black dark:text-white">Some text</p>

but this will not work:

<p class="transform translate-x-1 dark:translate-x-2">Some text</p>

All you have to do is enable dark mode on our desired utilities:

// tailwind.config.js
module.exports = {
  //...
  variants: {
    extend: {
      translate: ['dark'],
      typography: ['dark'], //if you've setup Tailwind Typography Plugin for dark mode
    },
  },
}

You'll notice, I added 'dark' to the variant list for typography, that's for the Tailwind Typography plugin I'm using. This is beyond the scope of this article, but I'll share how I implemented dark mode for that plugin soon.
Now that we've enabled the dark mode variant for our utilities, let's proceed.

Implementing The Feature

In order to do this, I had to create a components/themeModule folder containing some functions in the themeModule/initTheme.js and my toggle button component in themeModule/themeControl.vue.
So my file structure basically looks like this:

|
+-- components
| +-- themeModule
| +-- initTheme.js
| +-- themeControl.vue
|

What I'm trying to do can also very easily be implemented with a state management pattern like Vuex which happens to come with Nuxt by default. But, I just decided not to use it. But, if you're interested to see how you can implement this feature using Vuex, you can check out this great article by @Tony Ketcham where he used it.

Set Theme On User Visit

In themeModule/initTheme.js I have the following piece of code:

// components/themeModule/initTheme.js

const initTheme = () => {
  const savedTheme = localStorage.theme
  const userPrefersDark = window.matchMedia(
    '(prefers-color-scheme: dark)'
  ).matches
  const newTheme =
    {}(!savedTheme && userPrefersDark) ||
    (savedTheme && JSON.parse(savedTheme).mode === 'dark')
      ? (newTheme.mode = 'dark')
      : (newTheme.mode = 'light')

  localStorage.theme = JSON.stringify(newTheme)

  return { newTheme }
}

What's happening here?

First, we'll see if the "theme" is present in localStorage already, and if a value is present, it'll be assigned to savedTheme, if none, savedTheme will be undefined
Then, we get the preferred color scheme of the system. If it's dark, userPrefersDark will be true, else it'll be false
Assigning an empty object to newTheme, my desired structure for this object is this:

      theme: {
        mode: "dark" || "light",
        //... some other property
      }

This is because I intend to add more options like main color to the theming functionality.

I have a compound ternary operator that does basically two things:

   !savedTheme && userPrefersDark

Check if no theme has been set in localStorage and if the system the is set to "dark".
If this is true, it means that this is the first time the user has visited the page (hence, no cached theme in localStorage yet) and that the system preference has been set to dark.

   savedTheme && JSON.parse(savedTheme).mode === 'dark'

Check if theme was saved to localStorage and theme.mode was equal to "dark"
If this is true on the other hand, it means that this isn't the first user visit and that a mode has saved to localStorage, so we should use that.

These two conditions imply that the desired mode is dark. If either of them is true, the mode should be set to dark:

? (newTheme.mode = 'dark')

If both of the two compound conditions are false, the desired mode is dark:

: (newTheme.mode = 'light')

I hope this all makes sense. If you don't understand how ternary operators work, here's a link that will help: Make Your Code Cleaner with JavaScript Ternary Operator (javascripttutorial.net)

For now, here's the classic if else equivalent:

if (
  (!savedTheme && userPrefersDark) ||
  (savedTheme && JSON.parse(savedTheme).mode === 'dark')
) {
  newTheme.mode = 'dark'
} else {
  newTheme.mode = 'light'
}

Alright. now we can save the newTheme to localStorage and return it:

localStorage.theme = JSON.stringify(newTheme)

return { newTheme }
```



That's it for the `initTheme()` function.

I prefer to run this function at the topmost level of my app which is `layouts/default.vue`.

So, in that file, I added the following:



```html
<!-- layouts/default.vue -->
<!-- ... -->
<script>
  import { initTheme } from '../components/themeModule/initTheme'

  export default {
    data() {
      return {
        theme: {},
      }
    },

    watch: {
      theme: {
        deep: true,
        handler(data) {
          const { mode } = data
          const html = document.documentElement

          mode === 'dark'
            ? html.classList.add('dark')
            : html.classList.remove('dark')

          localStorage.theme = JSON.stringify(data)
        },
      },
    },
    methods: {
      // this function toggles the value of `theme.mode`
      toggle() {
        this.theme.mode === 'dark'
          ? (this.theme.mode = 'light')
          : (this.theme.mode = 'dark')
      },
    },

    beforeMount() {
      this.theme = initTheme().newTheme
      // listen to 'toggle-theme' event and run the `toggle()` method when fired
      this.$nuxt.$on('toggle-theme', this.toggle)
    },
  }
</script>
```



In `<script>`, I import `initTheme` function then I do the following:

- Create a `theme` data property in `data()`,
- Set the `theme` data to the value returned by `initTheme` in `beforeMount()` which runs when the app is visited.

> Take note of <code>this.$nuxt.$on('toggle-theme', this.toggle)</code>, this is a nuxt global custom event listener which will run the <code>toggle()</code> method when the event is emitted from <code>themeModule/themeControl.vue</code>. You'll see this emitter in the component code.

- The `toggle()` method checks if the current theme mode is "dark", if it is, it sets it to "light". If it's not "dark", it set's it to dark. That's the basic toggle functionality right there.
- Set up a watcher for `theme` data.
- `deep: true` ensures that the value properties of the object are watched as well.
- We have another ternary operator which checks to see if the new `mode` is `"dark"`, if it is, its adds the `.dark` class to `html` document. If the mode is not `"dark"`, it removes the `.dark` class.
- Then, it saves the new data to `localStorage`

Right now, the app basically checks `localStorage` and system preference to determine whether or not to enable dark mode. What's left is the toggle button/component.

### Adding Toggle Functionality

What's left now is to create a button component that users will click to toggle between light and dark mode. Behold, `themeModule/themeControl.vue`:



```html
<!-- components/themeModule/themeControl.vue -->
<!-- ... -->

<template>
  <button class="toggler" @click="toggle()">
    <div class="wrapper">
      <!-- custom icon components -->
      <feather-icon name="sun" />
      <feather-icon name="moon" />
    </div>
  </button>
</template>

<script>
  export default {
    data() {
      return {
        clickSound: '',
      }
    },

    methods: {
      toggleFunc() {
        // nuxt global event emitter
        this.$nuxt.$emit('toggle-theme')
        // play cool sound effect
        this.clickSound.play()
      },
    },

    beforeMount() {
      // get audio file from static folder, create new Audio function and assign it to `clickSound` data ob
      this.clickSound = new Audio('/audio/mixkit-classic-click-1117.mp3')
    },
  }
</script>

<style scoped>
    .toggler {
      @apply relative w-6 h-6 ml-6 overflow-hidden;
    }
    .toggler .wrapper {
      @apply inline-flex transition transform;
      /* dark variant for button */
      @apply dark:-translate-x-1/2;
    }
  }
</style>
```



Basically, when clicked, in the `toggleFunc()` method, a global custom event `toggle-theme` is emitted.
If you recall, we have a global listener in `layouts/default.vue`. This listener is in `layouts/default.vue`, is responsible for changing the theme in the app as we have seen in the previous section.

### The Sound Effect

For the sound effect, I just downloaded a free audio file I found on [mixkit.co](https://mixkit.co/free-sound-effects/click/), compressed the file using [www.onlineconverter.com](https://www.onlineconverter.com/compress-mp3), downloaded it again and added it to my `/static/audio` folder. This allows me to create a new Audio element from a file without webpack like so: `new Audio('/audio/mixkit-classic-click-1117.mp3')`, assign it to `this.clickSound` .
Then, play it in `toggleFunc()` like so: `this.clickSound.play()`.
It's pretty simple.

Here's my toggler in action:![baa7cee3-5cde-43d6-a971-8b37237d2a60_gif](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/d4uofl5ey7sgsem0ynwu.gif)

### The Toggler Animation

I created the transition by simply adding the `dark:-translate-x-1/2` variant to `.wrapper`. That's why I had to enable the dark mode variant for the the {% raw %}`translate`{% endraw %} utility in the beginning for this to work.
The icons are styled side-by-side in a wrapper. The container which is the {% raw %}`.toggler`{% endraw %}button has {% raw %}`overflow`{% endraw %} set to {% raw %}`hidden`{% endraw %}.
So, when the dark class is active, the {% raw %}`.wrapper`{% endraw %} translates on the x-axis by 50%, revealing the moon while hiding the star and vice-versa.

## Conclusion

Well, I've tried to give a detailed rundown of how I implemented this dark mode thing on my Nuxt site. Without Vuex 😋. If you have any thoughts, questions, or recommendations, please feel free to reach out. I'd really appreciate feedback.

## Further Reading

Here are some resources I think you might find useful:

- [Vue + Tailwind 2.0: dark mode using Vuex, localStorage, and user's default preference](https://dev.to/tonyketcham/vue-tailwind-2-0-dark-mode-using-vuex-localstorage-and-user-s-default-preference-439g)
- [TailwindCSS Dark Mode](https://tailwindcss.com/docs/dark-mode)

Appreciate and share 🙌🏾 if you feel this could be useful to someone out there ✨
Thanks for reading ❤.

_This post was originally published on my [blog](https://miracleio.me/blog/How-I-implemented-TailwindCSS-dark-mode-in-my-Nuxt-blog)_

Creating a blog using Nuxt and Nuxt Content - with TailwindCSS

Miracleio — Sat, 11 Sep 2021 23:38:54 +0000

What we're going to be building

We will be building a simple blog site using Nuxt which is a framework popularly used for server side rendering and Static Site Generation with Vue.

We'll also be using Nuxt Content which is a module which acts as a Git-based Headless CMS that fetches your Markdown, JSON, YAML, XML and CSV files through a MongoDB like API. It has powerful features that allow you to write blogs, documentations and more.

Prerequisites

Before we dive right in, you should have:

A basic understanding of HTML, CSS & JS, Vue and the Markdown syntax
Node installed
A text editor, we recommend VS Code with the Vetur extension or WebStorm
A terminal, I recommend using VS Code's integrated terminal

Getting Started

Let's install everything we need for the project.

Install nuxt using create-nuxt-app

To get started quickly you can use the create-nuxt-app.

Make sure you have npx installed (npx is shipped by default since npm 5.2.0) or npm v6.1 or yarn.

npx create-nuxt-app <project-name>

Choose Content - Git-based Headless CMS option from Nuxt.js modules

Proceed to select other options, here's my preset:

Installation complete! 🎉

Install nuxt content separately

If you already have Nuxt setup before now, you can install the content module by running the command

#install nuxt content

npm install @nuxt/content

Then we can add it to our modules property inside our nuxt.config file.

//nuxt.config.js
export default {
  modules: ['@nuxt/content'],
}

Install Tailwind and Tailwindcss typography via npm

Tailwindcss is a utility first css framework that provides us with custom classes we can use to style our app.

Tailwindcss Typography is "A plugin that provides a set of prose classes you can use to add beautiful typographic defaults to any vanilla HTML you don't control (like HTML rendered from Markdown, or pulled from a CMS)."

Install @nuxtjs/tailwindcss which is a nuxt module for tailwind integration as well as Tailwind and its peer-dependencies using npm:

npm install -D @nuxtjs/tailwindcss tailwindcss@latest postcss@latest autoprefixer@latest

Add the @nuxtjs/tailwindcss module to the buildModules section of your nuxt.config.js file:

// nuxt.config.js
export default {
  buildModules: ['@nuxtjs/tailwindcss'],
}

Create your configuration file

Next, generate your tailwind.config.js file:

npx tailwindcss init

This will create a minimal tailwind.config.js file at the root of your project:

//tailwind.config.js
module.exports = {
  purge: [],
  darkMode: false, // or 'media' or 'class'
  theme: {
    extend: {},
  },
  variants: {
    extend: {},
  },
  plugins: [],
}

Create a tailwind.css file in assets/css.tailwind.css use the @tailwind directive to inject Tailwind’s base, components, and utilities styles:

/*assets/css/tailwind.css*/
@tailwind base;
@tailwind components;
@tailwind utilities;

You can import the css file into your components or make it accessible globally by defining the CSS files/modules/libraries you want to set globally (included in every page).

  /* nuxt.config.js*/
  // Global CSS: https://go.nuxtjs.dev/config-css
  css: [
    // CSS file in the project
    '@/assets/css/tailwind.css',
  ],

Install Tailwind typography

# Using npm
npm install @tailwindcss/typography

Then add the plugin to your tailwind.config.js file:

// tailwind.config.js
module.exports = {
  purge: [],
  darkMode: false, // or 'media' or 'class'
  theme: {
    extend: {},
  },
  variants: {
    extend: {},
  },
  plugins: [require('@tailwindcss/typography')],
}

Configure Tailwind to remove unused styles in production

In your tailwind.config.js file, configure the purge option with the paths to all of your pages and components so Tailwind can tree-shake unused styles in production builds:

// tailwind.config.js
module.exports = {
  purge: [
    './components/**/*.{vue,js}',
    './layouts/**/*.vue',
    './pages/**/*.vue',
    './plugins/**/*.{js,ts}',
    './nuxt.config.{js,ts}',
  ],
  darkMode: false, // or 'media' or 'class'
  theme: {
    extend: {},
  },
  variants: {
    extend: {},
  },
  plugins: [require('@tailwindcss/typography')],
}

Now run

npm run dev

Quick note

While going through these steps, I ran into an issue of mismatched packages while trying to run npm run dev

Here's how I fixed it:

update the mismatched package(s), which in my case was the vue-server-renderer

npm i vue-server-renderer@latest --save

That fixed it for me, when I ran npm run dev

Sweet! 🎉, now we can move into the interesting stuff

Create your first blog post

The content module works by reading the files in our content/ directory.

So, navigate to content/ and create an articles/ folder.
Create a first-blog-post.md file and
insert the following

content/articles/first-blog-post.md

---

<!--- YAML Front matter section in-between triple dashes '---' -->

title: First Blog Post
description: Learning how to create my blog using nuxt content

---

# My first blog post

Hey there! 👋🏾

This is my first blog post learning nuxt content.

Note the YAML front matter section, this will be used later on to insert custom variables like title and description that we will access using $content.

Next, we're going to create a dynamic page which will be used to:

fetch the article content using asyncData before the page has been rendered. We have access to our content through the context by using the variable $content. Since we are using a dynamic page, we can know what article file to fetch using the params.slug variable provided by vue router to get the name of each article
render the article in the template using <nuxt-content>

Ok, navigate to pages/ and create a blog/ folder.
Create a _slug.vue (our dynamic page) file and
insert the following

pages/blog/_slug.vue

<template>
  <article>
    <!-- this is where we will render the article contents -->
    <nuxt-content :document="article" />
  </article>
</template>

<script>
  export default {
    async asyncData({ $content, params }) {
      //here, we will fetch the article from the article/ folder based on the name provided in the 'params.slug`
      const article = await $content('articles', params.slug).fetch()

      return { article }
    },
  }
</script>

To display our content we are using the <nuxt-content /> component by passing in the variable we returned into the :document="article" document prop.

Go to your site and you should see something like this

Accessing default injected variables

The content module provides lots of injected variables which we can use in our template.
Some of the ones will be using are:

body: body text
dir: directory
extension: file extension (.md in this example)
path: the file path
slug: the file slug
toc: an array containing our table of contents
createdAt: the file creation date
updatedAt: the date of the last file update

We can access this data using the article variable we created. Let's check them out by printing it with a <pre> tag in our template

<pre> {{ article }} </pre>

We should see something like this on our page

{
  "slug": "first-blog-post",
  "toc": [],
  "body": {
    "type": "root",
    "children": [
    // article content
    ]
  },
  "dir": "/articles",
  "path": "/articles/first-blog-post",
  "extension": ".md",
  "createdAt": "2021-07-11T02:34:43.695Z",
  "updatedAt": "2021-07-11T03:33:33.608Z"
}

Custom injected variables

We'll also use this to display custom injected variables specified in the YAML front matter which must be valid YAML at the top of the file.
This is useful for adding SEO variables such as title, description and image of your article.

<template>
  <article class="article">
      <!-- Our custom injected variables specified with the The YAML front matter goes here  -->
      <header class="article-header">
          <h1>{{article.title}}</h1>
          <p>{{article.description}}</p>

          <!-- container for article details -->
          <div class="details-cont">
              <!-- the format date function converts the default date to a readable form -->
              <span>{{formatDate(article.updatedAt)}}</span>
          </div>
      </header>

      <!-- this is where we will render the article contents -->
      <nuxt-content :document="article" />
  </article>
</template>

<script>
export default {
    async asyncData({ $content, params }) {
    //here, we will fetch the article from the article/ folder based on the name provided in the 'params.slug`
        const article = await $content('articles', params.slug).fetch();

        return {article}
    },
    methods: {
        // format the date to be displayed in a readable format
        formatDate(date){
            return new Date(date).toLocaleDateString('en', {year: 'numeric', month: 'long', day: 'numeric'})
        }
    }
}

Notice the formatDate function which we use to convert the article.updatedAt value to a more readable date.

We should have something like this:

Now, we have two heading <h1> elements. One from the YAML front matter and the main markdown. We can remove the one in the main markdown.
We can also add more content for the styles:

## <!--- content/articles/first-blog-post -->

title: My First Blog Post
description: Learning how to create my blog using nuxt, the nuxt content module and tailwindcss

---

Hey there! 👋🏾
This is my first blog post learning nuxt content.

I'm currently building it using the following:

- Nuxt.js
- Nuxt Content module
- Tailwindcss
- Tailwindcss typography

> Sweet huh?

Great! 😎 Let's touch it up a bit with some styling.

Styling with Tailwindcss and Tailwindcss typography

The content from our article shows up when we visit the slug along with some custom data. But it looks ugly, let's fix that.

First, we apply the Tailwindcss typography .prose class to the <article> element for some basic styles:

<article class="article prose lg:prose-xl"></article>

Now, we just create our custom styles in pages/blog/_slug.vue

<style scoped>
@layer components {
  .article {
      @apply prose lg:prose-xl;
      @apply p-4 mt-6 lg:mt-8 m-auto lg:max-w-3xl;
  }

  .article-header{
      @apply mb-12 pb-8 lg:mb-16 border-gray-200 border-b-2;
  }

  .article-header h1{
      @apply mb-0;
  }

  .article-header .details-cont span{
      @apply text-opacity-50 text-sm;
  }
}
</style>

Our page now looks like this:

Sweet indeed 😍

Adding HTML markup and Vue components in our article markdown

We can add valid html code in our markdown file.
Let's create an info box with some styling

<!--
    content/articles/first-blog-post.md

    ...rest of file

    HTML in markdown
    Info box with svg icon
 -->
<div class="flex gap-4 items-start p-6 bg-blue-200 text-gray-800 border-blue-700 border-l-4 rounded-md">
<span><svg class="text-blue-700" xmlns="http://www.w3.org/2000/svg" viewBox="-2 -2 24 24" width="24" height="24" preserveAspectRatio="xMinYMin" class="icon jam jam-info"><path class="text-blue-700" d='M10 20C4.477 20 0 15.523 0 10S4.477 0 10 0s10 4.477 10 10-4.477 10-10 10zm0-2a8 8 0 1 0 0-16 8 8 0 0 0 0 16zm0-10a1 1 0 0 1 1 1v5a1 1 0 0 1-2 0V9a1 1 0 0 1 1-1zm0-1a1 1 0 1 1 0-2 1 1 0 0 1 0 2z'/></svg></span>
<span class="text-gray-800" style="line-height: initial">Here we have important information we would love to share with you!</span>
</div>

You should have something like this:

Sweet, now we can make this a vue component that can be reused

Create infoBox.vue file in components/global.

<!-- components/global/infoBox.vue-->
<template>
  <div class="info-box">
    <span>
      <svg
        xmlns="http://www.w3.org/2000/svg"
        viewBox="-2 -2 24 24"
        width="24"
        height="24"
        preserveAspectRatio="xMinYMin"
        class="icon jam jam-info"
      >
        <path
          d="M10 20C4.477 20 0 15.523 0 10S4.477 0 10 0s10 4.477 10 10-4.477 10-10 10zm0-2a8 8 0 1 0 0-16 8 8 0 0 0 0 16zm0-10a1 1 0 0 1 1 1v5a1 1 0 0 1-2 0V9a1 1 0 0 1 1-1zm0-1a1 1 0 1 1 0-2 1 1 0 0 1 0 2z"
        />
      </svg>
    </span>
    <span>
      <slot name="info-box"> Some information gets diaplayed here </slot>
    </span>
  </div>
</template>

<script>
  export default {
    name: 'infoBox',
  }
</script>

<style scoped>
  @layer components {
    .icon {
      @apply text-gray-800;
    }

    .info-box {
      @apply flex gap-4 items-start p-6 bg-blue-200 text-gray-800 border-blue-500 border-l-4 rounded-md;
    }

    .info-box span {
      @apply text-gray-800 leading-none;
    }
  }
</style>

We are creating it in a components/global folder to register the component globally in order for nuxt to be able to auto import it into <nuxt-content>

Now, replace the html with our new infoBox component

<!-- infoBox component automatically imported as global component  -->
<info-box>
  <!-- insert into slot -->
  <template #info-box>
    Here we have important information we would love to share with you!
  </template>
</info-box>

If we view our page, we should still see our info box

The content API

It's pretty awesome that the content module provides an API that we can access on the http://localhost:3000/_content/ route. we can fetch data for all articles on the http://localhost:3000/_content/articles route.

We can access a single article using the slug of the article i.e http://localhost:3000/_content/articles/first-blog-post to access the data for http://localhost:3000/blog/first-blog-post.

Adding Previous and Next Article functionality

We're going to be adding a previous and next article functionality to our blog to navigate to other posts on our sites.
So, let's create about three duplicates of our content/articles/first-blog-post.md file so we can have more posts to navigate to.

Let's create our prevNext.vue component in our components/ folder

Here, we have a nuxt-link component which basically accesses the slug and title of the previous or next article.

<!-- components/prevNext -->

<template>
<!-- ...rest of file -->

<nuxt-link v-if="prev" :to="{ name: 'blog-slug', params: { slug: prev.slug } }" class="prev">
      <span class="icon-cont"><svg</svg></span>
      <span>{{ prev.title }}</span>
</nuxt-link>

<!-- nuxt-link for "next" -->
<!-- ...rest of file -->
</template>

This data is what will be passed as props to the component which we defined here:

<!-- components/prevNext -->

<script>
  export default {
    // create props for prev and next data that will be passed to the component
    props: {
      prev: {
        type: Object,
        default: () => null,
      },
      next: {
        type: Object,
        default: () => null,
      },
    },
  }
</script>

Our new component should look something like this:

<!-- components/prevNext -->
<template>
  <section id="prev-next" class="prev-next">
    <!-- if prev data is available display the link -->
    <nuxt-link
      v-if="prev"
      :to="{ name: 'blog-slug', params: { slug: prev.slug } }"
      class="prev"
    >
      <span class="icon-cont"
        ><svg
          xmlns="http://www.w3.org/2000/svg"
          viewBox="-5 -5 24 24"
          width="24"
          height="24"
          preserveAspectRatio="xMinYMin"
          class="icon jam jam-arrow-left"
        >
          <path
            d="M3.414 7.657l3.95 3.95A1 1 0 0 1 5.95 13.02L.293 7.364a.997.997 0 0 1 0-1.414L5.95.293a1 1 0 1 1 1.414 1.414l-3.95 3.95H13a1 1 0 0 1 0 2H3.414z"
          /></svg
      ></span>
      <span> {{ prev.title }} </span>
    </nuxt-link>
    <!-- else display empty span for styling purposes -->
    <span class="prev" v-else></span>

    <!-- if prev data is available display the link -->
    <nuxt-link
      v-if="next"
      :to="{ name: 'blog-slug', params: { slug: next.slug } }"
      class="next"
    >
      <span>{{ next.title }}</span>
      <span class="icon-cont">
        <svg
          xmlns="http://www.w3.org/2000/svg"
          viewBox="-5 -5 24 24"
          width="24"
          height="24"
          preserveAspectRatio="xMinYMin"
          class="icon jam jam-arrow-right"
        >
          <path
            d="M10.586 5.657l-3.95-3.95A1 1 0 0 1 8.05.293l5.657 5.657a.997.997 0 0 1 0 1.414L8.05 13.021a1 1 0 1 1-1.414-1.414l3.95-3.95H1a1 1 0 1 1 0-2h9.586z"
          />
        </svg>
      </span>
    </nuxt-link>
    <!-- else display empty span for styling purposes -->
    <span class="next" v-else> </span>
  </section>
</template>

<script>
  export default {
    // create props for prev and next data that will be passed to the component
    props: {
      prev: {
        type: Object,
        default: () => null,
      },
      next: {
        type: Object,
        default: () => null,
      },
    },
  }
</script>

<style scoped>
  @layer components {
    /* styling for the components */
    .prev-next {
      @apply flex gap-12 py-8 items-center justify-between m-auto max-w-xl lg: max-w-4xl;
    }

    .prev-next a {
      @apply flex gap-2;
    }
  }
</style>

Now let's get back to our components/blog/_slug.vue.

// components/blog/_slug.vue

export default {
  async asyncData({ $content, params }) {
    const article = await $content('articles', params.slug).fetch()

    // assign the first two objects in returned array to prev & next constant variables
    const [prev, next] = await $content('articles')
      // fetch only the title and slug from the articles
      .only(['title', 'slug', 'updatedAt'])
      // sortby time updated, in ascending order
      .sortBy('updatedAt', 'asc')
      // get the correct slug
      .surround(params.slug)
      // fetch data
      .fetch()

    // return the data to be vailable for use in the file
    return { article, prev, next }

// rest of <script>

We now have the data of the each of the first two sorted articles each in prev & next variables, which we will now pass to the prevNext component after the <article>

<!-- components/blog/_slug.vue -->

<!-- rest of file -->

<!-- Pass the data to the component props-->
<prev-next :prev="prev" :next="next"></prev-next>

Here we go:

Great!

Listing out all our Articles

Now, it'll be really nice if we could display our articles on our blog page.

Let's create a new page in our blogs/ folder; pages/blogs/index.vue

Then in the <script>, we pass in $content and params into our asyncData function.
Within the function we pass aritcles which is the folder which our articles are stored into $content and chain .only(['title', 'slug', 'updatedAt', 'description']) to fetch only those attributes from the articles,

.sortBy('createdAt', 'asc') to sort it

and lastly fetch() to fetch the data and assign it to const articles

<!-- pages/blog/index.vue -->

<script>
  export default {
    async asyncData({ $content }) {
      const articles = await $content('articles')
        .only(['title', 'slug', 'updatedAt', 'description'])
        .sortBy('createdAt', 'asc')
        .fetch()

      return { articles }
    },

    methods: {
      formatDate(date) {
        // format the date to be displayed in a readable format
        })
      },
    },
  }
</script>

Now we can use the v-for directive to render our articles from the articles data

<!-- pages/blog/index.vue -->

<template>
  <section class="blog">
    <header class="blog-header">
      <h1>It's nice you're here. Welcome.</h1>
      <p>
        Have a look what I've been spending hours behind the screen writing
        about
      </p>
    </header>

    <ul class="articles">
      <li class="article" v-for="article of articles" :key="article.slug">
        <nuxt-link :to="{ name: 'blog-slug', params: { slug: article.slug } }">
          <h2>{{ article.title }}</h2>
          <p>{{ article.description }}</p>

          <div class="details-cont">
            <span>{{ formatDate(article.updatedAt) }}</span>
          </div>
        </nuxt-link>
      </li>
    </ul>
  </section>
</template>

<!--- Styling the page -->
<style scoped>
  @layer base {
    .blog {
      @apply p-4 mt-6 lg:mt-8 m-auto lg:max-w-3xl;
    }

    .blog-header {
      @apply prose lg:prose-xl;
      @apply mb-12 pb-8 lg:mb-16;
    }

    .blog-header h1 {
      @apply mb-0;
    }

    .articles .article {
      @apply prose lg:prose-lg;
      @apply pl-0 py-2 list-none;
    }

    .articles .article h2 {
      @apply mb-0;
    }
  }
</style>

Let's visit http://localhost:3000/blog, we should see our blog page

Creating a navigation for our site

The last thing we are going to be doing is creating a simple navigation that will take us to our home page and blog page.

Let's create our siteHeader.vue component in components/ with some basic styling.

<!-- components/siteHeader.vue -->

<template>
  <header id="site-header" class="site-header">
    <div class="wrapper">
      <nuxt-link to="/">
        <figure class="site-logo">
          <h1>PortfolioX</h1>
        </figure>
      </nuxt-link>

      <nav class="site-nav">
        <ul class="links">
          <li class="link">
            <nuxt-link to="/blog">Blog</nuxt-link>
          </li>
        </ul>
      </nav>
    </div>
  </header>
</template>

<script>
  export default {}
</script>

<style scoped>
  @layer components {
    .site-header {
      @apply w-auto p-4 py-8 sticky top-0 bg-white bg-opacity-70 backdrop-filter backdrop-blur-md z-10;
    }

    .site-header .wrapper {
      @apply m-auto max-w-5xl flex items-center justify-between;
    }
  }
</style>

Next, we add it to our default site layout, in layouts/default.vue

<!-- layouts/default.vue -->

<template>
  <div>
    <site-header />
    <Nuxt />
  </div>
</template>

Our siteHeader.vue It is now automatically imported into our layout. Have a look at our page

Beautiful 😘

Conclusion

We've managed to build a pretty simple blog site with important features using just one module, nuxt/content.
The focus of this article was the content module, so, I'll drop links for more reading on tailwindcss.

I think this is a pretty awesome and useful feature in Nuxt.js.I think you would love to play around with it even more because there is a lot more functionality you can add to your project that we didn't cover here.

I hope you see this useful, I will consider writing on deployment in the future but I'll just drop some links that I feel are useful till then.

Thanks for reading. Happy coding 😎.

Futher Reading

Useful links

The content module documentation: https://content.nuxtjs.org/
NuxtJs documentation: https://nuxtjs.org/docs/2.x/get-started/installation
Tailwindcss documentation: https://tailwindcss.com/docs/

Awesome reads

An article on creatung a blog with Nuxt content: https://nuxtjs.org/blog/creating-blog-with-nuxt-content#add-a-search-field
An article on building a prtfolio site with NuxtJs: https://itnext.io/building-the-ultimate-portfolio-site-with-nuxt-js-and-netlify-beautiful-blazing-fast-100-seod-102913a60cfd

Duplicating elements with the Node.cloneNode() method

Miracleio — Thu, 10 Oct 2019 09:28:53 +0000

In one of the projects I'm working on, i needed to have new elements containing a lot of elements. I had already created one element and styled it. But i needed the content to be dynamically updated from a .json file.

So, I thought of a way to duplicate that element and give each its own unique content. Using the Node.cloneNode() method.

It's pretty straight foward

First, you declare and assign your node, the element you want to clone

var node = document.querySelector("#element");

Declare your clone

var clone = node.cloneNode([deep])

You can set the [deep] to be true if you want to copy the children of the node

Set to false if you don't

Now, you can append it into your DOM
document.getElementById("#papa").appendChild(clone);

Enjoy! 😁

These sites explain it way better!

https://www.w3schools.com/jsref/met_node_clonenode.asp
https://developer.mozilla.org/en-US/docs/Web/API/Node/cloneNode

By the way, this is my first post, I apologize for it's awkwardness 🙂

Forem: Miracleio

Meet Zhu Li: The AI Agent That Manages Your Notion Workspace From Any Channel

The problem: project data lives everywhere except where you can use it

How it's wired together

The organizational backbone: six Notion databases

The AI agent pipeline: from raw input to structured Notion data

The chat agent: your Notion workspace, conversational

What you can submit, and how

Video Demo

Show us the code

How I Used Notion MCP

Connection flow

How agents use MCP tools

MCP-to-MCP: Zhu Li as a MCP server

The chat agent: Notion MCP as a conversational interface

What Notion MCP unlocks that wasn't possible before

DevFlow - Build Anywhere with GitHub Copilot CLI

What I Built

Demo

How It Works

Example Commands

Video Walkthrough

Testing Instructions (For Judges)

My Experience with GitHub Copilot CLI

Building a Flexible Share System in React with the Web Share API

Setting Up the Project

Understanding the Web Share API

Creating the Share Hook

Breaking Down the Implementation

Using the Hook in Components

Browser Support and Considerations

Best Practices

Resources

Conclusion

Project Management Assembly of Agents Built with Agent.ai

What I Built

Why I Built It

How It Works

Demo

Orchestrator Agent (The Brains)

Project Creator Agent

Creating A Project

Managing Tasks in existing Project

Generating Task Report in existing Project

Triggering Task Reminders

Agent.ai Experience

Solutions

Conclusion

Related Links

Team members

Real-Time Authorization in a Chat Application with Permit.io and WebSockets

Introduction to Real-Time Authorization in Chat Applications

Why real-time chat apps require fine-grained access control

The challenges of implementing dynamic authorization in a chat context

Overview of how Permit.io’s authorization solutions can streamline this process with WebSockets

Setting Up a WebSocket-Based Chat Application

Setting up Next.js

Set up global styles

Setting up Authentication

Setting up Google OAuth

Create a Site Header component

Set up WebSockets with Ably

Message Item component

Message List component

Message Input component

Chat Channel List component

Chat component

Create Chat Page

Set up Permit.io

Create a new project

Create new resource

Edit resuorce

View roles

Udpate policies

Create resource instance

View Instances

Adding Permit.io to your Next.js application

Set up local PDP

User Hook

Create Users in Permit During Authentication