feat(runtime): extract tanstack router into plugin package

Author: BleedingDev

.changeset/create-runtime-tanstack-tailwind.md

@@ -0,0 +1,17 @@
+---
+'@modern-js/create': minor
+'@modern-js/runtime': minor
+'@modern-js/plugin-tanstack': minor
+---
+
+feat(create): support `--router tanstack` and `--tailwind` scaffolding
+
+- add router selection for React Router / TanStack Router in `@modern-js/create`
+- add Tailwind CSS v4 scaffold option (`--tailwind`) with `postcss.config.mjs` and `tailwind.config.ts`
+- for TanStack scaffolds, register `tanstackRouterPlugin()` and use `src/views` as the convention directory
+
+feat(runtime): move TanStack Router integration to `@modern-js/plugin-tanstack`
+
+- add `@modern-js/plugin-tanstack` runtime/cli package surface
+- remove `@modern-js/runtime/tanstack-router` export from `@modern-js/runtime`
+- migrate TanStack route generation/runtime ownership from core runtime to the standalone plugin

packages/document/docs/en/apis/app/runtime/router/router.mdx

@@ -8,6 +8,9 @@ sidebar_position: 1
 :::info
 The router solution based on [react-router v7](https://reactrouter.com/).
 
+This page documents the React Router runtime export (`@modern-js/runtime/router`).  
+If your app uses TanStack Router (`--router tanstack`), use `@modern-js/plugin-tanstack/runtime` and refer to TanStack Router API docs.
+
 :::
 
 ## hooks

packages/document/docs/en/components/init-app.mdx

@@ -58,3 +58,10 @@ Now, the project structure is as follows:
 │       └── page.tsx
 └── tsconfig.json
 ```
+
+When `--tailwind` is enabled, `postcss.config.mjs` and `tailwind.config.ts` are generated in the project root.
+When `--router tanstack` is enabled, the scaffold adds `@modern-js/plugin-tanstack`, registers `tanstackRouterPlugin()` in `modern.config.ts`, and uses `src/views` as the route convention directory.
+
+When `--bff` (default Effect runtime) or `--bff-runtime effect` is enabled, `modern.config.ts` enables `@modern-js/plugin-bff`, generates `api/effect/index.ts` + `shared/effect/api.ts`, and sets `bff.runtimeFramework` to `effect`.
+When `--bff-runtime hono` is enabled, `modern.config.ts` enables `@modern-js/plugin-bff`, generates `api/lambda/hello.ts`, and sets `bff.runtimeFramework` to `hono`.
+When `--workspace` is enabled, `@modern-js/*` dependencies use `workspace:*` versions for local monorepo linkage.

packages/document/docs/en/guides/basic-features/routes/routes.mdx

@@ -12,6 +12,11 @@ The routing mentioned in this section all refers to conventional routing.
 
 :::
 
+:::tip
+This page uses React Router import paths in examples (`@modern-js/runtime/router`).  
+If your project is created with `--router tanstack`, use `@modern-js/plugin-tanstack/runtime` instead.
+:::
+
 ## What is Nested Routing
 
 Nested routing is a pattern that couples URL segments with the component hierarchy and data. Typically, URL segments determine:
@@ -493,13 +498,19 @@ import Motivation from '@site-docs-en/components/convention-routing-motivation';
 
 ## FAQ
 
-1. Why is there `@modern-js/runtime/router` to re-export React Router API?
+1. Why should I import from `@modern-js/runtime/router` or `@modern-js/plugin-tanstack/runtime`?
 
 Notice that all the code examples in the documentation uses APIs exported from the `@modern-js/runtime/router` package instead of directly using the API exported from the React Router package. So, what is the difference?
 
-The API exported from `@modern-js/runtime/router` is the same as the API from the React Router package. If you encounter issues while using an API, check the React Router documentation and issues first.
+- `@modern-js/runtime/router` for React Router mode.
+- `@modern-js/plugin-tanstack/runtime` for TanStack Router mode.
+
+Use the Modern.js runtime export that matches your selected router framework, instead of importing directly from the upstream router package. This avoids dependency duplication and ensures compatibility with Modern.js route generation/runtime behavior.
+
+If you encounter API usage issues, check the corresponding upstream docs:
 
-Additionally, when using conventional routing, make sure to use the API from `@modern-js/runtime/router` instead of directly using the React Router API. Modern.js internally installs React Router, and using the React Router API directly in your application may result in two versions of React Router being present, causing unexpected behavior.
+- React Router docs for `@modern-js/runtime/router`.
+- TanStack Router docs for `@modern-js/plugin-tanstack/runtime`.
 
 :::note
 If you must directly use the React Router package's API (e.g., route behavior wrapped in a unified npm package), you can set [`source.alias`](/configure/app/source/alias) to point `react-router` and `react-router-dom` to the project's dependencies, avoiding the issue of two versions of React Router.

packages/document/docs/en/guides/get-started/tech-stack.mdx

@@ -16,7 +16,16 @@ Rsbuild supports building Vue applications. If you need to use Vue, you can refe
 
 ## Routing
 
-Modern.js uses [React Router v7](https://reactrouter.com/en/main) for routing.
+Modern.js provides two first-party routing frameworks:
+
+- [React Router v7](https://reactrouter.com/en/main) (default), via `@modern-js/runtime/router`.
+- [TanStack Router](https://tanstack.com/router), via `@modern-js/plugin-tanstack/runtime`.
+
+When creating a project, you can choose TanStack Router by using:
+
+```bash
+npx @modern-js/create@latest myapp --router tanstack
+```
 
 Modern.js supports conventional routing, self-controlled routing, or other routing schemes. Please refer to ["Routing"](/guides/basic-features/routes/routes) to make your choice.
 

packages/document/docs/zh/apis/app/runtime/router/router.mdx

@@ -7,6 +7,9 @@ sidebar_position: 1
 :::info 补充信息
 基于 [react-router](https://reactrouter.com/) 的路由解决方案。
 
+本页文档对应 React Router 运行时导出（`@modern-js/runtime/router`）。  
+如果应用使用 TanStack Router（`--router tanstack`），请使用 `@modern-js/plugin-tanstack/runtime`，并参考 TanStack Router 官方 API 文档。
+
 :::
 
 ## hooks

packages/document/docs/zh/components/init-app.mdx

@@ -58,3 +58,10 @@ npx @modern-js/create@latest myapp
 │       └── page.tsx
 └── tsconfig.json
 ```
+
+当启用 `--tailwind` 时，项目根目录会额外生成 `postcss.config.mjs` 和 `tailwind.config.ts`。
+当启用 `--router tanstack` 时，脚手架会添加 `@modern-js/plugin-tanstack`、在 `modern.config.ts` 中注册 `tanstackRouterPlugin()`，并使用 `src/views` 作为路由约定目录。
+
+当启用 `--bff`（默认 Effect 运行时）或 `--bff-runtime effect` 时，会在 `modern.config.ts` 中启用 `@modern-js/plugin-bff`，生成 `api/effect/index.ts` 与 `shared/effect/api.ts`，并将 `bff.runtimeFramework` 设置为 `effect`。
+当启用 `--bff-runtime hono` 时，会在 `modern.config.ts` 中启用 `@modern-js/plugin-bff`，生成 `api/lambda/hello.ts`，并将 `bff.runtimeFramework` 设置为 `hono`。
+当启用 `--workspace` 时，`@modern-js/*` 依赖会使用 `workspace:*` 版本，便于本地 monorepo 联调。

packages/document/docs/zh/guides/basic-features/routes/routes.mdx

@@ -12,6 +12,11 @@ Modern.js 的路由基于 [React Router 7](https://reactrouter.com/en/main)，
 
 :::
 
+:::tip
+本页示例默认使用 React Router 的导出路径（`@modern-js/runtime/router`）。  
+如果你的项目通过 `--router tanstack` 创建，请改用 `@modern-js/plugin-tanstack/runtime`。
+:::
+
 ## 什么是嵌套路由
 
 嵌套路由是一种将 URL 分段与组件层次结构和数据耦合起来的路由模式。通常，URL 段会决定：
@@ -495,13 +500,19 @@ import Motivation from '@site-docs/components/convention-routing-motivation';
 
 ## 常见问题
 
-1. 为什么要提供 `@modern-js/runtime/router` 来导出 React Router API ?
+1. 为什么要通过 `@modern-js/runtime/router` 或 `@modern-js/plugin-tanstack/runtime` 引入 API？
 
 可以发现，在文档中所有的代码用例都是使用 `@modern-js/runtime/router` 包导出的 API，而不是直接使用 React Router 包导出的 API。那两者有什么区别呢？
 
-首先，在 `@modern-js/runtime/router` 中导出的 API 和 React Router 包的 API 是完全一致的，如果某个 API 使用出现问题，请先检查 React Router 的文档和 Issues。
+- React Router 模式使用 `@modern-js/runtime/router`。
+- TanStack Router 模式使用 `@modern-js/plugin-tanstack/runtime`。
+
+建议优先使用与当前路由方案对应的 Modern.js 运行时导出，而不是直接从上游路由包中引入。这样可以避免依赖重复，并确保与 Modern.js 的路由生成和运行时行为保持一致。
+
+如果遇到 API 使用问题，可以分别参考上游文档：
 
-在使用约定式路由的情况下，务必使用 `@modern-js/runtime/router` 中的 API，不直接使用 React Router 的 API。因为 Modern.js 内部会安装 React Router，如果应用中使用了 React Router 的 API，可能会导致两个版本的 React Router 同时存在，出现不符合预期的行为。
+- `@modern-js/runtime/router` 对应 React Router 文档。
+- `@modern-js/plugin-tanstack/runtime` 对应 TanStack Router 文档。
 
 :::note
 

packages/document/docs/zh/guides/get-started/tech-stack.mdx

@@ -16,7 +16,16 @@ Modern.js 底层的 Rsbuild 支持构建 Vue 应用，如果你需要使用 Vue
 
 ## 路由
 
-Modern.js 的路由基于 [React Router 7](https://reactrouter.com/en/main)。
+Modern.js 提供两套一方路由方案：
+
+- 默认使用 [React Router 7](https://reactrouter.com/en/main)，通过 `@modern-js/runtime/router` 导出 API。
+- 支持 [TanStack Router](https://tanstack.com/router)，通过 `@modern-js/plugin-tanstack/runtime` 导出 API。
+
+创建项目时，可通过以下命令选择 TanStack Router：
+
+```bash
+npx @modern-js/create@latest myapp --router tanstack
+```
 
 Modern.js 支持约定式路由、自控式路由或其他路由方案，请参考 [页面入口](/guides/concept/entries) 进行选择。
 

packages/runtime/plugin-runtime/src/cli/index.ts

@@ -4,16 +4,34 @@ import {
   isReact18 as checkIsReact18,
   cleanRequireCache,
 } from '@modern-js/utils';
-import { documentPlugin } from '../document/cli';
-import { routerPlugin } from '../router/cli';
+import {
+  documentPlugin,
+} from '../document/cli';
+import {
+  getEntrypointRoutesDir,
+  handleFileChange,
+  handleGeneratorEntryCode,
+  handleModifyEntrypoints,
+  isRouteEntry,
+  routerPlugin,
+} from '../router/cli';
 import { builderPluginAlias } from './alias';
 import { generateCode } from './code';
 import { ENTRY_BOOTSTRAP_FILE_NAME, ENTRY_POINT_FILE_NAME } from './constants';
 import { isRuntimeEntry } from './entry';
 import { ssrPlugin } from './ssr';
 
 export { isRuntimeEntry } from './entry';
-export { ssrPlugin, routerPlugin, documentPlugin };
+export {
+  documentPlugin,
+  getEntrypointRoutesDir,
+  handleFileChange,
+  handleGeneratorEntryCode,
+  handleModifyEntrypoints,
+  isRouteEntry,
+  routerPlugin,
+  ssrPlugin,
+};
 export const runtimePlugin = (params?: {
   plugins?: CliPlugin<AppTools>[];
 }): CliPlugin<AppTools> => ({