Search Engine Optimization

Dirstarter comes with built-in SEO features to help your directory website rank better in search engines and look great when shared on social media.

Metadata ConfigurationCopy Anchor Link

The metadata configuration in Dirstarter is centralized and type-safe using Next.js's Metadata API. The base configuration is located in config/metadata.ts:

import type { Metadata } from "next"
import { linksConfig } from "~/config/links"
import { siteConfig } from "~/config/site"

export const metadataConfig: Metadata = {
  openGraph: {
    url: "/",
    siteName: siteConfig.name,
    locale: "en_US",
    type: "website",
  },
  twitter: {
    site: "@dirstarter",
    creator: "@piotrkulpinski",
    card: "summary_large_image",
  },
  alternates: {
    canonical: "/",
    types: { "application/rss+xml": linksConfig.feeds },
  },
}

Pages build their metadata with getPageData and getPageMetadata from lib/pages.ts. getPageMetadata merges the base config, sets the canonical URL and falls back to the site's home card when a page has no Open Graph image of its own.

Static PagesCopy Anchor Link

A static page reads its title and description from the translations and passes its own card:

const getData = cache(async () => {
  const t = await getTranslations("pages.about")
  const url = "/about"
  const title = t("title")
  const description = t("description", { siteName: siteConfig.name })

  return getPageData(url, title, description, {
    metadata: { openGraph: { images: await getPageOpenGraphImage("about") } },
    breadcrumbs: [{ url, title }],
  })
})

export async function generateMetadata() {
  return getPageMetadata(await getData())
}

Dynamic PagesCopy Anchor Link

Tool, category and blog post pages pass the card of the entity they show:

export async function generateMetadata(props: Props): Promise<Metadata> {
  const { tool, url, metadata } = await getData(props)

  const robots = !isToolPublished(tool) ? { index: false, follow: false } : undefined
  const openGraph = { images: getToolOpenGraphImage(tool) }

  return getPageMetadata({ url, metadata: { ...metadata, openGraph, robots } })
}

OpenGraph ImagesCopy Anchor Link

Dirstarter draws every Open Graph card with ogier, a card renderer built on satori. One route renders all of them: app/api/og/[type]/[slug]/route.ts. The type is page, tool, category or post, and the route loads the entity by its slug. Cards are never built from query parameters, so nobody can make your site render arbitrary text.

Versioned URLsCopy Anchor Link

Each card URL ends with a v query, a short hash of the data the card shows. The helpers in lib/opengraph.ts build these URLs:

getPageOpenGraphImage("about") // /api/og/page/about?v=...
getToolOpenGraphImage(tool) // /api/og/tool/<slug>?v=...
getCategoryOpenGraphImage(category) // /api/og/category/<slug>?v=...
getPostOpenGraphImage(post) // /api/og/post/<slug>?v=...

The version changes only when something on the card changes. So the route caches each image for a year, and an edit still produces a fresh image. A request with a stale or missing version, or any extra query parameter, is redirected to the current URL, so cache-busting parameters never render a second copy.

DesignCopy Anchor Link

lib/opengraph-cards.tsx holds the renderer and one loader per card type. Titles use Inter Display and the rest of the text uses Inter, loaded from local font files in lib/image-fonts.ts.

The card colors live in config/images.ts, next to the badge colors. satori cannot read the OKLCH tokens in app/styles.css, so the config keeps hex copies of them. Update both together when you change your brand colors.

Sitemap GenerationCopy Anchor Link

Dirstarter uses a split sitemap architecture with a sitemap index and individual sitemaps for each content type. This keeps each file small and cacheable while scaling to thousands of entries.

Sitemap IndexCopy Anchor Link

The index at app/sitemap.xml/route.ts lists all individual sitemaps:

export async function GET() {
  // Generates a sitemap index XML pointing to individual sitemaps
  // e.g., /sitemap/pages, /sitemap/tools, etc.
  // ...
}

Individual SitemapsCopy Anchor Link

Each content type has its own sitemap generated by app/sitemap/[id]/route.ts. The available sitemaps are defined as a constant, and the route renders each at request time, returning 404 for unknown ids:

const sitemaps = ["pages", "tools", "categories", "tags", "posts"]

export async function GET(_: Request, { params }: RouteContext<"/sitemap/[id]">) {
  await connection() // request-time only, so the cached queries are skipped at build

  const { id } = await params
  if (!sitemaps.includes(id)) {
    // 404 + Cache-Control: no-store
  }

  // Switches on `id` to query the appropriate content type
  // and generates a sitemap XML with loc + lastmod entries
  // ...
}

Robots.txtCopy Anchor Link

The robots.txt file is automatically generated and configured to allow search engines to crawl your site while protecting sensitive routes:

import type { MetadataRoute } from "next"
import { siteConfig } from "~/config/site"

export default function robots(): MetadataRoute.Robots {
  const baseUrl = siteConfig.url

  return {
    rules: [
      {
        userAgent: "*",
        allow: "/",
        disallow: ["/app*", "/auth*"],
      },
      {
        userAgent: "Googlebot",
        disallow: "/*/opengraph-image-",
      },
    ],
    sitemap: `${baseUrl}/sitemap.xml`,
  }
}

Additional SEO FeaturesCopy Anchor Link

1. Canonical URLs: Every page has a canonical URL to prevent duplicate content issues.
2. RSS Feed: Built-in RSS feed support for blog posts and content updates.
3. Structured Data: Automatically generated JSON-LD for tools and blog posts.
4. Mobile Optimization: All pages are responsive and mobile-friendly by default.
5. Performance: Built-in image optimization and lazy loading for better Core Web Vitals.