2 posts tagged with "tooling"

The ESLint configuration in Uptime Watcher is not small. With dozens of plugins and custom rules, understanding what is actually enabled can be painful.

To solve that, we integrated a static build of the ESLint Config Inspector directly into the Docusaurus site, so you can browse the current ESLint config as a web UI.

This post summarizes how that integration works and where to look if you want to extend or regenerate it.

High-level flow​

The data flow is documented in detail in docs/docusaurus/src/pages/engineering-tooling.mdx, but the core idea is simple:

1. Run @eslint/config-inspector against eslint.config.mjs.
2. Emit a static inspector site into docs/docusaurus/static/eslint-inspector/.
3. Let Docusaurus serve it under /Uptime-Watcher/eslint-inspector/.

The relevant commands live in package.json:

{
  "scripts": {
    "build:eslint-inspector": "npx @eslint/config-inspector build --outDir \"docs/docusaurus/static/eslint-inspector\" --base \"/Uptime-Watcher/eslint-inspector/\"",
    "build:eslint-inspector:local": "npm run build:eslint-inspector"
  }
}

The integration itself is driven by a dedicated script and a Docusaurus page.

Build script and verification​

The implementation summary is captured in docs/docusaurus/src/pages/ESLINT-INSPECTOR-DEPLOYMENT-SUMMARY.md, but the key artifacts are:

• scripts/build-eslint-inspector.mjs — orchestrates the inspector build.
• scripts/verify-eslint-inspector.mjs — sanity-checks the generated files.

The build script:

• Invokes npx @eslint/config-inspector build with the correct base URL.
• Copies the output into docs/docusaurus/static/eslint-inspector/.
• Writes a small redirect/loader page so navigation feels seamless.

The verification script checks that:

• The static directory exists.
• index.html and redirect assets are present.
• The expected _nuxt/, api/, and fonts/ assets exist.

When everything is wired correctly, you can run:

npm run build:eslint-inspector
npm run docusaurus:build

and the inspector will be part of the generated docs site.

Docusaurus integration​

On the Docusaurus side, the integration is intentionally light:

• Static files live under docs/docusaurus/static/eslint-inspector/.

• The Docusaurus config adds a link in the footer:

  {
    href: "https://nick2bad4u.github.io/Uptime-Watcher/eslint-inspector/",
    label: "🧪 ESlint Config",
  }
  

• The engineering tooling page includes a section describing the inspector and how it fits into npm run docs:build.

No special plugin is required; it is just a static SPA mounted at a well-known path.

Why this matters​

The ESLint config is a critical part of the project's quality gates. Having an inspector UI baked into the docs site provides concrete benefits:

• Discoverability — contributors can quickly see which rules are enabled without reading a large flat config.
• Reviewability — changes to eslint.config.mjs can be inspected in a UI before/after running the build script.
• Documentation — the Docusaurus pages and deployment summary explain exactly how the inspector is produced and where it lives.

How to regenerate the inspector​

If you change ESLint rules or want to refresh the inspector after a dependency update:

1. Update eslint.config.mjs as usual.

2. Run:

   npm run build:eslint-inspector
   

3. Optionally verify the output:

   node scripts/verify-eslint-inspector.mjs
   

4. Rebuild or redeploy the docs site:

   npm run docs:build
   

That is it — the inspector will reflect the new configuration.

For more detail, see the full

page in the docs.

Electron IPC is a common place where apps quietly rot: ad-hoc channels, mismatched payloads, and copy-pasted handlers that drift over time.

Uptime Watcher takes a different route. IPC contracts are treated as shared types, and we have scripts that fail the build when main and renderer drift apart.

This post explains how the IPC layer is structured, how static guards work, and how that shows up in the git history.

Shared contracts first​

IPC contracts live in the shared layer so both the Electron main process and the React renderer agree on channel names and payload types.

Key pieces:

• shared/types/ipc.ts — maps channels to request/response payloads.
• shared/ipc/rendererEvents.ts — typed event payloads emitted from main to renderer.
• shared/types.ts and related monitor/site types — domain objects used in IPC payloads.

The Electron side uses these contracts in services like electron/services/ipc/IpcService.ts, while the renderer consumes them via preload domain APIs under electron/preload/domains/ and src/services/*Service.ts.

Typed preload APIs​

Rather than calling ipcRenderer.send directly from React components, the preload script defines domain-specific APIs that wrap IPC calls.

Examples:

• electron/preload/domains/sitesApi.ts — site CRUD and monitoring operations.
• electron/preload/domains/monitoringApi.ts — monitor control surface.

Each API function:

• Uses a shared channel constant (e.g. SITES_CHANNELS.addSite).
• Accepts and returns typed payloads defined in @shared/types.
• Applies basic validation / shaping before invoking IPC.

On the renderer side, services like src/services/SiteService.ts consume those APIs, and stores such as src/stores/sites/useSitesStore.ts call the services, not IPC directly.

Static architecture guards​

The glue that keeps IPC contracts from drifting is a set of static checks run as part of CI and npm run lint:ci.

The core script is:

• scripts/architecture-static-guards.mjs

It validates things like:

• IPC channels referenced in Electron services are declared in the shared IPC types.
• Renderer services don"t talk directly to Electron modules; they go through the preload bridge.
• Event names used in the TypedEventBus correspond to entries in the shared event maps.

You can run these guards locally via:

npm run lint:architecture
npm run analyze:ipc
npm run check:ipc

These commands are wired into higher-level scripts like:

npm run lint:all:fix
npm run quality

If a new IPC channel is added only on one side, or if a handler starts returning the wrong shape, those scripts fail quickly.

Git history: when guards caught problems​

Multiple commits in the history reflect this IPC discipline.

IPC generation and checking​

The scripts that generate and verify IPC artifacts live under scripts/generate-ipc-artifacts.mts. Commits around that script tightened validation to ensure:

• All IPC channel enums are covered.
• Renderer event payload maps stay in sync with main-process emitters.

The npm run analyze:ipc and npm run check:ipc commands now run in CI (see lint:ci and quality scripts in package.json). That means changes to IpcService, preload domains, or shared types won"t silently break IPC contracts.

Event system and IPC alignment​

The TypedEventBus defined in electron/events/TypedEventBus.ts and electron/events/eventTypes.ts is wired into IPC so that:

• Internal events (e.g. monitor status changes) are raised with typed payloads.
• Renderer events are forwarded through a dedicated bridge that uses the shared renderer event payload map.

Architecture docs like docs/Architecture/ADRs/ADR_002_EVENT_DRIVEN_ARCHITECTURE.md and docs/Architecture/ADRs/ADR_005_IPC_COMMUNICATION_PROTOCOL.md are not free-form essays; they match real type definitions and the guards mentioned above.

When something drifts, the combination of TypeScript, the architecture script, and the IPC analyzer catches it.

Practical impact​

The IPC contract + static guard approach has concrete benefits:

• Safer refactors — you can rename a monitor field in the shared types, update the database mapping, and rely on the IPC checks to tell you where handler payloads need adjustment.
• Fewer runtime surprises — mismatched payloads or missing event subscriptions are caught at build time rather than during a 3am incident.
• Better documentation — the shared IPC types and ADRs serve as living docs; they are always under pressure from CI to stay honest.

How to extend IPC safely​

If you are adding a new IPC feature, the safe workflow looks like:

1. Define types first

   • Add or extend shared types in shared/types/ipc.ts and related domain types.

2. Wire Electron handlers

   • Implement handlers in electron/services/ipc/IpcService.ts or a domain-specific coordinator.
   • Emit typed events via the TypedEventBus where appropriate.

3. Expose preload APIs

   • Add domain functions under electron/preload/domains/*Api.ts that call the new channel.

4. Consume from renderer services

   • Call the preload APIs from src/services/*Service.ts.
   • Keep components and stores IPC-free.

5. Run the guards

   npm run analyze:ipc
   npm run check:ipc
   npm run lint:architecture
   

Following that pattern keeps main and renderer aligned and ensures that IPC remains a well-behaved, typed boundary instead of a global message bus.