No native iOS/Android steps are required. If running in Docker (recommended), ensure /var/run/docker.sock is mounted or DOCKER_HOST/DOCKER_PORT env vars are set for Docker integration detection.

Project setup

1. Copy source: Place the contents of source/ into your project root, or symlink src/, public/, drizzle/, data/ as needed.

2. TypeScript paths: Ensure tsconfig.json includes the ~ alias:

   {
     "compilerOptions": {
       "baseUrl": ".",
       "paths": {
         "~/*": ["./src/*"]
       }
     }
   }
   

3. Environment variables: Create .env (or .env.local) with:

   # Required
   NEXTAUTH_SECRET=your-secret-here
   NEXTAUTH_URL=http://localhost:3000
   # Database (SQLite default)
   DATABASE_URL=./data/homarr.db
   # Optional Docker integration
   DOCKER_HOST=unix:///var/run/docker.sock
   # Optional
   AUTH_PROVIDER=credentials   # or ldap, oidc
   

4. Run migrations: Before starting, apply DB schema:

   npx ts-node drizzle/migrate/migrate.ts
   # or if using the drizzle-kit approach:
   npx drizzle-kit migrate
   

5. Start dev server:

   npm run dev
   # or
   npx next dev
   

6. i18n: Locale JSON files live in public/locales/. next-i18next.config.js defines namespaces. Ensure next.config.js wraps with nextI18NextConfig.

Public API

BoardPage (default export from src/pages/board/index.tsx)

import BoardPage, { getServerSideProps } from '~/pages/board/index';
// Props inferred from getServerSideProps

The main dashboard page component. Calls useInitConfig with the server-fetched board config and renders <BoardLayout> + <Dashboard>. Wire getServerSideProps to load the correct board for the authenticated user; it reads the default board name from user settings, fetches the config JSON, checks guest access, and injects isDockerEnabled.

getServerSideProps (from src/pages/board/index.tsx)

export const getServerSideProps: (
  context: GetServerSidePropsContext
) => Promise<{
  props: {
    config: FrontendConfig;
    primaryColor: string;
    secondaryColor: string;
    primaryShade: number;
    isDockerEnabled: boolean;
    // ...i18n translations
  };
}>

Server-side data loader for the board page. Authenticates the session, resolves the user's default board, fetches its config, enforces login/guest access policy via checkForSessionOrAskForLogin, and detects Docker availability from environment. Use this as the canonical SSR entry point when embedding the board.

BoardsPage (default export from src/pages/manage/boards/index.tsx)

import BoardsPage, { getServerSideProps } from '~/pages/manage/boards/index';

Management UI for listing, creating, renaming, duplicating, and deleting boards. Uses api.boards.all.useQuery (tRPC) with server-side initial data from boardRouter. Requires an authenticated admin session. Mount under /manage/boards in your Next.js router.

MediaDisplay (from src/modules/common/index.ts)

export * from './MediaDisplay';
// Re-exports the MediaDisplay component
import { MediaDisplay } from '~/modules/common';

Common module export for displaying media content in widgets. Use it in custom widget implementations that need to render images or media from integrated services.

Working examples

Scenario - Rendering the default board page in a new Next.js project

Drop source/src/pages/board/index.tsx into your pages/ directory. The page fetches its own data server-side.

// pages/board/index.tsx  (already provided in source)
// Just ensure your _app.tsx wraps with SessionProvider and tRPC:
import { SessionProvider } from 'next-auth/react';
import { api } from '~/utils/api';
import type { AppProps } from 'next/app';

function MyApp({ Component, pageProps: { session, ...pageProps } }: AppProps) {
  return (
    <SessionProvider session={session}>
      <Component {...pageProps} />
    </SessionProvider>
  );
}

export default api.withTRPC(MyApp);

Scenario - Using getServerSideProps to inject board config

// pages/custom-board.tsx
import { GetServerSidePropsContext, InferGetServerSidePropsType } from 'next';
import { getServerSideProps } from '~/pages/board/index';
import { useInitConfig } from '~/config/init';

export { getServerSideProps };

export default function CustomBoardPage({
  config,
  isDockerEnabled,
}: InferGetServerSidePropsType<typeof getServerSideProps>) {
  useInitConfig(config);
  return (
    <div>
      <p>Docker enabled: {String(isDockerEnabled)}</p>
      <p>Board: {config.configProperties?.name}</p>
    </div>
  );
}

Scenario - Embedding the management index page for a portal app

// pages/admin/index.tsx
// The management page renders a quick-actions grid for the logged-in user.
// Just re-export as Next.js page:
export { default, getServerSideProps } from '~/pages/manage/index';

To mount at a custom route, copy the file and adjust imports. The page uses useSession and useTranslation internally; ensure SessionProvider and appWithTranslation wrappers are present in _app.tsx.

Scenario - Running DB migrations before server start

// scripts/migrate.ts
import { migrate } from '~/drizzle/migrate/migrate';
// Or invoke directly:
// npx ts-node drizzle/migrate/migrate.ts

async function main() {
  await migrate();
  console.log('Migrations applied');
}
main();

File walkthrough

• src/ - Contains all application logic: pages/ (Next.js routes), components/ (UI), server/ (tRPC routers, auth, DB queries), tools/ (server/client utilities), hooks/, config/, modules/, types/, utils/.
• drizzle/ - SQL migration files generated by Drizzle Kit; meta/ holds schema snapshots; migrate/migrate.ts is the migration runner.
• cli/ - Standalone Node.js CLI (cli.js) with commands for reset-password and reset-owner-password; runs independently of Next.js.
• public/ - Static files served by Next.js: locales/ (i18n JSON per language/namespace), imgs/ (logos, icons, favicons, PWA assets).
• data/ - default.json is the fallback board configuration; constants.ts exports app-wide constants.
• scripts/ - Helper scripts for development/build automation.
• docs/ - PNG/image assets used in README documentation only.
• .github/ - GitHub Actions workflows for Docker image builds, stale issue management, contributor greetings.
• .vscode/ - VS Code debugger launch config and editor settings for the monorepo.
• next.config.js - Webpack customizations, image domains, environment variable exposure.
• drizzle.config.ts - Drizzle ORM dialect and migration folder configuration.
• tsconfig.json - Path aliases (~/*), strict mode, Next.js plugin.
• vitest.config.ts - Unit/integration test runner configuration.
• turbo.json - Turborepo task pipeline for build, lint, test.

Common pitfalls and fixes

• Missing NEXTAUTH_SECRET: Auth will throw a hard error at startup; always set it even in development via .env.local.
• SQLite file permissions: If DATABASE_URL points to a path the process cannot write, Drizzle silently fails on migration; run chmod 664 on the DB file and parent directory.
• ~ path alias not resolved: Add "paths": { "~/*": ["./src/*"] } to tsconfig.json and install tsconfig-paths if running scripts outside Next.js (ts-node -r tsconfig-paths/register).
• Docker detection returns false: The check reads DOCKER_HOST, DOCKER_PORT, or /var/run/docker.sock; when running outside Docker, explicitly set DOCKER_HOST=unix:///var/run/docker.sock if a socket exists elsewhere.
• i18n namespace 404: Every page uses specific namespace arrays (e.g., boardNamespaces); if a locale JSON file is missing under public/locales/<lang>/, next-i18next will silently fall back and keys will render raw. Copy all files from public/locales/en/ as a baseline.
• @mantine/next SSR emotion cache: Without wrapping _document.tsx with Mantine's createGetInitialProps, styles will flash on load; follow the Mantine SSR guide and use createStylesServer from @mantine/next.

Vibe-coding prompt template

I have purchased the Homarr (homarr@0.16.0) source block. The source is in ./source/
and the integration guide is in ./source/USAGE.md.

My project is: [describe your existing Next.js / Node.js project and its structure].

Please integrate the Homarr dashboard into my project step by step:
1. Read USAGE.md and the file excerpts in source/src/pages/board/index.tsx,
   source/src/pages/manage/boards/index.tsx, and source/src/modules/common/index.ts.
2. Install all dependencies listed in USAGE.md ## Required dependencies into my package.json.
3. Copy and wire the necessary files from source/src/ into my project, preserving the ~ path alias.
4. Set up the environment variables from USAGE.md ## Project setup section.
5. Wire NextAuth, tRPC (api.withTRPC), and next-i18next (appWithTranslation) in my _app.tsx.
6. Apply Drizzle migrations using source/drizzle/migrate/migrate.ts before the dev server starts.
7. Show me how to render BoardPage at /board and ManagementPage at /manage using the real
   exports from source/ without inventing any new APIs.
8. Point out any conflicts with my existing code and suggest fixes.

License and credit

Homarr is released under the MIT License. See source/LICENSE for the full text. The upstream project is maintained at github.com/ajnart/homarr (archived; active development continues at homarr-labs/homarr). This block packages version 0.16.0.

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

전체 설치 가이드와 연동 프롬프트는 구매 후 열람할 수 있습니다.