next-runtime-toolkit

next-runtime-toolkit is a comprehensive Next.js and React utility package for runtime coordination and development-time debugging.

Included Modules

• next-runtime-toolkit/action-backpressure
  • Queue rapid async actions so they execute one at a time.
• next-runtime-toolkit/action-idempotency
  • Deduplicate identical in-flight actions by key.
• next-runtime-toolkit/hydration-guard
  • Highlight likely server/client mismatch sources during development.
• next-runtime-toolkit/stream-trace
  • Instrument suspense boundaries and visualize fallback timing.
• next-runtime-toolkit/cache-signals
  • Manually annotate cache hits, misses, refreshes, and revalidation events.
• next-runtime-toolkit/dev-notes
  • Add development-only UI notes with optional VS Code deep links.

Install

npm install next-runtime-toolkit

Example

'use client';

import {
  CacheSignalMarker,
  CacheSignalsProvider,
  HydrationGuard,
  HydrationGuardProvider,
  RuntimeNote,
  RuntimeNotesProvider,
  StreamTraceBoundary,
  StreamTraceProvider,
  useIdempotentAction,
  useQueuedAction
} from 'next-runtime-toolkit';

export function Example({
  saveDraft
}: {
  saveDraft: (id: string) => Promise<void>;
}) {
  const queued = useQueuedAction(saveDraft, { queueKey: 'draft-save' });
  const deduped = useIdempotentAction(saveDraft, {
    key: (id) => id,
    registryKey: 'draft-dedupe'
  });

  return (
    <RuntimeNotesProvider workspaceRoot="/Users/you/app">
      <HydrationGuardProvider>
        <CacheSignalsProvider>
          <StreamTraceProvider>
            <RuntimeNote
              title="Draft toolbar"
              note="This area combines action coordination and suspense tracing."
              file="app/editor/toolbar.tsx"
            >
              <HydrationGuard
                label="Draft timestamp"
                serverValue="2026-04-10T10:00:00.000Z"
                clientValue={new Date().toISOString()}
              >
                <CacheSignalMarker label="toolbar-cache" kind="revalidate" detail="Manual refresh">
                  <StreamTraceBoundary label="Editor sidebar" fallback={<div>Loading...</div>}>
                    <button onClick={() => void queued.run('draft-1')}>Queued Save</button>
                    <button onClick={() => void deduped.run('draft-1')}>Deduped Save</button>
                  </StreamTraceBoundary>
                </CacheSignalMarker>
              </HydrationGuard>
            </RuntimeNote>
          </StreamTraceProvider>
        </CacheSignalsProvider>
      </HydrationGuardProvider>
    </RuntimeNotesProvider>
  );
}

Notes

• The development overlays are intentionally explicit and manual. Next.js does not currently expose all runtime internals as stable public APIs, so the toolkit focuses on practical instrumentation.
• stream-trace instruments suspense timing, not the full internal React Flight protocol.
• cache-signals is designed for manual reporting rather than automatic Next.js cache introspection.

Compatibility

• Node.js >=18
• Next.js 14, 15, and 16
• React 18 and 19

Development

npm install
npm run test
npm run build

License

MIT