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

package/dist/esm-node/plugins/analyze/index.mjs

@@ -24,7 +24,7 @@ const analyze = ()=>({
                 const resolvedConfig = api.getNormalizedConfig();
                 const hooks = api.getHooks();
                 try {
-                    if (checkIsBuildCommands()) fs.emptydirSync(appContext.internalDirectory);
+                    if (checkIsBuildCommands(appContext.command)) fs.emptydirSync(appContext.internalDirectory);
                 } catch  {}
                 const apiOnly = await isApiOnly(appContext.appDirectory, resolvedConfig.source?.entriesDir, appContext.apiDirectory);
                 const [{ getProdEntrypoints, getProdServerRoutes }] = await Promise.all([
@@ -126,7 +126,7 @@ const analyze = ()=>({
                     htmlTemplates
                 };
                 api.updateAppContext(appContext);
-                if (checkIsBuildCommands()) {
+                if (checkIsBuildCommands(appContext.command)) {
                     await hooks.generateEntryCode.call({
                         entrypoints
                     });

package/dist/esm-node/plugins/analyze/utils.mjs

@@ -39,7 +39,7 @@ const parseModule = async ({ source, filename })=>{
     return await parse(content);
 };
 const getServerCombinedModuleFile = (internalDirectory, entryName)=>path.join(internalDirectory, entryName, 'server-loader-combined.js');
-const checkIsBuildCommands = ()=>{
+const checkIsBuildCommands = (contextCommand)=>{
     const buildCommands = [
         'dev',
         'start',
@@ -49,7 +49,8 @@ const checkIsBuildCommands = ()=>{
         'dev-worker'
     ];
     const command = getCommand();
-    return buildCommands.includes(command);
+    if (buildCommands.includes(command)) return true;
+    return 'dev' === contextCommand || 'start' === contextCommand || 'build' === contextCommand || 'deploy' === contextCommand;
 };
 const checkIsServeCommand = ()=>{
     const command = getCommand();

package/dist/esm-node/plugins/initialize/index.mjs

@@ -26,7 +26,7 @@ const initialize = ()=>({
             api.modifyResolvedConfig(async (resolved)=>{
                 let appContext = api.getAppContext();
                 const userConfig = api.getConfig();
-                const port = await getServerPort(resolved);
+                const port = await getServerPort(resolved, appContext.command);
                 appContext = {
                     ...appContext,
                     port,
@@ -61,9 +61,10 @@ function stabilizeConfig(resolve, config, keys) {
         resolve[key] = config[key] || {};
     });
 }
-async function getServerPort(config) {
+async function getServerPort(config, contextCommand) {
     const prodPort = Number(process.env.PORT) || config.server.port || 8080;
-    if (isDev() && isDevCommand()) return getPort(Number(process.env.PORT) || prodPort);
+    const isProgrammaticDev = 'dev' === contextCommand || 'start' === contextCommand;
+    if (isDev() && (isDevCommand() || isProgrammaticDev)) return getPort(Number(process.env.PORT) || prodPort);
     return prodPort;
 }
 export default initialize;

package/dist/esm-node/plugins/serverBuild.mjs

@@ -18,7 +18,7 @@ const serverBuild = ()=>({
         name: '@modern-js/server-build',
         setup (api) {
             api.onAfterBuild(async ()=>{
-                const { appDirectory, distDirectory, metaName } = api.getAppContext();
+                const { appDirectory, distDirectory, metaName, moduleType } = api.getAppContext();
                 if (!checkHasCache(appDirectory) && !checkHasConfig(appDirectory, metaName)) return;
                 const modernConfig = api.getNormalizedConfig();
                 const distDir = path.resolve(distDirectory);
@@ -38,7 +38,8 @@ const serverBuild = ()=>({
                 }, {
                     sourceDirs,
                     distDir,
-                    tsconfigPath
+                    tsconfigPath,
+                    moduleType
                 });
             });
         }

package/dist/types/commands/deploy.d.ts

@@ -1,3 +1,4 @@
 import type { CLIPluginAPI } from '@modern-js/plugin';
 import type { AppTools } from '../types';
-export declare const deploy: (api: CLIPluginAPI<AppTools>, options: any) => Promise<void>;
+import type { DeployOptions } from '../utils/types';
+export declare const deploy: (api: CLIPluginAPI<AppTools>, options?: DeployOptions) => Promise<void>;

package/dist/types/index.d.ts

@@ -3,13 +3,16 @@ import { initAppContext } from './utils/initAppContext';
 export * from './defineConfig';
 export * from './presetUltramodern';
 export declare const appTools: () => CliPlugin<AppTools>;
+export { build } from './commands/build';
+export { deploy } from './commands/deploy';
 export { dev } from './commands/dev';
 export { serve } from './commands/serve';
 export { defineConfig } from './defineConfig';
 export { type ResolveModernRsbuildConfigOptions, resolveModernRsbuildConfig, } from './rsbuild';
 export * from './types';
+export { closeServer } from './utils/createServer';
 export { generateWatchFiles } from './utils/generateWatchFiles';
-export type { DevOptions } from './utils/types';
+export type { BuildOptions, DeployOptions, DevOptions } from './utils/types';
 export { initAppContext };
 export default appTools;
 export { mergeConfig } from '@modern-js/plugin/cli';

package/dist/types/plugins/analyze/utils.d.ts

@@ -5,6 +5,6 @@ export declare const parseModule: ({ source, filename, }: {
     filename: string;
 }) => Promise<readonly [imports: readonly import("es-module-lexer").ImportSpecifier[], exports: readonly import("es-module-lexer").ExportSpecifier[], facade: boolean, hasModuleSyntax: boolean]>;
 export declare const getServerCombinedModuleFile: (internalDirectory: string, entryName: string) => string;
-export declare const checkIsBuildCommands: () => boolean;
+export declare const checkIsBuildCommands: (contextCommand?: string) => boolean;
 export declare const checkIsServeCommand: () => boolean;
 export declare const isSubDirOrEqual: (parent: string, child: string) => boolean;

package/dist/types/types/config/dev.d.ts

@@ -46,6 +46,12 @@ export interface DevServerUserConfig {
  * Although its name is the same as in Rsbuild, it is consumed by Modern.js.
  */
 export type DevUserConfig = Omit<BuilderDevConfig, 'setupMiddlewares'> & {
+    /**
+     * Customize the directory containing the Mock API entry file.
+     * Relative paths are resolved from the application directory.
+     * @default './config/mock'
+     */
+    mockDir?: string;
     setupMiddlewares?: SetupMiddlewares;
     /**
      * Dev server specific options.

package/docs/_nav.json

@@ -0,0 +1,36 @@
+[
+  {
+    "text": "UltraModern Guide",
+    "link": "/guides/get-started/ultramodern",
+    "activeMatch": "/guides/"
+  },
+  {
+    "text": "configure",
+    "link": "/configure/app/usage",
+    "activeMatch": "/configure/"
+  },
+  {
+    "text": "plugin-menu",
+    "link": "/plugin/introduction",
+    "activeMatch": "/plugin/"
+  },
+  {
+    "text": "apis",
+    "link": "/apis/app/commands",
+    "activeMatch": "/apis/"
+  },
+  {
+    "text": "Examples",
+    "link": "/tutorials/foundations/introduction",
+    "activeMatch": "/tutorials/"
+  },
+  {
+    "text": "community",
+    "link": "/community/showcase",
+    "activeMatch": "/community/"
+  },
+  {
+    "text": "Upstream Modern.js 2.x Docs",
+    "link": "https://modernjs.dev/v2"
+  }
+]

package/docs/apis/_meta.json

@@ -0,0 +1,13 @@
+[
+  "app/commands",
+  {
+    "type": "dir",
+    "name": "app/hooks",
+    "label": "file-conventions"
+  },
+  {
+    "type": "dir",
+    "name": "app/runtime",
+    "label": "runtime-api"
+  }
+]

package/docs/apis/app/commands.mdx

@@ -0,0 +1,205 @@
+---
+sidebar_position: 1
+---
+
+# Commands
+
+UltraModern.js has some built-in commands that can help you quickly start a development server, build production environment code, and more.
+
+Through this chapter, you can learn about the built-in commands of UltraModern.js and how to use them.
+
+## modern dev
+
+The `modern dev` command is used to start a local development server and compile the source code in the development environment.
+
+```bash
+Usage: modern dev [options]
+
+Options:
+  -e --entry <entry>    compiler by entry
+  -c --config <config>  specify the configuration file, which can be a relative or absolute path
+  -h, --help            show command help
+  --web-only            only start web service
+  --api-only            only start API service
+```
+
+After running `modern dev`, UltraModern.js will watch source file changes and apply hot module replacement.
+
+```bash
+$ modern dev
+
+info    Starting dev server...
+
+  > Local:    http://localhost:8080/
+  > Network:  http://192.168.0.1:8080/
+```
+
+### Compile Partial Pages
+
+In multi-page (MPA) projects, the `--entry` option can be added to specify one or more pages to compile. In this way, only part of the code in the project will be compiled, and the dev startup speed will be faster.
+
+For example, execute `modern dev --entry`, the entry selector will be displayed in the command line interface:
+
+```text
+$ modern dev --entry
+
+? Please select the entry that needs to be built
+❯ ◯ foo
+  ◯ bar
+  ◯ baz
+```
+
+For example, if you select the `foo` entry, only the code related to the `foo` entry will be compiled, and the code of other pages will not be compiled.
+
+### Specify the page by parameter
+
+You can also specify the page name through parameters after `--entry`, and the names of multiple pages can be separated by commas.
+
+```bash
+# Compile foo page
+modern dev --entry foo
+
+# Compile foo and bar pages
+modern dev --entry foo,bar
+```
+
+## modern start
+
+`modern start` is an alias of `modern dev` command, the usage of the two are exactly the same.
+
+## modern build
+
+The `modern build` command will build production-ready artifacts in the `dist/` directory by default. You can specify the output directory by modifying the configuration [`output.distPath`](/configure/app/output/dist-path).
+
+```bash
+Usage: modern build [options]
+
+Options:
+  -c --config <config>  specify the configuration file, which can be a relative or absolute path
+  -h, --help            show command help
+  -w --watch            turn on watch mode, watch for changes and rebuild
+```
+
+## modern runtime status
+
+The `modern runtime status` command reads the runtime status endpoint and prints the response. It targets `http://127.0.0.1:8080/_modern/runtime/status` by default.
+
+```bash
+Usage: modern runtime status [options]
+
+Options:
+  --endpoint <endpoint>  runtime status endpoint URL or path
+  --token <token>        runtime status auth token
+  --token-env <name>     environment variable name that stores runtime status auth token (default: "MODERN_RUNTIME_SIGNAL_TOKEN")
+  --header-name <name>   auth header name (default: "x-modernjs-runtime-signal-token")
+  --timeout <ms>         request timeout in milliseconds (default: "5000")
+  --json                 output as JSON format for machine reading
+  -h, --help             display help for command
+```
+
+If `--endpoint` is a path, it is resolved against `http://127.0.0.1:8080`. If `--token` is omitted, the command reads the token from the environment variable named by `--token-env`.
+
+By default, the command formats the response as readable key/value lines. Add `--json` to print the raw JSON payload.
+
+```bash
+modern runtime status --json
+```
+
+## modern runtime fallback-signal
+
+The `modern runtime fallback-signal` command posts a runtime fallback signal to the canary contract-gate endpoint. It targets `http://127.0.0.1:8080/_modern/contract-gates/runtime-fallback` by default.
+
+```bash
+Usage: modern runtime fallback-signal [options]
+
+Options:
+  --app <appName>          remote app name
+  --endpoint <endpoint>    runtime fallback signal endpoint URL or path
+  --reason <reason>        fallback reason (default: "runtime_fallback")
+  --phase <phase>          fallback phase (default: "load")
+  --entry <entry>          remote entry URL
+  --runtime-digest <digest>  runtime digest value
+  --metadata <json>        metadata JSON object string
+  --token <token>          runtime signal auth token
+  --token-env <name>       environment variable name that stores runtime signal auth token (default: "MODERN_RUNTIME_SIGNAL_TOKEN")
+  --header-name <name>     auth header name (default: "x-modernjs-runtime-signal-token")
+  --timeout <ms>           request timeout in milliseconds (default: "5000")
+  --json                   output as JSON format for machine reading
+  -h, --help               display help for command
+```
+
+The request body always includes `appName`, `reason`, and `phase`. It includes `entry`, `runtimeDigest`, and `metadata` only when those options are provided. `--metadata` must be a JSON object string.
+
+```bash
+modern runtime fallback-signal --app crm-shell --reason remote_load_failed --phase load --json
+```
+
+import ServeCommand from '@site-docs-en/components/serve-command';
+
+<ServeCommand />
+
+## modern inspect
+
+The `modern inspect` command is used to view the UltraModern.js config, [Rsbuild config](https://v2.rsbuild.rs/config/index) and Rspack config of the project.
+
+```bash
+Usage: modern inspect [options]
+
+Options:
+  --env <env>           view the configuration in the target environment (default: "development")
+  --output <output>     Specify the path to output in the dist (default: "./")
+  --verbose             Show the full function in the result
+  -c --config <config>  specify the configuration file, which can be a relative or absolute path
+  -h, --help            show command help
+```
+
+After executing the command `npx modern inspect` in the project root directory, the following files will be generated in the `dist` directory of the project:
+
+- `modern.js.config.mjs`:The Modern.js configuration currently used.
+- `rsbuild.config.mjs`: The Rsbuild config to use at build time.
+- `rspack.config.web.mjs`: The Rspack config used by to use at build time.
+
+```bash
+➜ npx modern inspect
+
+Inspect config succeed, open following files to view the content:
+
+  - Rsbuild Config: /root/my-project/dist/rsbuild.config.mjs
+  - Rspack Config (web): /root/my-project/dist/rspack.config.web.mjs
+  - Modern.js Config: /root/my-project/dist/modern.js.config.mjs
+```
+
+### Configuration Env
+
+By default, the inspect command will output the development configs, you can use the `--env production` option to output the production configs:
+
+```bash
+modern inspect --env production
+```
+
+### Verbose content
+
+By default, the inspect command will omit the function content in the config object, you can use the `--verbose` option to output the full content of the function:
+
+```bash
+modern inspect --verbose
+```
+
+### SSR Configuration
+
+If the project has enabled SSR, an additional `rspack.config.node.mjs` file will be generated in the `dist/`, corresponding to the Rspack configuration at SSR build time.
+
+```bash
+➜ npx modern inspect
+
+Inspect config succeed, open following files to view the content:
+
+  - Rsbuild Config: /root/my-project/dist/rsbuild.config.mjs
+  - Rspack Config (web): /root/my-project/dist/rspack.config.web.mjs
+  - Rspack Config (node): /root/my-project/dist/rspack.config.node.mjs
+  - Modern.js Config: /root/my-project/dist/modern.js.config.mjs
+```
+
+import DeployCommand from '@site-docs-en/components/deploy-command';
+
+<DeployCommand />

package/docs/apis/app/hooks/_meta.json

@@ -0,0 +1,28 @@
+[
+  {
+    "type": "dir",
+    "name": "src",
+    "label": "src/",
+    "collapsed": true
+  },
+  {
+    "type": "dir",
+    "name": "api",
+    "label": "api/",
+    "collapsed": true
+  },
+  {
+    "type": "dir",
+    "name": "server",
+    "label": "server/",
+    "collapsed": true
+  },
+  "shared",
+  {
+    "type": "dir",
+    "name": "config",
+    "label": "config/",
+    "collapsed": true
+  },
+  "modern-config"
+]

package/docs/apis/app/hooks/api/lambda.mdx

@@ -0,0 +1,13 @@
+---
+title: lambda/*.ts
+sidebar_position: 3
+---
+# lambda/*.ts
+
+After enabling BFF, the files under the `lambda/` directory will be registered as BFF routes according to conventions.
+
+:::note
+The files can be written in `js` or `ts` languages, but they must use `esm` syntax to export functions.
+:::
+
+For detailed information, refer to [BFF API Routes](/guides/advanced-features/bff/function.html#api-routes).

package/docs/apis/app/hooks/config/_meta.json

@@ -0,0 +1 @@
+["html", "favicon", "icon", "mock", "public", "upload"]

package/docs/apis/app/hooks/config/favicon.mdx

@@ -0,0 +1,29 @@
+---
+title: favicon.*
+sidebar_position: 3
+---
+
+# Favicon
+
+When there is a `favicon.*` file in the `config` directory at the root of the project, Modern.js will automatically set the file to the [html.favicon](/configure/app/html/favicon) configuration option for generating the favicon icon on the page:
+
+```
+./config
+└── favicon.ico
+```
+
+After the build is completed, you can see the following tags automatically generated in HTML:
+
+```html
+<link rel="icon" href="/favicon.ico" />
+```
+
+## Order
+
+When setting up the favicon, Modern.js looks for files in the following order:
+
+- `favicon.png`
+- `favicon.jpg`
+- `favicon.jpeg`
+- `favicon.svg`
+- `favicon.ico`

package/docs/apis/app/hooks/config/html.mdx

@@ -0,0 +1,9 @@
+---
+title: html/
+sidebar_position: 1
+---
+# html/
+
+You can inject custom HTML fragments at different locations of the default internal HTML template through the `config/html` directory.
+
+For specific usage, please refer to: [Custom HTML](/guides/basic-features/html).

package/docs/apis/app/hooks/config/icon.mdx

@@ -0,0 +1,29 @@
+---
+title: icon.*
+sidebar_position: 2
+---
+
+# Apple Touch Icon
+
+When there is an `icon.*` file in the `config` directory at the root of the project, Modern.js will automatically set the file to the [html.appIcon](/configure/app/html/app-icon) configuration option for generating the Apple Touch Icon icon under the iOS system.
+
+```
+./config
+└── icon.png
+```
+
+After the build is completed, you can see the following tags automatically generated in HTML:
+
+```html
+<link rel="apple-touch-icon" sizes="180x180" href="/static/image/icon.png" />
+```
+
+## Order
+
+When setting up the app icon, Modern.js looks for files in the following order:
+
+- `icon.png`
+- `icon.jpg`
+- `icon.jpeg`
+- `icon.svg`
+- `icon.ico`

package/docs/apis/app/hooks/config/mock.mdx

@@ -0,0 +1,10 @@
+---
+title: mock/
+sidebar_position: 5
+---
+# mock/
+
+When there is a `config/mock/index.ts` or `config/mock/index.js` file in the
+project directory, Modern.js will automatically enable the Mock service during
+development. Use [`dev.mockDir`](/configure/app/dev/mock-dir) to customize
+this directory.

package/docs/apis/app/hooks/config/public.mdx

@@ -0,0 +1,30 @@
+---
+title: public/
+sidebar_position: 3
+---
+# public/
+
+Any static assets can be placed in the `public/` directory, and the files will be deployed to the corresponding application domain by the server.
+
+## Description
+
+The file routing is based on the convention of the directory structure, where `public/` is the root directory corresponding to the root path of the Web application.
+
+For example, the `config/public/sdk/index.js` file will be deployed under `${domain}/sdk/index.js` after deployment.
+
+## Scenarios
+
+For example, authentication files required by third-party systems such as `robots.txt` and `auth.xml`.
+
+Or SDKs for other business parties (requiring unchanged routing), or HTML files without entry.
+
+:::info
+For static assets (such as SVG images) that need to be imported through import in the source code, it is recommended to manage them in the `src/assets` directory.
+
+:::
+
+## Code Compression
+
+If the file in the directory is a `.js` file, it will be automatically compressed during production environment construction.
+
+If the file ends with `.min.js`, it will not be compressed.

package/docs/apis/app/hooks/config/upload.mdx

@@ -0,0 +1,54 @@
+---
+title: upload/
+sidebar_position: 4
+---
+# upload/
+
+Any static assets can be placed in the `upload/` directory.
+
+## Description
+
+In the development environment, the static assets in this directory will be hosted under the `/upload` path. After building the application, the files in this directory will be copied to the dist directory.
+
+This file convention is mainly used for developers to use plugins to proactively upload static assets to the CDN.
+
+## Scenarios
+
+For example, SDKs for project use only, such as `google-analysis.js` (usually requires HTTP caching).
+
+Pictures, font files, common CSS, etc.
+
+## Code Compression
+
+If the file in the directory is a `.js` file, it will be automatically compressed during production environment construction.
+
+If the file ends with `.min.js`, it will not be compressed.
+
+## More Usage
+
+In React components, you can add this prefix through [Environment Variables](/guides/basic-features/env-vars.html#asset_prefix):
+
+```tsx
+export default () => {
+  return (
+    <img src={`${process.env.ASSET_PREFIX}/upload/banner.png`}></img>
+  );
+};
+```
+
+In addition, whether it is in [Custom HTML](/guides/basic-features/html) or any HTML file under [`config/public/`](/apis/app/hooks/config/public), you can directly use HTML tags to reference resources in the `config/upload/` directory:
+
+```html
+<script src="/upload/index.js"></script>
+```
+
+If you set the [`dev.assetPrefix`](/configure/app/dev/asset-prefix) or [`output.assetPrefix`](/configure/app/output/asset-prefix) prefix, you can also use template syntax to add the prefix directly:
+
+```html
+<script src="<%=assetPrefix %>/upload/index.js"></script>
+```
+
+:::info
+Modern.js does not support using files under `config/upload/` through URLs in `config/public/*.css` (such as background-image).
+
+:::

package/docs/apis/app/hooks/modern-config.mdx

@@ -0,0 +1,9 @@
+---
+title: modern.config.ts
+sidebar_position: 8
+---
+# modern.config.ts
+
+The Modern.js configuration file. Through this file, you can personalize the configuration of various aspects of the current project.
+
+To learn more about how to use the configuration, please refer to [Configuration Usage](/configure/app/usage).

package/docs/apis/app/hooks/server/server.mdx

@@ -0,0 +1,10 @@
+---
+title: modern.server.ts
+sidebar_position: 1
+---
+
+# modern.server.ts
+
+This file extends the Modern.js Server. In this file, you can configure [Middleware](/guides/advanced-features/web-server.html#middleware), [RenderMiddleware](/guides/advanced-features/web-server.html#rendermiddleware), or [Plugin](/guides/advanced-features/web-server.html#plugin) for the Server that starts with the Modern.js project.
+
+You can intercept and handle requests and responses, perform authentication and role checks, preprocess requests, and handle exceptions, etc. You can also insert specific business logic into the built-in processing logic (including route matching, resource addressing, header injection, page rendering, and static web hosting).

package/docs/apis/app/hooks/shared.mdx

@@ -0,0 +1,7 @@
+---
+title: shared/
+sidebar_position: 5
+---
+# shared/
+
+Shared source code directory. When there is common code in `api/`, `server/`, and `src/` in the project, you can put these codes in the `shared` directory instead of directly referencing them.

package/docs/apis/app/hooks/src/app.mdx

@@ -0,0 +1,30 @@
+# App.tsx
+
+The entry identifier when using [Self-controlled Routing](/guides/concept/entries.html#self-controlled-routing) in the application.
+
+`App.tsx` is not the actual application entry; Modern.js will automatically generate the real entry file, which is roughly as follows:
+
+```js
+// runtime-global-context
+import { setGlobalContext } from '@modern-js/runtime/context';
+import App from '@_modern_js_src/App';
+
+setGlobalContext({
+  App,
+});
+
+// index.tsx
+import './runtime-global-context';
+import { createRoot } from '@modern-js/runtime/react';
+import { render } from '@modern-js/runtime/browser';
+
+const ModernRoot = createRoot();
+
+render(<ModernRoot />, 'root');
+```
+
+When `createRoot` is executed, it will retrieve the registered Global App and generate the actual React component.
+
+:::note
+In scenarios with multiple entry points, each entry can have its own independent `App.tsx`. For more details, see [Entry Points](/guides/concept/entries).
+:::