Components Reference

This wiki uses two layers of components. The first layer is Starwind UI - pre-built Astro components (Table, Badge, Card, etc.) installed into the project via the Starwind CLI. The second layer is custom homelab components that wrap Starwind UI and read data from homelab.ts.

---

Component locations

Type	Location
Custom homelab components	src/components/homelab/
Starwind UI components	src/components/starwind/
homelab.ts constants	src/config/homelab.ts

Never edit files in src/components/starwind/ directly. These are managed by the Starwind CLI. Use the class prop for any one-off styling changes.

---

Custom homelab components

ExternalLink

Renders an anchor tag that opens in a new tab with rel="noopener noreferrer". Use this for all external links in .mdx pages.

File: src/components/homelab/ExternalLink.astro

Starwind dependencies: none

Usage:

import ExternalLink from '@/components/homelab/ExternalLink.astro'

<ExternalLink href="https://example.com">Link text</ExternalLink>

---

Mermaid

Renders a Mermaid diagram from a code string. Uses the Mermaid CDN for client-side rendering - no npm install required. Automatically adapts to Starlight’s light and dark theme.

Use this for architecture diagrams, flow diagrams, and any other content that benefits from a visual rather than an ASCII block or prose description.

File: src/components/homelab/Mermaid.astro

Starwind dependencies: none

Props:

Prop	Type	Required	Description
code	string	Yes	A valid Mermaid diagram string

Usage:

import Mermaid from '@/components/homelab/Mermaid.astro'

<Mermaid code={`flowchart LR
    A([Browser]) --> B[Cloudflare Edge]
    B --> C[Internal service]`} />

Mermaid supports several diagram types. The most useful for this wiki are flowchart for architecture and traffic flow, and sequenceDiagram for auth flows.

Flowchart example:

<Mermaid code={`flowchart TD
    A[Internet] --> B[Cloudflare]
    B --> C[Traefik]
    C --> D[Keycloak]
    C --> E[Pangolin]`} />

Sequence diagram example:

<Mermaid code={`sequenceDiagram
    Browser->>Cloudflare Access: Request page
    Cloudflare Access->>Keycloak: Redirect to OIDC login
    Keycloak->>Browser: Google/Microsoft login
    Browser->>Keycloak: Authenticate
    Keycloak->>Cloudflare Access: Token
    Cloudflare Access->>Vercel: Forward request
    Vercel->>Browser: Page`} />

For full Mermaid syntax reference see mermaid.js.org.

---

ServiceCard

Renders a single service as a card with name, description, internal URL, external URL, port, version, and a colour-coded status badge.

File: src/components/homelab/ServiceCard.astro

Starwind dependencies: card, badge

Props:

Prop	Type	Required	Description
service	Service	Yes	A Service object from homelab.ts

Usage:

import ServiceCard from '@/components/homelab/ServiceCard.astro'
import { ARCANE_PROJECTS } from '@/config/homelab'

<ServiceCard service={ARCANE_PROJECTS[0]} />

To render a grid of cards:

import ServiceCard from '@/components/homelab/ServiceCard.astro'
import { ARCANE_PROJECTS } from '@/config/homelab'

<div class="grid grid-cols-1 md:grid-cols-2 gap-4">
  {ARCANE_PROJECTS.map((s) => <ServiceCard service={s} />)}
</div>

---

AppInventory

Renders a table of services with status badges, URLs, version, port, and optional image column. Use this for app inventory tables.

File: src/components/homelab/AppInventory.astro

Starwind dependencies: table, badge

Props:

Prop	Type	Default	Description
services	Service[]	required	Array of Service objects from homelab.ts
showVersion	boolean	true	Show version column
showPort	boolean	true	Show port column
showImage	boolean	false	Show Docker image column

Usage:

import AppInventory from '@/components/homelab/AppInventory.astro'
import { ARCANE_PROJECTS } from '@/config/homelab'

<AppInventory services={ARCANE_PROJECTS} />

{/* Hide version and port, show Docker image */}
<AppInventory services={ARCANE_PROJECTS} showVersion={false} showPort={false} showImage={true} />

---

DnsTable

Renders a Cloudflare DNS record table with proxy status badges (orange for proxied, grey for DNS-only, blue for tunnel).

File: src/components/homelab/DnsTable.astro

Starwind dependencies: table, badge

Props:

Prop	Type	Required	Description
records	DnsRecord[]	Yes	Array of DnsRecord objects from homelab.ts

Usage:

import DnsTable from '@/components/homelab/DnsTable.astro'
import { DNS_RECORDS } from '@/config/homelab'

<DnsTable records={DNS_RECORDS} />

---

KeycloakClients

Renders a table of registered Keycloak OIDC clients with their redirect URIs and post-logout URIs.

File: src/components/homelab/KeycloakClients.astro

Starwind dependencies: table

Props:

Prop	Type	Required	Description
clients	KeycloakClient[]	Yes	Array of KeycloakClient objects from homelab.ts

Usage:

import KeycloakClients from '@/components/homelab/KeycloakClients.astro'
import { KEYCLOAK_CLIENTS } from '@/config/homelab'

<KeycloakClients clients={KEYCLOAK_CLIENTS} />

---

PangolinResources

Renders a table of Pangolin tunnelled resources with status badges, internal targets, and authentication notes.

File: src/components/homelab/PangolinResources.astro

Starwind dependencies: table, badge

Props:

Prop	Type	Required	Description
resources	PangolinResource[]	Yes	Array of PangolinResource objects from homelab.ts

Usage:

import PangolinResources from '@/components/homelab/PangolinResources.astro'
import { PANGOLIN_RESOURCES } from '@/config/homelab'

<PangolinResources resources={PANGOLIN_RESOURCES} />

---

PortRegistry

Renders a sorted table of ports in use. Accepts an optional host filter to show only TrueNAS or VPS ports. Reads from the PORTS array in homelab.ts.

File: src/components/homelab/PortRegistry.astro

Starwind dependencies: table

Props:

Prop	Type	Required	Description
ports	PortEntry[]	Yes	Array of PortEntry objects from homelab.ts
host	’TrueNAS’ | ‘VPS’	No	Filter to a single host. Omit to show all.

Usage:

import PortRegistry from '@/components/homelab/PortRegistry.astro'
import { PORTS } from '@/config/homelab'

<PortRegistry ports={PORTS} host="TrueNAS" />

---

NetworkDevices

Renders a table of known network devices with hostname, IP, vendor, and MAC address.

File: src/components/homelab/NetworkDevices.astro

Starwind dependencies: table

Props:

Prop	Type	Required	Description
devices	NetworkDevice[]	Yes	Array of NetworkDevice objects from homelab.ts

Usage:

import NetworkDevices from '@/components/homelab/NetworkDevices.astro'
import { NETWORK_DEVICES } from '@/config/homelab'

<NetworkDevices devices={NETWORK_DEVICES} />

---

Starwind UI components in direct use

Some pages use Starwind components directly rather than through a homelab wrapper. This is appropriate when the data is not from homelab.ts (for example, a one-off table on a specific page).

Import directly from @/components/starwind/:

import { Table, TableBody, TableCell, TableHead, TableHeader, TableRow } from '@/components/starwind/table'
import { Badge } from '@/components/starwind/badge'
import { Card, CardHeader, CardTitle, CardDescription, CardContent } from '@/components/starwind/card'

---

Adding a Starwind UI component

Use the CLI to add new components. Do not create files in src/components/starwind/ manually.

npx starwind@latest add component-name

For example, to add the Tabs component:

npx starwind@latest add tabs

This copies the component source into src/components/starwind/tabs/. It is then available to import at @/components/starwind/tabs.

To see all available components, visit the Starwind UI documentation.

To update a component to the latest version:

npx starwind@latest update component-name

---

Adding a new custom homelab component

Step 1. Create a new .astro file in src/components/homelab/. Name it in PascalCase, for example MyComponent.astro.

Step 2. Add the required Starwind components if not already installed:

npx starwind@latest add table badge

Step 3. Write the component. Import types from homelab.ts and Starwind components from @/components/starwind/. Add a comment block at the top documenting the props and usage.

Step 4. Export any new types needed from homelab.ts.

Step 5. Use the component in an .mdx page by importing it from @/components/homelab/MyComponent.astro.

Step 6. Add the new component to this reference page.

---

Installed Starwind components

Component	Import path	Used by
Badge	@/components/starwind/badge	AppInventory, ServiceCard, DnsTable, PangolinResources
Card	@/components/starwind/card	ServiceCard
Table	@/components/starwind/table	AppInventory, DnsTable, KeycloakClients, PangolinResources, NetworkDevices, PortRegistry

Install additional components as needed with npx starwind@latest add <name>.

---

Useful links

• Starwind UI documentation
• Mermaid diagram syntax
• homelab.ts reference
• Wiki guide overview