├── .gitignore
├── README.md
├── components
    └── stack
    │   └── Stack.tsx
├── next.config.js
├── package-lock.json
├── package.json
├── pages
    ├── _app.tsx
    ├── about.module.css
    ├── about.tsx
    ├── api
    │   └── hello.ts
    ├── index.module.css
    └── index.tsx
├── public
    ├── favicon.ico
    └── vercel.svg
├── screen.gif
├── styles
    └── globals.css
└── tsconfig.json


/.gitignore:
--------------------------------------------------------------------------------
 1 | # See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
 2 | 
 3 | # dependencies
 4 | /node_modules
 5 | /.pnp
 6 | .pnp.js
 7 | 
 8 | # testing
 9 | /coverage
10 | 
11 | # next.js
12 | /.next/
13 | /out/
14 | 
15 | # production
16 | /build
17 | 
18 | # misc
19 | .DS_Store
20 | *.pem
21 | 
22 | # debug
23 | npm-debug.log*
24 | yarn-debug.log*
25 | yarn-error.log*
26 | .pnpm-debug.log*
27 | 
28 | # local env files
29 | .env*.local
30 | 
31 | # vercel
32 | .vercel
33 | 
34 | # typescript
35 | *.tsbuildinfo
36 | next-env.d.ts
37 | 
38 | .idea
39 | 


--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
  1 | # NextJS stack transitions
  2 | 
  3 | This repo is an example of [NextJS](https://nextjs.org/) route transitions via a [Stack component](./components/stack/Stack.tsx)
  4 | whose purpose is to render flexible "how" and "when" the playIn and playOut of each
  5 | page component is played.
  6 | 
  7 | The main goal is to have the same Stack logic existing on [@cher-ami/router](https://github.com/cher-ami/router)
  8 | but on nextJS file system routing. Secondary, to be able to handle route transitions
  9 | without a DOM bound animation library like React Spring. This example is
 10 | animated with GSAP, but could be with any other libs.
 11 | 
 12 | <br>
 13 | <img alt="screen" src="./screen.gif">
 14 | <br>
 15 | 
 16 | ## How it works
 17 | 
 18 | When the user update the browser history by clicking on "About" link, the Stack
 19 | will render two pages components:
 20 | 
 21 | ```
 22 | App
 23 |  |_ Stack
 24 |       |_ Home          (prev page playOut)
 25 |       |_ About         (current page playIn)
 26 | ```
 27 | 
 28 | When the transition is complete, prev page is unmount.
 29 | 
 30 | ```
 31 | App
 32 |  |_ Stack
 33 |       |_ About
 34 | ```
 35 | 
 36 | In order to do this, each page register for the parent Stack component a playIn and playOut
 37 | function + the DOM root element via `useImperativeHandle`. The Stack can thus be able to access
 38 | these properties.
 39 | 
 40 | ```jsx
 41 | const Home = forwardRef((props, handleRef) => {
 42 |   const $root = useRef(null)
 43 |   useImperativeHandle(handleRef, () => ({
 44 |     playIn: () =>
 45 |       gsap.timeline().fromTo(
 46 |         $root.current,
 47 |         { autoAlpha: 0 },
 48 |         { autoAlpha: 1 }
 49 |       ),
 50 |     playOut: () =>
 51 |       gsap.timeline().to($root.current, {
 52 |         autoAlpha: 0,
 53 |       }),
 54 |     $root: $root.current,
 55 |   }))
 56 | })
 57 | ```
 58 | 
 59 | Otherwise, the root App component will manage the transitions function added to Stack component by props.
 60 | We can now control the scenario with previous and current page components \o/
 61 | 
 62 | ```jsx
 63 | function App({ Component, pageProps }) {
 64 |   const custom = useCallback(
 65 |     ({ prev, current }) =>
 66 |       new Promise(async (resolve) => {
 67 |         // playOut prev page component
 68 |         if (prev) await prev.playOut?.()
 69 |         // when playOut is complete, playin new current page component
 70 |         await current.playIn?.()
 71 |         resolve()
 72 |       }),
 73 |     []
 74 |   )
 75 |   return (
 76 |     <div className={"App"}>
 77 |       <Stack Component={Component} customTransitions={custom} />
 78 |     </div>
 79 |   )
 80 | }
 81 | ```
 82 | 
 83 | ## Test it online
 84 | 
 85 | [nextjs-stack-transitions.vercel.app](https://nextjs-stack-transitions-dpbcjaqqi-willybrauner.vercel.app)
 86 | 
 87 | ## Install the example
 88 | 
 89 | Clone the repos and move to the cloned repository:
 90 | 
 91 | ```shell
 92 | git clone <this-repos> && cd nextjs-route-stack-transitions-example
 93 | ```
 94 | 
 95 | Install dependencies:
 96 | 
 97 | ```shell
 98 | npm i
 99 | # or
100 | yarn
101 | ```
102 | 
103 | Run the nextJS dev-server:
104 | 
105 | ```shell
106 | npm run dev
107 | ```
108 | 
109 | ## Credits
110 | 
111 | Willy Brauner
112 | 


--------------------------------------------------------------------------------
/components/stack/Stack.tsx:
--------------------------------------------------------------------------------
  1 | import React, { useRef, useReducer, useLayoutEffect, useEffect, memo } from "react"
  2 | import { NextComponentType, NextPageContext } from "next"
  3 | import { Router } from "next/router"
  4 | 
  5 | export interface IRouteStack {
  6 |   componentName?: string
  7 |   playIn?: () => Promise<any>
  8 |   playOut?: () => Promise<any>
  9 |   $root?: HTMLElement
 10 | }
 11 | 
 12 | export interface TCustomTransitionsParams {
 13 |   prev: IRouteStack
 14 |   current: IRouteStack
 15 |   unmountPrev: () => void
 16 | }
 17 | 
 18 | export interface IProps {
 19 |   Component: NextComponentType<NextPageContext>
 20 |   customTransitions: (T: TCustomTransitionsParams) => Promise<void>
 21 |   pageProps
 22 | }
 23 | 
 24 | const useIsomorphicLayoutEffect =
 25 |   typeof window !== "undefined" && window.document?.createElement ? useLayoutEffect : useEffect
 26 | 
 27 | /**
 28 |  * Stack component
 29 |  * @param props
 30 |  */
 31 | function Stack(props: IProps): JSX.Element {
 32 |   const $prevRef = useRef<IRouteStack>(null)
 33 |   const $currentRef = useRef<IRouteStack>(null)
 34 | 
 35 |   const componentReducer = (
 36 |     state: {
 37 |       prev?: NextComponentType<NextPageContext>
 38 |       prevPageProps?
 39 |       current?: NextComponentType<NextPageContext>
 40 |       pageProps?
 41 |       count: number
 42 |     },
 43 |     action: { type: "update" | "unmount-prev"; component?; pageProps? }
 44 |   ) => {
 45 |     switch (action.type) {
 46 |       case "update":
 47 |         return {
 48 |           ...state,
 49 |           prev: state.current,
 50 |           prevPageProps: state.pageProps,
 51 | 
 52 |           current: action.component,
 53 |           pageProps: action.pageProps,
 54 |           count: state.count + 1,
 55 |         }
 56 |       case "unmount-prev":
 57 |         return {
 58 |           ...state,
 59 |           prev: null,
 60 |           prevPageProps: null,
 61 |         }
 62 |       default:
 63 |         throw new Error()
 64 |     }
 65 |   }
 66 | 
 67 |   const [state, dispatch] = useReducer(componentReducer, {
 68 |     prev: null,
 69 |     prevPageProps: null,
 70 |     current: props.Component,
 71 |     pageProps: props.pageProps,
 72 |     count: 0,
 73 |   })
 74 | 
 75 |   // --------------------------------------------------------------------------- NEW COMPONENT
 76 | 
 77 |   // 1. each time stack get new Component as props
 78 |   // update global reducer state
 79 |   const firstRender = useRef(true)
 80 |   useIsomorphicLayoutEffect(() => {
 81 |     if (firstRender.current) {
 82 |       firstRender.current = false
 83 |       return
 84 |     }
 85 | 
 86 |     if (!props.Component) return
 87 |     dispatch({
 88 |       type: "update",
 89 |       component: props.Component,
 90 |       pageProps: props.pageProps,
 91 |     })
 92 |   }, [props.Component, props.pageProps])
 93 | 
 94 |   // --------------------------------------------------------------------------- PATCH
 95 | 
 96 |   /**
 97 |    * NextJS will remove module.css property from HTML document when route change
 98 |    * This hake allows to copy this CSS to avoid page style clip on page play-out transition
 99 |    * MAXI tricky but no choice. Farmer Motion got the same issue
100 |    * https://github.com/vercel/next.js/discussions/18724#discussioncomment-967618
101 |    *
102 |    */
103 |   const copies = useRef([])
104 |   const onLoad = (): void => {
105 |     resetStyleCopies()
106 |     // Create a clone of every <style> and <link> that currently affects the page. It doesn't matter
107 |     // if Next.js is going to remove them or not since we are going to remove the copies ourselves
108 |     // later on when the transition finishes.
109 |     const nodes = Array.from(
110 |       document.querySelectorAll("link[rel=stylesheet], style:not([media=x])")
111 |     )
112 |     copies.current = nodes.map((el) => el.cloneNode(true))
113 |     for (let copy of copies.current) {
114 |       // Remove Next.js' data attributes so the copies are not removed from the DOM in the route
115 |       // change process.
116 |       copy.removeAttribute("data-n-p")
117 |       copy.removeAttribute("data-n-href")
118 |       // Add duplicated nodes to the DOM.
119 |       document.head.appendChild(copy)
120 |     }
121 |   }
122 |   // Remove previous page's styles after the transition has finalized.
123 |   const resetStyleCopies = (): void => {
124 |     for (let copy of copies.current) {
125 |       document.head.removeChild(copy)
126 |     }
127 |     copies.current = []
128 |   }
129 | 
130 |   useIsomorphicLayoutEffect(() => {
131 |     Router.events.on("beforeHistoryChange", onLoad)
132 |     return () => {
133 |       Router.events.off("beforeHistoryChange", onLoad)
134 |     }
135 |   }, [])
136 | 
137 |   // --------------------------------------------------------------------------- ANIMATE
138 | 
139 |   // 2. animate when route state changed
140 |   useIsomorphicLayoutEffect(() => {
141 |     if (!state.current) {
142 |       console.log("No current route in state", state)
143 |       return
144 |     }
145 | 
146 |     const unmountPrev = () => {
147 |       dispatch({ type: "unmount-prev" })
148 |       resetStyleCopies()
149 |     }
150 | 
151 |     props
152 |       .customTransitions({
153 |         prev: $prevRef.current,
154 |         current: $currentRef.current,
155 |         unmountPrev,
156 |       })
157 |       // when internal promise is resolved
158 |       .then(unmountPrev)
159 |   }, [state.count, state.current, props.customTransitions])
160 | 
161 |   // --------------------------------------------------------------------------- RENDER
162 | 
163 |   // prettier-ignore
164 |   return (
165 |     <div className={"Stack"}>
166 |       {state.prev && (
167 |         <state.prev
168 |           {...(state.prevPageProps || {})}
169 |           ref={$prevRef}
170 |           key={state.count}
171 |         />
172 |       )}
173 |       {state.current && (
174 |         <state.current
175 |           {...(state.pageProps || {})}
176 |           ref={$currentRef}
177 |           key={state.count + 1}
178 |         />
179 |       )}
180 |     </div>
181 |   );
182 | }
183 | 
184 | export default memo(Stack)
185 | 


--------------------------------------------------------------------------------
/next.config.js:
--------------------------------------------------------------------------------
1 | /** @type {import('next').NextConfig} */
2 | const nextConfig = {
3 |   reactStrictMode: false,
4 |   swcMinify: true,
5 | }
6 | 
7 | module.exports = nextConfig
8 | 


--------------------------------------------------------------------------------
/package.json:
--------------------------------------------------------------------------------
 1 | {
 2 |   "name": "nextjs-stack-transitions",
 3 |   "version": "0.1.0",
 4 |   "scripts": {
 5 |     "dev": "next dev",
 6 |     "build": "next build && next export",
 7 |     "start": "next start",
 8 |     "deploy": "vercel --prod"
 9 |   },
10 |   "dependencies": {
11 |     "gsap": "^3.11.3",
12 |     "react": "18.2.0",
13 |     "react-dom": "18.2.0"
14 |   },
15 |   "devDependencies": {
16 |     "next": "^12.3.1",
17 |     "@types/node": "18.8.3",
18 |     "@types/react": "18.0.21",
19 |     "@types/react-dom": "18.0.6",
20 |     "prettier": "^2.7.1",
21 |     "typescript": "4.8.4",
22 |     "vercel": "^28.4.8"
23 |   },
24 |   "prettier": {
25 |     "semi": false,
26 |     "printWidth": 100
27 |   }
28 | }
29 | 


--------------------------------------------------------------------------------
/pages/_app.tsx:
--------------------------------------------------------------------------------
 1 | import "../styles/globals.css"
 2 | import type { AppProps } from "next/app"
 3 | import Link from "next/link"
 4 | import Stack, { TCustomTransitionsParams } from "../components/stack/Stack"
 5 | import { useCallback, useState } from "react"
 6 | 
 7 | export const TRANSITION_DURATION = 0.7
 8 | 
 9 | function App({ Component, pageProps }: AppProps): JSX.Element {
10 |   /**
11 |    * Select transition example type
12 |    */
13 |   const [transitionFn, setTransitionFn] = useState("crossed")
14 |   const handleSelectChange = (e) => {
15 |     const v = e.target.value
16 |     console.log(e.target.value)
17 |     setTransitionFn(v)
18 |   }
19 | 
20 |   /**
21 |    * Crossed transitions example
22 |    * - playOut & playIn together
23 |    */
24 |   const crossed = useCallback(
25 |     ({ prev, current }: TCustomTransitionsParams): Promise<void> =>
26 |       new Promise(async (resolve) => {
27 |         if (prev) prev.playOut?.()
28 |         await current.playIn?.()
29 |         resolve()
30 |       }),
31 |     []
32 |   )
33 | 
34 |   /**
35 |    * Sequential transitions example
36 |    * - playOut then, playIn
37 |    */
38 |   const sequential = useCallback(
39 |     ({ prev, current }: TCustomTransitionsParams): Promise<void> =>
40 |       new Promise(async (resolve) => {
41 |         if (prev) await prev.playOut?.()
42 |         await current.playIn?.()
43 |         resolve()
44 |       }),
45 |     []
46 |   )
47 | 
48 |   return (
49 |     <div className={"App"}>
50 |       <select onChange={handleSelectChange} defaultValue={"crossed"}>
51 |         <option>crossed</option>
52 |         <option>sequential</option>
53 |       </select>
54 |       <br />
55 |       <br />
56 |       <nav>
57 |         <Link href="/">Home</Link>
58 |         <br />
59 |         <Link href="/about">About</Link>
60 |       </nav>
61 |       <Stack
62 |         pageProps={pageProps}
63 |         Component={Component}
64 |         customTransitions={transitionFn === "crossed" ? crossed : sequential}
65 |       />
66 |     </div>
67 |   )
68 | }
69 | 
70 | export default App
71 | 


--------------------------------------------------------------------------------
/pages/about.module.css:
--------------------------------------------------------------------------------
1 | .root {
2 |   color: green;
3 | }
4 | 


--------------------------------------------------------------------------------
/pages/about.tsx:
--------------------------------------------------------------------------------
 1 | import css from "./about.module.css"
 2 | import { gsap } from "gsap"
 3 | import { forwardRef, useRef, useImperativeHandle } from "react"
 4 | import { TRANSITION_DURATION } from "./_app"
 5 | 
 6 | function About(props, handleRef): JSX.Element {
 7 |   const $root = useRef<HTMLDivElement>(null)
 8 | 
 9 |   const playIn = () =>
10 |     gsap
11 |       .timeline({ defaults: { duration: TRANSITION_DURATION, ease: "power3.out" } })
12 |       .fromTo($root.current, { autoAlpha: 0, x: -50 }, { autoAlpha: 1, x: 0 })
13 | 
14 |   const playOut = () =>
15 |     gsap
16 |       .timeline({ defaults: { duration: TRANSITION_DURATION, ease: "power3.out" } })
17 |       .to($root.current, { autoAlpha: 0, x: 50 })
18 | 
19 |   useImperativeHandle(handleRef, () => ({
20 |     playIn,
21 |     playOut,
22 |     $root: $root.current,
23 |   }))
24 | 
25 |   return (
26 |     <div ref={$root} className={css.root}>
27 |       <h1>About</h1>
28 |     </div>
29 |   )
30 | }
31 | 
32 | About.displayName = "About"
33 | export default forwardRef<HTMLDivElement>(About)
34 | 


--------------------------------------------------------------------------------
/pages/api/hello.ts:
--------------------------------------------------------------------------------
 1 | // Next.js API route support: https://nextjs.org/docs/api-routes/introduction
 2 | import type { NextApiRequest, NextApiResponse } from "next"
 3 | 
 4 | type Data = {
 5 |   name: string
 6 | }
 7 | 
 8 | export default function handler(
 9 |   req: NextApiRequest,
10 |   res: NextApiResponse<Data>
11 | ) {
12 |   res.status(200).json({ name: "John Doe" })
13 | }
14 | 


--------------------------------------------------------------------------------
/pages/index.module.css:
--------------------------------------------------------------------------------
1 | .root {
2 |   color: red;
3 | }
4 | 


--------------------------------------------------------------------------------
/pages/index.tsx:
--------------------------------------------------------------------------------
 1 | import css from "./index.module.css"
 2 | import { gsap } from "gsap"
 3 | import { forwardRef, useRef, useImperativeHandle } from "react"
 4 | import { TRANSITION_DURATION } from "./_app"
 5 | 
 6 | function Home(props, handleRef): JSX.Element {
 7 |   const $root = useRef<HTMLDivElement>(null)
 8 | 
 9 |   const playIn = () =>
10 |     gsap
11 |       .timeline({ defaults: { duration: TRANSITION_DURATION, ease: "power3.out" } })
12 |       .fromTo($root.current, { autoAlpha: 0, x: -50 }, { autoAlpha: 1, x: 0 })
13 | 
14 |   const playOut = () =>
15 |     gsap
16 |       .timeline({ defaults: { duration: TRANSITION_DURATION, ease: "power3.out" } })
17 |       .to($root.current, { autoAlpha: 0, x: 50 })
18 | 
19 |   useImperativeHandle(handleRef, () => ({
20 |     playIn,
21 |     playOut,
22 |     $root: $root.current,
23 |   }))
24 | 
25 |   return (
26 |     <div ref={$root} className={css.root}>
27 |       <h1>Home</h1>
28 |     </div>
29 |   )
30 | }
31 | 
32 | Home.displayName = "Home"
33 | export default forwardRef<HTMLDivElement>(Home)
34 | 


--------------------------------------------------------------------------------
/public/favicon.ico:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/willybrauner/nextjs-stack-transitions/f3106c40e9ffed67d6027a8172d6ae5c32aff0c7/public/favicon.ico


--------------------------------------------------------------------------------
/public/vercel.svg:
--------------------------------------------------------------------------------
1 | <svg width="283" height="64" viewBox="0 0 283 64" fill="none" 
2 |     xmlns="http://www.w3.org/2000/svg">
3 |     <path d="M141.04 16c-11.04 0-19 7.2-19 18s8.96 18 20 18c6.67 0 12.55-2.64 16.19-7.09l-7.65-4.42c-2.02 2.21-5.09 3.5-8.54 3.5-4.79 0-8.86-2.5-10.37-6.5h28.02c.22-1.12.35-2.28.35-3.5 0-10.79-7.96-17.99-19-17.99zm-9.46 14.5c1.25-3.99 4.67-6.5 9.45-6.5 4.79 0 8.21 2.51 9.45 6.5h-18.9zM248.72 16c-11.04 0-19 7.2-19 18s8.96 18 20 18c6.67 0 12.55-2.64 16.19-7.09l-7.65-4.42c-2.02 2.21-5.09 3.5-8.54 3.5-4.79 0-8.86-2.5-10.37-6.5h28.02c.22-1.12.35-2.28.35-3.5 0-10.79-7.96-17.99-19-17.99zm-9.45 14.5c1.25-3.99 4.67-6.5 9.45-6.5 4.79 0 8.21 2.51 9.45 6.5h-18.9zM200.24 34c0 6 3.92 10 10 10 4.12 0 7.21-1.87 8.8-4.92l7.68 4.43c-3.18 5.3-9.14 8.49-16.48 8.49-11.05 0-19-7.2-19-18s7.96-18 19-18c7.34 0 13.29 3.19 16.48 8.49l-7.68 4.43c-1.59-3.05-4.68-4.92-8.8-4.92-6.07 0-10 4-10 10zm82.48-29v46h-9V5h9zM36.95 0L73.9 64H0L36.95 0zm92.38 5l-27.71 48L73.91 5H84.3l17.32 30 17.32-30h10.39zm58.91 12v9.69c-1-.29-2.06-.49-3.2-.49-5.81 0-10 4-10 10V51h-9V17h9v9.2c0-5.08 5.91-9.2 13.2-9.2z" fill="#000"/>
4 | </svg>


--------------------------------------------------------------------------------
/screen.gif:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/willybrauner/nextjs-stack-transitions/f3106c40e9ffed67d6027a8172d6ae5c32aff0c7/screen.gif


--------------------------------------------------------------------------------
/styles/globals.css:
--------------------------------------------------------------------------------
 1 | * {
 2 |   box-sizing: border-box;
 3 | }
 4 | html,
 5 | body {
 6 |   padding: 0;
 7 |   margin: 0;
 8 |   font-family: sans-serif;
 9 |   color-scheme: dark;
10 |   font-size: 25px;
11 | }
12 | 
13 | .App {
14 |   padding: 2rem;
15 | }
16 | 
17 | .Stack {
18 |   position: relative;
19 | }
20 | 
21 | .Stack > * {
22 |   top: 0;
23 |   visibility: hidden;
24 |   position: absolute;
25 | }
26 | 
27 | a:hover {
28 |   color: indianred;
29 |   cursor: pointer;
30 | }
31 | 
32 | select {
33 |   border: none;
34 |   cursor: pointer;
35 |   background: none;
36 |   font-size: 18px;
37 |   outline: none;
38 | }
39 | 


--------------------------------------------------------------------------------
/tsconfig.json:
--------------------------------------------------------------------------------
 1 | {
 2 |   "compilerOptions": {
 3 |     "target": "esNext",
 4 |     "lib": ["dom", "dom.iterable", "esnext"],
 5 |     "allowJs": true,
 6 |     "skipLibCheck": true,
 7 |     "strict": false,
 8 |     "forceConsistentCasingInFileNames": true,
 9 |     "noEmit": true,
10 |     "esModuleInterop": true,
11 |     "module": "esnext",
12 |     "moduleResolution": "node",
13 |     "resolveJsonModule": true,
14 |     "isolatedModules": true,
15 |     "jsx": "preserve",
16 |     "incremental": true
17 |   },
18 |   "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx"],
19 |   "exclude": ["node_modules"]
20 | }
21 | 


--------------------------------------------------------------------------------