Add Nextra documentation site and slim down README #7
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Owner
ryanhefner
commented
Jan 22, 2026
ryanhefner
commented
- Create Nextra 4 docs site with full documentation at docs/
- Migrate all API reference, guides, and troubleshooting content
- Add Next.js section with overview, App Router, and Pages Router pages
- Add React Native section with navigation and app state tracking
- Slim down README to quick start essentials with links to react-fathom.com
- Preserve Fathom referral link and all feature documentation
- Create Nextra 4 docs site with full documentation at docs/ - Migrate all API reference, guides, and troubleshooting content - Add Next.js section with overview, App Router, and Pages Router pages - Add React Native section with navigation and app state tracking - Slim down README to quick start essentials with links to react-fathom.com - Preserve Fathom referral link and all feature documentation
- Replace Nextra with custom Chakra UI v3 docs components - Create DocsLayout, Sidebar, TableOfContents, Navbar components - Add MDX components: Callout, CodeBlock, Cards, Steps, Tabs - Set up next-mdx-remote for MDX processing - Add frontmatter support for all content pages - Remove Nextra-specific imports from MDX files - This serves as the prototype for a potential chakra-docs kit
- Add rehype-pretty-code + shiki for syntax highlighting - Add code filename support via MDX fence meta - Add Edit on GitHub link to all pages - Add auto sidebar generation from file structure with _meta.ts - Add Pagefind search with Cmd+K keyboard shortcut - Update CodeBlock with Figure/Figcaption for filename display - Add data-pagefind-body for search indexing
- Add Breadcrumbs component for navigation context - Add PackageInstall and NpmToYarn components for package manager switching - Add getLastUpdated() using git log for file modification dates - Add getBreadcrumbs() to build navigation breadcrumb trail - Integrate breadcrumbs and last updated display into DocsLayout - Export new components from index.ts and add to MDXComponents
- Add Accordion, AccordionItem, and Collapsible components for collapsible content - Add FileTree, Folder, and File components for visualizing directory structures - FileTree supports file type icons and highlighting for added/removed files - Export new components from index.ts and add to MDXComponents
- Add dynamic OG image generation for social sharing - Add sitemap.ts and robots.ts for SEO - Add print styles for clean documentation printing - Add changelog page with release history - Add Changelog component for displaying version history - Enhance layout metadata with OpenGraph and Twitter card support
- Add AnnouncementBanner component with dismiss persistence - Add custom 404 page with search and popular links - Add keyboard shortcuts: j/k for prev/next page, / to focus search - Update Search to listen for custom open-search event - Integrate KeyboardShortcuts and AnnouncementBanner into DocsLayout
- Create LandingPage component with hero, framework cards, features, and code example - Move documentation route from / to /docs - Update all internal links to use /docs prefix - Update navigation, sitemap, and breadcrumbs for new structure - Update 404 page with simplified navbar - Landing page at / showcases React, Next.js, and React Native support
- Add react-fathom and fathom-client as dependencies - Set up NextFathomProviderApp in the root provider - Analytics enabled when NEXT_PUBLIC_FATHOM_SITE_ID is set - Add .env.example with configuration template
- Create React (Vite + React Router) example with: - FathomProvider setup - Pageview tracking on route changes - Custom event tracking demo - Self-documenting docs page - Create React Native (Expo) example with: - FathomProvider from react-fathom/native - Event tracking demo - Offline support documentation - Navigation tracking example - Update examples README with live demo links - Update landing page to link to example subdomains - Examples will be hosted at: - react.react-fathom.com - native.react-fathom.com - next-app.react-fathom.com - next-pages.react-fathom.com
- Add self-documenting docs page to next-app (App Router) example - Add interactive events demo page to next-app example - Add self-documenting docs page to next-pages (Pages Router) example - Add interactive events demo page to next-pages example - Update navigation in both examples to include new pages - Update README files with live demo links - Update landing page to show both Next.js demo links
- Fix List components (UnorderedList/OrderedList -> List.Root/List.Item) - Fix duplicate _light props in PackageInstall component - Remove unused Modal import from Search component - Fix Input variant (unstyled -> flushed) in Search component - Use native HTML elements for CodeBlock to avoid type issues - Change opengraph-image runtime from edge to nodejs for fs access - Add getMDXComponents function for RSC compatibility - Remove 'use client' from MDXComponents to work with RSC - Add eslint.ignoreDuringBuilds to next.config.mjs - Add webpackIgnore comment for pagefind dynamic import
- Add output: 'export' to docs site next.config.mjs - Add force-static export config to robots.ts and sitemap.ts - Remove opengraph-image.tsx (incompatible with static export + optional catch-all) - Add output: 'export' to next-app example - Remove package-lock.json files from examples
Change react-fathom dependency from file:../.. to ^0.2.0 to avoid duplicate React issues during development builds.
- Add ReactRouterFathomTrackView component for React Router v6+ and Remix - Export via react-fathom/react-router path - Support options: disableAutoTrack, includeSearchParams, includeHash, transformUrl - Add react-router-dom as optional peer dependency - Include comprehensive test coverage (9 tests)
- Add comprehensive React Router / Remix documentation - Update docs navigation to include React Router section - Add ReactRouterFathomTrackView to React example - Update README with React Router usage and links - Update getting-started with React Router peer dependency
- Add GatsbyFathomTrackView component using @reach/router's globalHistory - Add gatsby-browser.js helpers (createGatsbyFathomPlugins, trackGatsbyPageview) - Add comprehensive tests for Gatsby integration - Create Gatsby documentation page - Update README and getting-started with Gatsby information
- Add TanStackRouterFathomTrackView component using useRouterState hook - Add comprehensive tests for TanStack Router integration - Create TanStack Router documentation page - Update README and getting-started with TanStack Router information - Configure rollup and package.json for tanstack-router export path
Previously, nested providers would completely replace parent default
options. Now child providers deep merge their options with parent
options, allowing children to override specific values while
inheriting others.
Example:
- Parent: { _site_id: 'abc', _value: 100 }
- Child: { _value: 200 }
- Result: { _site_id: 'abc', _value: 200 }
- Add `debug` prop to FathomProvider (boolean or options object)
- When enabled, emits debug events for all tracking calls
- Console logging with colored output and emojis
- `onTrack` callback for custom UI integration (toast notifications)
- `subscribeToDebug` context method for reactive subscriptions
- New `useDebugSubscription` hook for consuming debug events
- Export DebugEvent, DebugOptions, and DebugEventCallback types
- Works without siteId for demo/development scenarios
- Does not block actual Fathom tracking
Example usage:
```tsx
<FathomProvider debug> // Simple console logging
<FathomProvider debug={{ enabled: true, onTrack: showToast }}>
```
- Create EventStream component to display debug events as a toggleable toast stream - Enable debug mode in docs site FathomProvider for event visualization - Add event tracking to CodeBlock (copy code) and Search (open, result click) components - EventStream persists visibility preference in localStorage
- Add debug mode to features list - Document debug prop and useDebugSubscription hook - Add useDebugSubscription to hooks table
The FathomContext provides default stub implementations for all tracking methods, so optional chaining is not needed when calling them.
- Add Cmd/Ctrl + . keyboard shortcut to toggle visibility - Show shortcut hint in the panel footer
Codecov Report❌ Patch coverage is
Additional details and impacted files@@ Coverage Diff @@
## main #7 +/- ##
==========================================
- Coverage 94.62% 93.14% -1.48%
==========================================
Files 19 25 +6
Lines 484 759 +275
Branches 103 210 +107
==========================================
+ Hits 458 707 +249
- Misses 26 51 +25
- Partials 0 1 +1 ☔ View full report in Codecov by Sentry. 🚀 New features to boost your workflow:
|
Update package.json files to use file: references instead of npm versions. This allows the docs site and examples to use the local package directly, making them useful as test cases during development without requiring a publish step. - docs: file:.. - examples/*: file:../..
- Add React Router, Gatsby, and TanStack Router to frameworks grid - Add Debug Mode and Tree-Shakeable to features list - Simplify framework cards to link directly to docs - Update grid layouts for better responsive display
- Create /debug subpackage for debugging utilities - Add EventStream component that displays tracked events in a panel - Export useDebugSubscription and debug types from /debug - Update all examples to use react-fathom/debug EventStream - Enable debug mode in all example sites
- Add onError callback prop to FathomProvider for error handling on tracking calls - Add safeClientCall helper that wraps client methods with try-catch - Add try-catch around localStorage access in EventStream to handle private browsing - Add transformUrl option to Next.js integrations for URL transformation before tracking - Add comprehensive tests for EventStream component
- Add buildTrackingUrl utility in src/next/utils.ts - Refactor NextFathomTrackViewApp to use shared utility - Refactor NextFathomTrackViewPages to use shared utility - Update test mocks to include pathname and search
- Add 5 tests for onError callback in FathomProvider - Add transformUrl tests for NextFathomTrackViewApp - Add transformUrl tests for NextFathomTrackViewPages (initial and route change) - Add 7 tests for buildTrackingUrl utility
- Add SVG logos for React, Next.js, React Router, Gatsby, TanStack Router, and React Native - Display logo grid in hero section - Update framework cards to use logos instead of emojis - Handle dark mode inversion for Next.js logo
Docs site: - Add comprehensive metadata (keywords, authors, robots) - Add static OG image (SVG) - Add Open Graph and Twitter card images - Add Twitter creator handle Example sites: - Add Open Graph tags to Next.js App Router example - Add meta tags and OG tags to Next.js Pages Router example - Add meta tags and OG tags to React example
Create @react-fathom/example-ui package with: - ExampleProvider: Chakra UI + color mode for non-Next.js apps - ExampleProviderNext: Chakra UI + next-themes for Next.js apps - ExampleLayout: Shared nav, footer, and theme toggle for Next.js - ExampleLayoutSimple: Shared layout for React Router apps - ColorModeContext: Simple color mode for non-Next.js apps - ColorModeButton: Theme toggle components Update all examples to use shared package: - next-app: Uses ExampleProviderNext + ExampleLayout - next-pages: Uses ExampleProviderNext + ExampleLayout - react: Uses ExampleProvider + ExampleLayoutSimple
- Create EventStreamPanel component using useDebugSubscription hook - Integrate EventStreamPanel into ExampleLayout and ExampleLayoutSimple - Add showEventStream prop to layouts (default: true) - Remove redundant EventStream imports from example sites
- Add transpilePackages for react-fathom in docs Next.js config - Add siteId fallback to 'DEMO' in docs provider - Add warning when siteId is not configured (debug events still flow) - Add try-catch around localStorage in EventStream - Add debug logging when EventStream is hidden
- Add CustomEvent dispatch in FathomProvider for debug events - Update docs EventStream to use forceShow prop and listen to global events - This fixes context sharing issues with linked packages in Next.js
- Create TanStack Router example with file-based routing and Vite - Create Gatsby example with @reach/router integration - Both examples include OG tags and meta tags for SEO - Both examples use Chakra UI for styling - Update examples README with new examples and live demo links
- docs: Static export to out/ - react: Vite build to dist/ - next-app: Next.js with App Router - next-pages: Next.js with Pages Router - tanstack-router: Vite build to dist/ - gatsby: Gatsby build to public/ Each config includes install and build commands that first build the root react-fathom package, then the example site.
Create local re-export files (docs/lib/fathom.ts and fathom-next.ts) that import directly from source files to ensure a single context instance. This fixes the issue where module resolution created separate context instances for the linked package vs the docs app components. Updated all docs component imports to use @/lib/fathom and @/lib/fathom-next instead of importing from 'react-fathom' directly.
- dev:all - Runs docs and all example sites on different ports - dev:proxy - Runs all sites with subdomain proxy on port 8080 Sites and ports: docs: localhost:3000 / docs.localhost:8080 next-app: localhost:3001 / next-app.localhost:8080 next-pages: localhost:3002 / next-pages.localhost:8080 react: localhost:3003 / react.localhost:8080 tanstack: localhost:3004 / tanstack.localhost:8080 gatsby: localhost:3005 / gatsby.localhost:8080 The proxy uses native Node.js http module with WebSocket support for HMR.
Apply consistent minimal styling across all example sites: - Narrower max-width (640px) for focused reading - Larger, bolder headlines with secondary text in gray - Red accent color (#E53935) for CTAs - Thin horizontal dividers between sections - Simplified header without sticky positioning - Cleaner footer with smaller text - Black/red button styling - Generous whitespace and spacing Updated files: - Shared layouts (ExampleLayout, ExampleLayoutSimple) - Gatsby Layout and Navbar - Next.js App/Pages Router CSS and pages - React (Vite) home page - TanStack Router home page
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.