Skip to content

hashgraph-online/awesome-codex-plugins / plugins/alpoxdev/hypercore/skills/hyper-architecture

hyper-architecture

Verified

[Hyper] Use this skill when the user asks for architecture, project setup, or performance work - building, auditing, restructuring, or reviewing project structure, routes, data or server boundaries, the lint/format/type tooling baseline (oxlint, Prettier, tsconfig, rustfmt, clippy), or build and runtime performance - in a Next.js App Router, TanStack Start, Vite with TanStack Router, Astro, Expo, Lynx (ReactLynx), Hono, Axum, Tauri v2, Electron, or Rust CLI, WASM, or MCP server project. It detects the stack from manifests and config files, routes each touched package of a monorepo separately, and applies the matching bundled stack guide, the shared setup baseline, and that stack's performance rules. Do not use it for stacks outside those eleven or for work that crosses no architecture, setup, or performance boundary, such as copy edits, a plain dependency bump, or one build failure.

FileKindSize
SKILL.ko.mdmarkdown19.9 KB
SKILL.mdskill md18.4 KB
assets/evals/astro-cases.jsonlother17.1 KB
assets/evals/axum-cases.jsonlother13.7 KB
assets/evals/electron-cases.jsonlother14.6 KB
assets/evals/expo-cases.jsonlother18.3 KB
assets/evals/hono-cases.jsonlother22.2 KB
assets/evals/hyper-architecture-cases.jsonlother26.0 KB
assets/evals/lynx-cases.jsonlother17.9 KB
assets/evals/nextjs-cases.jsonlother21.5 KB
assets/evals/rust-cases.jsonlother17.8 KB
assets/evals/tanstack-start-cases.jsonlother21.0 KB
assets/evals/tauri-cases.jsonlother18.6 KB
assets/evals/vite-cases.jsonlother18.6 KB
assets/templates/setup/repo/editorconfigother357 B
assets/templates/setup/repo/gitattributesother714 B
assets/templates/setup/repo/lefthook.ymlconfig843 B
assets/templates/setup/rust/clippy.tomlconfig110 B
assets/templates/setup/rust/rust-toolchain.tomlconfig86 B
assets/templates/setup/rust/rustfmt.tomlconfig200 B
assets/templates/setup/rust/workspace-lints.tomlconfig809 B
assets/templates/setup/typescript/oxlintrc.jsonconfig929 B
assets/templates/setup/typescript/oxlintrc.react.jsonconfig1.1 KB
assets/templates/setup/typescript/prettierignoreother316 B
assets/templates/setup/typescript/prettierrc.jsonconfig263 B
assets/templates/setup/typescript/tsconfig.base.jsonconfig551 B
references/official/astro/astro-2026-11-07.ko.mdmarkdown18.6 KB
references/official/astro/astro-2026-11-07.mdmarkdown17.0 KB
references/official/axum/axum-docs.ko.mdmarkdown5.7 KB
references/official/axum/axum-docs.mdmarkdown4.8 KB
references/official/axum/ecosystem-docs.ko.mdmarkdown3.8 KB
references/official/axum/ecosystem-docs.mdmarkdown3.5 KB
references/official/axum/sqlx-docs.ko.mdmarkdown5.5 KB
references/official/axum/sqlx-docs.mdmarkdown4.7 KB
references/official/axum/tower-docs.ko.mdmarkdown4.2 KB
references/official/axum/tower-docs.mdmarkdown3.7 KB
references/official/axum/utoipa-docs.ko.mdmarkdown4.1 KB
references/official/axum/utoipa-docs.mdmarkdown3.7 KB
references/official/electron/electron-2026-11-08.ko.mdmarkdown15.7 KB
references/official/electron/electron-2026-11-08.mdmarkdown14.1 KB
references/official/expo/expo-react-native-2026-11-04.ko.mdmarkdown23.0 KB
references/official/expo/expo-react-native-2026-11-04.mdmarkdown21.5 KB
references/official/hono/drizzle-docs.ko.mdmarkdown7.0 KB
references/official/hono/drizzle-docs.mdmarkdown6.6 KB
references/official/hono/hono-docs.ko.mdmarkdown15.8 KB
references/official/hono/hono-docs.mdmarkdown14.8 KB
references/official/lynx/lynx-2026-11-07.ko.mdmarkdown14.3 KB
references/official/lynx/lynx-2026-11-07.mdmarkdown14.0 KB
references/official/nextjs/current-docs-2026-11-04.ko.mdmarkdown13.1 KB
references/official/nextjs/current-docs-2026-11-04.mdmarkdown12.0 KB
references/official/nextjs/drizzle-docs.ko.mdmarkdown6.7 KB
references/official/nextjs/drizzle-docs.mdmarkdown6.3 KB
references/official/nextjs/nextjs-docs.ko.mdmarkdown13.6 KB
references/official/nextjs/nextjs-docs.mdmarkdown13.9 KB
references/official/rust/rust-crates-2026-11-07.ko.mdmarkdown22.6 KB
references/official/rust/rust-crates-2026-11-07.mdmarkdown22.0 KB
references/official/tanstack-start/current-docs-2026-11-04.ko.mdmarkdown16.0 KB
references/official/tanstack-start/current-docs-2026-11-04.mdmarkdown14.7 KB
references/official/tanstack-start/tanstack-router-2026-11-04.ko.mdmarkdown10.5 KB
references/official/tanstack-start/tanstack-router-2026-11-04.mdmarkdown9.6 KB
references/official/tanstack-start/tanstack-start-2026-11-04.ko.mdmarkdown25.8 KB
references/official/tanstack-start/tanstack-start-2026-11-04.mdmarkdown23.9 KB
references/official/tauri/tanstack-vite-react-2026-11-04.ko.mdmarkdown14.1 KB
references/official/tauri/tanstack-vite-react-2026-11-04.mdmarkdown13.1 KB
references/official/tauri/tauri-v2-2026-11-04.ko.mdmarkdown18.5 KB
references/official/tauri/tauri-v2-2026-11-04.mdmarkdown17.6 KB
references/official/tooling/tooling-2026-11-07.ko.mdmarkdown21.0 KB
references/official/tooling/tooling-2026-11-07.mdmarkdown20.5 KB
references/official/vite/current-docs-2026-11-04.ko.mdmarkdown11.2 KB
references/official/vite/current-docs-2026-11-04.mdmarkdown10.3 KB
rules/astro/actions-middleware-env.ko.mdmarkdown14.6 KB
rules/astro/actions-middleware-env.mdmarkdown12.9 KB
rules/astro/content.ko.mdmarkdown8.1 KB
rules/astro/content.mdmarkdown7.3 KB
rules/astro/performance.ko.mdmarkdown11.3 KB
rules/astro/performance.mdmarkdown10.0 KB
rules/astro/project-structure.ko.mdmarkdown11.2 KB
rules/astro/project-structure.mdmarkdown9.6 KB
rules/astro/rendering-and-islands.ko.mdmarkdown10.2 KB
rules/astro/rendering-and-islands.mdmarkdown8.7 KB
rules/astro/testing.ko.mdmarkdown10.4 KB
rules/astro/testing.mdmarkdown9.4 KB
rules/axum/conventions.ko.mdmarkdown5.3 KB
rules/axum/conventions.mdmarkdown4.8 KB
rules/axum/database.ko.mdmarkdown11.9 KB
rules/axum/database.mdmarkdown10.2 KB
rules/axum/errors.ko.mdmarkdown6.5 KB
rules/axum/errors.mdmarkdown6.0 KB
rules/axum/handlers.ko.mdmarkdown5.6 KB
rules/axum/handlers.mdmarkdown5.0 KB
rules/axum/middleware.ko.mdmarkdown5.4 KB
rules/axum/middleware.mdmarkdown4.9 KB
rules/axum/openapi.ko.mdmarkdown9.5 KB
rules/axum/openapi.mdmarkdown8.3 KB
rules/axum/performance.ko.mdmarkdown9.6 KB
rules/axum/performance.mdmarkdown8.6 KB
rules/axum/platform.ko.mdmarkdown6.9 KB
rules/axum/platform.mdmarkdown6.3 KB
rules/axum/project-structure.ko.mdmarkdown10.8 KB
rules/axum/project-structure.mdmarkdown9.9 KB
rules/axum/routes.ko.mdmarkdown7.3 KB
rules/axum/routes.mdmarkdown6.3 KB
rules/axum/testing.ko.mdmarkdown5.2 KB
rules/axum/testing.mdmarkdown4.6 KB
rules/axum/validation.ko.mdmarkdown4.8 KB
rules/axum/validation.mdmarkdown4.4 KB
rules/electron/packaging.ko.mdmarkdown7.9 KB
rules/electron/packaging.mdmarkdown7.0 KB
rules/electron/performance.ko.mdmarkdown5.8 KB
rules/electron/performance.mdmarkdown5.0 KB
rules/electron/processes-and-ipc.ko.mdmarkdown10.6 KB
rules/electron/processes-and-ipc.mdmarkdown9.7 KB
rules/electron/project-structure.ko.mdmarkdown8.8 KB
rules/electron/project-structure.mdmarkdown8.1 KB
rules/electron/renderer.ko.mdmarkdown10.8 KB
rules/electron/renderer.mdmarkdown9.8 KB
rules/electron/security.ko.mdmarkdown10.3 KB
rules/electron/security.mdmarkdown9.2 KB
rules/electron/testing.ko.mdmarkdown5.7 KB
rules/electron/testing.mdmarkdown5.0 KB
rules/expo/data-state-and-boundaries.ko.mdmarkdown4.7 KB
rules/expo/data-state-and-boundaries.mdmarkdown4.3 KB
rules/expo/native-platform-and-security.ko.mdmarkdown8.2 KB
rules/expo/native-platform-and-security.mdmarkdown7.5 KB
rules/expo/performance.ko.mdmarkdown11.2 KB
rules/expo/performance.mdmarkdown10.1 KB
rules/expo/project-structure.ko.mdmarkdown13.4 KB
rules/expo/project-structure.mdmarkdown13.2 KB
rules/expo/routing-and-navigation.ko.mdmarkdown8.6 KB
rules/expo/routing-and-navigation.mdmarkdown8.0 KB
rules/expo/testing-and-validation.ko.mdmarkdown5.1 KB
rules/expo/testing-and-validation.mdmarkdown4.8 KB
rules/hono/conventions.ko.mdmarkdown3.7 KB
rules/hono/conventions.mdmarkdown3.5 KB
rules/hono/database.ko.mdmarkdown11.7 KB
rules/hono/database.mdmarkdown10.8 KB
rules/hono/errors.ko.mdmarkdown3.9 KB
rules/hono/errors.mdmarkdown3.7 KB
rules/hono/handlers.ko.mdmarkdown2.5 KB
rules/hono/handlers.mdmarkdown2.2 KB
rules/hono/middleware.ko.mdmarkdown3.3 KB
rules/hono/middleware.mdmarkdown3.0 KB
rules/hono/openapi.ko.mdmarkdown11.7 KB
rules/hono/openapi.mdmarkdown10.9 KB
rules/hono/performance.ko.mdmarkdown8.9 KB
rules/hono/performance.mdmarkdown8.0 KB
rules/hono/platform.ko.mdmarkdown5.0 KB
rules/hono/platform.mdmarkdown4.7 KB
rules/hono/project-structure.ko.mdmarkdown10.4 KB
rules/hono/project-structure.mdmarkdown9.9 KB
rules/hono/routes.ko.mdmarkdown6.9 KB
rules/hono/routes.mdmarkdown6.6 KB
rules/hono/testing-rpc.ko.mdmarkdown5.6 KB
rules/hono/testing-rpc.mdmarkdown5.2 KB
rules/hono/validation.ko.mdmarkdown3.7 KB
rules/hono/validation.mdmarkdown3.5 KB
rules/lynx/native-and-platform.ko.mdmarkdown11.4 KB
rules/lynx/native-and-platform.mdmarkdown10.7 KB
rules/lynx/performance.ko.mdmarkdown11.6 KB
rules/lynx/performance.mdmarkdown10.6 KB
rules/lynx/project-structure.ko.mdmarkdown10.2 KB
rules/lynx/project-structure.mdmarkdown9.6 KB
rules/lynx/testing.ko.mdmarkdown7.0 KB
rules/lynx/testing.mdmarkdown6.4 KB
rules/lynx/threading.ko.mdmarkdown13.0 KB
rules/lynx/threading.mdmarkdown12.0 KB
rules/lynx/ui-and-data.ko.mdmarkdown11.8 KB
rules/lynx/ui-and-data.mdmarkdown10.8 KB
rules/nextjs/data-fetching.ko.mdmarkdown9.9 KB
rules/nextjs/data-fetching.mdmarkdown9.3 KB
rules/nextjs/db.ko.mdmarkdown8.1 KB
rules/nextjs/db.mdmarkdown7.3 KB
rules/nextjs/execution-model.ko.mdmarkdown5.0 KB
rules/nextjs/execution-model.mdmarkdown4.5 KB
rules/nextjs/hooks.ko.mdmarkdown5.8 KB
rules/nextjs/hooks.mdmarkdown5.3 KB
rules/nextjs/performance.ko.mdmarkdown12.5 KB
rules/nextjs/performance.mdmarkdown11.2 KB
rules/nextjs/platform.ko.mdmarkdown7.7 KB
rules/nextjs/platform.mdmarkdown7.0 KB
rules/nextjs/project-structure.ko.mdmarkdown9.4 KB
rules/nextjs/project-structure.mdmarkdown9.0 KB
rules/nextjs/route-handlers.ko.mdmarkdown4.7 KB
rules/nextjs/route-handlers.mdmarkdown4.3 KB
rules/nextjs/routes.ko.mdmarkdown5.0 KB
rules/nextjs/routes.mdmarkdown4.6 KB
rules/nextjs/server-actions.ko.mdmarkdown7.1 KB
rules/nextjs/server-actions.mdmarkdown6.4 KB
rules/nextjs/services.ko.mdmarkdown5.8 KB
rules/nextjs/services.mdmarkdown5.5 KB
rules/nextjs/validation.ko.mdmarkdown2.2 KB
rules/nextjs/validation.mdmarkdown2.3 KB
rules/rust/cli.ko.mdmarkdown13.6 KB
rules/rust/cli.mdmarkdown12.0 KB
rules/rust/crate-layout.ko.mdmarkdown11.4 KB
rules/rust/crate-layout.mdmarkdown10.1 KB
rules/rust/errors-and-logging.ko.mdmarkdown13.0 KB
rules/rust/errors-and-logging.mdmarkdown11.6 KB
rules/rust/mcp-server.ko.mdmarkdown15.2 KB
rules/rust/mcp-server.mdmarkdown13.8 KB

rules/electron/renderer.md

View on GitHub
# Renderer: React, Tailwind CSS v4, TanStack Router and Query

> The renderer is a sandboxed web app: React renders it, Tailwind v4 styles it from the renderer build only, TanStack Router routes it with hash or memory history, and TanStack Query caches every IPC read behind one desktop adapter.

Rules are labelled `official` when a page in `references/official/electron/electron-2026-11-08.md` states them, and `hypercore-default` when this package chose the default.

## 1. Bootstrap

- `official` — Mount one `createRoot` in `src/renderer/src/main.tsx`, with `QueryClientProvider` above `RouterProvider`, inside `StrictMode`. Keep `StrictMode` in development: duplicate IPC listeners exposed by effect re-runs mean a missing unsubscribe, not a reason to drop it.
- `hypercore-default` — `src/renderer/src/router.tsx` owns the one `QueryClient`, the one history instance, and the one router; nothing else constructs them.

```tsx
// src/renderer/src/router.tsx
import { QueryClient } from '@tanstack/react-query'
import { createHashHistory, createRouter } from '@tanstack/react-router'
import { routeTree } from './routeTree.gen'
import { desktop } from './platform/desktop'

export const queryClient = new QueryClient({
  defaultOptions: { queries: { staleTime: 30_000, refetchOnWindowFocus: false, networkMode: 'always' } },
})

export const router = createRouter({
  routeTree,
  history: createHashHistory(),
  context: { queryClient, desktop },
  defaultPreloadStaleTime: 0,
})

declare module '@tanstack/react-router' {
  interface Register { router: typeof router }
}
```

## 2. TanStack Router

- `official` — TanStack Router uses browser history by default. Hash history suits environments without a server that rewrites to `index.html`, and memory history keeps the location in memory; pass the instance as `createRouter({ routeTree, history })`.
- `official` — The packaged renderer has no server to rewrite deep paths. Under `file://` a browser-history route such as `/settings` becomes `file:///…/index.html/settings` and breaks on reload or in a new window. Even under a custom protocol, a reload of a deep browser-history path asks the protocol handler for a file that does not exist.
- `hypercore-default` — Use `createHashHistory()` for a single-window app. Use one `createMemoryHistory()` router per tab or pane when the app owns several independent locations (the pattern Cherry Studio ships). Keep browser history only when the `protocol.handle` callback deliberately falls back to `index.html` for unknown paths and that fallback is tested.
- `official` — Configure `tanstackRouter({ target: 'react', autoCodeSplitting: true })` before `@vitejs/plugin-react`, both inside `renderer.plugins`. The plugin resolves `routesDirectory` (default `./src/routes`) and `generatedRouteTree` (default `./src/routeTree.gen.ts`) from the process working directory, not from electron-vite's `renderer.root`, so pass absolute paths such as `join(import.meta.dirname, 'src/renderer/src/routes')`; a missing override fails with `ENOENT … scandir '<repo>/src/routes'`. `routeTree.gen.ts` is generated; edit route files, never the tree.
- `official` — `beforeLoad` guards and redirects control navigation only. Every main-process handler authorizes its own operation, because injected script can call the preload API without visiting the guarded route.
- `official` — Route loaders and preloads are speculative: they must not write, prompt, open dialogs, or trigger native side effects. Put validated search values that change a loader's output in `loaderDeps`, and define `pendingComponent`, `errorComponent`, and `notFoundComponent` for meaningful route hierarchies.

## 3. TanStack Query over IPC

- `hypercore-default` — `src/renderer/src/platform/desktop.ts` is the only renderer file that reads `window.desktop`. It turns each `{ ok: false }` result into a thrown `DesktopError`, so a `queryFn` rejects as Query requires, and it exposes typed methods only.
- `official` — A `queryFn` must resolve data or throw. A query key is a serializable array that contains every input the `queryFn` uses.
- `hypercore-default` — Each domain under `features/<domain>/` defines its `queryOptions` once; the route loader calls `ensureQueryData` with the same options the component reads with `useSuspenseQuery`. Mutations call the desktop adapter and invalidate only the affected keys.
- `official` — Query treats data as stale by default and refetches on mount, window focus, and reconnect; `focusManager` listens for `visibilitychange` in the renderer. In a desktop window every alt-tab can therefore re-run IPC reads. Choose `staleTime` and `refetchOnWindowFocus` per query on purpose instead of leaving the web defaults. When focus refetch is wanted, drive `focusManager.setEventListener` from the `BrowserWindow` `focus` and `blur` events that main pushes through the preload.
- `official` — Query's default `networkMode: 'online'` pauses queries while Chromium reports offline; `'always'` is the documented mode for a `queryFn` that does not need the network. IPC-backed queries use `'always'`; queries that reach a remote API keep `'online'`.
- `official` — Passing the `AbortSignal` to an IPC call does not cancel work in main. Native cancellation needs its own channel (for example a cancel message or a `MessagePort` the main side watches).
- `hypercore-default` — Data that main pushes (file watchers, download progress, update status) reaches Query through a preload `on*` subscription in one effect that calls `queryClient.setQueryData` or `invalidateQueries`, and returns the unsubscribe function. Do not also poll the same data with `refetchInterval`.
- `hypercore-default` — Tests create a fresh `QueryClient` per test with `retry: false` and a fake desktop adapter; they never touch the real `window.desktop`.

## 4. Tailwind CSS v4

- `official` — Install `tailwindcss` and `@tailwindcss/vite`, add `tailwindcss()` to the renderer Vite plugins, and put `@import "tailwindcss";` in the renderer CSS entry. Version 4 needs no `tailwind.config.js` and no PostCSS config; theme values live in CSS with `@theme`, plugins with `@plugin`, and custom variants with `@custom-variant`.
- `official` — The plugin belongs to the renderer build only. In `electron.vite.config.ts` that is `renderer.plugins`; a root-level or `main` plugin never scans the renderer and only slows the Node builds.
- `official` — Automatic source detection skips `.gitignore`d paths and `node_modules`. Register class sources outside the renderer root (a workspace UI package, a `node_modules` component library) with `@source`, and exclude fixtures with `@source not`.
- `official` — Tailwind v4 targets Safari 16.4, Chrome 111, and Firefox 128. Every supported Electron major ships a far newer Chromium, so no v3 compatibility mode or extra PostCSS step is needed.
- `hypercore-default` — Implement dark mode with `@custom-variant dark (&:where(.dark, .dark *));` and a class set on `<html>` from the OS theme that main reports (`nativeTheme`) through the preload, so the window background, title bar, and CSS agree.
- `hypercore-default` — Keep design tokens in one `@theme` block in `main.css`. A shared component library keeps its own CSS and is pulled in with `@source`, not by copying its classes.

## Review gate

1. A renderer file reads `window.desktop` outside `platform/desktop.ts`, or imports `electron` or `node:*`.
2. The router uses browser history while production loads `file://` or a protocol handler with no tested `index.html` fallback.
3. The router plugin follows the React plugin, or either one, or Tailwind, sits outside `renderer.plugins`.
4. More than one `QueryClient` or router exists, or a loader and its component use different query options.
5. A `queryFn` returns an `{ ok: false }` envelope as data instead of throwing.
6. Window-focus refetch policy was left at the web default for queries that call IPC, without a stated reason.
7. A push subscription has no unsubscribe, or pushed data is also polled.
8. `tailwind.config.js` or a PostCSS Tailwind step remains alongside `@tailwindcss/vite` with no migration note.

## Sources

> Checked 2026-11-08.

| Claim | Source |
|---|---|
| Browser, hash, and memory history and passing an instance to `createRouter` | https://tanstack.com/router/latest/docs/framework/react/guide/history-types |
| Router plugin order, `routesDirectory`, and `generatedRouteTree` | https://tanstack.com/router/latest/docs/framework/react/installation/with-vite |
| Loader, preload, guard, and route-state behavior | https://tanstack.com/router/v1/docs/framework/react/guide/data-loading, https://tanstack.com/router/v1/docs/framework/react/guide/authenticated-routes |
| Query defaults, `focusManager`, network modes, query keys, and query functions | https://tanstack.com/query/latest/docs/framework/react/guides/important-defaults, https://tanstack.com/query/latest/docs/reference/focusManager, https://tanstack.com/query/latest/docs/framework/react/guides/network-mode, https://tanstack.com/query/latest/docs/framework/react/guides/query-keys |
| `routesDirectory` resolving from the working directory inside an electron-vite renderer | https://github.com/TanStack/router/issues/1170 |
| Tailwind v4 Vite install, CSS-first configuration, and browser targets | https://tailwindcss.com/docs/installation/using-vite, https://tailwindcss.com/docs/theme, https://tailwindcss.com/docs/compatibility |
| Source detection and `@source` | https://tailwindcss.com/docs/detecting-classes-in-source-files |
| Dark mode custom variant | https://tailwindcss.com/docs/dark-mode |
| `file://` breaking browser-history routes, memory routers per tab, hash history on desktop | surveyed apps: https://github.com/CherryHQ/cherry-studio, https://github.com/chatboxai/chatbox |
| The desktop adapter, envelope-to-throw rule, push-to-cache pattern, and token location | this package's convention, not an official requirement |
rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit.Stars: 469kUpdated Claude CodeCodexVerifiedInstall
rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure.Stars: 469kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 469kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 194kUpdated Claude CodeCodexVerifiedInstall