Rating System

Starlight Recipes integrates a rating system powered by Countify. This allows users to submit a 1-to-5 star vote, displaying the average rating and total vote count on your recipe pages.

Setup

The rating system requires an on-demand rendering environment and a unique secret to function.

1. Install an Astro Server Adapter
   You must use a Server Adapter to handle live vote submissions.

   npm pnpm yarn

   Cloudflare Netlify Node Vercel

   npx astro add cloudflare

   npx astro add netlify

   npx astro add node

   npx astro add vercel

   pnpm astro add cloudflare

   pnpm astro add netlify

   pnpm astro add node

   pnpm astro add vercel

   yarn astro add cloudflare

   yarn astro add netlify

   yarn astro add node

   yarn astro add vercel

2. Configure your Rating Secret
   Generate a random GUID and set it as the environment variable STARLIGHT_RECIPES_RATING_SECRET. This acts as a private namespace to prevent others from spamming your Countify counters.

   Generate Magic Secret

   .env

   STARLIGHT_RECIPES_RATING_SECRET=CLICK_GENERATE_TO_CREATE_SECRET

   Data Persistence

   The rating data is tied directly to two things:

   • Your Secret: If you change the STARLIGHT_RECIPES_RATING_SECRET, all existing ratings will be “lost” as the system will look into a new, empty namespace.
   • File Names: Ratings are linked to the recipe’s filename without extension (e.g., virgin-colada). Renaming the file will reset the rating for that specific recipe.

How it works

Once configured, the system generates a unique hash for each recipe based on its id. This hash tracks two metrics: sum (total stars) and count (total votes).

Build-time vs. Real-time

It is important to understand when data is fetched to manage expectations around the “Popular Recipes” sidebar:

• Popular Recipes Sidebar: The sorting order for “popular” recipes is calculated only at build time. If users vote after your site is deployed, the sidebar order will not change until you redeploy your site to refetch the updated totals.
• Recipe Pages: When a user visits a specific recipe, the current average rating is fetched live.
• Sidebar Configuration: You can adjust the number of items shown in the sidebar using popularRecipeCount. If the rating system is not configured, this section is hidden automatically.

Reliability & User Experience

To keep your site fast and resilient against external API issues, the system follows these fallback behaviors:

• Service Downtime: If Countify is unavailable or slow (timing out after 10 seconds during fetch), the UI gracefully falls back to showing 0 stars and 0 votes rather than breaking the page.
• Submission Limits: To prevent abuse, users are limited to one vote per recipe every 24 hours. If a submission fails due to network issues or rate limiting, the system returns an error state so your UI can prompt the user to try again later.
• Production Check: If the “Popular Recipes” group is missing from your sidebar in production, verify that STARLIGHT_RECIPES_RATING_SECRET is correctly set in your hosting provider’s environment variables and that the build server has outgoing network access.