@bleedingdev/modern-js-app-tools 3.5.0-ultramodern.1 → 3.5.0-ultramodern.100

package/docs/guides/upgrade/tailwindcss.mdx

@@ -0,0 +1,92 @@
+# Tailwind Plugin Changes
+
+Modern.js 3.0 recommends integrating Tailwind CSS through Rsbuild's native approach, no longer relying on the `@modern-js/plugin-tailwindcss` plugin, to fully utilize Rsbuild's more flexible configuration capabilities and better build experience.
+
+## Migration Steps
+
+The migration operations in this section are only required if the project uses the `@modern-js/plugin-tailwindcss` plugin and the `tailwindcss` version is v2 or v3.
+
+### 1. Remove Old Plugin
+
+Remove the `@modern-js/plugin-tailwindcss` dependency and configuration.
+
+**2.0 Version:**
+
+```ts title="modern.config.ts"
+import { defineConfig } from '@modern-js/app-tools';
+import tailwindcssPlugin from '@modern-js/plugin-tailwindcss';
+
+export default defineConfig({
+  plugins: [tailwindcssPlugin()],
+});
+```
+
+**3.0 Version:**
+
+```ts title="modern.config.ts"
+import { defineConfig } from '@modern-js/app-tools';
+
+export default defineConfig({
+  plugins: [],
+});
+```
+
+Also remove the `@modern-js/plugin-tailwindcss` dependency from `package.json`.
+
+### 2. Configure PostCSS
+
+Create or update the `postcss.config.cjs` file.
+
+```js title="postcss.config.cjs"
+module.exports = {
+  plugins: {
+    tailwindcss: {},
+  },
+};
+```
+
+### 3. Tailwind CSS Configuration Migration
+
+**Single Configuration Case**:
+
+- If only configured in `tailwind.config.{ts,js}`, no additional processing is needed
+- If only configured in `modern.config.ts`, you need to migrate Tailwind-related configurations to `tailwind.config.{ts,js}`
+
+**Dual Configuration Case**:
+
+If both `tailwind.config.{ts,js}` and `modern.config.ts` have configurations, you need to merge the configurations from both and migrate the merged configuration to `tailwind.config.{ts,js}`.
+
+**Special Directory Handling**:
+
+If the project has storybook or config/html directories, you need to add them to the `content` in `tailwind.config.{ts,js}`:
+
+```ts title="tailwind.config.ts"
+export default {
+  content: [
+    './src/**/*.{js,jsx,ts,tsx}',
+    './storybook/**/*', // If storybook directory exists
+    './config/html/**/*.{html,ejs,hbs}', // If config/html directory exists
+  ],
+};
+```
+
+### 4. CSS Style Import
+
+Change the CSS import method to the `@tailwind` directive approach.
+
+**2.0 Version:**
+
+```css
+@import 'tailwindcss/base.css';
+@import 'tailwindcss/components.css';
+@import 'tailwindcss/utilities.css';
+```
+
+**3.0 Version:**
+
+```css
+@tailwind base;
+@tailwind components;
+@tailwind utilities;
+```
+

package/docs/guides/upgrade/web-server.md

@@ -0,0 +1,109 @@
+# Custom Web Server Changes
+
+This chapter covers upgrades for two types of legacy custom Server APIs:
+
+- **unstableMiddleware**
+- **Hook**
+
+These two approaches are mutually exclusive in the legacy version. When migrating, please choose the corresponding path based on the capabilities actually used in the project.
+
+## unstableMiddleware
+
+### Core Differences
+
+- **File Structure**: `server/index.ts` → `server/modern.server.ts`
+- **Export Method**: `unstableMiddleware` array → `defineServerConfig`
+- **Context API**: Modern.js Server Context → Hono Context (`c.req`/`c.res`)
+- **Middleware Execution**: Legacy version could skip calling `next()`, new version must call it for subsequent chain execution
+- **Response Method**: `c.response.raw()` → `c.text()` / `c.json()`
+
+### File and Export
+
+```typescript
+// Legacy - server/index.ts
+export const unstableMiddleware: UnstableMiddleware[] = [middleware1, middleware2];
+
+// New - server/modern.server.ts
+import { defineServerConfig } from '@modern-js/server-runtime';
+
+export default defineServerConfig({
+  middlewares: [
+    { name: 'middleware1', handler: middleware1 },
+    { name: 'middleware2', handler: middleware2 },
+  ],
+});
+```
+
+### Type and next Call
+
+```typescript
+// Legacy
+import type { UnstableMiddleware, UnstableMiddlewareContext } from '@modern-js/server-runtime';
+const middleware: UnstableMiddleware = async (c: UnstableMiddlewareContext, next) => {
+  return c.response.raw('response'); // Will continue rendering even without calling next
+};
+
+// New
+import { defineServerConfig, type MiddlewareHandler } from '@modern-js/server-runtime';
+const middleware: MiddlewareHandler = async (c, next) => {
+  await next(); // Must call
+  return c.text('response');
+};
+```
+
+### Context API Comparison
+
+| Legacy API               | New API                 | Description            |
+| -------------------- | ---------------------- | ------------- |
+| `c.request.cookie`   | `getCookie(c, 'key')`  | Cookie reading      |
+| `c.req.cookie()`     | `getCookie(c, 'key')`  | Hono v4 deprecated    |
+| `c.request.pathname` | `c.req.path`           | Request path          |
+| `c.request.host`     | `c.req.header('Host')` | Request host          |
+| `c.request.query`    | `c.req.query()`        | Query parameters          |
+| `c.request.headers`  | `c.req.header()`       | Request headers           |
+| `c.response.status`  | `c.status()`           | Response status code         |
+| `c.response.set`     | `c.res.headers.set`    | Set response headers         |
+| `c.response.raw`     | `c.text` / `c.json`    | Response body           |
+
+## afterRender Hook
+
+The `afterRender` Hook is used to process HTML after page rendering is complete. In the new version, you need to use `renderMiddlewares` to achieve the same functionality.
+
+### Core Differences
+
+- **File Structure**: `server/index.ts` → `server/modern.server.ts`
+- **Export Method**: `afterRender` in `hook` object → `renderMiddlewares` in `defineServerConfig`
+- **Processing Method**: Direct HTML string modification → Get and modify response through middleware
+
+### Migration Example
+
+```typescript
+// Legacy - server/index.ts
+export const afterRender = (ctx, next) => {
+  ctx.template = ctx.template
+    .replace('<head>', '<head><meta name="author" content="ByteDance">')
+    .replace('<body>', '<body><div id="loading">Loading...</div>')
+    .replace('</body>', '<script>console.log("Page loaded")</script></body>');
+  next();
+};
+
+// New - server/modern.server.ts
+import { defineServerConfig, type MiddlewareHandler } from '@modern-js/server-runtime';
+
+const renderMiddleware: MiddlewareHandler = async (c, next) => {
+  await next(); // Wait for page rendering first
+  const { res } = c;
+  const html = await res.text();
+
+  const modified = html
+    .replace('<head>', '<head><meta name="author" content="ByteDance">')
+    .replace('<body>', '<body><div id="loading">Loading...</div>')
+    .replace('</body>', '<script>console.log("Page loaded")</script></body>');
+
+  c.res = c.body(modified, { status: res.status, headers: res.headers });
+};
+
+export default defineServerConfig({
+  renderMiddlewares: [{ name: 'custom-content-injection', handler: renderMiddleware }],
+});
+```

package/docs/index.md

@@ -0,0 +1,4 @@
+---
+pageType: home
+---
+# UltraModern.js 3.0 - A SuperApp framework for Effect, TanStack, SSR, BFF, and Micro Verticals

package/lib/types.d.ts

@@ -1,8 +1,6 @@
 /// <reference types="node" />
 /// <reference types="react" />
 /// <reference types="react-dom" />
-/// <reference types="@rsbuild/core/types" />
-/// <reference path="../dist/types/index.d.ts" />
 
 declare namespace NodeJS {
   interface ProcessEnv {
@@ -12,7 +10,8 @@ declare namespace NodeJS {
   }
 }
 
-// reference @rsbuild/core/types, but there are some differences, such as svg
+// Keep this app-environment surface independent from framework configuration
+// declarations so strict app typecheck does not enter toolchain internals.
 /**
  * Image assets
  */

package/package.json

@@ -17,34 +17,54 @@
     "modern",
     "modern.js"
   ],
-  "version": "3.5.0-ultramodern.1",
+  "version": "3.5.0-ultramodern.100",
   "types": "./dist/types/index.d.ts",
   "main": "./dist/cjs/index.js",
   "exports": {
     ".": {
       "types": "./dist/types/index.d.ts",
-      "import": "./dist/esm-node/index.mjs",
-      "require": "./dist/cjs/index.js",
+      "node": {
+        "import": "./dist/esm-node/index.mjs",
+        "require": "./dist/cjs/index.js"
+      },
       "default": "./dist/cjs/index.js"
     },
     "./builder": {
       "types": "./dist/types/builder/index.d.ts",
-      "import": "./dist/esm-node/builder/index.mjs",
-      "require": "./dist/cjs/builder/index.js",
+      "node": {
+        "import": "./dist/esm-node/builder/index.mjs",
+        "require": "./dist/cjs/builder/index.js"
+      },
       "default": "./dist/cjs/builder/index.js"
     },
+    "./config": {
+      "types": "./dist/types/config/public.d.ts",
+      "import": "./dist/esm-node/config/public.mjs",
+      "require": "./dist/cjs/config/public.js",
+      "default": "./dist/cjs/config/public.js"
+    },
     "./cli": {
       "types": "./dist/types/index.d.ts",
-      "import": "./dist/esm-node/index.mjs",
-      "require": "./dist/cjs/index.js",
+      "node": {
+        "import": "./dist/esm-node/index.mjs",
+        "require": "./dist/cjs/index.js"
+      },
       "default": "./dist/cjs/index.js"
     },
     "./cli/run": {
       "types": "./dist/types/run/index.d.ts",
-      "import": "./dist/esm-node/run/index.mjs",
-      "require": "./dist/cjs/run/index.js",
+      "node": {
+        "import": "./dist/esm-node/run/index.mjs",
+        "require": "./dist/cjs/run/index.js"
+      },
       "default": "./dist/cjs/run/index.js"
     },
+    "./cloudflare-output-verifier": {
+      "types": "./dist/types/plugins/deploy/platforms/cloudflare-output-verifier/index.d.ts",
+      "import": "./dist/esm-node/plugins/deploy/platforms/cloudflare-output-verifier/index.mjs",
+      "require": "./dist/cjs/plugins/deploy/platforms/cloudflare-output-verifier/index.js",
+      "default": "./dist/cjs/plugins/deploy/platforms/cloudflare-output-verifier/index.js"
+    },
     "./types": {
       "types": "./lib/types.d.ts",
       "default": "./lib/types.d.ts"
@@ -66,6 +86,9 @@
       ],
       "builder": [
         "./dist/types/builder/index.d.ts"
+      ],
+      "config": [
+        "./dist/types/config/public.d.ts"
       ]
     }
   },
@@ -73,64 +96,79 @@
     "modern": "bin/modern.js",
     "modern-app": "bin/modern.js"
   },
+  "nx": {
+    "targets": {
+      "build": {
+        "inputs": [
+          "build",
+          "^build",
+          "{workspaceRoot}/packages/document/docs/en/**/*"
+        ],
+        "outputs": [
+          "{projectRoot}/dist",
+          "{projectRoot}/docs"
+        ]
+      }
+    }
+  },
   "dependencies": {
     "@babel/parser": "^8.0.0",
     "@babel/traverse": "^8.0.0",
     "@babel/types": "^8.0.0",
     "@loadable/component": "5.16.7",
-    "@rsbuild/core": "2.1.0",
+    "@modern-js/builder": "npm:@bleedingdev/modern-js-builder@3.5.0-ultramodern.100",
+    "@modern-js/i18n-utils": "npm:@bleedingdev/modern-js-i18n-utils@3.5.0-ultramodern.100",
+    "@modern-js/plugin": "npm:@bleedingdev/modern-js-plugin@3.5.0-ultramodern.100",
+    "@modern-js/plugin-data-loader": "npm:@bleedingdev/modern-js-plugin-data-loader@3.5.0-ultramodern.100",
+    "@modern-js/prod-server": "npm:@bleedingdev/modern-js-prod-server@3.5.0-ultramodern.100",
+    "@modern-js/server": "npm:@bleedingdev/modern-js-server@3.5.0-ultramodern.100",
+    "@modern-js/server-core": "npm:@bleedingdev/modern-js-server-core@3.5.0-ultramodern.100",
+    "@modern-js/server-utils": "npm:@bleedingdev/modern-js-server-utils@3.5.0-ultramodern.100",
+    "@modern-js/types": "npm:@bleedingdev/modern-js-types@3.5.0-ultramodern.100",
+    "@modern-js/utils": "npm:@bleedingdev/modern-js-utils@3.5.0-ultramodern.100",
+    "@rsbuild/core": "2.1.5",
     "@swc/core": "1.15.43",
     "@swc/helpers": "^0.5.23",
     "compression-webpack-plugin": "^12.0.0",
-    "es-module-lexer": "^2.1.0",
+    "es-module-lexer": "^2.3.0",
     "esbuild": "^0.28.1",
     "flatted": "^3.4.2",
     "import-meta-resolve": "^4.2.0",
     "mlly": "^1.8.2",
     "ndepe": "^0.1.13",
     "pkg-types": "^2.3.1",
-    "std-env": "4.1.0",
-    "@modern-js/builder": "npm:@bleedingdev/modern-js-builder@3.5.0-ultramodern.1",
-    "@modern-js/i18n-utils": "npm:@bleedingdev/modern-js-i18n-utils@3.5.0-ultramodern.1",
-    "@modern-js/plugin": "npm:@bleedingdev/modern-js-plugin@3.5.0-ultramodern.1",
-    "@modern-js/plugin-data-loader": "npm:@bleedingdev/modern-js-plugin-data-loader@3.5.0-ultramodern.1",
-    "@modern-js/prod-server": "npm:@bleedingdev/modern-js-prod-server@3.5.0-ultramodern.1",
-    "@modern-js/server-core": "npm:@bleedingdev/modern-js-server-core@3.5.0-ultramodern.1",
-    "@modern-js/server": "npm:@bleedingdev/modern-js-server@3.5.0-ultramodern.1",
-    "@modern-js/server-utils": "npm:@bleedingdev/modern-js-server-utils@3.5.0-ultramodern.1",
-    "@modern-js/types": "npm:@bleedingdev/modern-js-types@3.5.0-ultramodern.1",
-    "@modern-js/utils": "npm:@bleedingdev/modern-js-utils@3.5.0-ultramodern.1"
+    "std-env": "4.2.0"
   },
   "devDependencies": {
-    "@rslib/core": "0.23.0",
+    "@rslib/core": "0.23.2",
+    "@scripts/rstest-config": "2.66.0",
     "@types/babel__traverse": "7.28.0",
-    "@types/node": "^26.0.1",
-    "@typescript/native-preview": "7.0.0-dev.20260624.1",
+    "@types/node": "^26.1.1",
+    "@typescript/native-preview": "7.0.0-dev.20260707.2",
     "ts-node": "^10.9.2",
     "tsconfig-paths": "^4.2.0",
-    "typescript": "^6.0.3",
-    "@scripts/rstest-config": "2.66.0"
+    "typescript": "^7.0.2"
   },
   "peerDependencies": {
     "ts-node": "^10.9.2",
     "tsconfig-paths": "^4.2.0"
   },
   "peerDependenciesMeta": {
-    "tsconfig-paths": {
+    "ts-node": {
       "optional": true
     },
-    "ts-node": {
+    "tsconfig-paths": {
       "optional": true
     }
   },
   "sideEffects": false,
   "publishConfig": {
-    "registry": "https://registry.npmjs.org/",
     "access": "public"
   },
   "scripts": {
     "dev": "rslib build --watch",
-    "build": "rslib build && pnpm -w tsgo:dts \"$PWD\"",
+    "build": "rslib build && pnpm -w tsgo:dts \"$PWD\" && pnpm run verify:public-surface && node ./scripts/copy-main-doc.mjs",
+    "verify:public-surface": "node ./tests/config/verify-public-surface.mjs",
     "test": "rstest"
   }
 }

package/rslib.config.mts

@@ -1,6 +1,10 @@
 import { rslibConfig } from '@modern-js/rslib';
 import { defineConfig } from '@rslib/core';
-import path from 'path';
+
+const APP_TOOLS_CODE_ENTRY_GLOBS = [
+  './src/**/*.{js,jsx,ts,tsx,mts,cts}',
+  './src/esm/*.mjs',
+];
 
 export default defineConfig({
   ...rslibConfig,
@@ -10,11 +14,8 @@ export default defineConfig({
       source: {
         ...libConfig.source,
         entry: {
-          index: [
-            './src/**',
-            '!src/plugins/deploy/platforms/templates/*.mjs',
-            '!src/plugins/deploy/platforms/templates/*.cjs',
-          ],
+          // Deploy templates are copy-only; `src/esm` still needs compiled CJS.
+          index: APP_TOOLS_CODE_ENTRY_GLOBS,
         },
       },
       output: {
@@ -25,12 +26,10 @@ export default defineConfig({
             to: './esm',
           },
           {
-            from: 'plugins/deploy/platforms/templates/*.cjs',
-            context: path.join(__dirname, 'src'),
-          },
-          {
-            from: 'plugins/deploy/platforms/templates/*.mjs',
-            context: path.join(__dirname, 'src'),
+            from: './src/plugins/deploy/platforms/templates',
+            to: './plugins/deploy/platforms/templates',
+            // These JavaScript-named assets must bypass Rspack's minimizer.
+            info: { minimized: true },
           },
         ],
       },

package/scripts/copy-main-doc.mjs

@@ -0,0 +1,50 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+// Copies the English docs from packages/document into this package as
+// `docs/`, so every project gets version-matched offline docs
+// for AI coding agents (see AGENTS.md generated by @modern-js/create).
+// Runs as part of `build` (see package.json build script + nx build
+// outputs), so the bundle is produced whenever the package is built —
+// including in CI/release where publish runs with `--ignore-scripts` and
+// prepublishOnly would be skipped. The directory is gitignored, so it only
+// materializes as a build output, never committed to the working tree.
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const pkgRoot = path.resolve(__dirname, '..');
+const source = path.resolve(pkgRoot, '../../document/docs/en');
+// Bundle root: docs land directly under `docs/` (no `docs/en` nesting) to
+// keep the path agents read as short as possible.
+const target = path.resolve(pkgRoot, 'docs');
+
+// Top-level doc sections excluded from the bundle to keep it small.
+// Agents rarely need these while coding (blog/showcase, narrative
+// tutorials, framework-plugin authoring); llms.txt covers them online.
+// Keep this list in sync with scripts/check-doc-bundle.mjs.
+export const EXCLUDED_SECTIONS = ['community', 'tutorials', 'plugin'];
+
+if (!fs.existsSync(source)) {
+  console.error(`[copy-main-doc] source docs not found: ${source}`);
+  process.exit(1);
+}
+
+fs.rmSync(target, { recursive: true, force: true });
+fs.mkdirSync(path.dirname(target), { recursive: true });
+fs.cpSync(source, target, {
+  recursive: true,
+  filter: src => {
+    const rel = path.relative(source, src);
+    const top = rel.split(path.sep)[0];
+    return rel === '' || !EXCLUDED_SECTIONS.includes(top);
+  },
+});
+
+const count = fs
+  .readdirSync(target, { recursive: true, withFileTypes: true })
+  .filter(entry => entry.isFile()).length;
+
+if (count === 0) {
+  console.error('[copy-main-doc] no files copied');
+  process.exit(1);
+}
+console.log(`[copy-main-doc] bundled ${count} doc files into docs`);