@modern-js/app-tools 3.11.0 → 3.11.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -48,8 +48,8 @@ class BottomTemplatePlugin {
48
48
  this.name = 'bottom-template';
49
49
  }
50
50
  }
51
- __webpack_require__.d(__webpack_exports__, {
52
- BottomTemplatePlugin: ()=>BottomTemplatePlugin
51
+ __webpack_require__.d(__webpack_exports__, {}, {
52
+ BottomTemplatePlugin: BottomTemplatePlugin
53
53
  });
54
54
  exports.BottomTemplatePlugin = __webpack_exports__.BottomTemplatePlugin;
55
55
  for(var __rspack_i in __webpack_exports__)if (-1 === [
@@ -7,7 +7,7 @@ const info = (file)=>({
7
7
  function createPublicPattern(appContext, config, chain) {
8
8
  const { publicDir } = createCopyInfo(appContext, config);
9
9
  return {
10
- info: info,
10
+ info,
11
11
  from: '**/*',
12
12
  to: 'public',
13
13
  context: publicDir,
@@ -8,7 +8,7 @@ const info = (file)=>({
8
8
  function createPublicPattern(appContext, config, chain) {
9
9
  const { publicDir } = createCopyInfo(appContext, config);
10
10
  return {
11
- info: info,
11
+ info,
12
12
  from: '**/*',
13
13
  to: 'public',
14
14
  context: publicDir,
@@ -35,3 +35,40 @@ If the value of `supportHtml5History` is `true`, `BrowserRouter` would be used,
35
35
  When SSR is enabled, `supportHtml5History` is not supported.
36
36
 
37
37
  :::
38
+
39
+ ## useTransitions
40
+
41
+ - **Type:** `boolean`
42
+ - **Default:** `undefined`, which follows React Router's default behavior (enabled)
43
+
44
+ Whether to wrap router state updates in [`React.startTransition`](https://react.dev/reference/react/startTransition). The value is passed to React Router's [`<RouterProvider useTransitions>`](https://reactrouter.com/api/data-routers/RouterProvider).
45
+
46
+ When enabled, the page mount after the initial Data Loader finishes and every navigation are rendered concurrently. Benefits:
47
+
48
+ - During navigation, the current page stays on screen until the next page is ready, instead of showing a loading state first.
49
+ - Rendering can yield to the main thread, so the page keeps responding to user input while switching pages.
50
+
51
+ It also introduces two behaviors that differ from synchronous rendering:
52
+
53
+ - A render may be discarded and run again. Component bodies, `useMemo` and `useState` initializers, and class component constructors may run more than once, so code in them that changes external state (such as creating an instance and assigning it to a global variable, registering event listeners, or sending analytics) also runs more than once.
54
+ - There may be a gap between render and commit. External state read during render may have changed by the time it is subscribed to in `useLayoutEffect`, and updates that happen in the gap are lost.
55
+
56
+ If your application contains such code and cannot be refactored yet, set it to `false` to render router state updates synchronously:
57
+
58
+ ```ts title="src/modern.runtime.ts"
59
+ import { defineRuntimeConfig } from '@modern-js/runtime';
60
+
61
+ export default defineRuntimeConfig({
62
+ router: {
63
+ useTransitions: false,
64
+ },
65
+ });
66
+ ```
67
+
68
+ :::tip
69
+
70
+ - This option only affects router state updates. Updates triggered by `startTransition` or `useTransition` in your own code are not affected.
71
+ - See the [React Router documentation](https://reactrouter.com/explanation/react-transitions) for how to make your code transition-safe.
72
+ - `future.v7_startTransition` is deprecated. When `useTransitions` is not set, the value of `future.v7_startTransition` is used.
73
+
74
+ :::
@@ -17,7 +17,7 @@ Choose a release containing MCP Apps support. Run `pnpm dev`. The explicit BFF r
17
17
 
18
18
  ## Build cards
19
19
 
20
- Declare local default-export React components or this project's MF exposes in `mcp-views.json`:
20
+ Declare local default-export React components, this project's MF exposes, or exposes of deployed remotes in `mcp-views.json`:
21
21
 
22
22
  ```json
23
23
  {
@@ -46,6 +46,31 @@ mcpAppsPlugin({
46
46
  });
47
47
  ```
48
48
 
49
+ ### Reference deployed remotes
50
+
51
+ When another project publishes the card as an MF remote, set `remote` to the manifest URL of the remote:
52
+
53
+ ```json
54
+ {
55
+ "remote": "https://ui.example.com/mf-manifest.json",
56
+ "views": {
57
+ "todos": { "expose": "./Todos" },
58
+ "stats": { "expose": "./Stats" }
59
+ },
60
+ "csp": { "resourceDomains": ["https://cdn.example.com"] }
61
+ }
62
+ ```
63
+
64
+ The top-level `remote` is shared by all expose views. A view can set its own `remote` to override it. Component paths still reference local components. Without a top-level or view-level `remote`, exposes refer to this application. With a top-level `remote`, expose views in the same config cannot refer to this application's exposes. To mix both, omit the top-level `remote` and set `remote` only on the views that reference a deployed remote.
65
+
66
+ - The URL must be an absolute HTTP(S) URL whose path ends with `.json`. Entries that are not manifests, such as `remoteEntry.js`, are not supported
67
+ - The remote's name is not needed. The runtime reads it from the manifest
68
+ - The shell reads the remote manifest and loads the expose when the card opens. Republishing the remote needs no rebuild or restart of the MCP server. Exposes are not checked at build time. A missing expose shows a load error in the card
69
+ - This project does not need the MF plugin, but it must install the runtime that `mf.runtime` points to. Set `mf.runtime` as above when the remote uses another MF implementation
70
+ - The manifest origin is added to CSP automatically. Declare other origins serving the remote's scripts and styles, such as a CDN, in `csp.resourceDomains`. The manifest and scripts must allow cross-origin requests
71
+ - The remote must share React as a singleton so it uses the shell's React
72
+ - Adding a card or changing `remote` or `expose` still requires rebuilding the MCP server
73
+
49
74
  Local cards build as separate entries without the framework page runtime. With `source.enableAsyncEntry`, each entry adds a dynamic import boundary so MF shared dependencies can initialize. The MF plugin enables this option automatically. Otherwise cards mount directly without an extra request.
50
75
 
51
76
 
@@ -41,3 +41,5 @@ If running normally, you can see the following output in the console:
41
41
  error SSR Error - App Prerender, error = ReferenceError: a is not defined
42
42
  at Index (/somepath/page.tsx:3:1)
43
43
  ```
44
+
45
+ To configure the built-in production server logger with `MODERN_SERVER_LOG_LEVEL`, see [Production server logs](/guides/basic-features/deploy.md#production-server-logs).
@@ -109,6 +109,12 @@ export const action = async ({ request }: ActionFunctionArgs) => {
109
109
 
110
110
  The return value of the `action` function can be any serializable content or a [Fetch Response](https://developer.mozilla.org/en-US/docs/Web/API/Response) instance. You can access the content via [`useActionData`](https://reactrouter.com/en/main/hooks/use-action-data).
111
111
 
112
+ ### Redirects
113
+
114
+ An action can return or throw `redirect('/dashboard')` imported from `@modern-js/runtime/router` to navigate after a submission. This also applies to submissions made with `useFetcher`.
115
+
116
+ Actions run when a form or `submit` triggers a mutation request. Visiting a route alone does not run its action. To redirect when loading a route, use `redirect` in its loader.
117
+
112
118
  ## useSubmit and useFetcher
113
119
 
114
120
  ### Difference
@@ -83,6 +83,37 @@ If you use Rush as your Monorepo management tool, you can add the following comm
83
83
 
84
84
  After the build is completed, Modern.js will generate all dependencies in the `.output/node_modules` directory of the project. Similarly, you can run the Modern.js server using `node .output/index`.
85
85
 
86
+ ### Production server logs
87
+
88
+ The built-in Node.js production server defaults to the `info` log level. It prints informational messages, warnings and errors, without logging every page or static asset request.
89
+
90
+ Set `MODERN_SERVER_LOG_LEVEL` when starting the server to change its log level:
91
+
92
+ ```bash
93
+ MODERN_SERVER_LOG_LEVEL=warn node .output/index
94
+ ```
95
+
96
+ The supported values are the [rslog](https://github.com/rstackjs/rslog) log levels:
97
+
98
+ | Value | Output |
99
+ | --------- | ------------------------------------------------------------------- |
100
+ | `silent` | No logs |
101
+ | `error` | Errors only |
102
+ | `warn` | Warnings and errors |
103
+ | `info` | Informational messages, warnings and errors (default) |
104
+ | `log` | Everything at `info`, plus messages written with `logger.log()` |
105
+ | `verbose` | All logs, including debug messages, request logs and timing details |
106
+
107
+ To enable per-request logs, including static asset requests:
108
+
109
+ ```bash
110
+ MODERN_SERVER_LOG_LEVEL=verbose node .output/index
111
+ ```
112
+
113
+ Setting `DEBUG` to a non-empty value also enables `verbose` logging, unless `MODERN_SERVER_LOG_LEVEL` explicitly selects another level.
114
+
115
+ This environment variable controls the built-in server logger. It does not override a custom logger or enable logging when `server.logger` is `false`.
116
+
86
117
  ## Netlify
87
118
 
88
119
  Netlify is a popular Web development platform designed for building, deploying, and maintaining modern web projects. Deploying on Netlify mainly requires configuring the `netlify.toml` file.
@@ -177,6 +177,64 @@ export default defineConfig({
177
177
  });
178
178
  ```
179
179
 
180
+ ## SSG Matching for Parent and Child Routes
181
+
182
+ For a blog, `src/routes/blog/page.tsx` renders the list and `src/routes/blog/[slug]/page.tsx` renders an article. After enabling SSG, you can prerender both the list and selected articles:
183
+
184
+
185
+ ```ts title="modern.config.ts"
186
+ export default defineConfig({
187
+ output: {
188
+ ssg: {
189
+ routes: ['/blog', '/blog/hello'],
190
+ },
191
+ },
192
+ })
193
+ ```
194
+
195
+ Each path generates its own static HTML. The built-in production server matches SSG pages by their exact paths:
196
+
197
+ | Request path | Behavior |
198
+ | ---------------------- | --------------------------------------------------------------- |
199
+ | `/blog` | Returns the static HTML for the blog list |
200
+ | `/blog/hello` | Returns the static HTML for the article |
201
+ | `/blog/does-not-exist` | Does not match an SSG page and falls back to an available entry |
202
+
203
+ Requests to a trailing-slash URL such as `/blog/` receive an HTTP 308 redirect to `/blog`, preserving the query string. For example, `/blog/?preview=1` redirects to `/blog?preview=1`.
204
+
205
+ The SSG page at `/blog` does not act as a fallback for `/blog/*`. Defining a `[slug]` route does not automatically generate static HTML for every slug. List the concrete paths in `routes`.
206
+
207
+ This example does not enable SSR or prerender the root entry `/`. An unmatched path therefore receives the root entry's CSR shell, and routing continues in the browser. The initial HTML response is typically HTTP 200. An unknown slug alone does not cause the server to return 404.
208
+
209
+ If a matching SSR entry exists, SSR determines the response content and status. If no entry matches, the server returns 404. If you also configure the root entry `/` for SSG, it only matches its own path and no longer provides a wildcard fallback.
210
+
211
+ ## Handling 404 Responses During Prerendering
212
+
213
+ Continuing the example, suppose you add `/blog/scheduled` to `output.ssg.routes`, but the article has not been published yet. Its loader can throw a 404 during the build. Here, `getPost` is your application's article lookup function, and `publishedAt` is the publication timestamp in milliseconds:
214
+
215
+
216
+ ```ts title="src/routes/blog/[slug]/page.data.ts"
217
+ import { getPost } from '@/data/posts'
218
+
219
+ export const loader = async ({ params }: { params: { slug: string } }) => {
220
+ const post = await getPost(params.slug)
221
+ if (!post || post.publishedAt > Date.now()) {
222
+ throw new Response('Not Found', { status: 404 })
223
+ }
224
+ return post
225
+ }
226
+ ```
227
+
228
+ When prerendering returns 404 or another non-2xx response, the build:
229
+
230
+ - Logs a warning containing the path and status code.
231
+ - Skips the page's static HTML file and SSG route registration.
232
+ - Continues generating pages with successful responses.
233
+
234
+ The error page is therefore not saved as static HTML that would later be served with HTTP 200. Requests to `/blog/scheduled` follow the entry fallback rules above. The build-time 404 is not stored as the path's runtime response status.
235
+
236
+ SSG only generates pages during a build. Reaching the publication time does not automatically generate the missing static HTML. Rebuild and redeploy to generate the article's SSG page.
237
+
180
238
  ## Multi-entry
181
239
 
182
240
  For multi-entry apps, configure per entry via `output.ssgByEntries`:
@@ -89,6 +89,24 @@ Modern.js 3.0 uses React Router v7 as the default routing library. React Router
89
89
 
90
90
  If you need to use React Router v5 or React Router v6, you need to use **self-controlled routing** mode. Self-controlled routing allows you to fully control routing configuration without being limited by Modern.js convention-based routing.
91
91
 
92
+ ### Router updates use transitions by default
93
+
94
+ React Router v7 wraps router state updates in `React.startTransition` by default. In v6 this behavior required enabling `future.v7_startTransition`. After upgrading, the page mount after the initial Data Loader finishes and every navigation switch from synchronous rendering to concurrent rendering. A render may be discarded and run again, and there may be a gap between render and commit.
95
+
96
+ If your project changes external state during render, you may see the following issues after upgrading:
97
+
98
+ - An instance is created in `useMemo` and assigned to a global variable. After it runs again, multiple instances exist and logic that relies on a singleton throws.
99
+ - A React Router v6 `RouterProvider` is nested inside a page. It reads the router state during render but only subscribes in `useLayoutEffect`, so it may miss the initialization notification and the page stays blank. See [React Router issue #14356](https://github.com/remix-run/react-router/issues/14356).
100
+
101
+ Keep render free of side effects as React requires:
102
+
103
+ - Create instances, register listeners, send analytics, and modify global variables in `useEffect`.
104
+ - Read external state with [`useSyncExternalStore`](https://react.dev/reference/react/useSyncExternalStore).
105
+ - Create objects such as routers and stores outside components.
106
+ - Enable `StrictMode` in development to surface code that breaks when run twice.
107
+
108
+ If your code cannot be refactored yet, set [`router.useTransitions`](/configure/app/runtime/router.md#usetransitions) to `false` to restore synchronous rendering.
109
+
92
110
  ## Using @modern-js/create to Create Monorepo and Modern.js Module
93
111
 
94
112
  Modern.js 3.0 no longer supports creating Monorepo projects and Modern.js Module projects through `@modern-js/create`.
package/package.json CHANGED
@@ -15,7 +15,7 @@
15
15
  "modern",
16
16
  "modern.js"
17
17
  ],
18
- "version": "3.11.0",
18
+ "version": "3.11.2",
19
19
  "types": "./dist/types/index.d.ts",
20
20
  "main": "./dist/cjs/index.js",
21
21
  "exports": {
@@ -113,11 +113,11 @@
113
113
  }
114
114
  },
115
115
  "dependencies": {
116
- "@babel/parser": "^7.29.11",
117
- "@babel/traverse": "^7.29.10",
116
+ "@babel/parser": "^7.29.12",
117
+ "@babel/traverse": "^7.29.12",
118
118
  "@babel/types": "^7.29.11",
119
- "@rsbuild/core": "2.2.13",
120
- "@swc/core": "1.16.20",
119
+ "@rsbuild/core": "2.3.1",
120
+ "@swc/core": "1.16.21",
121
121
  "@swc/helpers": "^0.5.17",
122
122
  "es-module-lexer": "^1.7.0",
123
123
  "flatted": "^3.4.4",
@@ -126,16 +126,16 @@
126
126
  "ndepe": "^0.1.13",
127
127
  "pkg-types": "^1.3.1",
128
128
  "std-env": "^3.10.0",
129
- "@modern-js/builder": "3.11.0",
130
- "@modern-js/i18n-utils": "3.11.0",
131
- "@modern-js/plugin": "3.11.0",
132
- "@modern-js/prod-server": "3.11.0",
133
- "@modern-js/plugin-data-loader": "3.11.0",
134
- "@modern-js/server": "3.11.0",
135
- "@modern-js/server-core": "3.11.0",
136
- "@modern-js/server-utils": "3.11.0",
137
- "@modern-js/types": "3.11.0",
138
- "@modern-js/utils": "3.11.0"
129
+ "@modern-js/builder": "3.11.2",
130
+ "@modern-js/i18n-utils": "3.11.2",
131
+ "@modern-js/plugin": "3.11.2",
132
+ "@modern-js/plugin-data-loader": "3.11.2",
133
+ "@modern-js/prod-server": "3.11.2",
134
+ "@modern-js/server": "3.11.2",
135
+ "@modern-js/server-core": "3.11.2",
136
+ "@modern-js/server-utils": "3.11.2",
137
+ "@modern-js/types": "3.11.2",
138
+ "@modern-js/utils": "3.11.2"
139
139
  },
140
140
  "devDependencies": {
141
141
  "@types/babel__traverse": "7.28.0",
@@ -143,8 +143,8 @@
143
143
  "ts-node": "^10.9.2",
144
144
  "tsconfig-paths": "^4.2.0",
145
145
  "typescript": "^5",
146
- "@modern-js/rslib": "3.11.0",
147
- "@scripts/rstest-config": "2.66.4"
146
+ "@modern-js/rslib": "3.11.2",
147
+ "@scripts/rstest-config": "2.66.6"
148
148
  },
149
149
  "peerDependencies": {
150
150
  "ts-node": "^10.9.2",