Verse of the Day
Relevant source files
The following files were used as context for generating this wiki page:
The Verse of the Day feature retrieves and displays a daily biblical scripture from the YouVersion API. It serves as a spiritual component integrated into specific parts of the website, such as error pages, and uses a fallback mechanism to ensure content remains available if the external service fails.
Sources: src/features/verse/verse.utils.ts, e2e/specs/not-found.spec.ts:4-15
System Architecture
The feature follows a modular architecture within the src/features/verse directory. It consists of type definitions, utility functions for API interaction, and a server-side entry point for Astro environment integration.
Data Flow
The system initiates a request by determining the current day of the year. It performs a two-step fetch process: first to identify the passage ID for the current day, and second to retrieve the specific text and reference for that passage.
The following sequence diagram illustrates the retrieval process:
The system uses a 8,000ms timeout for all external requests to prevent long-running hanging processes.
Sources: src/features/verse/verse.utils.ts:7, src/features/verse/verse.utils.ts:98-124
Data Structures and Configuration
The feature uses a specific TypeScript type and several constants to interact with the Berean Standard Bible (BSB) version on YouVersion.
Verse Type
| Field | Type | Description |
|---|---|---|
reference | string | The biblical citation (e.g., "John 3:16"). |
source | 'api' | 'fallback' | Indicates if the data came from the live API or local fallback. |
text | string | The actual text of the scripture. |
url | string | A direct link to the verse on Bible.com. |
Sources: src/features/verse/verse.types.ts:1-6
Core Constants
| Constant | Value | Description |
|---|---|---|
YOUVERSION_API_ORIGIN | https://api.youversion.com/v1 | Base URL for API requests. |
YOUVERSION_BSB_ID | 3034 | The specific internal ID for the BSB translation. |
FALLBACK_VERSE | Psalm 119:105 | Hardcoded verse used during failures or missing API keys. |
Sources: src/features/verse/verse.utils.ts:3-5, src/features/verse/verse.utils.ts:13-18
Implementation Details
API Key Management
The getTodayVerse function retrieves the YVP_APP_KEY from the Astro server environment. If this key is missing, the system returns the FALLBACK_VERSE without attempting a network request.
export async function getTodayVerse(): Promise<Verse> {
return fetchTodayVerse({ appKey: YVP_APP_KEY })
}
Sources: src/features/verse/verse.server.ts:1-9, src/features/verse/verse.utils.ts:40-45
Day Calculation
The system maps every day of the year to a specific entry in the YouVersion database using the dayOfYear function. This function calculates the integer index (1-366) based on UTC time.
Sources: src/features/verse/verse.utils.ts:20-26
Fallback Logic
The system is designed for high availability. It returns the FALLBACK_VERSE in the following scenarios:
- The
appKeyis not provided. - The network request to YouVersion fails (e.g., 500 status code).
- The API response is missing the expected
passage_id. - The API response is missing the passage
contentorreference.
Sources: src/features/verse/verse.utils.ts:47-53, src/features/verse/verse.utils.test.ts:58-69
Automation and Deployment
A Netlify build hook (NETLIFY_BUILD_HOOK_URL) is configured to trigger a daily rebuild of the site. This ensures that the static site content, including the Verse of the Day, is refreshed every 24 hours to match the current date.
Sources: README.md:12-13
Usage in UI
The verse is notably used on the "Not Found" (404) page. When a user navigates to a non-existent route, the site displays the verse inside a blockquote element with a link back to Bible.com.
Sources: e2e/specs/not-found.spec.ts:7-14