Featured Repositories

Purpose and Scope

Featured repositories are the curated GitHub projects that OpenWiki treats as high-value public examples. They are used in two different ways: as homepage or discovery metadata for repository cards, and as route inputs for prerendering public wiki pages. This matters because OpenWiki is designed to generate source-grounded wikis on demand, but the README also calls out “Featured wiki prerendering for fast public docs pages” as a product capability. Featured repositories are therefore not just marketing content; they are part of the app’s performance and discovery strategy.

Sources: README.md, app/lib/featured-repositories.ts, app/(wiki)/static-params.ts

The feature starts with a static catalog of repositories. Each entry has a GitHub-style full name, a canonical GitHub URL, a short description, and a human-readable star label. That static catalog gives the app enough information to render a useful card or derive route parameters even before live metadata has been fetched. When storage and GitHub metadata are available, OpenWiki enriches those cards with current descriptions, owner avatars, GitHub URLs, and star counts from stored repository metadata.

Sources: app/lib/featured-repositories.ts, app/lib/featured-repository-metadata.ts

Relevant Source Files

README.md — Describes OpenWiki’s product promise and explicitly lists featured wiki prerendering as one of the capabilities users get from the hosted app.
app/lib/featured-repositories.ts — Defines the static featured repository catalog and the public TypeScript shapes used for featured repository cards.
app/lib/featured-repository-metadata.ts — Builds runtime card data from the featured catalog plus stored metadata, refreshes stale GitHub metadata, and ensures featured repositories exist in storage.
app/(wiki)/static-params.ts — Converts featured repository URLs into Next.js static route parameters for repository root pages and published wiki page slugs.
app/api/repositories/featured/route.ts — Exposes the featured card list through a dynamic API route with no-store caching and storage-configuration error handling.

Catalog and Card Model

The core catalog type is FeaturedRepository. It contains description, fullName, repoUrl, and starLabel. The catalog includes projects such as react/react, microsoft/vscode, vercel/eve, tailwindlabs/tailwindcss, supabase/supabase, rust-lang/rust, golang/go, vercel/ai, huggingface/transformers, and langchain-ai/langchain. The intent is to keep the seed data small, stable, and independently renderable: every entry has enough information to identify the repository, link to it, and display a reasonable fallback card.

Sources: app/lib/featured-repositories.ts

The runtime UI shape is FeaturedRepositoryCard. It keeps the user-facing fields from the catalog but separates approximate fallback stars from live metadata. A card has description, fullName, iconSrc, repoUrl, starCount, and optional starLabel. When OpenWiki has a numeric stargazersCount from stored metadata, that value becomes starCount and the static starLabel is omitted. When live metadata is not present, starCount is null and the original label remains available for display.

Sources: app/lib/featured-repositories.ts, app/lib/featured-repository-metadata.ts

That split is useful for public deployments. The application can ship curated cards immediately, avoid blocking the page on GitHub for every request, and still improve freshness after metadata refresh jobs run. It also prevents the static catalog from pretending to be the source of truth for values that naturally change, such as stars, descriptions, and owner avatars. The catalog defines which repositories are featured; storage-backed metadata defines what is currently known about them.

Sources: app/lib/featured-repository-metadata.ts

Metadata Enrichment and Refreshing

getFeaturedRepositoryCards is the main server-side read path for featured cards. It asks storage for metadata keyed by each featured fullName, builds a map by repository name, and then returns cards in the same order as the static catalog. For each featured repository, stored metadata can override the description and GitHub URL, provide the owner avatar URL, and supply a numeric star count. If no stored avatar exists, the code falls back to getGitHubOwnerAvatarFallbackUrl using the repository owner parsed from the fullName.

Sources: app/lib/featured-repository-metadata.ts, app/lib/featured-repositories.ts

The function also has a deliberate degraded mode. Its options include fallbackOnStorageConfigurationError?: boolean, and when that flag is set, a recognized storage configuration error returns static featured cards instead of throwing. That is useful for contexts where OpenWiki should still render something when the database or artifact configuration is not ready. The public API route does not set this option; it instead converts storage configuration problems into an explicit error response through the shared storage-error helper.

Sources: app/lib/featured-repository-metadata.ts, app/api/repositories/featured/route.ts

Metadata freshness is handled separately by refreshFeaturedRepositoryMetadata. The refresh path first ensures that every featured repository has a storage record, then loads stored metadata for the full featured list, filters to stale records, and refreshes stale repositories concurrently. The source sets featuredMetadataMaxAgeMs to six hours and featuredMetadataRefreshConcurrency to six, which means refresh work is bounded and does not fan out across the whole catalog without limits. Each successful refresh records default branch, description, owner avatar URL, repository ID, and stargazer count.

Sources: app/lib/featured-repository-metadata.ts

Refresh results are explicit. FeaturedRepositoryMetadataRefreshResult reports refreshed, stale, and an array of per-repository errors with fullName and message. This makes the refresh operation suitable for operational code that wants to update as much metadata as possible without failing the whole batch when one GitHub request fails. The implementation increments the success count per repository and stores individual error messages rather than collapsing failures into a single exception.

Sources: app/lib/featured-repository-metadata.ts

Prerendering and Static Route Parameters

Featured repositories also feed the wiki routing layer. getFeaturedWikiStaticParams returns root route parameters with owner and repo for each valid featured repository URL. It does this through a private getFeaturedRepositories helper that parses repoUrl with parseGitHubRepoUrl, deduplicates by fullName, and drops entries that cannot be parsed. This gives Next.js a concise list of repository landing pages that can be statically generated from the curated catalog.

Sources: app/(wiki)/static-params.ts, app/lib/featured-repositories.ts

Individual wiki pages have a second static parameter path. getFeaturedWikiSlugStaticParams uses the same parsed featured repositories, then asks storage for published wiki route parameters through listPublishedWikiRouteParams. The returned values include owner, repo, and slug, so Next.js can prerender already-published pages for featured repositories. If storage cannot load the published slugs, the function logs a warning and returns an empty array rather than failing the build or static parameter collection step.

Sources: app/(wiki)/static-params.ts

The practical effect is that the static catalog acts as a stable seed, while storage determines how much of the existing wiki tree can be prebuilt. A newly featured repository can be included as a root route candidate immediately, but slug-level prerendering depends on previously published wiki artifacts and route metadata. That matches the product model described in the README: OpenWiki publishes navigable wikis and keeps them fresh, while featured projects get a faster public path when the app already knows their pages.

Sources: README.md, app/(wiki)/static-params.ts

Featured Repositories API

The featured repositories API is implemented by app/api/repositories/featured/route.ts. It exports dynamic = "force-dynamic", so the route is treated as dynamic rather than statically cached by the framework. The GET handler returns JSON with a single top-level repositories property whose value comes from getFeaturedRepositoryCards(). The response includes cache-control: no-store, which makes sense because card metadata can be refreshed independently and should not be assumed immutable by downstream caches.

Sources: app/api/repositories/featured/route.ts, app/lib/featured-repository-metadata.ts

Compact reference:

Surface	Contract	Behavior
`featuredRepositories`	`FeaturedRepository[]`	Static ordered catalog of curated repositories.
`FeaturedRepository`	`description`, `fullName`, `repoUrl`, `starLabel`	Minimum data needed to identify and render a fallback card.
`FeaturedRepositoryCard`	`description`, `fullName`, `iconSrc`, `repoUrl`, `starCount`, optional `starLabel`	Runtime card shape enriched from storage when available.
`getFeaturedRepositoryCards(options?)`	Returns `Promise<FeaturedRepositoryCard[]>`	Reads stored metadata and falls back to static card data only when configured for storage configuration errors.
`refreshFeaturedRepositoryMetadata()`	Returns `Promise<FeaturedRepositoryMetadataRefreshResult>`	Ensures records exist, refreshes stale GitHub metadata with bounded concurrency, and reports per-repository errors.
`getFeaturedWikiStaticParams()`	Returns `{ owner, repo }[]`	Builds root wiki static params from valid, deduplicated featured repository URLs.
`getFeaturedWikiSlugStaticParams()`	Returns `Promise<{ owner, repo, slug }[]>`	Loads published wiki page params for featured repositories and returns an empty list on storage lookup failure.
`GET /api/repositories/featured`	Returns `{ repositories }`	Dynamic no-store endpoint for featured repository cards.

The route’s error boundary is intentionally narrow. If getFeaturedRepositoryCards throws a storage configuration error, the handler asks storageConfigurationErrorResponse to turn it into a response and returns that response when available. Other errors are rethrown. This preserves visibility for unexpected failures while giving deployment misconfiguration a consistent API-level response path. Because the handler does not opt into the static-card fallback option, consumers of this endpoint should be prepared for storage-related error responses during incomplete setup.

Sources: app/api/repositories/featured/route.ts, app/lib/featured-repository-metadata.ts

Implementation Guidance

When adding a featured repository, update only the catalog fields that identify and describe the repository: fullName, repoUrl, description, and a fallback starLabel. Use a canonical public GitHub URL, because route static parameters are derived from repoUrl rather than from fullName directly. The static params helper will ignore unparsable URLs and deduplicate repeated repositories, but treating those checks as guardrails rather than normal control flow keeps the featured list predictable.

Sources: app/lib/featured-repositories.ts, app/(wiki)/static-params.ts

After changing the catalog, consider the two runtime paths separately. Discovery cards can render from static data, but live metadata requires storage and the refresh path. Prerendered slug pages require published wiki route params in storage, so adding a repository to the catalog does not automatically create every page. The next useful reads are the wiki routing documentation for how { owner, repo, slug } maps to pages, and the storage setup documentation for the services that back repository metadata and published wiki artifacts.

Sources: README.md, app/lib/featured-repository-metadata.ts, app/(wiki)/static-params.ts

Ask a question...