# ismamz/next-transition-router architecture

> Architecture diagram of the GitHub repository ismamz/next-transition-router, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-10-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ismamz/next-transition-router
- Repository: https://github.com/ismamz/next-transition-router

## Overview

##### Project Type and Purpose
- This is an open-source React/Next.js library (“next-transition-router”) designed to add animated page transitions to Next.js App Router applications.
- It provides a provider component (`TransitionRouter`), a custom `Link` component, and hooks (`useTransitionRouter`, `useTransitionState`) to integrate with any animation library (e.g., GSAP, Framer Motion).

##### File Structure Analysis
- Top-level
- package.json, pnpm-workspace.yaml, builds the library and example.
- /src – library source
– context.tsx: React Context for transition state
– index.ts: public exports
– link.tsx: custom `Link` component implementation
– router.tsx: `TransitionRouter` provider, event interception
– utils.ts: shared helper functions
- /example – demo Next.js App Router project showing usage
– app/layout.tsx, providers.tsx: injects the TransitionRouter
– app/page.tsx, demo pages, components, styles
– Tailwind, PostCSS, TS config for styling/demo
- Patterns
- React Context + Hooks for state management
- Client-side provider wrapping the entire app
- Optional auto-link detection vs explicit Link component
- Provider handles lifecycle: leave → page load → enter

##### README Insights
- Core API: `TransitionRouter` props `leave`, `enter`, optional `auto`
- Hooks: `useTransitionRouter` for programmatic navigation, `useTransitionState` for transition stage
- Integration points: next/app layout, any animation library callbacks, cleanup functions

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% Demo Application Layer
  subgraph "Demo Next.js App" 
    direction TB
    AppLayout["App Layout"]:::app
    Providers["Providers Wrapper"]:::app
    PageHome["Page: Home"]:::app
    PageDemo["Page: Demo"]:::app
    UIComponents["Demo UI Components"]:::app
    Styles["Styles & Config"]:::app
  end

  %% Library Layer
  subgraph "next-transition-router Library"
    direction TB
    Entry["Library Entry (src/index.ts)"]:::lib
    Provider["TransitionRouter Provider"]:::lib
    Context["React Context\n(transition state)"]:::lib
    LinkComp["Custom Link Component"]:::lib
    Utils["Utility Functions"]:::lib
    Hooks["Hooks\n(useTransitionRouter,\nuseTransitionState)"]:::lib
  end

  %% External Dependencies
  subgraph "External Animation Engine" 
    direction TB
    AnimLib["Animation Library\n(GSAP/Framer Motion)"]:::ext
  end

  Browser["Browser Navigation Events"]:::ext

  %% Relationships
  AppLayout --> Providers
  Providers --> Entry
  Entry --> Provider
  Provider --> Context
  Context --> Hooks
  Entry --> LinkComp
  Entry --> Utils
  LinkComp --> Provider
  Browser --> Provider
  Provider -->|"leave()"| AnimLib
  AnimLib -->|"onComplete"| Provider
  Provider -->|"Next.js Router"| PageHome
  Provider -->|"Next.js Router"| PageDemo
  PageHome -->|"enter()"| AnimLib
  PageDemo -->|"enter()"| AnimLib
  Hooks --> UIComponents
  UIComponents --> Provider

  %% Click Events
  click Provider "https://github.com/ismamz/next-transition-router/blob/main/src/router.tsx"
  click Context "https://github.com/ismamz/next-transition-router/blob/main/src/context.tsx"
  click LinkComp "https://github.com/ismamz/next-transition-router/blob/main/src/link.tsx"
  click Hooks "https://github.com/ismamz/next-transition-router/blob/main/src/index.ts"
  click Entry "https://github.com/ismamz/next-transition-router/blob/main/src/index.ts"
  click Utils "https://github.com/ismamz/next-transition-router/blob/main/src/utils.ts"
  click AppLayout "https://github.com/ismamz/next-transition-router/blob/main/example/app/layout.tsx"
  click Providers "https://github.com/ismamz/next-transition-router/blob/main/example/app/providers.tsx"
  click PageHome "https://github.com/ismamz/next-transition-router/blob/main/example/app/page.tsx"
  click PageDemo "https://github.com/ismamz/next-transition-router/blob/main/example/app/demo/page.tsx"
  click UIComponents "https://github.com/ismamz/next-transition-router/tree/main/example/components/"
  click Styles "https://github.com/ismamz/next-transition-router/blob/main/example/app/styles.css"

  %% Styles
  classDef lib fill:#f9f,stroke:#333,stroke-width:1px
  classDef app fill:#9f9,stroke:#333,stroke-width:1px
  classDef ext fill:#ff9,stroke:#333,stroke-width:1px
```
