@modern-js/app-tools 3.7.0 → 3.8.0

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.
Files changed (306) hide show
  1. package/bin/modern-bundle-docs.js +7 -0
  2. package/dist/cjs/builder/generator/createBuilderProviderConfig.js +5 -1
  3. package/dist/cjs/bundleDocs.js +114 -0
  4. package/dist/cjs/commands/build.js +2 -1
  5. package/dist/cjs/commands/deploy.js +4 -2
  6. package/dist/cjs/commands/index.js +0 -4
  7. package/dist/cjs/config/default.js +2 -0
  8. package/dist/cjs/index.js +52 -14
  9. package/dist/cjs/plugins/analyze/index.js +2 -2
  10. package/dist/cjs/plugins/analyze/utils.js +3 -2
  11. package/dist/cjs/plugins/initialize/index.js +4 -3
  12. package/dist/cjs/plugins/serverBuild.js +3 -2
  13. package/dist/esm/builder/generator/createBuilderProviderConfig.mjs +5 -1
  14. package/dist/esm/bundleDocs.mjs +62 -0
  15. package/dist/esm/commands/build.mjs +2 -1
  16. package/dist/esm/commands/deploy.mjs +4 -2
  17. package/dist/esm/commands/index.mjs +0 -4
  18. package/dist/esm/config/default.mjs +2 -0
  19. package/dist/esm/index.mjs +15 -1
  20. package/dist/esm/plugins/analyze/index.mjs +2 -2
  21. package/dist/esm/plugins/analyze/utils.mjs +3 -2
  22. package/dist/esm/plugins/initialize/index.mjs +4 -3
  23. package/dist/esm/plugins/serverBuild.mjs +3 -2
  24. package/dist/esm-node/builder/generator/createBuilderProviderConfig.mjs +5 -1
  25. package/dist/esm-node/bundleDocs.mjs +63 -0
  26. package/dist/esm-node/commands/build.mjs +2 -1
  27. package/dist/esm-node/commands/deploy.mjs +4 -2
  28. package/dist/esm-node/commands/index.mjs +0 -4
  29. package/dist/esm-node/config/default.mjs +2 -0
  30. package/dist/esm-node/index.mjs +15 -1
  31. package/dist/esm-node/plugins/analyze/index.mjs +2 -2
  32. package/dist/esm-node/plugins/analyze/utils.mjs +3 -2
  33. package/dist/esm-node/plugins/initialize/index.mjs +4 -3
  34. package/dist/esm-node/plugins/serverBuild.mjs +3 -2
  35. package/dist/types/bundleDocs.d.ts +20 -0
  36. package/dist/types/commands/deploy.d.ts +2 -1
  37. package/dist/types/index.d.ts +4 -1
  38. package/dist/types/plugins/analyze/utils.d.ts +1 -1
  39. package/dist/types/types/config/dev.d.ts +6 -0
  40. package/docs/apis/app/commands.md +241 -0
  41. package/docs/apis/app/hooks/api/lambda.md +9 -0
  42. package/docs/apis/app/hooks/config/favicon.md +24 -0
  43. package/docs/apis/app/hooks/config/html.md +5 -0
  44. package/docs/apis/app/hooks/config/icon.md +24 -0
  45. package/docs/apis/app/hooks/config/mock.md +6 -0
  46. package/docs/apis/app/hooks/config/public.md +26 -0
  47. package/docs/apis/app/hooks/config/upload.md +50 -0
  48. package/docs/apis/app/hooks/modern-config.md +5 -0
  49. package/docs/apis/app/hooks/server/server.md +5 -0
  50. package/docs/apis/app/hooks/shared.md +3 -0
  51. package/docs/apis/app/hooks/src/app.md +30 -0
  52. package/docs/apis/app/hooks/src/entry.md +34 -0
  53. package/docs/apis/app/hooks/src/entry.server.md +51 -0
  54. package/docs/apis/app/hooks/src/modern.runtime.md +5 -0
  55. package/docs/apis/app/hooks/src/routes.md +86 -0
  56. package/docs/apis/app/hooks/src/server.md +3 -0
  57. package/docs/apis/app/runtime/bff/use-hono-context.md +27 -0
  58. package/docs/apis/app/runtime/core/create-root.md +19 -0
  59. package/docs/apis/app/runtime/core/render.md +39 -0
  60. package/docs/apis/app/runtime/core/runtime-context.md +156 -0
  61. package/docs/apis/app/runtime/router/router.md +280 -0
  62. package/docs/apis/app/runtime/ssr/no-ssr.md +35 -0
  63. package/docs/apis/app/runtime/ssr/renderStreaming.md +67 -0
  64. package/docs/apis/app/runtime/ssr/renderString.md +60 -0
  65. package/docs/apis/app/runtime/ssr/requestHandler.md +44 -0
  66. package/docs/apis/app/runtime/utility/css-in-js.md +40 -0
  67. package/docs/apis/app/runtime/utility/head.md +35 -0
  68. package/docs/apis/app/runtime/utility/loadable.md +82 -0
  69. package/docs/community/blog/2022-0708-updates.md +91 -0
  70. package/docs/community/blog/2022-0910-updates.md +76 -0
  71. package/docs/community/blog/overview.md +63 -0
  72. package/docs/community/blog/v2-release-note.md +238 -0
  73. package/docs/community/blog/v3-release-note.md +622 -0
  74. package/docs/community/contributing-guide.md +253 -0
  75. package/docs/community/releases.md +27 -0
  76. package/docs/community/showcase.md +34 -0
  77. package/docs/community/team.md +14 -0
  78. package/docs/configure/app/bff/cross-project.md +20 -0
  79. package/docs/configure/app/bff/prefix.md +29 -0
  80. package/docs/configure/app/builder-plugins.md +66 -0
  81. package/docs/configure/app/dev/asset-prefix.md +13 -0
  82. package/docs/configure/app/dev/before-start-url.md +17 -0
  83. package/docs/configure/app/dev/client.md +41 -0
  84. package/docs/configure/app/dev/hmr.md +10 -0
  85. package/docs/configure/app/dev/host.md +18 -0
  86. package/docs/configure/app/dev/https.md +77 -0
  87. package/docs/configure/app/dev/lazy-compilation.md +39 -0
  88. package/docs/configure/app/dev/live-reload.md +10 -0
  89. package/docs/configure/app/dev/mock-dir.md +31 -0
  90. package/docs/configure/app/dev/progress-bar.md +19 -0
  91. package/docs/configure/app/dev/server.md +124 -0
  92. package/docs/configure/app/dev/setup-middlewares.md +32 -0
  93. package/docs/configure/app/dev/start-url.md +48 -0
  94. package/docs/configure/app/dev/watch-files.md +27 -0
  95. package/docs/configure/app/dev/write-to-disk.md +10 -0
  96. package/docs/configure/app/experiments/source-build.md +31 -0
  97. package/docs/configure/app/html/app-icon.md +28 -0
  98. package/docs/configure/app/html/crossorigin.md +10 -0
  99. package/docs/configure/app/html/favicon.md +16 -0
  100. package/docs/configure/app/html/inject.md +10 -0
  101. package/docs/configure/app/html/meta.md +24 -0
  102. package/docs/configure/app/html/mount-id.md +10 -0
  103. package/docs/configure/app/html/output-structure.md +10 -0
  104. package/docs/configure/app/html/script-loading.md +10 -0
  105. package/docs/configure/app/html/tags.md +15 -0
  106. package/docs/configure/app/html/template-parameters.md +33 -0
  107. package/docs/configure/app/html/template.md +10 -0
  108. package/docs/configure/app/html/title.md +18 -0
  109. package/docs/configure/app/output/asset-prefix.md +11 -0
  110. package/docs/configure/app/output/assets-retry.md +77 -0
  111. package/docs/configure/app/output/charset.md +10 -0
  112. package/docs/configure/app/output/clean-dist-path.md +16 -0
  113. package/docs/configure/app/output/convert-to-rem.md +79 -0
  114. package/docs/configure/app/output/copy.md +10 -0
  115. package/docs/configure/app/output/css-modules.md +48 -0
  116. package/docs/configure/app/output/data-uri-limit.md +26 -0
  117. package/docs/configure/app/output/disable-css-module-extension.md +55 -0
  118. package/docs/configure/app/output/disable-inline-runtime-chunk.md +41 -0
  119. package/docs/configure/app/output/disable-svgr.md +16 -0
  120. package/docs/configure/app/output/disable-ts-checker.md +49 -0
  121. package/docs/configure/app/output/dist-path.md +43 -0
  122. package/docs/configure/app/output/enable-asset-manifest.md +36 -0
  123. package/docs/configure/app/output/enable-css-module-tsdeclaration.md +28 -0
  124. package/docs/configure/app/output/enable-inline-route-manifests.md +16 -0
  125. package/docs/configure/app/output/externals.md +20 -0
  126. package/docs/configure/app/output/filename-hash.md +10 -0
  127. package/docs/configure/app/output/filename.md +55 -0
  128. package/docs/configure/app/output/inject-styles.md +10 -0
  129. package/docs/configure/app/output/inline-scripts.md +29 -0
  130. package/docs/configure/app/output/inline-styles.md +29 -0
  131. package/docs/configure/app/output/legal-comments.md +18 -0
  132. package/docs/configure/app/output/minify.md +22 -0
  133. package/docs/configure/app/output/override-browserslist.md +22 -0
  134. package/docs/configure/app/output/polyfill.md +12 -0
  135. package/docs/configure/app/output/source-map.md +30 -0
  136. package/docs/configure/app/output/split-route-chunks.md +16 -0
  137. package/docs/configure/app/output/ssg.md +81 -0
  138. package/docs/configure/app/output/ssgByEntries.md +90 -0
  139. package/docs/configure/app/output/svg-default-export.md +30 -0
  140. package/docs/configure/app/output/temp-dir.md +20 -0
  141. package/docs/configure/app/performance/build-cache.md +39 -0
  142. package/docs/configure/app/performance/chunk-split.md +40 -0
  143. package/docs/configure/app/performance/dns-prefetch.md +15 -0
  144. package/docs/configure/app/performance/preconnect.md +16 -0
  145. package/docs/configure/app/performance/prefetch.md +21 -0
  146. package/docs/configure/app/performance/preload.md +23 -0
  147. package/docs/configure/app/performance/print-file-size.md +40 -0
  148. package/docs/configure/app/performance/profile.md +10 -0
  149. package/docs/configure/app/performance/remove-console.md +10 -0
  150. package/docs/configure/app/performance/remove-moment-locale.md +10 -0
  151. package/docs/configure/app/plugins.md +59 -0
  152. package/docs/configure/app/resolve/alias-strategy.md +10 -0
  153. package/docs/configure/app/resolve/alias.md +9 -0
  154. package/docs/configure/app/resolve/condition-names.md +13 -0
  155. package/docs/configure/app/resolve/dedupe.md +9 -0
  156. package/docs/configure/app/resolve/extensions.md +13 -0
  157. package/docs/configure/app/runtime/0-intro.md +58 -0
  158. package/docs/configure/app/runtime/plugins.md +58 -0
  159. package/docs/configure/app/runtime/router.md +35 -0
  160. package/docs/configure/app/security/check-syntax.md +69 -0
  161. package/docs/configure/app/security/nonce.md +15 -0
  162. package/docs/configure/app/security/sri.md +20 -0
  163. package/docs/configure/app/server/base-url.md +26 -0
  164. package/docs/configure/app/server/port.md +18 -0
  165. package/docs/configure/app/server/public-routes.md +22 -0
  166. package/docs/configure/app/server/routes.md +86 -0
  167. package/docs/configure/app/server/rsc.md +26 -0
  168. package/docs/configure/app/server/ssr-by-entries.md +25 -0
  169. package/docs/configure/app/server/ssr.md +78 -0
  170. package/docs/configure/app/server/tsconfig-path.md +59 -0
  171. package/docs/configure/app/source/alias-strategy.md +14 -0
  172. package/docs/configure/app/source/alias.md +23 -0
  173. package/docs/configure/app/source/config-dir.md +20 -0
  174. package/docs/configure/app/source/decorators.md +25 -0
  175. package/docs/configure/app/source/define.md +16 -0
  176. package/docs/configure/app/source/disable-default-entries.md +28 -0
  177. package/docs/configure/app/source/enable-async-entry.md +54 -0
  178. package/docs/configure/app/source/enable-async-pre-entry.md +26 -0
  179. package/docs/configure/app/source/entries-dir.md +35 -0
  180. package/docs/configure/app/source/entries.md +179 -0
  181. package/docs/configure/app/source/exclude.md +10 -0
  182. package/docs/configure/app/source/global-vars.md +106 -0
  183. package/docs/configure/app/source/include.md +36 -0
  184. package/docs/configure/app/source/main-entry-name.md +24 -0
  185. package/docs/configure/app/source/pre-entry.md +10 -0
  186. package/docs/configure/app/source/react-compiler.md +68 -0
  187. package/docs/configure/app/source/transform-import.md +27 -0
  188. package/docs/configure/app/split-chunks.md +17 -0
  189. package/docs/configure/app/tools/autoprefixer.md +44 -0
  190. package/docs/configure/app/tools/bundler-chain.md +26 -0
  191. package/docs/configure/app/tools/css-extract.md +33 -0
  192. package/docs/configure/app/tools/css-loader.md +17 -0
  193. package/docs/configure/app/tools/dev-server.md +113 -0
  194. package/docs/configure/app/tools/html-plugin.md +41 -0
  195. package/docs/configure/app/tools/less.md +81 -0
  196. package/docs/configure/app/tools/lightningcss-loader.md +35 -0
  197. package/docs/configure/app/tools/minify-css.md +53 -0
  198. package/docs/configure/app/tools/postcss.md +34 -0
  199. package/docs/configure/app/tools/rspack.md +10 -0
  200. package/docs/configure/app/tools/sass.md +78 -0
  201. package/docs/configure/app/tools/style-loader.md +10 -0
  202. package/docs/configure/app/tools/swc.md +65 -0
  203. package/docs/configure/app/tools/ts-checker.md +109 -0
  204. package/docs/configure/app/usage.md +276 -0
  205. package/docs/guides/advanced-features/bff/cross-project.md +109 -0
  206. package/docs/guides/advanced-features/bff/extend-server.md +120 -0
  207. package/docs/guides/advanced-features/bff/frameworks.md +124 -0
  208. package/docs/guides/advanced-features/bff/function.md +314 -0
  209. package/docs/guides/advanced-features/bff/operators.md +554 -0
  210. package/docs/guides/advanced-features/bff/sdk.md +116 -0
  211. package/docs/guides/advanced-features/bff/upload.md +101 -0
  212. package/docs/guides/advanced-features/bff.md +18 -0
  213. package/docs/guides/advanced-features/build-performance.md +130 -0
  214. package/docs/guides/advanced-features/compatibility.md +120 -0
  215. package/docs/guides/advanced-features/international/advanced.md +128 -0
  216. package/docs/guides/advanced-features/international/api.md +231 -0
  217. package/docs/guides/advanced-features/international/best-practices.md +286 -0
  218. package/docs/guides/advanced-features/international/configuration.md +227 -0
  219. package/docs/guides/advanced-features/international/locale-detection.md +126 -0
  220. package/docs/guides/advanced-features/international/quick-start.md +128 -0
  221. package/docs/guides/advanced-features/international/resource-loading.md +154 -0
  222. package/docs/guides/advanced-features/international/routing.md +130 -0
  223. package/docs/guides/advanced-features/international.md +27 -0
  224. package/docs/guides/advanced-features/low-level.md +46 -0
  225. package/docs/guides/advanced-features/page-performance/code-split.md +77 -0
  226. package/docs/guides/advanced-features/page-performance/inline-assets.md +159 -0
  227. package/docs/guides/advanced-features/page-performance/optimize-bundle.md +97 -0
  228. package/docs/guides/advanced-features/page-performance/react-compiler.md +69 -0
  229. package/docs/guides/advanced-features/server-monitor/logger.md +41 -0
  230. package/docs/guides/advanced-features/server-monitor/metrics.md +58 -0
  231. package/docs/guides/advanced-features/server-monitor/monitors.md +242 -0
  232. package/docs/guides/advanced-features/source-build.md +164 -0
  233. package/docs/guides/advanced-features/web-server.md +288 -0
  234. package/docs/guides/basic-features/alias.md +102 -0
  235. package/docs/guides/basic-features/css/css-in-js.md +72 -0
  236. package/docs/guides/basic-features/css/css-modules.md +212 -0
  237. package/docs/guides/basic-features/css/css.md +27 -0
  238. package/docs/guides/basic-features/css/tailwindcss.md +27 -0
  239. package/docs/guides/basic-features/data/data-cache.md +510 -0
  240. package/docs/guides/basic-features/data/data-fetch.md +415 -0
  241. package/docs/guides/basic-features/data/data-write.md +227 -0
  242. package/docs/guides/basic-features/debug/mock.md +109 -0
  243. package/docs/guides/basic-features/debug/proxy.md +21 -0
  244. package/docs/guides/basic-features/debug/rsdoctor.md +62 -0
  245. package/docs/guides/basic-features/debug/using-storybook.md +112 -0
  246. package/docs/guides/basic-features/deploy.md +458 -0
  247. package/docs/guides/basic-features/env-vars.md +177 -0
  248. package/docs/guides/basic-features/html.md +255 -0
  249. package/docs/guides/basic-features/output-files.md +141 -0
  250. package/docs/guides/basic-features/render/before-render.md +108 -0
  251. package/docs/guides/basic-features/render/overview.md +47 -0
  252. package/docs/guides/basic-features/render/rsc.md +525 -0
  253. package/docs/guides/basic-features/render/ssg.md +228 -0
  254. package/docs/guides/basic-features/render/ssr-cache.md +201 -0
  255. package/docs/guides/basic-features/render/ssr.md +321 -0
  256. package/docs/guides/basic-features/render/streaming-ssr.md +264 -0
  257. package/docs/guides/basic-features/routes/config-routes.md +426 -0
  258. package/docs/guides/basic-features/routes/routes.md +498 -0
  259. package/docs/guides/basic-features/static-assets/json-files.md +120 -0
  260. package/docs/guides/basic-features/static-assets/svg-assets.md +168 -0
  261. package/docs/guides/basic-features/static-assets/wasm-assets.md +62 -0
  262. package/docs/guides/basic-features/static-assets.md +160 -0
  263. package/docs/guides/basic-features/testing/playwright.md +120 -0
  264. package/docs/guides/basic-features/testing/rstest.md +251 -0
  265. package/docs/guides/concept/builder.md +37 -0
  266. package/docs/guides/concept/entries.md +319 -0
  267. package/docs/guides/concept/server.md +35 -0
  268. package/docs/guides/get-started/ai-coding-agents.md +58 -0
  269. package/docs/guides/get-started/glossary.md +63 -0
  270. package/docs/guides/get-started/introduction.md +36 -0
  271. package/docs/guides/get-started/quick-start.md +236 -0
  272. package/docs/guides/get-started/tech-stack.md +82 -0
  273. package/docs/guides/get-started/upgrade.md +123 -0
  274. package/docs/guides/topic-detail/module-federation/application.md +116 -0
  275. package/docs/guides/topic-detail/module-federation/deploy.md +104 -0
  276. package/docs/guides/topic-detail/module-federation/i18n.md +670 -0
  277. package/docs/guides/topic-detail/module-federation/introduce.md +35 -0
  278. package/docs/guides/topic-detail/module-federation/ssr.md +118 -0
  279. package/docs/guides/topic-detail/module-federation/usage.md +219 -0
  280. package/docs/guides/troubleshooting/builder.md +110 -0
  281. package/docs/guides/troubleshooting/cli.md +35 -0
  282. package/docs/guides/troubleshooting/dependencies.md +119 -0
  283. package/docs/guides/troubleshooting/hmr.md +144 -0
  284. package/docs/guides/upgrade/config.md +963 -0
  285. package/docs/guides/upgrade/entry.md +463 -0
  286. package/docs/guides/upgrade/other.md +183 -0
  287. package/docs/guides/upgrade/overview.md +33 -0
  288. package/docs/guides/upgrade/tailwindcss.md +91 -0
  289. package/docs/guides/upgrade/web-server.md +109 -0
  290. package/docs/index.md +33 -0
  291. package/docs/llms.txt +285 -0
  292. package/docs/plugin/cli-plugins/api.md +573 -0
  293. package/docs/plugin/cli-plugins/life-cycle.md +2 -0
  294. package/docs/plugin/introduction.md +152 -0
  295. package/docs/plugin/official/cli-plugins/plugin-bff.md +5 -0
  296. package/docs/plugin/official/cli-plugins/plugin-ssg.md +5 -0
  297. package/docs/plugin/official/cli-plugins/plugin-styled-components.md +5 -0
  298. package/docs/plugin/official/cli-plugins.md +4 -0
  299. package/docs/plugin/plugin-system.md +238 -0
  300. package/docs/plugin/runtime-plugins/api.md +194 -0
  301. package/docs/plugin/runtime-plugins/life-cycle.md +2 -0
  302. package/docs/plugin/server-plugins/api.md +209 -0
  303. package/docs/plugin/server-plugins/life-cycle.md +13 -0
  304. package/docs/tutorials/examples/csr-auth.md +9 -0
  305. package/docs/tutorials/foundations/introduction.md +16 -0
  306. package/package.json +46 -13
package/docs/guides/basic-features/html.md ADDED
@@ -0,0 +1,255 @@
1
+ # HTML Template
2
+
3
+ Modern.js provides **JSX syntax** and **HTML(EJS) syntax** to customize the HTML template.
4
+
5
+ ## JSX Syntax
6
+
7
+ According to Modern.js conventions, you can create a `Document.tsx` file under `src/` or the entry directory and default export a component. The rendering result of this component can be used as the HTML template of the entry.
8
+
9
+ For example, consider the following directory structure:
10
+
11
+ ```bash
12
+ .
13
+ └── src
14
+ ├── Document.tsx
15
+ ├── entry-a
16
+ │ ├── Document.tsx
17
+ │ └── routes
18
+ ├── entry-b
19
+ │ └── routes
20
+ └── modern-app-env.d.ts
21
+ ```
22
+
23
+ `entry-a` will use the `Document.tsx` file under the current entry as the template. If there is no `Document.tsx` file under the current entry, like `entry-b`, it will look for the `Document.tsx` file under the root directory.
24
+
25
+ If not found, default template will be used.
26
+
27
+ :::tip
28
+ `Document.tsx` is compiled at build time by the Modern.js Document plugin using a dedicated Rspack child compiler targeting Node.js, and is rendered to a string with `renderToStaticMarkup` as the HTML template content, similar to [Static Site Generation](/guides/basic-features/render/ssg.md). The HTML template module is not part of the page bundler compilation, so React Hooks in the component will not run in the browser runtime, and non-JavaScript assets such as images cannot be resolved or imported.
29
+ :::
30
+
31
+ ### HTML Components
32
+
33
+ Modern.js provides some components for rendering pages to help developers generate templates. These components can be used from `@modern-js/runtime/document`:
34
+
35
+ ```tsx
36
+ import { Html, Body, Root, Head, Scripts } from '@modern-js/runtime/document';
37
+ ```
38
+
39
+ - `Html`: provide the ability of native HTML Element and render necessary components that the developer did not add by default. `<Head>` and `<Body>` must exist, and other components can be assembled as needed.
40
+
41
+ - `Body`: provide the ability of native Body Element and needs to contain the `<Root>` component internally. It also supports other elements as child elements at the same time, such as adding footers.
42
+
43
+ - `Root`: the root node `<div id='root'></div>` to be rendered. The default id of the root node is `id = 'root'`. You can set `props.rootId` to change the id attribute. Child components can be added and will be rendered in the HTML template. After React rendering is complete, it will be overwritten and is generally used to implement global Loading.
44
+
45
+ - `Head`: provide the ability of native Head Element and automatically fills in `<meta>` and `<Scripts>` components.
46
+
47
+ - `Scripts`: Used to control the placement of the `<script>` tags generated by the build. By default, they are placed within the `<Head>` component.
48
+
49
+ - `Comment`: retain user-written comments like `<!-- gateway -->` and outputs them to the rendered HTML.
50
+
51
+ ### Template Parameters
52
+
53
+ Because it is in JSX format, various variables can be used freely in the component to assign values to various custom components in `Document.tsx`.
54
+
55
+ Modern.js also provides `DocumentContext` to provide some configuration and environment parameters for easy access. The main parameters are:
56
+
57
+ - `processEnv`: provides the `process.env` during the build.
58
+ - `config`: the configuration of the Modern.js project. Currently, only the output configuration is exposed.
59
+ - `entryName`: the current entry name.
60
+ - `templateParams`: parameters of HTML template (compatible with traditional templates, so it's not recommended for use).
61
+
62
+ ### Basic Example
63
+
64
+ ```tsx
65
+ import React, { useContext } from 'react';
66
+ import {
67
+ Html,
68
+ Root,
69
+ Head,
70
+ Body,
71
+ Comment,
72
+ DocumentContext,
73
+ } from '@modern-js/runtime/document';
74
+
75
+ export default function Document(): React.ReactElement {
76
+ // the params provide by DocumentContext
77
+ const {
78
+ config: { output: htmlConfig },
79
+ entryName,
80
+ templateParams,
81
+ } = useContext(DocumentContext);
82
+
83
+ return (
84
+ <Html>
85
+ <Head>
86
+ <link href="https://modernjs.dev" />
87
+ <Comment>{'<!-- Need a Comment -->'}</Comment>
88
+ </Head>
89
+ <Body>
90
+ <Root rootId="root">
91
+ <h1 style={{ color: 'red' }}>Some Params: </h1>
92
+ <h2>entryName: {entryName}</h2>
93
+ <h2>title: {htmlConfig.title}</h2>
94
+ <h2>rootId: {templateParams.mountId}</h2>
95
+ </Root>
96
+ <h1>bottom</h1>
97
+ </Body>
98
+ </Html>
99
+ );
100
+ }
101
+ ```
102
+
103
+ The above JSX components will generate the following HTML template:
104
+
105
+ ```html
106
+ <!DOCTYPE html>
107
+ <html>
108
+ <head>
109
+ <meta charset="utf-8" />
110
+ <meta
111
+ name="viewport"
112
+ content="width=device-width, initial-scale=1.0, shrink-to-fit=no, viewport-fit=cover, minimum-scale=1.0, maximum-scale=1.0, user-scalable=no"
113
+ />
114
+ <meta http-equiv="x-ua-compatible" content="ie=edge" />
115
+ <meta name="renderer" content="webkit" />
116
+ <meta name="layoutmode" content="standard" />
117
+ <meta name="imagemode" content="force" />
118
+ <meta name="wap-font-scale" content="no" />
119
+ <meta name="format-detection" content="telephone=no" />
120
+ <link rel="icon" href="/a.icon" />
121
+ <script defer src="/static/js/builder-runtime.js"></script>
122
+ <script defer src="/static/js/lib-react.js"></script>
123
+ <script defer src="/static/js/lib-polyfill.js"></script>
124
+ <script defer src="/static/js/lib-router.js"></script>
125
+ <script defer src="/static/js/main.js"></script>
126
+ <link href="https://modernjs.dev" />
127
+ <!-- Need a Comment -->
128
+ </head>
129
+
130
+ <body>
131
+ <div id="root">
132
+ <!--<?- html ?>-->
133
+ <h1 style="color:red">Some Params:</h1>
134
+ <h2>entryName: main</h2>
135
+ <h2>title：</h2>
136
+ <h2>rootId: root</h2>
137
+ </div>
138
+ <h1>bottom</h1>
139
+ <!--<?- chunksMap.js ?>-->
140
+ <!--<?- SSRDataScript ?>-->
141
+ </body>
142
+ </html>
143
+ ```
144
+
145
+ ### Scripts Component Example
146
+
147
+ You can use the `<Scripts>` component to insert the `<script>` tags generated by the build inside the `<body>` tag:
148
+
149
+ ```tsx
150
+ import React from 'react';
151
+ import { Html, Root, Head, Body, Scripts } from '@modern-js/runtime/document';
152
+
153
+ export default function Document(): React.ReactElement {
154
+ return (
155
+ <Html>
156
+ <Head></Head>
157
+ <Body>
158
+ <Root rootId="root"></Root>
159
+ <Scripts />
160
+ </Body>
161
+ </Html>
162
+ );
163
+ }
164
+ ```
165
+
166
+ ## HTML Syntax
167
+
168
+ Modern.js also supports generating HTML files using HTML (EJS) syntax.
169
+
170
+ By default, Modern.js projects come with a built-in HTML template for generating HTML code. If you need to customize the HTML template, you can use two methods: **Custom HTML Fragments** and **Fully Custom HTML Templates**.
171
+
172
+ ### Custom HTML Fragments
173
+
174
+ Under the application root directory, create the `config/html/` directory, which supports the creation of four types of HTML fragments:
175
+
176
+ - `top.html`
177
+ - `head.html`
178
+ - `body.html`
179
+ - `bottom.html`
180
+
181
+ **These fragments will be injected into the default HTML template according to their positions.**
182
+
183
+ ```xml
184
+ <!DOCTYPE html>
185
+ <html>
186
+ <head>
187
+ <%= topTemplate %>
188
+ <%= headTemplate %>
189
+ {/* rspack inject css */}
190
+ </head>
191
+ <body>
192
+ <noscript>
193
+ We're sorry but react app doesn't work properly without JavaScript
194
+ enabled. Please enable it to continue.
195
+ </noscript>
196
+ <div id="<%= mountId %>"></div>
197
+ <%= bodyTemplate %>
198
+ {/* rspack inject js */}
199
+ {/* <?- bottomTemplate ?> */}
200
+ </body>
201
+ </html>
202
+ ```
203
+
204
+ HTML fragments support the use of [Lodash template](https://lodash.com/docs/4.17.15#template).
205
+
206
+ For example, to insert an external script in `body.html`:
207
+
208
+ ```html title="config/html/body.html"
209
+ <script src="//example.com/assets/a.js"></script>
210
+ ```
211
+
212
+ :::info
213
+ The implementation of custom HTML fragments is to merge the fragments with the built-in template. Since the `<title>` already exists in the default template, the title tag in the custom HTML template will not take effect. Please use [html.title](/configure/app/html/title.md) to modify the page title.
214
+
215
+ :::
216
+
217
+ ### Customize the entire HTML Template
218
+
219
+ In some cases, HTML fragments may not offer enough control. Modern.js provides a fully customized way.
220
+
221
+ :::caution Note
222
+ It is generally not recommended to directly override the default HTML template, as some functional options may be lost. If it is truly necessary to customize the entire HTML template, it is recommended to modify based on the built-in template as needed.
223
+
224
+ :::
225
+
226
+ Under the `config/html/` directory, create an `index.html` file that will replace the default HTML template.
227
+
228
+ :::info
229
+ The default HTML template can be viewed in `node_modules/.modern-js/${entryName}/index.html`.
230
+
231
+ :::
232
+
233
+ ### Template Parameters
234
+
235
+ The parameters used in the template can be defined by the [html.templateParameters](/configure/app/html/template-parameters.md) configuration.
236
+
237
+ ### Config By Entry
238
+
239
+ The HTML fragments in the `config/html/` directory take effect for all entries in the application. If you want to customize HTML fragments by entry, you can create a directory named after the **entry name** under the `config/html/` directory, and then customize the HTML fragments in this directory.
240
+
241
+ For example, the following HTML fragments are only effective for the `entry1` entry:
242
+
243
+ ```bash
244
+ .
245
+ ├── config/
246
+ │ └── html/
247
+ │ └── entry1
248
+ │ ├── head.html
249
+ │ └── body.html
250
+ └── src/
251
+ ├── entry1/
252
+ │ └── routes
253
+ └── entry2/
254
+ └── routes
255
+ ```
package/docs/guides/basic-features/output-files.md ADDED
@@ -0,0 +1,141 @@
1
+ # Output Files
2
+
3
+ This chapter will introduces the directory structure of output files and how to control the output directory of different types of files.
4
+
5
+ ## Default Directory Structure
6
+
7
+ The following is a basic directory for output files. By default, the compiled files will be output in the `dist` directory of current project.
8
+
9
+ ```bash
10
+ dist
11
+ ├── static
12
+ │ ├── css
13
+ │ │ ├── [name].[hash].css
14
+ │ │ └── [name].[hash].css.map
15
+ │ │
16
+ │ └── js
17
+ │ ├── [name].[hash].js
18
+ │ ├── [name].[hash].js.LICENSE.txt
19
+ │ └── [name].[hash].js.map
20
+ │
21
+ └── html
22
+ └── [name]
23
+ └── index.html
24
+ ```
25
+
26
+ The most common output files are HTML files, JS files, and CSS files:
27
+
28
+ - HTML files: default output to the `html` directory.
29
+ - JS files: default output to `static/js` directory,
30
+ - CSS files: default output to the `static/css` directory.
31
+
32
+ In addition, JS files and CSS files sometimes generate some related files:
33
+
34
+ - License files: contains open source license, which is output to the same level directory of the JS file, and adds `.LICENSE.txt` suffix.
35
+ - Source Map files: contains the source code mappings, which is output to the same level directory of JS files and CSS files, and adds a `.map` suffix.
36
+
37
+ In the filename, `[name]` represents the entry name corresponding to this file, such as `index`, `main`. `[hash]` is the hash value generated based on the content of the file.
38
+
39
+ ## Modify the Directory
40
+
41
+ Modern.js provides some configs to modify the directory or filename, you can:
42
+
43
+ - Modify the filename through [output.filename](/configure/app/output/filename.md).
44
+ - Modify the output path of through [output.distPath](/configure/app/output/dist-path.md).
45
+ - Modify the license file through [output.legalComments](/configure/app/output/legal-comments.md).
46
+ - Remove Source Map file through [output.sourceMap](/configure/app/output/source-map.md).
47
+ - Remove the folder corresponding to the HTML files through [html.outputStructure](/configure/app/html/output-structure.md).
48
+
49
+ ## Static Assets
50
+
51
+ When you import static assets such as images, SVG, fonts, media, etc. in the code, they will also be output to the `dist/static` directory, and automatically assigned to the corresponding subdirectories according to the file type:
52
+
53
+ ```bash
54
+ dist
55
+ └── static
56
+ ├── image
57
+ │ └── foo.[hash].png
58
+ │
59
+ ├── svg
60
+ │ └── bar.[hash].svg
61
+ │
62
+ ├── font
63
+ │ └── baz.[hash].woff2
64
+ │
65
+ └── media
66
+ └── qux.[hash].mp4
67
+ ```
68
+
69
+ You can use the [output.distPath](/configure/app/output/dist-path.md) config to uniformly input these static assets into a directory, for example, output to the `assets` directory:
70
+
71
+ ```ts
72
+ export default {
73
+ output: {
74
+ distPath: {
75
+ image: 'assets',
76
+ svg: 'assets',
77
+ font: 'assets',
78
+ media: 'assets',
79
+ },
80
+ },
81
+ };
82
+ ```
83
+
84
+ The above config produces the following directory structure:
85
+
86
+ ```bash
87
+ dist
88
+ └── assets
89
+ ├── foo.[hash].png
90
+ ├── bar.[hash].svg
91
+ ├── baz.[hash].woff2
92
+ └── qux.[hash].mp4
93
+ ```
94
+
95
+ ## Flatten the Directory
96
+
97
+ Sometimes you don't want the dist directory to have too many levels, you can set the directory to an empty string to flatten the generated directory.
98
+
99
+ See the example below:
100
+
101
+ ```ts
102
+ export default {
103
+ output: {
104
+ distPath: {
105
+ js: '',
106
+ css: '',
107
+ html: '',
108
+ },
109
+ },
110
+ html: {
111
+ outputStructure: 'flat',
112
+ }
113
+ };
114
+ ```
115
+
116
+ The above config produces the following directory structure:
117
+
118
+ ```bash
119
+ dist
120
+ ├── [name].[hash].css
121
+ ├── [name].[hash].css.map
122
+ ├── [name].[hash].js
123
+ ├── [name].[hash].js.map
124
+ └── [name].html
125
+ ```
126
+
127
+ ## Not Written to Disk
128
+
129
+ By default, Modern.js will write the generated files to disk, so developers can view the file content or configure proxy rules for static assets.
130
+
131
+ In development, you can choose to keep the generated files in the Dev Server's memory to reduce the overhead of file operations.
132
+
133
+ Just set the `dev.writeToDisk` config to `false`:
134
+
135
+ ```ts
136
+ export default {
137
+ dev: {
138
+ writeToDisk: false,
139
+ },
140
+ };
141
+ ```
package/docs/guides/basic-features/render/before-render.md ADDED
@@ -0,0 +1,108 @@
1
+ # Render Preprocessing
2
+
3
+ In certain scenarios, applications need to perform preprocessing operations before rendering. Modern.js recommends using **[Runtime Plugins](/plugin/introduction.md#runtime-plugins)** to implement this type of logic.
4
+
5
+ ## Defining a Runtime Plugin
6
+
7
+ ```ts
8
+ import type { RuntimePlugin } from '@modern-js/runtime';
9
+
10
+ const myRuntimePlugin = (): RuntimePlugin => ({
11
+ name: 'my-runtime-plugin',
12
+ setup: api => {
13
+ api.onBeforeRender(context => {
14
+ // Logic to execute before rendering
15
+ console.log('Before rendering:', context);
16
+ });
17
+ },
18
+ });
19
+
20
+ export default myRuntimePlugin;
21
+ ```
22
+
23
+ ## Registering the Plugin
24
+
25
+ Register the plugin in your project's `src/modern.runtime.ts` file:
26
+
27
+ ```ts
28
+ import { defineRuntimeConfig } from '@modern-js/runtime';
29
+ import myRuntimePlugin from './plugins/myRuntimePlugin';
30
+
31
+ export default defineRuntimeConfig({
32
+ plugins: [myRuntimePlugin()],
33
+ });
34
+ ```
35
+
36
+ ## Use Case -- Global Data Injection
37
+
38
+ Through the `context` parameter of the `onBeforeRender` hook, you can inject global data into your application. Application components can access this data using the `use(RuntimeContext)` Hook.
39
+
40
+ :::info
41
+
42
+ This feature is particularly useful in the following scenarios:
43
+
44
+ - Applications requiring page-level preliminary data
45
+ - Custom data injection workflows
46
+ - Framework migration scenarios (e.g., migrating from Next.js)
47
+
48
+ :::
49
+
50
+ **Defining a Data Injection Plugin**
51
+
52
+ ```ts
53
+ import type { RuntimePlugin } from '@modern-js/runtime';
54
+
55
+ const dataInjectionPlugin = (): RuntimePlugin => ({
56
+ name: 'data-injection-plugin',
57
+ setup: api => {
58
+ api.onBeforeRender(context => {
59
+ // Inject data into the context
60
+ context.message = 'Hello World';
61
+ });
62
+ },
63
+ });
64
+
65
+ export default dataInjectionPlugin;
66
+ ```
67
+
68
+ **Using Injected Data in Components**
69
+
70
+ ```tsx
71
+ import { use } from 'react';
72
+ import { RuntimeContext } from '@modern-js/runtime';
73
+
74
+ export default function MyComponent() {
75
+ const context = use(RuntimeContext);
76
+ const { message } = context;
77
+
78
+ return <div>{message}</div>;
79
+ }
80
+ ```
81
+
82
+ **Using with SSR**
83
+
84
+ In SSR scenarios, the browser can access data injected via `onBeforeRender` during server-side rendering. Developers can decide whether to re-fetch data on the browser side to override server data based on their requirements.
85
+
86
+ ```ts
87
+ import type { RuntimePlugin } from '@modern-js/runtime';
88
+
89
+ const dataInjectionPlugin = (): RuntimePlugin => ({
90
+ name: 'data-injection-plugin',
91
+ setup: api => {
92
+ api.onBeforeRender(context => {
93
+ if (process.env.MODERN_TARGET === 'node') {
94
+ // Set data during server-side rendering
95
+ context.message = 'Hello World By Server';
96
+ } else {
97
+ // Check data during client-side rendering
98
+ if (!context.message) {
99
+ // If server data is not available, set client data
100
+ context.message = 'Hello World By Client';
101
+ }
102
+ }
103
+ });
104
+ },
105
+ });
106
+
107
+ export default dataInjectionPlugin;
108
+ ```
package/docs/guides/basic-features/render/overview.md ADDED
@@ -0,0 +1,47 @@
1
+ # Rendering Mode Overview
2
+
3
+ Modern.js supports multiple rendering modes, and different rendering modes are suitable for different scenarios. Choosing the right rendering mode can significantly improve application performance and user experience.
4
+
5
+ ## Rendering Mode Quick Reference
6
+
7
+ | Rendering Mode | Characteristics | Use Cases |
8
+ | ----------------- | -------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
9
+ | **CSR** | Executes JavaScript in the browser to render pages | Applications with strong interactivity and low SEO requirements |
10
+ | **SSR** | Pre-renders complete HTML pages on the server | Websites with high requirements for first-screen performance and SEO |
11
+ | **Streaming SSR** | Renders and returns progressively, displaying initial UI faster | Applications requiring faster first-screen perception speed (**Default SSR mode**) |
12
+ | **RSC** | Components render on the server, reducing client JS size; high cohesion between data and component logic, reducing state passing | Projects pursuing optimal performance and needing to reduce client-side code |
13
+ | **SSG** | Generates static pages at build time, can be cached by CDN | Websites with relatively static content, such as blogs and documentation sites |
14
+
15
+ ## Performance Comparison
16
+
17
+ | Rendering Technology | Core Advantages | Main Bottlenecks |
18
+ | ----------------------- | ------------------------------------------------------ | ------------------------------------------------ |
19
+ | **SSR** | Server-side pre-rendering, beneficial for SEO | Must wait for all data to load before responding |
20
+ | **Streaming SSR** | Renders and returns progressively, faster first screen | JS bundle size is still large |
21
+ | **Streaming SSR + RSC** | Reduces client JS size | - |
22
+
23
+ ## How to Choose
24
+
25
+ ### Quick Decision Guide
26
+
27
+ - **Static Content + SEO Required** → **SSG**
28
+ - **SEO Required + First Screen Performance** → **Streaming SSR** (default)
29
+ - **Pursuing Optimal Performance** → **Streaming SSR + RSC**
30
+ - **CSR Project Gradual Optimization** → **CSR + RSC**
31
+ - **Highly Interactive + No SEO Needed** → **CSR**
32
+
33
+ ### Combining Modes
34
+
35
+ Modern.js supports combining multiple rendering modes:
36
+
37
+ - **Streaming SSR + RSC**: Streaming rendering + reduced client-side code
38
+ - **SSG + SSR**: Some pages static, some pages dynamic
39
+ - **CSR + RSC**: Client-side rendering + partial Server Components
40
+
41
+ ## Related Documentation
42
+
43
+ - [Server-Side Rendering (SSR)](/guides/basic-features/render/ssr.md)
44
+ - [Streaming Server-Side Rendering (Streaming SSR)](/guides/basic-features/render/streaming-ssr.md)
45
+ - [React Server Components (RSC)](/guides/basic-features/render/rsc.md)
46
+ - [Static Site Generation (SSG)](/guides/basic-features/render/ssg.md)
47
+ - [Rendering Cache](/guides/basic-features/render/ssr-cache.md)