Skip to content

README.md

Latest commit

 

History

History
132 lines (103 loc) · 4.35 KB

README.md

File metadata and controls

132 lines (103 loc) · 4.35 KB

@remcostoeten/dev-widget

npm version CI License: MIT

Minimal, type-safe dev widget for React apps.

Installation

bun add @remcostoeten/dev-widget

React usage

import { DevWidget } from '@remcostoeten/dev-widget/react'

export function App(): React.ReactElement {
	return (
		<>
			<main>App</main>
			<DevWidget
				mode='development-only'
				theme={{ mode: 'system', accent: '#3bb273' }}
				features={{
					performance: { enabled: true, fpsThreshold: 50 },
					auth: { enabled: true, provider: 'better-auth' }
				}}
			/>
		</>
	)
}

Features

  • Auth domain
  • Routes domain
  • Links domain
  • Performance domain
  • System domain
  • Monitor domain

Feature checklist

  • React widget shell with tab categories
  • Domain lifecycle (setup/start/stop) via runtime registry
  • Plugin API with typed event subscription
  • Event bus for cross-domain communication
  • Next.js log ingestion route handler
  • In-memory storage adapter
  • Tauri storage adapter export
  • Route discovery adapter for Next.js and React projects
  • Right rail with diagnostics render panel
  • Keyboard shortcuts (toggle + Escape)
  • Accessibility: focus-visible, reduced-motion handling, live region announcements
  • Internal subpath export (@remcostoeten/dev-widget/internal)
  • Source maps and declaration output in package build
  • CI publish artifact validation step
  • Demo app build pipeline

Needs additional work

  • AI providers: openai and local modes are declared but not implemented yet; only rules and custom are active (src/domains/performance/aiProviderFactory.ts).
  • Runtime prop updates: DevWidget memoizes runtime by shouldRender only, so runtime does not re-bootstrap when non-visibility props change after mount (src/devWidget.tsx).
  • Storage wiring: providers.storage is part of public config but not wired into runtime/domain persistence flow yet (src/types/public.ts and src/core/bootstrap.ts).
  • Endpoint validation: Next log handler accepts event payloads without schema validation; malformed event shapes can be persisted (src/adapters/next/routeHandler.ts).
  • CI parity: local checks pass, but final release confidence still depends on a pushed branch and green remote GitHub Actions run.

Plugin API

import { createRuntime } from '@remcostoeten/dev-widget'

const runtime = createRuntime({ mode: 'always' })

await runtime.registerPlugin({
	id: 'my-plugin',
	version: '1.0.0',
	register(ctx) {
		ctx.onEvent('performance/drop-detected', function onDrop(payload) {
			console.log('FPS drop:', payload.fps)
		})
	}
})

Subpath exports

import { DevWidget } from '@remcostoeten/dev-widget/react'
import { createLogHandler } from '@remcostoeten/dev-widget/next'
import { createTauriStorage } from '@remcostoeten/dev-widget/tauri'
import type { WidgetDomain } from '@remcostoeten/dev-widget/internal'

Accessibility

The widget includes keyboard shortcuts, focus-visible styling, live announcements, and reduced-motion support. See specs/10-dev-widget-accessibility-keyboard-spec.md for the detailed behavior contract.

Core options

  • enabled?: boolean
  • mode?: 'development-only' | 'always'
  • theme?: { mode?: 'system' | 'light' | 'dark'; accent?: string; density?: 'compact' | 'comfortable'; radius?: 'none' | 'sm' | 'md' | 'lg' }
  • features?: { auth?: boolean | AuthOptions; routes?: boolean | RoutesOptions; performance?: boolean | PerfOptions; system?: boolean | SystemOptions; links?: boolean | LinksOptions }
  • disable?: FeatureId[]
  • providers?: { auth?: AuthConfig; ai?: AiConfig; storage?: StorageConfig }
  • keyboard?: { toggleKey?: string; enableShortcuts?: boolean }
  • accessibility?: { reducedMotion?: 'system' | 'always' | 'never'; announceUpdates?: boolean }
  • rightRail?: { enabled?: boolean; defaultPanel?: string | null; collapsible?: boolean; panels?: PanelConfig[] }

Changelog

Contributing

bun run lint
bun run format:check
bun run type-check
bun test
bun run build

License

MIT