Monorepo example

[tl-frameplay]

Hey guys, we appreciate you sharing this great library.

So far, everything is amazing, but we are having issues strongly type using a monorepo. Before we say which monorepo to avoid promoting one over the other; do you have any examples how tanstack router is meant to work for Typescript in a monorepo?

Specifically, we have a monorepo package called "router", where tanstack router is installed, and the actual "router" file in an app of the monorepo where all the routes are configured and the router exported for the app.

Thank you kindly.

[rahulretnan]

With Nx Workspace, I updated the Vite Config as follows:

/// <reference types='vitest' />
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import { nxViteTsPaths } from '@nx/vite/plugins/nx-tsconfig-paths.plugin';
import { TanStackRouterVite } from '@tanstack/router-vite-plugin';
import { join } from 'path';

export default defineConfig({
  root: __dirname,
  cacheDir: '../../node_modules/.vite/apps/web',

  server: {
    port: 4200,
    host: 'localhost',
  },

  preview: {
    port: 4300,
    host: 'localhost',
  },

  plugins: [
    react(),
    TanStackRouterVite({
      routesDirectory: join(__dirname, 'src/routes'),
      generatedRouteTree: join(__dirname, 'src/routeTree.gen.ts'),
      routeFileIgnorePrefix: '-',
      quoteStyle: 'single',
    }),
    nxViteTsPaths(),
  ],

  // Uncomment this if you are using workers.
  // worker: {
  //  plugins: [ nxViteTsPaths() ],
  // },

  build: {
    outDir: '../../dist/apps/web',
    reportCompressedSize: true,
    commonjsOptions: {
      transformMixedEsModules: true,
    },
  },

  test: {
    globals: true,
    cache: {
      dir: '../../node_modules/.vitest',
    },
    environment: 'jsdom',
    include: ['src/**/*.{test,spec}.{js,mjs,cjs,ts,mts,cts,jsx,tsx}'],

    reporters: ['default'],
    coverage: {
      reportsDirectory: '../../coverage/apps/web',
      provider: 'v8',
    },
  },
});

[DNYLA]

I've set this up but was wondering how would i allow other libraries to share the types for my router so when using navigate() or Link i have full type saftey.

[bzbetty]

@rahulretnan do you find the watch still works? as soon as I add in a root: __dirname it regens fine on startup but seems to fail on changes.

[sohamnandi77]

Hi @tl-frameplay @rahulretnan , can you please help me in figuring out how routing will work in Microfrontend architecture.. I am using turborepo and tanstack Router
I am just now sure, routing which are defined in packages will work in apps

[mer10z]

I'm also using turborepo and trying to figure out how to do this. Currently we have a number of packages that are router agnostic and one app package that declares the router module. Now I'm trying to split up that app into multiple packages that all use the same router with type checking, but I'm not sure how to do it without creating a circular dependency between the packages. I've tried a few hacky things that didn't work and will continue trying, but if anyone has a solution to this it would be great to hear. We're not using file based routing so TanStackRouterVite isn't an option.

[davidturissini]

I'm starting to tackle this exact problem in our app. We are also using a monorepo setup. We have a top level "app" package that imports lots of other packages that are more focused on components, specific business logic, etc. We want the lower level library packages to be able to participate in Tanstack router's type safety. The problem is that we've defined all of the routes on the "app" level and the children packages cannot take a dependency on "app" because, well, circular dependencies and all the fun that comes with that.

But since we only care about making the types available to all children packages, I'm exploring adding a small typescript task that just outputs the route's d.ts file into a lower level package that can be consumed by everyone. This seems to solve the circular dependency problem. This new "router" package does not contain any source code references back to the app. It's basically as if a developer manually copied the d.ts file and exported it.

Still working out how this plays out long term but its very promising so far.

[sohamnandi77]

I guess, @tannerlinsley finally heard us.😅 He is including a example of tanstack router in monorepo. Thanks, Really, appreciate the Effort. ✨

Basic:
https://github.com/tanstack/router/tree/main/examples/react/router-monorepo-simple

With React Query:

https://github.com/TanStack/router/tree/main/examples/react/router-monorepo-react-query

[schiller-manuel]

actually this was added by @beaussan :)

[nktnet1]

I gave it a go and made a turborepo template with tanstack router at the core:

• https://github.com/nktnet1/rt-stack

It's not a small example, with many other components such as

• tailwind/shadcn
• trpc
• hono
• drizzle-orm
• better-auth

and so on, but hopefully someone finds it helpful :).

[HipsterZipster]

this is awesome. nice job man!

[taylorfsteele]

I'm going to hijack this discussion post to try to explain my main difficulty with the current recommendation of how Router supports monorepos, and what I think some potential solutions are. It all revolves around cyclical dependencies (get it?). What do I mean?

Lets say I have the monorepo setup that's currently in the docs:

.
└── packages/
    ├── app
    ├── package-1
    ├── package-2
    └── router

The main thing to note here is that router is where our routes folder, routeTree.gen.ts file, and router instance are defined. For the sake of this example, lets only worry about file based routing. app is really just an empty shell that consumes the routes. This setup looks great because now the exported functions from router can now be consumed by the other packages to get that sweet, sweet, type inference. In theory too, if we had multiple apps / multiple routers, we'd be able to know which app/router is which because they export their own instance. Cool, looks good.

Now lets imagine that in router I have a route with some search params with some validation:

import { createFileRoute } from "@tanstack/react-router";
import * as v from "valibot";

const searchSchema = v.object({
  redirect: v.optional(v.string()),
});

export const Route = createFileRoute("/hello")({
  component: HelloPage,
  validateSearch: searchSchema,
});

function SignInPage() {
  const { redirect } = Route.useSearch();

  return <>Hello</>;
}

Now lets add a component from package-1 to the route:

import { Redirect } from "@acme/package-1"
import { createFileRoute } from "@tanstack/react-router";
import * as v from "valibot";

const searchSchema = v.object({
  redirect: v.optional(v.string()),
});

export const Route = createFileRoute("/hello")({
  component: HelloPage,
  validateSearch: searchSchema,
});

function SignInPage() {
  const { redirect } = Route.useSearch();

  return (
    <>
      <Redirect />
    </>
  );
}

Lets say that this this component is the actual thing that cares about our search param. These typed & validated search params are a really powerful feature of Router. Personally, I really like the idea of having component that require / consume these params be responsible for getting them, similar to other ideas of having components that consume specific data be responsible for getting that data. Router thought of that too, and it's great that you can access to these typed & validated values even outside of route components via the Route object or the getRouteApi function.

Except wait a second, how does package-1 access those types or objects? Well it would need to install our router package as a workspace dependency, consume those typed APIs, and then export our component again to be consumed by router:

import { getRouteApi } from "@acme/router";

const routeApi = getRouteApi('/hello');

export const Redirect = () => {
  const routeSearch = routeApi.useSearch();

  return <>Do something with redirect {routeSearch.redirect}</>;
}

But now we've created a cyclical dependency:

router -> package-1 -> router -> app

Big no-no in monorepos, most tools will yell at you if you have cyclical dependencies, if not outright refuse to run.

So how to solve this? Well there's a few ideas I can think of:

1). Router concerns are router concerns.

Leave the router stuff to the router and have packages expect that data via props / another data contract:

function SignInPage() {
  const { redirect } = Route.useSearch();

  return (
    <>
      <Redirect redirect={redirect} />
    </>
  );
}

I'm totally cool with this being the answer. It's not what I want, but it makes sense. Now our graph has the correct direction again: package-1 -> router -> app. But we lose that composability that can be really powerful with component based design. I can't have the component that actually cares about & uses the data be responsible for getting it .

2). Loosen types

Loosen up our types as outlined in the docs:

const search = useSearch({
    strict: false,
  })

I'm down to loosen these types, and type them inside our package instead. But we're better than that, right? Ok cool, moving on.

3). Create a new sink for the Route APIs in our graph

Go onto any of these GitHub issues where people complain about cyclical dependencies and the first answer is to create a new package or combine existing packages. We're not gonna combine package-1 and router, the whole point of the monorepo is to split them up, so lets focus on the former. Our graph would become something like

package-that-has-router-apis -> package-1 && router -> app

But Router doesn't really support this at the moment. When I generate my types for the router, they're kind of stuck inside that router package. Maybe this is the reasoning behind the idea of "Move all generated code out of the src and app directories. Preferably a .tanstack directory." in the V2 ideas. This opens up a can of worms if you have multiple router instances in the same repo, so I can see why this might be tricky. You might have to have separate sink packages for each router, idk.

4). Import the package in the app only

This is how the current monorepo example is set up. In this paradigm, package-1 would export the page, not found, and error components for that route, then we set those components on that route in app. This is the real answer, right? I'm not convinced. To me--and this is just pure personal preference--the app is the router, and the router is the app. I don't really like the idea of splitting up my page from my router, I think the DX of having my router far away from the page / layout / outlet that's rendered is kind of backwards.

With file based routing, I really like how we can look at our files in our routes folder and understand the structure of the app at a glance. I think by spreading them out like this we've taken the idea of the monorepo too far. I want my router to be responsible for pages and routing, not just routing. Maybe this means that we do need to go back to the single responsibility pattern outlined in solution 1, I'm not sure. All of this is to say that something about splitting my pages from my router feels off to me. I'm open to being wrong on this, but I feel like I'm losing a key advantage of what I like about file based routing.

5). Cheat

This is kind of what @davidturissini mentioned in their reply above, which is to just grab the types via a script or task and make them available at a lower package in the graph. I'd go even further honestly, I'd be fine with putting something like that at the root of the repo, something like a routerGen.d.ts at the root of the repo that only overwrites types. A package is probably better, but the point is to get these types available somewhere lower in the graph / ambiently available in the repo. This has the same issue as above for if there are multiple routers in the same repo, but probably alleviated by good package management.

My preferred solution
I would love for Router to be able to generate these types for me, but not necessarily tie them to my router or app package. The type generation & type safety is probably my favorite feature of Router, but it's difficult to leverage them in a monorepo. I would love to be able to tell Router "Generate X files in Y directories, I'll handle hooking everything up so they're imported and used correctly.". If there's a way to do that now, I haven't really been able to get it to work correctly by changing the generatedRouteTree path option.

Someone tell me if I'm missing something or doing something wrong, because I've found it difficult to get my sweet, sweet type safety with Router in a monorepo. Idk, let me know what you think or if I'm over complicating this.

[schiller-manuel]

cc @beaussan