Smoke-test the examples against a packed v7 tarball

The examples pin `"@tanem/react-nprogress": "latest"` and nothing in CI
touches them, so v7's packaging would first meet them the moment 7.0.0
publishes. Ran `npm run build && npm pack`, clean-installed the tarball into
all eight examples in place of the registry pin, and drove each progress bar
in a headless browser. Both Next examples were additionally checked under
`next build && next start`. Every example starts, advances and completes with
no console errors, and the CJS entry plus the `"use client"` directive hold
up on the Next server. The `"latest"` pins are restored: CodeSandbox resolves
the registry, not the tarball.

Three things needed fixing along the way.

The react-router example passed one `nodeRef`, held by `Home`, to every
CSSTransition, and it was never attached to a DOM node, since `<Routes>`
cannot take a ref. react-transition-group ends the transition on the next
tick when the ref does not resolve, so the fade classes never applied and
`onEntered` fired straight after `onEnter`: the bar completed 323ms after a
click instead of running for the 1200ms the example configures. A `Fade`
wrapper now owns a ref per `key` and renders the element it points at.
Reproduced against the published 6.0.4 too, so it predates v7.

Next rewrites `next-env.d.ts` on every run, with different contents for
`next dev` and `next build`, and in a format prettier rejects. It is now
gitignored and prettier-ignored in both Next examples, as create-next-app
has it.

`next build` also reconfigures `jsx` to `react-jsx`, which Next 16 requires,
so both example tsconfigs now carry that instead of `preserve`.

AGENTS.md records the tarball smoke-test procedure.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Author: tanem

.prettierignore

@@ -1,4 +1,5 @@
 README.md
 coverage
 dist
+next-env.d.ts
 package.json

AGENTS.md

@@ -126,6 +126,18 @@ needed but test on CodeSandbox before merging.
 Do not bump vite, @vitejs/plugin-react, next, or typescript in examples
 beyond the versions in the reference templates.
 
+Before a release that changes packaging, smoke-test the examples against the
+tarball rather than the registry: `npm run build && npm pack` at the repo
+root, point each example's `@tanem/react-nprogress` dependency at the tarball,
+clean-install so it wins over any stale `node_modules`, then run the example
+and drive its progress bar in a browser. The Next examples also need
+`next build && next start`, since they resolve the CJS entry on the server.
+Restore the `"latest"` pin afterwards: CodeSandbox resolves the registry.
+
+`next-env.d.ts` in the Next examples is generated, and `next dev` and
+`next build` write different contents into it, so it is gitignored and listed
+in `.prettierignore` rather than tracked.
+
 ## Writing Style
 
 - Avoid marketing or promotional language. State facts plainly.

examples/next-app-router/.gitignore

@@ -1,2 +1,3 @@
 .next/
 /node_modules
+next-env.d.ts

examples/next-app-router/next-env.d.ts

@@ -16,7 +16,7 @@
     "moduleResolution": "bundler",
     "resolveJsonModule": true,
     "isolatedModules": true,
-    "jsx": "preserve",
+    "jsx": "react-jsx",
     "incremental": true,
     "plugins": [
       {

examples/next-app-router/tsconfig.json

@@ -1,2 +1,3 @@
 .next/
-/node_modules
+/node_modules
+next-env.d.ts

examples/next-pages-router/.gitignore

@@ -16,7 +16,7 @@
     "moduleResolution": "bundler",
     "resolveJsonModule": true,
     "isolatedModules": true,
-    "jsx": "preserve",
+    "jsx": "react-jsx",
     "incremental": true
   },
   "include": [

examples/next-pages-router/next-env.d.ts

@@ -13,6 +13,7 @@ import {
   useParams,
 } from 'react-router-dom'
 import { CSSTransition, TransitionGroup } from 'react-transition-group'
+import type { CSSTransitionProps } from 'react-transition-group/CSSTransition'
 
 import Bar from './Bar'
 import Container from './Container'
@@ -122,10 +123,45 @@ const Progress: FC<{ isAnimating: boolean }> = ({ isAnimating }) => {
   )
 }
 
+// `nodeRef` has to resolve to a mounted DOM node, and `<Routes>` cannot take a
+// ref, so the transition owns a wrapper element to point at. It also has to be
+// a fresh ref per `key`, which is why this is a component rather than a ref
+// held by `Home`. With an unresolved ref, react-transition-group ends the
+// transition on the next tick: the fade classes never apply and `onEntered`
+// fires immediately, so the progress bar completes on click instead of over
+// `timeout`. TransitionGroup clones its children with the props it manages, so
+// everything else is forwarded through.
+const Fade: FC<
+  {
+    children: ReactNode
+    onEnter(): void
+    onEntered(): void
+  } & Pick<
+    CSSTransitionProps<HTMLDivElement>,
+    'appear' | 'enter' | 'exit' | 'in' | 'onExited'
+  >
+> = ({ children, onEnter, onEntered, ...managed }) => {
+  const nodeRef = useRef<HTMLDivElement>(null)
+
+  return (
+    <CSSTransition
+      {...managed}
+      classNames="fade"
+      nodeRef={nodeRef}
+      onEnter={onEnter}
+      onEntered={onEntered}
+      // Timeout has been increased by 4x from the original version for demo
+      // purposes.
+      timeout={1200}
+    >
+      <div ref={nodeRef}>{children}</div>
+    </CSSTransition>
+  )
+}
+
 const Home = () => {
   const [isLoading, setIsLoading] = useState(false)
   const location = useLocation()
-  const nodeRef = useRef(null)
 
   return (
     <>
@@ -144,29 +180,22 @@ const Home = () => {
         </ul>
         <div style={styles.content}>
           <TransitionGroup>
-            {/*
-            Timeout has been increased by 4x from the original version
-            for demo purposes.
-            */}
-            <CSSTransition
-              classNames="fade"
+            <Fade
               key={location.key}
-              nodeRef={nodeRef}
               onEnter={() => {
                 setIsLoading(true)
               }}
               onEntered={() => {
                 setIsLoading(false)
               }}
-              timeout={1200}
             >
               <Routes location={location}>
                 <Route element={<HSL home={true} />} path="/" />
                 <Route element={<HSL />} path="/hsl/:h/:s/:l" />
                 <Route element={<RGB />} path="/rgb/:r/:g/:b" />
                 <Route element={<div>Not Found</div>} path="*" />
               </Routes>
-            </CSSTransition>
+            </Fade>
           </TransitionGroup>
         </div>
       </div>