Plan for migrating to unplugin to make the router-plugin compatible with other bundlers

[SeanCassiere]

Currently, the router plugin is only available for vite. This leaves people who use bundlers like webpack and rollup having to install the @tanstack/router-cli package and run it every time they start up their dev server. This is not the most optimal experience. Additionally, it also makes features like experimental.enableCodeSplitting only available to the vite users.

The intention here is to begin the migration to using unplugin so the router plugin can be made available for other bundlers like webpack, rspack, etc. in the future.

Currently, the router plugin packages are:

• @tanstack/router-generator
• @tanstack/router-cli
• @tanstack/router-vite-plugin

And by the end of this migration, it should be:

• @tanstack/router-generator
• @tanstack/router-cli
• @tanstack/router-plugin
• @tanstack/router-vite-plugin
• @tanstack/start-vite-plugin

For this task to be considered complete, the following milestones need to be achieved.

Note

Each of these major tasks (like 1, 2, ...), should go through in separate PRs to make reverts easier, whilst minor tasks (like 2.1, 2.2, ...) would be batched together under their respective majors.

Migration tasks

Preview Give feedback

1. 1. Copy the Start specific logic (currently that's the babel stuff appending "use server" to the createServerFn calls) into its own @tanstack/start-vite-plugin package. (feat(start-vite-plugin): copy the TanStack Start specific plugin logic into its own standalone vite plugin #1768)
2. 2. Remove the logic that's in the new @tanstack/start-vite-plugin package from the existing@tanstack/router-vite-plugin package. (refactor(router-vite-plugin): remove the start logic from @tanstack/router-vite-plugin and update @tanstack/start with the new imports #1771)
3. 3. Create the new @tanstack/router-plugin package. (refactor: setup the @tanstack/router-plugin package using "unplugin" #1778)
4. 3.1 Copy the existing router-vite-plugin logic (minus the Start stuff) into a new package named @tanstack/router-plugin that uses unplugin.
5. 3.2 Make sure the new @tanstack/router-plugin package exports the relevant vite plugins from @tanstack/router-plugin/vite.
6. 4. Refactor @tanstack/router-vite-plugin package to simply be a proxy, re-exporting from @tanstack/router-plugin/vite and the root. (refactor(router-vite-plugin): proxy for re-exporting from @tanstack/router-plugin/vite #1785)
7. 5. Update the documentation to show the vite plugin setup using @tanstack/router-plugin/vite. This'll be a non-breaking change for anyone using @tanstack/router-vite-plugin. (docs: update the documentation on the @tanstack/router-plugin package #1793)
8. 6. Setup the rspack export. (fix(router-plugin): add the rspack/rsbuild handler for file-based routing #1794)
9. 6.1 Setup @tanstack/router-plugin with a webpack export (@tanstack/router-plugin/rspack).
10. 6.2 Documentation for setting up TanStack Router using the rspack plugin.
11. 6.3 (optional) setup an example with TanStack Router using rspack.

For now, I've included rspack as the only bundler we're targeting to support next. The plugins for the other bundlers can be added in the future either through community contributions or when maintainers get more bandwidth 😅.

[SeanCassiere]

Tasks 1 and 2 are done (Start logic has been moved from the router-plugin into its own plugin). Had a minor setback where CI was broken because nx wasn't upgraded 😅 (#9412432), but otherwise all good 👍🏼.

• @tanstack/start-vite-plugin 🚀

Tomorrow I'll begin setting up "unplugin".

[SeanCassiere]

Tasks 3 and 4 are done.

• Now @tanstack/router-vite-plugin is just a proxy for @tanstack/router-plugin/vite

With just a preliminary search, I'm finding it difficult to find basic webpack react starter repos. I may just have to target rspack as the next bundler supported instead 🤔.

[SeanCassiere]

Tasks 5 and 6 are done.

The rspack/rsbuild plugin doesn't support the experimental code-splitting functionality yet due some limitations in using the resolveId and transform calls from unplugin to rspack.

Community contributions and anyone with knowledge on creating plugins for rspack would greatly be appreciated here.

[lachieh]

@ScriptedAlchemy might have some ideas about rspack.

[SeanCassiere]

@ScriptedAlchemy might have some ideas about rspack.

I'm happy to hear em ☺️! Shall we move this to a new issue? Or discord?

[honzahruby]

Hi, love your work, it’s great to unplugin being used here. Is there any plan for supporting webpack as well? Rspack is cool but wasn’t the main point of this issue to make this plugin widely available? Webpack still has 300x more users than rspack 👀

[SeanCassiere]

Hi, love your work, it’s great to unplugin being used here. Is there any plan for supporting webpack as well? Rspack is cool but wasn’t the main point of this issue to make this plugin widely available? Webpack still has 300x more users than rspack 👀

If you are able to make a contribution to this I'd be more than happy to help out with the PR 💪🏼.

If you are unable, a link to a decent starter bare-bones Webpack React starter with HMR would be appreciated 🙌🏼 (for testing, etc.)

Realistically, I could just add a webpack.ts file go YOLO and ship the plugin. But I don't want to just "trust" that the unplugin webpack output works, so I'm testing all the router-plugin features for each bundler by hand before ensuring they work.

[honzahruby]

@SeanCassiere I was able to put together a webpack quickstart example. Unfortunately, the plugin doesn't "just work"™️ for webpack. Please have a look at #1864 if you find some time.

When I change anything in the routes folder, it blows up 😕

[webpack-dev-middleware] TypeError [ERR_INVALID_ARG_TYPE]: The "path" argument must be of type string. Received undefined
    at new NodeError (node:internal/errors:405:5)
    at validateString (node:internal/validators:162:11)
    at isAbsolute (node:path:1156:5)
    at handleFile (file:///Users/honza/Sites/router/packages/router-plugin/dist/esm/router-generator.js:37:33)
    at file:///Users/honza/Sites/router/packages/router-plugin/dist/esm/router-generator.js:51:15
    at run (file:///Users/honza/Sites/router/packages/router-plugin/dist/esm/router-generator.js:44:13)
    at Object.watchChange (file:///Users/honza/Sites/router/packages/router-plugin/dist/esm/router-generator.js:50:13)
    at file:///Users/honza/Sites/router/node_modules/.pnpm/unplugin@1.10.2/node_modules/unplugin/dist/index.mjs:1862:80
    at Set.forEach (<anonymous>)
    at file:///Users/honza/Sites/router/node_modules/.pnpm/unplugin@1.10.2/node_modules/unplugin/dist/index.mjs:1861:41 {
  code: 'ERR_INVALID_ARG_TYPE'

[SeanCassiere]

@SeanCassiere I was able to put together a webpack quickstart example. Unfortunately, the plugin doesn't "just work"™️ for webpack. Please have a look at #1864 if you find some time.

When I change anything in the routes folder, it blows up 😕

[webpack-dev-middleware] TypeError [ERR_INVALID_ARG_TYPE]: The "path" argument must be of type string. Received undefined
    at new NodeError (node:internal/errors:405:5)
    at validateString (node:internal/validators:162:11)
    at isAbsolute (node:path:1156:5)
    at handleFile (file:///Users/honza/Sites/router/packages/router-plugin/dist/esm/router-generator.js:37:33)
    at file:///Users/honza/Sites/router/packages/router-plugin/dist/esm/router-generator.js:51:15
    at run (file:///Users/honza/Sites/router/packages/router-plugin/dist/esm/router-generator.js:44:13)
    at Object.watchChange (file:///Users/honza/Sites/router/packages/router-plugin/dist/esm/router-generator.js:50:13)
    at file:///Users/honza/Sites/router/node_modules/.pnpm/unplugin@1.10.2/node_modules/unplugin/dist/index.mjs:1862:80
    at Set.forEach (<anonymous>)
    at file:///Users/honza/Sites/router/node_modules/.pnpm/unplugin@1.10.2/node_modules/unplugin/dist/index.mjs:1861:41 {
  code: 'ERR_INVALID_ARG_TYPE'

Down with the flu ATM. Will look into this in a couple days.