@modern-js/app-tools 3.11.0 → 3.11.1
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.
- package/dist/cjs/builder/shared/bundlerPlugins/HtmlBottomTemplate.js +2 -2
- package/dist/esm/builder/generator/createCopyPattern.mjs +1 -1
- package/dist/esm-node/builder/generator/createCopyPattern.mjs +1 -1
- package/docs/configure/app/runtime/router.md +37 -0
- package/docs/guides/advanced-features/server-monitor/logger.md +2 -0
- package/docs/guides/basic-features/data/data-write.md +6 -0
- package/docs/guides/basic-features/deploy.md +31 -0
- package/docs/guides/basic-features/render/ssg.md +58 -0
- package/docs/guides/upgrade/other.md +18 -0
- package/package.json +17 -17
|
@@ -48,8 +48,8 @@ class BottomTemplatePlugin {
|
|
|
48
48
|
this.name = 'bottom-template';
|
|
49
49
|
}
|
|
50
50
|
}
|
|
51
|
-
__webpack_require__.d(__webpack_exports__, {
|
|
52
|
-
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 === [
|
|
@@ -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
|
+
:::
|
|
@@ -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.
|
|
18
|
+
"version": "3.11.1",
|
|
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.
|
|
117
|
-
"@babel/traverse": "^7.29.
|
|
116
|
+
"@babel/parser": "^7.29.12",
|
|
117
|
+
"@babel/traverse": "^7.29.12",
|
|
118
118
|
"@babel/types": "^7.29.11",
|
|
119
|
-
"@rsbuild/core": "2.
|
|
120
|
-
"@swc/core": "1.16.
|
|
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.
|
|
130
|
-
"@modern-js/
|
|
131
|
-
"@modern-js/plugin": "3.11.
|
|
132
|
-
"@modern-js/
|
|
133
|
-
"@modern-js/
|
|
134
|
-
"@modern-js/server": "3.11.
|
|
135
|
-
"@modern-js/server-core": "3.11.
|
|
136
|
-
"@modern-js/
|
|
137
|
-
"@modern-js/
|
|
138
|
-
"@modern-js/utils": "3.11.
|
|
129
|
+
"@modern-js/builder": "3.11.1",
|
|
130
|
+
"@modern-js/plugin": "3.11.1",
|
|
131
|
+
"@modern-js/plugin-data-loader": "3.11.1",
|
|
132
|
+
"@modern-js/i18n-utils": "3.11.1",
|
|
133
|
+
"@modern-js/prod-server": "3.11.1",
|
|
134
|
+
"@modern-js/server": "3.11.1",
|
|
135
|
+
"@modern-js/server-core": "3.11.1",
|
|
136
|
+
"@modern-js/types": "3.11.1",
|
|
137
|
+
"@modern-js/server-utils": "3.11.1",
|
|
138
|
+
"@modern-js/utils": "3.11.1"
|
|
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.
|
|
147
|
-
"@scripts/rstest-config": "2.66.
|
|
146
|
+
"@modern-js/rslib": "3.11.1",
|
|
147
|
+
"@scripts/rstest-config": "2.66.5"
|
|
148
148
|
},
|
|
149
149
|
"peerDependencies": {
|
|
150
150
|
"ts-node": "^10.9.2",
|