Required dependencies

npm install @headlessui/react @kubernetes/client-node classnames compare-versions \
  dockerode follow-redirects gamedig i18next ical.js js-yaml json-rpc-2.0 luxon \
  memory-cache minecraftstatuspinger next next-i18next ping pretty-bytes raw-body \
  react react-dom react-i18next react-icons recharts swr

@kubernetes/client-node and dockerode include native Node.js bindings. Ensure your environment has a C++ build toolchain (build-essential / Xcode CLT). No iOS/Android linking required — this is a Node.js/Next.js web application only.

Project setup

1. Copy source/ into your repository root (or a sub-directory, e.g. apps/homepage/).
2. Ensure jsconfig.json aliases match your directory structure. The project expects these aliases (also configured in vitest.config.mjs):

   {
     "compilerOptions": {
       "baseUrl": ".",
       "paths": {
         "components/*": ["src/components/*"],
         "pages/*": ["src/pages/*"],
         "utils/*": ["src/utils/*"],
         "widgets/*": ["src/widgets/*"],
         "styles/*": ["src/styles/*"]
       }
     }
   }
   

3. Create your YAML config files. Homepage reads from /app/config/ by default (override with the HOMEPAGE_CONFIG_DIR env var):

   export HOMEPAGE_CONFIG_DIR=/path/to/your/config
   

4. Set optional environment variables:

   HOMEPAGE_VAR_*=value        # arbitrary secrets injected into YAML via {{HOMEPAGE_VAR_*}}
   LOG_LEVEL=debug             # pino log level
   PORT=3000                   # Next.js port (default 3000)
   

5. Run in development or production:

   npm run dev      # development with hot reload
   npm run build && npm start   # production
   

6. For Docker deployment, use the provided docker-entrypoint.sh as the container entry point; it sets correct permissions before starting Next.js.

Public API

getStaticProps (default export from src/pages/index.jsx)

export async function getStaticProps(): Promise<{
  props: {
    initialSettings: Record<string, unknown>;
    fallback: Record<string, unknown>;
    _nextI18Next: unknown;
  };
}>;

Next.js static generation hook. Called at build time to load YAML-backed settings, services, bookmarks, and widgets into the page as SWR fallback data. Wire this into your pages/index.jsx if you are embedding the dashboard into a custom Next.js app.

slugifyAndEncode (named export from src/components/tab)

export function slugifyAndEncode(name: string): string;

Converts a tab display name into a URL-safe, encoded slug used to synchronise the active tab with the router query. Use this whenever you need to build a programmatic link to a specific named tab (e.g. generating anchor hrefs in a custom navigation component).

servicesResponse / widgetsResponse / bookmarksResponse (from utils/config/api-response)

export async function servicesResponse(): Promise<object>;
export async function widgetsResponse(): Promise<object>;
export async function bookmarksResponse(): Promise<object>;

Server-side helpers that read YAML config files and return serialisable data structures ready to be sent as JSON. Used directly in the API route handlers under src/pages/api/. Call these in any custom API route or getServerSideProps to expose the same data to other parts of your stack.

Working examples

Scenario - Custom API route re-exposing services data

A buyer wants to feed their own frontend with the services list parsed by Homepage's YAML reader.

// pages/api/my-services.ts
import type { NextApiRequest, NextApiResponse } from "next";
// Alias must resolve: utils -> src/utils (see jsconfig.json)
import { servicesResponse } from "utils/config/api-response";

export default async function handler(req: NextApiRequest, res: NextApiResponse) {
  const data = await servicesResponse();
  res.status(200).json(data);
}

Scenario - Generating tab anchor links

A buyer has a custom navigation sidebar and needs stable href values that match Homepage's internal routing.

// components/Sidebar.tsx
import { slugifyAndEncode } from "components/tab";

const TAB_NAMES = ["Home", "Media", "Infrastructure"];

export function Sidebar() {
  return (
    <nav>
      {TAB_NAMES.map((name) => (
        <a key={name} href={`/?tab=${slugifyAndEncode(name)}`}>
          {name}
        </a>
      ))}
    </nav>
  );
}

Scenario - Consuming widgets data in a separate Express service

A buyer runs Homepage alongside an Express API and wants to expose widget configuration as a REST endpoint.

// express-server/routes/widgets.ts
import express from "express";
// Requires ts-node with paths from tsconfig matching src/ aliases
import { widgetsResponse } from "utils/config/api-response";

const router = express.Router();

router.get("/widgets", async (_req, res) => {
  try {
    const widgets = await widgetsResponse();
    res.json(widgets);
  } catch (err) {
    res.status(500).json({ error: (err as Error).message });
  }
});

export default router;

File walkthrough

• .devcontainer/ - Defines a reproducible VS Code dev container with Node, Python, and helper scripts.
• .github/ - GitHub Actions pipelines for Docker image publishing, linting, testing, i18n sync, and release automation.
• .vscode/ - Preconfigured launch profiles for debugging Next.js and running Vitest from VS Code.
• docs/ - Full MkDocs-Material documentation source, served at gethomepage.dev.
• images/ - PNG/WebP banners and screenshots referenced by the README.
• k3d/ - Sample manifests and scripts for running Homepage in a local k3d Kubernetes cluster.
• public/ - Static files (icons, fonts) served at the root URL by Next.js.
• src/ - Core application: Next.js pages, React components, widget integrations, API routes, and utilities.
• next-i18next.config.js - Configures i18next namespaces, language aliases (e.g. zh-CN → zh-Hans), and the embedded prettyBytes formatter used in translations.
• vitest.config.mjs - Configures Vitest with path aliases mirroring jsconfig.json, V8 coverage, and a thread-pool runner.
• docker-entrypoint.sh - Adjusts file ownership and exec's the Next.js server; required for rootless Docker deployments.
• tailwind.config.js - Extends Tailwind with custom colours and the typography/forms plugins used throughout the UI.

Common pitfalls and fixes

• HOMEPAGE_CONFIG_DIR not set — Homepage silently falls back to /app/config/; set the env var explicitly or symlink your YAML files there.
• Path aliases unresolved in a monorepo — jsconfig.json and vitest.config.mjs both define aliases; if you move src/, update baseUrl in both files and the resolve.alias map in Vitest config.
• @kubernetes/client-node build failure — Requires node-gyp and a native build toolchain; install build-essential (Linux) or Xcode Command Line Tools (macOS) before npm install.
• next-i18next locale files missing at runtime — The public/locales/ directory must be present; if you stripped it, useTranslation hooks will silently return the key string instead of translated text.
• ESM/CJS interop with vitest — vitest.config.mjs uses esbuild.jsx: "automatic"; if you add a jest.config.js alongside it, the two transform pipelines will conflict — use only Vitest for this codebase.
• SWR cache not refreshing in production — Homepage uses Revalidate toggle component; ensure stale-while-revalidate headers are not stripped by a reverse proxy such as Nginx, which would prevent client-side polling from receiving fresh data.

Vibe-coding prompt template

I have added the Homepage source (upstream package: user@example.com) to the
`source/` directory of my project. I also have USAGE.md describing the real
exports and setup steps.

Please integrate Homepage into my existing project step-by-step:

1. Read USAGE.md and source/jsconfig.json to understand path aliases.
2. Add the required npm dependencies listed in USAGE.md to my package.json.
3. Set up the Next.js page at pages/index.jsx (or app/page.tsx if I use App
   Router) by wiring getStaticProps from source/src/pages/index.jsx.
4. Create API routes that call servicesResponse, widgetsResponse, and
   bookmarksResponse from source/src/utils/config/api-response.
5. Set the HOMEPAGE_CONFIG_DIR environment variable in my .env.local to point
   at my YAML config directory.
6. Ensure tsconfig.json (or jsconfig.json) path aliases match those in
   source/vitest.config.mjs.
7. Confirm the build runs with `npm run build` and surface any missing locale
   files or native module errors with fixes.

Show each changed file in full and explain any non-obvious decision.

License and credit

Homepage is released under the GNU General Public License v3.0. See source/LICENSE for the full text. Upstream repository and documentation: https://github.com/gethomepage/homepage / https://gethomepage.dev.

This product’s unique contribution is clean room implementation of valuable code block into AVCP compatible standard.

The full install guide and integration prompts unlock after purchase.