docs: Migrate to tanstack router by MichaelParadis · Pull Request #2895 · GetJobber/atlantis

MichaelParadis · 2026-02-02T15:59:18Z

Motivations

There are some improvements we want to make to the doc site such as linking directly to tabs and using hashes to link directly to headings. While react-router-dom supports this type of stuff we are currently using a super old version (react router dom v5 which was last updated 2 years ago). Since it was such an old version finding resources for this version would be difficult.

In theory I could have updated react-router-dom on the docs site, however I decided to migrate to tanstack router for the following reasons:

There was a ticket to migrate to tanstack router https://jobber.atlassian.net/browse/JOB-111826
TSR is the library we use in other repos

Future work

Adding support for copying and going to headings in other tabs (for example the implement tab)

Changes

Migration from react-router-dom to tanstack router. Mostly handled by cursor.
Use tanstack router path params for the following:
1. Tab to display (web, mobile and implement)
2. Component name for the docs
Used tanstack router search params for
1. Determining if the legacy or v2 versions of components should be shown
2. Determining if the minimal version of the site should be used
Added mdx plugins for generating the table of contents for the design tab
Added support for copying the link to h2s on the design tab
Unified checks related to the url to leverage tanstack router instead of mixing between react router dom and vanilla JS
Simplified how routes are generated

Added

Added ability to link to the tabs on a component
Added ability to link to h2 on a docs page

Changed

Deprecated

Removed

Fixed

Security

Testing

Verify that you can copy links to components and the respective tabs in them.
Verify that you can link between the legacy and supported versions of components
Verify that you can copy links to h2s on the design tab of components
Verify that the side navigation will navigate you between tabs and to the headings when viewing a component. For example while on the Button component in the implement tab when you click "variants" it takes you to the design tab and scrolls to that heading

Changes can be
tested via Pre-release

In Atlantis we use Github's built in pull request reviews.

Runs but still a lot to fix / improve

…ng root routes

…ermining which iframe to use. Update the tabs to reset when the component changes

cloudflare-workers-and-pages · 2026-02-02T16:07:16Z

Deploying atlantis with Cloudflare Pages

Latest commit:	`2a8795f`
Status:	✅ Deploy successful!
Preview URL:	https://f5f05ebd.atlantis.pages.dev
Branch Preview URL:	https://mike-migrate-to-tanstack-rou.atlantis.pages.dev

View logs

MichaelParadis · 2026-02-03T18:35:22Z


  useEffect(() => {
    if (code) {
+      console.log("updating code");


Remove this

… a mdx file for the sidebar navigation

…ate-to-tanstack-router

scotttjob

Smoke tested locally. Can't find any major issues.

This is overall a low-risk PR because it shouldn't affect the build output of the product. Michael if you can run a diff output and confirm the build is identical, then I saw we just ship it (I'll come back and approve).

Overall there's some chunky code in places, just in terms of length, but we're doing a fair amount of complex functionality in here. We can continue to iterate once react-router is out properly.

scotttjob · 2026-03-12T15:12:17Z

+  label: string;
+}
+
+export type RecmaVFile = VFile & {


What is a Recma?

It is a JS processor for markdown files for writing plugins with mdx files
https://github.com/mdx-js/recma

scotttjob · 2026-03-12T15:17:17Z

 import { Box, Content, Typography } from "@jobber/components";
-import { MouseEvent, useEffect, useState } from "react";
+import { Link, useMatches, useParams } from "@tanstack/react-router";
+import omit from "lodash/omit";


I have a polite, module bundler friendly related request. Is there any way we can avoid lodash usage moving forward?

Nuked in a23f7b6

scotttjob · 2026-03-12T15:58:03Z

+ * Recma plugin: injects `export const toc = [...]` from file.data.toc so the
+ * compiled MDX module exports a TOC for the sidebar.
+ */
+export function recmaInjectToc() {


I'd love some more detailed JS Doc comments in here explaining what some of this code is up, and why. May help future us/LLMs.

Added a few more comments in 190e05c I totally lost my initial references for this

scotttjob · 2026-03-12T15:59:34Z

-      }, 100);
-    }
-  };
+  const newParams = omit(params, "tab");


Just so I'm not all "no way lodash" without any support as how to work without lodash omit, In this case, I know it's a little clunky but it doesn't require any libraries:

const newParams = { ...params };
delete newParams.tab;

The other solution {tab:_tab, ...newParams} = params doesn't work for us because we lint away unused variables, so the delete is the backup.

I can nuke lodash. I tried doing the import of lodash to help with tree shaking but I can nuke it. I used import omit from "lodash/omit" instead of the heavier import { omit } from "lodash"

scotttjob · 2026-03-12T16:10:33Z

 * This isn't really a Layout component, but it's not really a component component either. We could make a "Views" directory maybe, or a "Template" directory?
 * @returns ReactNode
 */
-// eslint-disable-next-line max-statements


:that-thing-you-do-with-your-fingers-that-sounds-like-a-snap-rainbow:

scotttjob · 2026-03-12T16:11:02Z

    [PageMeta, currentPlatform],
  );

-  // Set initial type based on what's available for this component


:that-thing-you-do-with-your-fingers-that-sounds-like-a-snap-rainbow:

scotttjob · 2026-03-12T16:11:36Z

    }
  }, [code, type, updateCode]);

-  const handleTabChange = (tabIn: number) => {


:that-thing-you-do-with-your-fingers-that-sounds-like-a-snap-rainbow:

scotttjob · 2026-03-12T16:19:01Z

-import UseResizeObserverDocs from "../content/hooks/useResizeObserver.stories.mdx";
-import UseStepperDocs from "../content/hooks/useStepper.stories.mdx";
-import UseWindowDimensionsDocs from "../content/hooks/useWindowDimensions.stories.mdx";
+import UseBoolDocs, {


All this extra boilerplate...I really want to find a better solve for this long-term. It's not the worst, but it's not great either.

Yeah, I do want to remove the boiler plate on this. I was original going to migrate to file based routing in TSR but that made things chunky and I figured getting to TSR was a good first step

scotttjob · 2026-03-12T16:22:26Z

  {
    path: "/guides",
    handle: "Guides",
-    exact: true,


scotttjob · 2026-03-12T16:23:03Z

    "react-element-to-jsx-string": "^15.0.0",
    "react-markdown": "^10.1.0",
-    "react-native-svg-web": "^1.0.9",
-    "react-router": "5.3.4",


MichaelParadis · 2026-03-12T16:49:37Z

@scotttjob I just pushed a fix in 2a8795f which solves a problem I just found where if you clicked on a mobile usage or props link on the sidebar it wouldn't actually go to the mobile tab and would instead stay on web (or whatever platform you were currently on)

taylorvnoj · 2026-03-12T17:59:11Z

I am QA-ing 👀

taylorvnoj

big improvement! sooo excited about the linking! All the QA items you listed work as described.

I see Scott reviewed also and dug deeper into the code than I did. I'm approving but want to make sure Scott is 👍🏻 also!

MichaelParadis added 4 commits January 30, 2026 14:05

Initial cursor migration of react-router-dom to tanstack router.

b33e427

Runs but still a lot to fix / improve

Move providers around to follow the tanstack router method of renderi…

8461b77

…ng root routes

Refactor useAtlantisPreviewViewer to leverage tanstack router for det…

9e70aef

…ermining which iframe to use. Update the tabs to reset when the component changes

Update to support legacy navigation

1d16871

MichaelParadis added 3 commits February 2, 2026 10:09

Fix typescript errors

810cd09

Temp fix for typescript and tanstack router links

1fb9a2f

Fixed incorrect datepicker visual test page

6d8bb77

MichaelParadis commented Feb 3, 2026

View reviewed changes

MichaelParadis added 21 commits February 11, 2026 09:50

Added remark and remca plugins for getting the table of contents from…

7d70640

… a mdx file for the sidebar navigation

Updated component docs view to use the new generated table of contents

29379a4

Added table of contents for the side nav on all components

37321e9

Merge branch 'master' of github.com:GetJobber/atlantis into MIKE/migr…

4e4b7eb

…ate-to-tanstack-router

Merge branch 'master' of github.com:GetJobber/atlantis into MIKE/migr…

6f3a8b0

…ate-to-tanstack-router

Added initial linkable headings to the design tab

a4a5b2d

Fix broken dependency

55fdb50

Fix anchor links on other pages

41da6e3

Add table of contents to other exported content

fb3d079

Fix url to copy on linkable heading

3f7195c

Merge branch 'master' of github.com:GetJobber/atlantis into MIKE/migr…

aabdfae

…ate-to-tanstack-router

Use tsr for managing stuff in the location object

ad5c4ef

Unify logic for getting the component type and tab on based on the url

1994c85

Improve linkable heading behaviour

2c1ed0c

Improve code based routing

2125c29

Delete unneeded file

9563679

Fix handling of 404s to render the navigation skeleton

e435009

Fix bad setstate when rendering

ed7c307

Updated snippets and generators

16435a5

Merge branch 'master' of github.com:GetJobber/atlantis into MIKE/migr…

171bf17

…ate-to-tanstack-router

Fixed unneeded eslint disable

749fe40

MichaelParadis marked this pull request as ready for review March 11, 2026 16:17

MichaelParadis requested a review from a team as a code owner March 11, 2026 16:17

jobbiebot Bot added review requested Team UX Foundations labels Mar 11, 2026

MichaelParadis requested review from scotttjob and taylorvnoj March 11, 2026 16:17

MichaelParadis added 3 commits March 12, 2026 06:51

Merge branch 'master' of github.com:GetJobber/atlantis into MIKE/migr…

8de29c3

…ate-to-tanstack-router

Fix various merge conflict issues

eb88be5

Fix incorrect nav menu link

c79587b

scotttjob reviewed Mar 12, 2026

View reviewed changes

MichaelParadis added 3 commits March 12, 2026 09:39

Added some comments to mdx-extract-toc

190e05c

No longer use lodash omit

a23f7b6

Fixed usage and props not going to the mobile tab if it should

2a8795f

taylorvnoj approved these changes Mar 12, 2026

View reviewed changes

jobbiebot Bot added approved and removed review requested labels Mar 12, 2026

MichaelParadis merged commit 278eec4 into master Mar 12, 2026
14 of 15 checks passed

MichaelParadis deleted the MIKE/migrate-to-tanstack-router branch March 12, 2026 19:23

Conversation

MichaelParadis commented Feb 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Motivations

Future work

Changes

Added

Changed

Deprecated

Removed

Fixed

Security

Testing

Uh oh!

cloudflare-workers-and-pages Bot commented Feb 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Deploying atlantis with Cloudflare Pages

Uh oh!

Choose a reason for hiding this comment

Uh oh!

scotttjob left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

MichaelParadis commented Mar 12, 2026

Uh oh!

taylorvnoj commented Mar 12, 2026

Uh oh!

taylorvnoj left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

MichaelParadis commented Feb 2, 2026 •

edited

Loading

cloudflare-workers-and-pages Bot commented Feb 2, 2026 •

edited

Loading