@bleedingdev/modern-js-app-tools 3.5.0-ultramodern.98 → 3.5.0-ultramodern.99

package/docs/guides/get-started/ai-coding-agents.mdx

@@ -0,0 +1,63 @@
+---
+title: AI Tools
+sidebar_position: 6
+---
+
+# Modern.js For AI
+
+Modern.js provides a toolkit for AI agents that makes your project agent-ready out of the box, helping you use AI to develop, upgrade, and migrate Modern.js applications more accurately and efficiently.
+
+## Bundled docs
+
+Modern.js ships the English docs that match your installed version together with `@modern-js/app-tools`. After you install or upgrade, they live at `node_modules/@modern-js/app-tools/docs/`, available offline with no extra setup.
+
+AI agents use them to get APIs, config, and conventions that exactly match your framework version, rather than relying on potentially outdated training data.
+
+## AGENTS.md
+
+`AGENTS.md` gives AI coding agents project-level guidance — telling them to read the bundled docs before making changes and to follow Modern.js conventions. A `CLAUDE.md` is generated alongside it, reusing the same guidance for Claude Code via the `@AGENTS.md` import.
+
+- **New projects**: `npx @modern-js/create` generates both files by default; pass `--no-agents-md` to skip them.
+- **Existing projects**: run `npx @modern-js/create agents-md` at the project root to create or update them. Re-run it any time; your own additions are preserved.
+
+Modern.js only maintains the content inside the `<!-- BEGIN:modernjs-agent-rules -->` markers in `AGENTS.md`; anything you write outside them is left untouched.
+
+## llms.txt
+
+llms.txt is an online documentation index following the [llms.txt specification](https://llmstxt.org/), auto-generated by [`@rspress/plugin-llms`](https://rspress.rs/plugin/official-plugins/llms) for AI tools to retrieve the full docs online:
+
+- Index: [`https://modernjs.dev/llms.txt`](https://modernjs.dev/llms.txt)
+- Full text: [`https://modernjs.dev/llms-full.txt`](https://modernjs.dev/llms-full.txt) (large — fetch on demand)
+
+Use it when you need content beyond the bundled docs — just let your agent retrieve it on demand, no need to copy docs into your project. Typical cases: looking up another framework version, a section not included in the bundle, or getting Modern.js information outside of a project (for example before a project exists, or when researching on its own).
+
+## Skills
+
+Skills are on-demand AI capabilities following the [Agent Skills open standard](https://github.com/vercel-labs/skills). User-facing Skills:
+
+| Skill | Identifier | Description |
+|---|---|---|
+| Upgrade to v3 | `modernjs-migrate-to-v3` | Migrate a v2 app to v3: safe rewrites + manual checklist + migration report |
+| Enable features | `modernjs-feature-enable` | Enable BFF / SSG / styled-components for v3 apps, and scaffold Tailwind CSS / custom Web Server |
+
+> Skills are not force-installed or implicitly installed — you install them explicitly. RSC and micro-frontend setups are configuration or architecture decisions, not one-click `modernjs-feature-enable` actions.
+
+## Installing Skills
+
+Modern.js user-facing Skills live in the repo's root `skills/` directory and follow the [Agent Skills open standard](https://github.com/vercel-labs/skills). The recommended way is the standard `skills` CLI, installing straight from GitHub:
+
+```bash
+# List installable Skills
+npx skills add web-infra-dev/modern.js --list
+
+# Install a single Skill into your agent directory (--agent: claude-code / codex / cursor / ...)
+npx skills add web-infra-dev/modern.js --skill modernjs-migrate-to-v3 --agent codex -y
+```
+
+It installs the entire Skill directory (`SKILL.md` + `scripts/` + `references/`) into the corresponding agent directory, ready to trigger there.
+
+> To pin a specific version, append `#<ref>` (a tag, branch, or commit) to the repo — it installs the Skill as of that ref (replace `<tag>` with a release tag that contains this Skill):
+>
+> ```bash
+> npx skills add web-infra-dev/modern.js#<tag> --skill modernjs-migrate-to-v3 --agent codex -y
+> ```

package/docs/guides/get-started/glossary.mdx

@@ -0,0 +1,63 @@
+---
+sidebar_position: 4
+---
+
+# Glossary
+
+## BFF
+
+BFF is short for "Backend For Frontend". It is an architecture pattern that involves creating a backend service for frontend applications.
+
+The BFF service acts as an intermediary between the frontend application and the server API, and can provide customized APIs for the frontend to use. This allows frontend developers to have more control over the data and functionality they need, without relying on the backend service to provide the corresponding capabilities.
+
+## Bundler
+
+import Bundler from '@site-docs-en/components/bundler.mdx';
+
+<Bundler />
+
+## CSR
+
+CSR stands for "Client-Side Rendering". It means that the page is rendered in the browser using JavaScript, and logic such as data fetching, templates, and routing is completed on the client side rather than the server.
+
+In CSR, the server sends an empty HTML shell and some JavaScript scripts to the browser, and the browser fetching data from the server's API and renders dynamic content to the page.
+
+## Module Federation
+
+import ModuleFederation from '@site-docs-en/components/module-federation.mdx';
+
+<ModuleFederation />
+
+## Rsbuild
+
+import Rsbuild from '@site-docs-en/components/rsbuild.mdx';
+
+<Rsbuild />
+
+## Rspack
+
+import Rspack from '@site-docs-en/components/rspack.mdx';
+
+<Rspack />
+
+## SSR
+
+SSR stands for "Server-Side Rendering". It means that the HTML of the web page is generated by the server and sent to the client, rather than sending only an empty HTML shell and relying on JavaScript to generate the page content.
+
+In traditional client-side rendering, the server sends an empty HTML shell and some JavaScript scripts to the client, and then fetching data from the server's API and fills the page with dynamic content. This leads to slow initial page loading times and is not conducive to user experience and SEO.
+
+With SSR, the server generates HTML that already contains dynamic content and sends it to the client. This makes the initial page loading faster and more SEO-friendly, as search engines can crawl the rendered page.
+
+## SSG
+
+SSG stands for "Static Site Generation". It means that web pages are pre-rendered as static HTML and served directly to the client, without the need for the server to generate HTML in real-time.
+
+In traditional SSR, the server generates HTML in real-time every time a user requests a page. With SSG, HTML can be generated in advance during the build process and hosted on a CDN or other static assets service.
+
+Compared to traditional SSR, SSG can provide faster loading speeds and less server-side overhead, as there is no need to maintain a server to generate HTML in real-time. However, SSG is not suitable for websites that require dynamic content, as the HTML is generated during the build process and does not support real-time updates.
+
+## SWC
+
+import SWC from '@site-docs-en/components/swc.mdx';
+
+<SWC />

package/docs/guides/get-started/introduction.mdx

@@ -0,0 +1,45 @@
+---
+title: Introduction
+sidebar_position: 1
+---
+
+# Introduction to Modern.js
+
+**Modern.js is a progressive web framework based on React**. At ByteDance, we use Modern.js to build upper-level frameworks that have supported the development of thousands of web applications.
+
+Modern.js can provide developers with an ultimate **Development Experience** and enable applications to have better **User Experience**.
+
+In the process of developing React applications, developers usually need to design implementation plans for certain features or use other libraries and frameworks to solve these problems. Modern.js supports all configurations and tools needed by React applications, and has built-in **additional features and optimizations**. Developers can use React to build the UI of the application, and then gradually adopt the features of Modern.js to solve common application requirements, such as routing, data acquisition, and state management.
+
+It mainly includes the following features:
+
+- 🚀 **Rust Bundler**: Modern.js uses Rsbuild/Rspack as the build tool, providing blazing fast compilation.
+- 🪜 **Progressive**: Create projects with the most streamlined templates, gradually enable plugin features through the generator, and customize solutions.
+- 🏠 **Integration**: Development and production environment web server are unique, CSR and SSR are isomorphic development, and API service calls are functions as interfaces.
+- 🕸 **Convention Routing**: Using file-based routing helps developers quickly set up applications.
+
+## Comparison with Others
+
+### Next.js
+
+Next.js is one of the most popular React frameworks in the community. It is developed by Vercel.
+
+If you want to build a single-page application (SPA) and render it on the client side, Next.js may not be the best choice because many of its features are designed around server-first principles. If you need to use client-side rendering, you can only use limited functionality through Next.js's "static exports" feature.
+
+Modern.js considers both client-side rendering (CSR) and server-side rendering (SSR) to be equally important. When you build a Modern.js application, it defaults to client-side rendering. You can also enable SSR or Server Components whenever you need it, and even enable SSR for specific pages. The whole process is fully progressive.
+
+### Umi
+
+Umi is the underlying frontend framework for the Ant Group. Modern.js and Umi share many similarities, such as support for plugin system, convention-based routing, and micro-generators.
+
+**The main difference between Modern.js and Umi is their approach to optimizing build speed**. Umi uses MFSU technology to improve build speed, while Modern.js uses Rspack to achieve 5 to 10 times faster build speed. From our perspective, Rust tools like Rspack are more in line with the long-term evolution of the front-end toolchain, as they can strike a good balance between performance, stability, and ecosystem compatibility.
+
+In addition, Modern.js provides richer server-side features, including comprehensive SSR capabilities, integrated BFF development capabilities, and support for custom web servers. These capabilities have been extensively validated by ByteDance in numerous online applications and can be directly used in production environments.
+
+### Remix
+
+Pelease refer to [Modern.js vs Remix](https://github.com/web-infra-dev/modern.js/discussions/4872).
+
+## Next Step
+
+If you want to understand the compatibility-first differences between Modern.js v3 and UltraModern.js v3, read [UltraModern.js](/guides/get-started/ultramodern).

package/docs/guides/get-started/quick-start.mdx

@@ -0,0 +1,92 @@
+---
+title: Quick Start
+sidebar_position: 2
+---
+
+# Quick Start
+
+## Environment
+
+import Prerequisites from '@site-docs-en/components/prerequisites';
+
+<Prerequisites />
+
+## Installation
+
+## Initialize
+
+import InitApp from '@site-docs-en/components/init-app';
+
+<InitApp />
+
+## Development
+
+import DebugApp from '@site-docs-en/components/debug-app';
+
+<DebugApp />
+
+## Configuration
+
+In an UltraModern.js project created using `@bleedingdev/modern-js-create`, a `modern.config.ts` file is generated by default.
+
+You can modify the configuration through this file to override the default behavior of Modern.js. For example, to enable SSR, add the following configuration:
+
+```ts title="modern.config.ts"
+import { appTools, defineConfig } from '@modern-js/app-tools';
+
+export default defineConfig({
+  server: {
+    ssr: true,
+  },
+  plugins: [appTools()],
+});
+```
+
+After running `pnpm run dev` again, you can find that the project has completed page rendering on the server in the browser's Network menu.
+
+## Core npm Package
+
+In a newly created project, the `@modern-js/app-tools` npm package is installed by default. It is the core package of the Modern.js framework and provides the following capabilities:
+
+- It offers commonly used CLI commands such as `modern dev`, `modern build`, and more.
+- It integrates Rsbuild, providing build capabilities.
+- It integrates Modern.js Server, providing capabilities for development and production servers.
+
+`@modern-js/app-tools` is implemented based on the plugin system of Modern.js. Essentially, it is a plugin. Therefore, you need to register `appTools` in the `plugins` field of the configuration file:
+
+```ts title="modern.config.ts"
+import { appTools, defineConfig } from '@modern-js/app-tools';
+
+export default defineConfig({
+  plugins: [appTools()],
+});
+```
+
+## Build the project
+
+import BuildOutput from '@site-docs-en/components/build-output';
+
+<BuildOutput />
+
+## Verify
+
+Run `pnpm run serve` in the project to verify whether the build artifacts run normally locally:
+
+```bash
+$ pnpm run serve
+
+  Modern.js Framework
+
+info    Starting production server...
+
+  > Local:    http://localhost:8080/
+  > Network:  http://192.168.0.1:8080/
+```
+
+Open `http://localhost:8080/` in the browser, and the content should be consistent with that of `pnpm run dev`.
+
+## Deployment
+
+import Deploy from '@site-docs-en/components/deploy';
+
+<Deploy />

package/docs/guides/get-started/tech-stack.mdx

@@ -0,0 +1,97 @@
+---
+sidebar_position: 4
+---
+
+# Tech Stack
+
+The Modern.js framework comes with built-in popular libraries and development tools from the community.
+
+In this document, you can learn about the main technology stack involved in the Modern.js framework, as well as some optional libraries and tools.
+
+## UI Library
+
+Modern.js uses [React 19](https://react.dev/) to build user interfaces and is also compatible with React 18.
+
+Rsbuild supports building Vue applications. If you need to use Vue, you can refer to ["Rsbuild - Vue"](https://v2.rsbuild.rs/guide/framework/vue).
+
+## Routing
+
+Modern.js provides two first-party routing frameworks:
+
+- [TanStack Router](https://tanstack.com/router) (UltraModern default), via `@modern-js/plugin-tanstack/runtime`.
+- [React Router](https://reactrouter.com/en/main), via `@modern-js/runtime/router`.
+
+When creating an UltraModern project, TanStack Router is included by default:
+
+```bash
+pnpm dlx @bleedingdev/modern-js-create myapp
+```
+
+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.
+
+## Package Manager
+
+Modern.js can be used with any community package manager, such as [npm](https://www.npmjs.com/package/npm), [yarn](https://classic.yarnpkg.com/lang/en/), [pnpm](https://pnpm.io/), or [Bun](https://bun.sh/).
+
+We recommend using pnpm for faster installation speed.
+
+## Bundler
+
+Modern.js uses [Rspack](https://rspack.rs/) to bundle your web applications.
+
+## Transpiler
+
+Modern.js uses [SWC](https://swc.rs/) as JavaScript transpiler to transform TypeScript or JSX into JavaScript code that can run in browsers and perform syntax downgrades.
+
+When using Rspack for building, `babel-loader` is not enabled by default. If you need to add [Babel](https://babeljs.io/) plugins, you can configure them through [`babel plugin`](https://v2.rsbuild.rs/plugins/list/plugin-babel#babel-plugin), which will generate additional compilation overhead and slow down Rspack build speed to some extent.
+
+## Minimizer
+
+During production builds, Modern.js uses [SWC](https://swc.rs/) to minify JS code.
+
+## CSS Transformer
+
+Modern.js uses [PostCSS](https://postcss.org/) to transform CSS code and enables [autoprefixer](https://github.com/postcss/autoprefixer) by default to add CSS prefixes.
+
+Modern.js supports enabling ["Lightning CSS"](/configure/app/tools/lightningcss-loader), which uses Lightning CSS to downgrade CSS syntax.
+
+Modern.js supports enabling ["Tailwind CSS"](/guides/basic-features/css/tailwindcss) and is compatible with both Tailwind CSS v3 and v4.
+
+## CSS Preprocessors
+
+Modern.js supports three CSS preprocessors: [Sass](https://sass-lang.com/), [Less](https://lesscss.org/), and [Stylus](https://stylus-lang.com/):
+
+- Sass and Less are supported by default and ready to use.
+- Stylus is optional and can be used by referring to the ["Stylus Plugin"](https://v2.rsbuild.rs/plugins/list/plugin-stylus).
+
+## CSS Modules
+
+Modern.js provides out-of-the-box support for [CSS Modules](https://github.com/css-modules/css-modules), which is implemented internally based on [css-loader](https://www.npmjs.com/package/css-loader).
+
+Please refer to ["Use CSS Modules"](/guides/basic-features/css/css-modules) for usage instructions.
+
+## CSS-in-JS
+
+Modern.js supports the use of [styled-components](https://styled-components.com/). Please refer to ["Using CSS-in-JS"](/en/guides/basic-features/css/css-in-js) for usage instructions.
+
+If you need to use other CSS-in-JS solutions, you can integrate them into your project on your own.
+
+## UI Components
+
+Modern.js can be used with any React UI component library from the community, such as [MUI](https://mui.com/), [Ant Design](https://ant.design/), [Arco Design](https://github.com/arco-design/arco-design), [Semi Design](https://semi.design/), [Radix UI](https://www.radix-ui.com/), and more.
+
+## Component Development
+
+Modern.js supports the use of [Storybook](https://storybook.js.org/) for developing UI components. This feature is optional. Please refer to ["Using Storybook"](/guides/basic-features/debug/using-storybook) to enable it.
+
+## Testing Framework
+
+Modern.js recommends [Rstest](https://rstest.rs/) for unit tests and component tests. Rstest is built on Rspack for fast startup and execution, and it can reuse your Modern.js app configuration through [`@modern-js/adapter-rstest`](/guides/basic-features/testing/rstest).
+
+For end-to-end (E2E) tests, you can use [Playwright](/guides/basic-features/testing/playwright).
+
+## Node.js Framework
+
+import TechStackNodeFramework from '@site-docs-en/components/tech-stack-node-framework';
+
+<TechStackNodeFramework />