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

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/package.json

@@ -17,20 +17,24 @@
     "modern",
     "modern.js"
   ],
-  "version": "3.5.0-ultramodern.97",
+  "version": "3.5.0-ultramodern.99",
   "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": {
@@ -41,14 +45,18 @@
     },
     "./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": {
@@ -88,21 +96,36 @@
     "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",
-    "@modern-js/builder": "npm:@bleedingdev/modern-js-builder@3.5.0-ultramodern.97",
-    "@modern-js/i18n-utils": "npm:@bleedingdev/modern-js-i18n-utils@3.5.0-ultramodern.97",
-    "@modern-js/plugin": "npm:@bleedingdev/modern-js-plugin@3.5.0-ultramodern.97",
-    "@modern-js/plugin-data-loader": "npm:@bleedingdev/modern-js-plugin-data-loader@3.5.0-ultramodern.97",
-    "@modern-js/prod-server": "npm:@bleedingdev/modern-js-prod-server@3.5.0-ultramodern.97",
-    "@modern-js/server": "npm:@bleedingdev/modern-js-server@3.5.0-ultramodern.97",
-    "@modern-js/server-core": "npm:@bleedingdev/modern-js-server-core@3.5.0-ultramodern.97",
-    "@modern-js/server-utils": "npm:@bleedingdev/modern-js-server-utils@3.5.0-ultramodern.97",
-    "@modern-js/types": "npm:@bleedingdev/modern-js-types@3.5.0-ultramodern.97",
-    "@modern-js/utils": "npm:@bleedingdev/modern-js-utils@3.5.0-ultramodern.97",
+    "@modern-js/builder": "npm:@bleedingdev/modern-js-builder@3.5.0-ultramodern.99",
+    "@modern-js/i18n-utils": "npm:@bleedingdev/modern-js-i18n-utils@3.5.0-ultramodern.99",
+    "@modern-js/plugin": "npm:@bleedingdev/modern-js-plugin@3.5.0-ultramodern.99",
+    "@modern-js/plugin-data-loader": "npm:@bleedingdev/modern-js-plugin-data-loader@3.5.0-ultramodern.99",
+    "@modern-js/prod-server": "npm:@bleedingdev/modern-js-prod-server@3.5.0-ultramodern.99",
+    "@modern-js/server": "npm:@bleedingdev/modern-js-server@3.5.0-ultramodern.99",
+    "@modern-js/server-core": "npm:@bleedingdev/modern-js-server-core@3.5.0-ultramodern.99",
+    "@modern-js/server-utils": "npm:@bleedingdev/modern-js-server-utils@3.5.0-ultramodern.99",
+    "@modern-js/types": "npm:@bleedingdev/modern-js-types@3.5.0-ultramodern.99",
+    "@modern-js/utils": "npm:@bleedingdev/modern-js-utils@3.5.0-ultramodern.99",
     "@rsbuild/core": "2.1.5",
     "@swc/core": "1.15.43",
     "@swc/helpers": "^0.5.23",
@@ -144,7 +167,7 @@
   },
   "scripts": {
     "dev": "rslib build --watch",
-    "build": "rslib build && pnpm -w tsgo:dts \"$PWD\" && pnpm run verify:public-surface",
+    "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/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`);