🔁 Revalidator SDK

A lightweight SDK to programmatically trigger Incremental Static Regeneration (ISR) revalidation in Next.js via secure API endpoints.

Perfect for CMSs, dashboards, or admin panels to force-refresh statically cached content on demand.

🚀 Features

• ✅ Revalidate any public path or tag
• ✅ Retry with exponential backoff and timeout
• ✅ Debug logs for development
• ✅ Secured with bearer token
• ✅ Tag allowlisting (prevents misuse)
• ✅ TypeScript support
• ✅ Plug-and-play with any backend or dashboard

📦 Installation

npm install revalidator-sdk
# or
yarn add revalidator-sdk

🧩 Usage

1. Initialize the SDK

import { Revalidator } from "revalidator-sdk"

const revalidator = new Revalidator({
  baseUrl: "https://yourdomain.com",
  token: "your-secret-token",
  debuger: true, // Optional: enable verbose logging
  allowedTags: ["home", "blogs", "blog-info", "whatever", "...."]
})

// You can also link it as CDN
<script src="https://unpkg.com/ayady-revalidator-sdk@latest/dist/index.global.js"></script>

2. Revalidate a Specific Path

await revalidator.revalidatePath("/pathname")

3. Revalidate by Tag

await revalidator.revalidateTag("tagName")

✅ Allowed Tags

Please, provide your own predefined tag you use in your nextjs app to revalidate it, support only next app router 13+ to current

ℹ️ Attempting to revalidate a tag not in your allowed option list will throw an error.

🛡 API Reference

new Revalidator(options)

| Option | Type | Required | Description | |-----------|-----------|----------|------------------------------------------| | baseUrl | string | ✅ Yes | Full URL to your deployed site (no / at the end) | | token | string | ✅ Yes | Secret bearer token for revalidation API | | allowedTags | string[] | ❌ No | Array of tag list for revalidation API | | debuger | boolean | ❌ No | Enable debug logging (default: false) |

revalidatePath(path: string): Promise<any>

Revalidate a specific public-facing page or route.

revalidateTag(tag: string): Promise<any>

Revalidate all pages or content linked to a tag. The tag must be in the allowlist.

💥 Error Handling

The SDK throws a custom RevalidatorError if something goes wrong:

import { RevalidatorError } from "revalidator-sdk"

try {
  await revalidator.revalidateTag("worker-list")
} catch (err) {
  if (err instanceof RevalidatorError) {
    console.error("Status:", err.statusCode)
    console.error("Details:", err.responseBody)
  }
}

🧪 Example API Route (Next.js)

In your Next.js /api/revalidate.ts route handler:

export async function POST(req: Request) {
  const { searchParams } = new URL(req.url)
  const path = searchParams.get("path")
  const tag = searchParams.get("tag")

  const authHeader = req.headers.get("authorization")
  if (authHeader !== "Bearer your-secret-token") {
    return new Response("Unauthorized", { status: 401 })
  }

  try {
    if (path) {
      await res.revalidate(path)
    } else if (tag) {
      // revalidateTag logic here
    }

    return Response.json({ revalidated: true })
  } catch {
    return new Response("Revalidation failed", { status: 500 })
  }
}

📘 License

MIT © [Ahmed Saeed]

📦 Version

Current SDK Version: 1.0.6