kubetail / dashboard-ui
CLAUDE.md1.8k starsChanged 7 days agoApache-2.0View on GitHub
React 19 + React Router 8 + Apollo Client 4 (GraphQL) + Jotai + Vite + Tailwind v4. UI primitives from @kubetail/ui. Package manager is pnpm; never npm or npx. Path alias: @/* → src/*. The React compiler is off. The Go server does not serve index.html. In production the Dashboard backend renders modules/dashboard/templates/index.tmpl and takes the script, style and font tags from .vite/manifest.json, so build.manifest: true in vite.config.ts is load-bearing. A change to index.html's <head>, title or inline theme…
Trending
Less talk lately.about the whole repository
Who's talking about kubetail-org/kubetail
- A Hacker News story“Show HN: Kubetail – Real-time log search for Kubernetes”Hacker News · May 1, 2025 · 126 points
- A Hacker News story“Show HN: Kubetail – Web-based real-time log viewer for Kubernetes”Hacker News · Feb 13, 2024 · 70 points
- @damyr.fr“Sur Kube tu as github.com/kubetail-org..., mais le graph d'event manque faut avouer”Bluesky · May 26, 2025 · 4 likes
- @matsuu.bsky.social“k8sのログをブラウザ経由で参照できるダッシュボード実装。pod単位のほか、deploymentやdaemonsetの単位で複数Podのログをまとめてのリアルタイム表示もできる。正規表現による絞り込みも可。”Bluesky · May 4, 2025 · 4 likes
- @chrisshort.net“kubetail-org/kubetail: Real-time logging dashboard for Kubernetes. View logs in a terminal or a browser. …”Bluesky · May 22, 2026 · 1 likes
The biggest 5 of 27 mentions linking to the repository that our crawl found. Each line is their own headline.
See all 27
Talked about on GitHub, Bluesky and Hacker News (27 times).
On GitHub · 20
- Oct 24, 2025🐋 Release kubetail-0.15.4 — kubetail-org/helm-charts1 reaction
- Oct 22, 2026chore(deps): update kubetail to v0.18.1 — uniget-org/tools0 reactions · 2 comments
- Jul 13, 2026💎 Knowledge Update & Optimization: 13 Jul 2026 — nubenetes/awesome-kubernetes0 reactions · 40 comments
- Jul 12, 2026💎 Knowledge Update & Optimization: 12 Jul 2026 — nubenetes/awesome-kubernetes0 reactions · 40 comments
- Jul 12, 2026💎 Knowledge Update & Optimization: 12 Jul 2026 — nubenetes/awesome-kubernetes0 reactions · 40 comments
15 more on GitHub
- Jun 25, 2026x/vulndb: potential Go vuln in github.com/kubetail-org/kubetail/modules/cli: GHSA-v8j7-hp7c-738f — golang/vulndb0 reactions · 1 comment
- Feb 5, 2026feat(kubetail): add package — brioche-dev/brioche-packages0 reactions
- Dec 8, 2025add kubetail — ai-solution-eng/frameworks0 reactions
- Oct 4, 2025feat: add kubetail plugin — asdf-vm/asdf-plugins0 reactions
- Sep 28, 2025Add kubetail plugin — kubernetes-sigs/krew-index0 reactions · 8 comments
- Sep 26, 2025new naming conflict with a project — johanhaleby/kubetail0 reactions · 2 comments
- Sep 19, 2025dev-util/kubetail-bin: add 0.7.5, 0.8.2 — gentoo/gentoo0 reactions · 6 comments
- Sep 18, 2025[Request]: kubetail — ScoopInstaller/Main0 reactions · 1 comment
- Jul 11, 2025🎣 Patch release — kubetail-org/helm-charts0 reactions
- Jul 9, 2025Add Real-Time Log Streaming with Kubetail — kubestellar/ui0 reactions · 5 comments
- Jun 21, 2025TypeScript definitions missing in v8 — nmn/react-timeago0 reactions · 1 comment
- May 21, 2025kubetail-org/kubetail: 一个通用的 Kubernetes 日志仪表板,可以暴漏在浏览器当中查看。 — awesome-ops/awesome-ops.github.io0 reactions
- May 20, 2025Integrate Kubetail graphical Logs for pods and jobs into Kubestellar — kubestellar/ui0 reactions · 9 comments
- May 2, 2025Vendoring a package using "local" imports from another directory? — openSUSE/obs-service-go_modules0 reactions
- Feb 2, 2025new addon: kubetail — kubernetes/minikube0 reactions · 26 comments
On Bluesky · 5
- May 26, 2025Sur Kube tu as github.com/kubetail-org..., mais le graph d'event manque faut avouer — @damyr.fr4 likes and reposts · 1 reply
- May 4, 2025k8sのログをブラウザ経由で参照できるダッシュボード実装。pod単位のほか、deploymentやdaemonsetの単位で複数Podのログをまとめてのリアルタイム表示もできる。正規表現による絞り込みも可。 — @matsuu.bsky.social4 likes and reposts
- May 22, 2026kubetail-org/kubetail: Real-time logging dashboard for Kubernetes. View logs in a terminal or a browser. Run anywhere - desktop, cluster,… — @chrisshort.net1 likes and repost
- May 1, 2025Show HN: Kubetail – Real-time log search for Kubernetes Hi Everyone! Kubetail is a general-purp... https://github.com/kubetail-org/kubetail… — @kubernetes.activitypub.awakari.com.ap.brid.gy1 likes and repost
- Feb 13, 2024Show HN: Kubetail – Web-based real-time log viewer for Kubernetes Discussion — @hn100.bsky.social1 likes and repost
On Hacker News · 2
- May 1, 2025Show HN: Kubetail – Real-time log search for Kubernetes126 points · 35 comments
- Feb 13, 2024Show HN: Kubetail – Web-based real-time log viewer for Kubernetes70 points · 33 comments
In this repository9 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- crates/CLAUDE.mdCLAUDE.md
- e2e/CLAUDE.mdCLAUDE.md
- modules/CLAUDE.mdCLAUDE.md
- proto/CLAUDE.mdCLAUDE.md
- release-cliSkill
- release-clusterSkill
- release-notesSkill
- release-versionSkill
The file
Files
dashboard-ui — React single-page app
React 19 + React Router 8 + Apollo Client 4 (GraphQL) + Jotai + Vite + Tailwind v4. UI primitives from @kubetail/ui. Package manager is pnpm; never npm or npx. Path alias: @/* → src/*. The React compiler is off.
The Go server does not serve index.html. In production the Dashboard backend renders modules/dashboard/templates/index.tmpl and takes the script, style and font tags from .vite/manifest.json, so build.manifest: true in vite.config.ts is load-bearing. A change to index.html's <head>, title or inline theme script is repeated in index.tmpl. → ADR: embed the UI by a copy step and render from the Vite manifest
Checks
pnpm format # oxfmt: formats and sorts imports
pnpm lint # oxlint (type-aware), then `oxfmt --check`. A warning fails the run.
pnpm build # tsc -b && vite build. `tsc -b` (`make vet-ts`) is the only type-check, and it covers test files
pnpm test run # `pnpm test` alone is watch mode and never exitsLayout
src/routes.tsxholds every route;src/main.tsxthe provider stack. Pages are insrc/pages/<page>/(home,console,auth), reusable widgets insrc/components/widgets/, app-wide modules insrc/lib/.- Files under
components/are PascalCase. Files underpages/,lib/andlog-viewer/are kebab-case with named exports, except a page's route component, which is its file's default export. New files outsidecomponents/follow that.
Runtime config, environment and base path
appConfig(src/app-config.ts) iswindow.runtimeConfig, which the server writes into the page (modules/dashboard/pkg/app/website.go).pnpm devhas no server-rendered page, so the app runs on the defaults in that file (desktop, base path/) whatever the backend's config says; aVITE_variable listed inENV_KEYSoverrides one, parsed to the default's type (a boolean istrueorfalse, a list is comma-separated).appConfig.environmentisdesktoporcluster. Indesktop,KubeConfigEffectholds the oneKUBE_CONFIG_WATCHsubscription and preferences are stored on the server. Inclusterthe subscription is skipped, the kube context is'', and preferences live in localStorage alone.- Several modules read
appConfigwhen they load (lib/kubeconfig.tsx,lib/preferences.tsx,pages/console/state.ts,apollo-client.ts).withAppConfigin a test cannot change what they already read. - Build every URL to the server with
getBasename()andjoinPaths(src/lib/util.ts), asgetSessiondoes. The app can be served under a base path or behind the kube-apiserver's service proxy. Router links get the basename from the router; a raw<a href>orfetchadds it by hand. pnpm devproxies/api/,/graphql,/cluster-api-proxy/and/healthztolocalhost:4000(vite.config.ts). A new backend route prefix needs an entry there.
GraphQL
- There are two Apollo clients (
src/apollo-client.ts).dashboardClientis the provider's default.getClusterAPIClient(kubeContext)returns one client per kube context for the Cluster API, and is chosen in two places only: the console (pages/console/index.tsx) andpages/home/log-metadata-provider.tsx. useIsClusterAPIEnabled(kubeContext)decides which one, and returnsundefinedwhile it does not know yet. The console mounts no viewer until it answers.- Queries and mutations go over HTTP, subscriptions over WebSocket (
graphql-ws). The HTTP chain is error link → retry link → CSRF link → HTTP link; subscriptions skip all three, so nothing global handles a subscription's errors: the code that subscribes does. - The CSRF token is a module variable in
src/lib/auth.tsx, never in storage. It comes from theX-CSRF-Tokenresponse header ofGET /api/auth/session. It goes out as theX-CSRF-Tokenheader on HTTP, ascsrfTokenin the WebSocket'sconnectionParams, and as a hiddencsrfTokenfield in the download form. A new way of calling the server carries it too. - Operations live in
src/lib/graphql/<server>/ops.ts, fragments infragments.ts, and nowhere else. Codegen globs those directories only, so a document defined in a component gets no types. - Write them with the generated
gql()function from./__generated__/gql, called on a template string:gql(`…`). Not Apollo'sgqltag. Fragment masking is off: read a fragment's fields directly. - A constant is
SCREAMING_SNAKE. One that belongs to a feature is prefixed by it (HOME_,CONSOLE_,SOURCE_PICKER_) and suffixed by its kind (_FETCH,_GET,_FIND,_WATCH,_FOLLOW); the operation name is its PascalCase. pnpm graphql-codegenregenerates__generated__/from the two schemas under../modules/. Run it after changingops.ts,fragments.tsor either schema, and commit the result. Never edit__generated__/. The two presets incodegen.tsoverride the same four defaults; keep them in step. → ADR: override the codegen client preset's v6 defaults- The console's log operations are written once, in
dashboard/ops.ts, and sent to either server. Codegen checks them against the Dashboard's schema alone. - Custom scalars arrive as
anyand are converted by the cache.dateFieldandbigIntFieldinapollo-client.tsturn named fields intoDateandbigint. A new time or int64 field needs a type policy there, or it is a string. Read a scalar withasto the type it has at run time. - Kubernetes lists are a query plus a watch, through the shared hooks in
src/lib/hooks.ts:useListQueryWithSubscription,useCounterQueryWithSubscription. Don't pairuseQueryanduseSubscriptionby hand. A paginated list field needsk8sPagination()inDashboardCustomCache.
State
- URL search params hold what a link should reproduce: the console's
kubeContext,source,grep,mode,cursorand its filters, written withsetSearchParams. Changingsourceis the exception: it reloads the page. - Jotai holds page state and derived data: a page's atoms in a
state.tsbeside it, app-wide ones inlib/. There is no JotaiProvider: atoms are module-global and outlive a route change. An atom's name ends inAtom, a family's inAtomFamily. - A fetcher component writes an atom, views read the atom.
WorkloadDataFetcher,LogMetadataProvider,SourcesFetcherandKubeConfigEffectrender nothing: they run the Apollo hooks and set atoms. - User settings go through
usePreferences(src/lib/preferences.tsx) and its wrappersuseTheme,useTimezone,useTimestampFormat. The localStorage keykubetail:preferencesis also read by the inline script inindex.htmlandindex.tmplbefore React loads; keep its shape in step with both. - Shared accessors, not raw calls:
useSessionfor the session,useKubeConfigfor the kubeconfig,useDashboardServerStatusand its siblings for health. - A page checks the session by wrapping itself in
AuthRequired.
The log viewer
src/components/widgets/log-viewer/ is headless: it imports only React, @tanstack/react-virtual and cn, and exports through index.ts.
types.tsis the contract. The console'sClientisLogServerClient(pages/console/log-server-client.ts), whose cursor is a record's timestamp.- A new
clientobject resets the viewer.LogViewerremounts its inner component when the prop's identity changes, sopages/console/index.tsxmemoizes the client on the kube context, sources, filters and grep, and keeps those stable with deep-compared values. - Row keys are stable: records sit in a
DoubleTailedArray, so prepending older lines moves no existing key. RecordRow(pages/console/main.tsx) ismemowith a hand-written comparator. A new prop is added to the comparator, or the row does not re-render for it.
Security invariants
What an ordinary change here can break, beside the root guide's list:
- Log text and Kubernetes names are attacker-controlled. Outside tests,
src/has nodangerouslySetInnerHTML,innerHTMLoreval. A log message reaches the DOM in one place,<AnsiHtml text={record.message} />fromfancy-ansi(pages/console/main.tsx); every other column is a React text child. Copy and width measurement usestripAnsi. - A name that becomes part of a CSS identifier goes through
cssEncode(src/lib/util.ts). - The Kubernetes token a user types at login is posted once and never stored client-side. The session is the server's cookie.
- Every state-changing request carries the CSRF token (GraphQL).
Styling
- Tailwind utilities inline in
className;src/index.cssis the Tailwind config. Merge classes withcn(...)from@/lib/utiland nothing else. - Primitives come from
@kubetail/ui/elements/<name>, by deep import. Don't import@base-ui/reactdirectly. - Colour with the semantic tokens (
bg-background,text-muted-foreground), not raw palette classes. Dark mode is thedarkclass on<html>. - Icons are
lucide-react; the Kubernetes workload glyphs are local SVGs imported as components with?react.
Tests
Vitest + @testing-library/react (jsdom), co-located as foo.test.ts[x]. Globals are on: describe, it, expect and vi need no import.
renderElement(element, mocks?)from@/test-utilswraps a component in a fresh Jotai store, Apollo'sMockedProviderwith the real cache, and aMemoryRouter.mocksareMockLink.MockedResponse[]built from the real documents inops.ts; results carry__typename;delay: Infinityholds a request pending.withAppConfig(overrides, fn)runsfnwithappConfigpatched and restores it.vitest.setup.tsmocks for every test:useSession(default: signed out, soAuthRequiredredirects), the CSRF token functions, anduseIsClusterAPIEnabled(default:true). A test of a signed-in page sets(useSession as Mock).mockReturnValue({ session: { user: 'test' } }).vi.resetAllMocks()runs after every test, so amockReturnValueormockImplementationbelongs inbeforeEach: set at module scope it lasts one test.- To wait, use
await waitFor(...)or fake timers (vi.useFakeTimers()withvi.advanceTimersByTimeAsync).requestAnimationFrameis a zero-delay timer in tests, so code that schedules a frame is driven the same way. - Log viewer doubles:
createMockClientandcreateMockLogViewerHandleinsrc/mocks/log-viewer.ts.FakeClient(log-viewer/fake-client.ts) streams generated records for trying the viewer by hand; the barrel does not export it.
Lint conventions
.oxlintrc.json is the lint: oxlint's correctness, suspicious and perf categories plus a chosen list of rules. A rule turned off or given options says why in a comment. → ADR: lint the dashboard UI with oxlint's categories and a chosen rule list
- Imports are grouped, a blank line between groups: third-party packages,
@kubetail/*,@/…, relative./…, then stylesheets.pnpm formatsorts them (sortImportsin.oxfmtrc.json). - No
anyoutside tests (no-explicit-anyand theno-unsafe-*rules). Read JSON and other outside data asunknownand check it, asparseSessioninlib/auth.tsxdoes. Tests turn theno-unsafe-*rules off, since a mock's calls areany. → ADR: forbid any in the dashboard UI outside tests - A disable comment is
oxlint-disable, names its rule, gives a reason after--, and is rare; an unused one fails the lint.eslint-disablecomments are ignored. - TypeScript is
strictwithnoUnusedLocalsandnoUnusedParameters. - A new dependency must be at least ten days old (
minimumReleaseAgeinpnpm-workspace.yaml);@kubetail/uiis exempt. - A dependency must declare every package it imports. The sandbox installs with pnpm's global virtual store, where an undeclared import fails with
Cannot find packagewhile the host and CI pass. Take a release that declares it, or add apackageExtensionsentry. Types are covered:tsconfig.app.jsonmapsreactto@types/react. → ADR: keep the sandbox's build outputs off the host mount
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

