Adds support for custom text and image background

README.md

@@ -20,13 +20,22 @@ All endpoints accept:
 
 - `width` (optional, default `1170`)
 - `height` (optional, default `2532`)
+- `backgroundImageUrl` (optional): remote image URL used as full-canvas background
+- `overlayAlpha` (optional): black tint alpha between `0` and `1`
+- `handleText` (optional): custom text rendered below progress text (same style)
 
 Routes:
 
 - `/api/days?width=1170&height=2532`
 - `/api/months?width=1170&height=2532`
 - `/api/current-month?width=1170&height=2532`
 
+Example with customization:
+
+- `/api/days?width=1170&height=2532&backgroundImageUrl=https%3A%2F%2Fimages.example.com%2Fbg.jpg&overlayAlpha=0.35&handleText=%40yourhandle`
+- `/api/months?width=1170&height=2532&backgroundImageUrl=https%3A%2F%2Fimages.example.com%2Fbg.jpg&overlayAlpha=0.35&handleText=%40yourhandle`
+- `/api/current-month?width=1170&height=2532&backgroundImageUrl=https%3A%2F%2Fimages.example.com%2Fbg.jpg&overlayAlpha=0.35&handleText=%40yourhandle`
+
 ## Local Development
 
 ```bash

app/api/current-month/route.tsx

@@ -1,4 +1,4 @@
-import { NextRequest } from "next/server";
+import type { NextRequest } from "next/server";
 import { englishToNepali } from "@/lib/date_helper";
 import { generateCurrentMonthGridJSON } from "@/lib/generator";
 import {
@@ -8,6 +8,8 @@ import {
   imageGenerationErrorResponse,
   invalidDimensionsResponse,
   parseDimensionsFromRequestUrl,
+  parseOgRenderOptionsFromRequestUrl,
+  parseOgTextOptionsFromRequestUrl,
 } from "@/lib/og_image";
 
 export const runtime = "edge";
@@ -16,6 +18,8 @@ export async function GET(request: NextRequest) {
   try {
     const dimensions = parseDimensionsFromRequestUrl(request.url);
     if (!dimensions) return invalidDimensionsResponse();
+    const renderOptions = parseOgRenderOptionsFromRequestUrl(request.url);
+    const textOptions = parseOgTextOptionsFromRequestUrl(request.url);
 
     const { width, height } = dimensions;
     const currentDateInNepal = getCurrentDateInNepal();
@@ -25,6 +29,7 @@ export async function GET(request: NextRequest) {
       nepaliDate,
       width,
       height,
+      textOptions,
     );
 
     const secondsUntilMidnight = getSecondsUntilNepalMidnight(currentDateInNepal);
@@ -34,6 +39,7 @@ export async function GET(request: NextRequest) {
       width,
       height,
       secondsUntilMidnight,
+      renderOptions,
     );
   } catch (error) {
     return imageGenerationErrorResponse(error);

app/api/days/route.tsx

@@ -1,4 +1,4 @@
-import { NextRequest } from "next/server";
+import type { NextRequest } from "next/server";
 import { englishToNepali } from "@/lib/date_helper";
 import {
   calculateNepaliYearProgress,
@@ -11,6 +11,8 @@ import {
   imageGenerationErrorResponse,
   invalidDimensionsResponse,
   parseDimensionsFromRequestUrl,
+  parseOgRenderOptionsFromRequestUrl,
+  parseOgTextOptionsFromRequestUrl,
 } from "@/lib/og_image";
 
 export const runtime = "edge";
@@ -19,6 +21,8 @@ export async function GET(request: NextRequest) {
   try {
     const dimensions = parseDimensionsFromRequestUrl(request.url);
     if (!dimensions) return invalidDimensionsResponse();
+    const renderOptions = parseOgRenderOptionsFromRequestUrl(request.url);
+    const textOptions = parseOgTextOptionsFromRequestUrl(request.url);
 
     const { width, height } = dimensions;
     const currentDateInNepal = getCurrentDateInNepal();
@@ -30,6 +34,7 @@ export async function GET(request: NextRequest) {
       nepaliDate,
       width,
       height,
+      textOptions,
     );
 
     const secondsUntilMidnight = getSecondsUntilNepalMidnight(currentDateInNepal);
@@ -39,6 +44,7 @@ export async function GET(request: NextRequest) {
       width,
       height,
       secondsUntilMidnight,
+      renderOptions,
     );
   } catch (error) {
     return imageGenerationErrorResponse(error);

app/api/months/route.tsx

@@ -1,4 +1,4 @@
-import { NextRequest } from "next/server";
+import type { NextRequest } from "next/server";
 import { englishToNepali } from "@/lib/date_helper";
 import {
   calculateNepaliYearProgress,
@@ -11,6 +11,8 @@ import {
   imageGenerationErrorResponse,
   invalidDimensionsResponse,
   parseDimensionsFromRequestUrl,
+  parseOgRenderOptionsFromRequestUrl,
+  parseOgTextOptionsFromRequestUrl,
 } from "@/lib/og_image";
 
 export const runtime = "edge";
@@ -19,6 +21,8 @@ export async function GET(request: NextRequest) {
   try {
     const dimensions = parseDimensionsFromRequestUrl(request.url);
     if (!dimensions) return invalidDimensionsResponse();
+    const renderOptions = parseOgRenderOptionsFromRequestUrl(request.url);
+    const textOptions = parseOgTextOptionsFromRequestUrl(request.url);
 
     const { width, height } = dimensions;
     const currentDateInNepal = getCurrentDateInNepal();
@@ -30,6 +34,7 @@ export async function GET(request: NextRequest) {
       nepaliDate,
       width,
       height,
+      textOptions,
     );
 
     const secondsUntilMidnight = getSecondsUntilNepalMidnight(currentDateInNepal);
@@ -39,6 +44,7 @@ export async function GET(request: NextRequest) {
       width,
       height,
       secondsUntilMidnight,
+      renderOptions,
     );
   } catch (error) {
     return imageGenerationErrorResponse(error);

lib/generator.ts

@@ -6,6 +6,7 @@ import {
   type NepaliDate,
   NEPALI_MONTHS,
 } from "./date_helper";
+import type { OgTextOptions } from "./og_image";
 
 function getLastDayOfNepaliMonth(year: number, month: number): number {
   try {
@@ -62,6 +63,7 @@ export function generateDotsGridJSON(
   currentNepaliDate: NepaliDate,
   screenWidth: number,
   screenHeight: number,
+  textOptions?: OgTextOptions,
 ) {
   const { totalDays, currentDay, remainingDays } = progress;
 
@@ -168,6 +170,35 @@ export function generateDotsGridJSON(
     },
   };
 
+  const handleText = textOptions?.handleText;
+  const handleTextNode = handleText
+    ? {
+        type: "div",
+        props: {
+          style: {
+            display: "flex",
+            justifyContent: "center",
+            alignItems: "center",
+            marginTop: "8px",
+            width: "100%",
+          },
+          children: {
+            type: "text",
+            props: {
+              style: {
+                color: "gray",
+                fontSize: `${fontSize}px`,
+                fontFamily: "system-ui, -apple-system, sans-serif",
+                fontWeight: "500",
+                textAlign: "center",
+              },
+              children: handleText,
+            },
+          },
+        },
+      }
+    : null;
+
   return {
     grid: {
       type: "div",
@@ -196,6 +227,7 @@ export function generateDotsGridJSON(
           },
           dateText,
           progressText,
+          handleTextNode,
         ],
       },
     },
@@ -211,6 +243,7 @@ export function generateMonthsGridJSON(
   currentNepaliDate: NepaliDate,
   screenWidth: number,
   screenHeight: number,
+  textOptions?: OgTextOptions,
 ) {
   const { totalDays, remainingDays, currentDay } = progress;
 
@@ -403,6 +436,35 @@ export function generateMonthsGridJSON(
     },
   };
 
+  const handleText = textOptions?.handleText;
+  const handleTextNode = handleText
+    ? {
+        type: "div",
+        props: {
+          style: {
+            display: "flex",
+            justifyContent: "center",
+            alignItems: "center",
+            marginTop: "8px",
+            width: "100%",
+          },
+          children: {
+            type: "text",
+            props: {
+              style: {
+                color: "gray",
+                fontSize: `${fontSize}px`,
+                fontFamily: "system-ui, -apple-system, sans-serif",
+                fontWeight: "500",
+                textAlign: "center",
+              },
+              children: handleText,
+            },
+          },
+        },
+      }
+    : null;
+
   return {
     grid: {
       type: "div",
@@ -432,6 +494,7 @@ export function generateMonthsGridJSON(
           },
           dateText,
           progressText,
+          handleTextNode,
         ],
       },
     },
@@ -446,6 +509,7 @@ export function generateCurrentMonthGridJSON(
   currentNepaliDate: NepaliDate,
   screenWidth: number,
   screenHeight: number,
+  textOptions?: OgTextOptions,
 ) {
   const topPadding = Math.round((screenHeight * 34) / 100);
   const bottomPadding = Math.round((screenHeight * 20) / 100);
@@ -566,6 +630,35 @@ export function generateCurrentMonthGridJSON(
     },
   };
 
+  const handleText = textOptions?.handleText;
+  const handleTextNode = handleText
+    ? {
+        type: "div",
+        props: {
+          style: {
+            display: "flex",
+            justifyContent: "center",
+            alignItems: "center",
+            marginTop: "8px",
+            width: "100%",
+          },
+          children: {
+            type: "text",
+            props: {
+              style: {
+                color: "gray",
+                fontSize: `${textFontSize}px`,
+                fontFamily: "system-ui, -apple-system, sans-serif",
+                fontWeight: "500",
+                textAlign: "center",
+              },
+              children: handleText,
+            },
+          },
+        },
+      }
+    : null;
+
   return {
     grid: {
       type: "div",
@@ -594,6 +687,7 @@ export function generateCurrentMonthGridJSON(
           },
           dateText,
           progressText,
+          handleTextNode,
         ],
       },
     },