@modern-js/app-tools 3.6.0 → 3.8.0

package/docs/guides/upgrade/tailwindcss.md

@@ -0,0 +1,91 @@
+# 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,33 @@
+[NEWModern.js 3.0 is released!→](/community/blog/v3-release-note)
+
+# Modern.js 3.0A Progressive React Framework for modern web development
+
+[Introduction](/guides/get-started/introduction)[Quick Start](/guides/get-started/quick-start)
+
+[Rust BundlerBuilt with Rspack bundler for faster build speed.](/guides/concept/builder)[Integrated BFFDevelop BFF code in the same project, enjoy simple function calls.](/guides/advanced-features/bff/index)[Nested RoutesFile-as-route, comes with lots performance optimizations.](/guides/basic-features/routes/routes)[Multi-Rendering ModeRSC, SSR, SSG, all out of the box for you.](/guides/basic-features/render/ssr)[CSS SolutionsCSS Modules, CSS-in-JS, Tailwind CSS, take your pick.](/guides/basic-features/css/css)[Easy to ConfigureLaunch with zero configuration, then everything is configurable.](/configure/app/usage)
+
+Guide
+
+- [Quick Start](/guides/get-started/quick-start)
+- [Core Concept](/guides/concept/entries)
+- [Basic Features](/guides/basic-features/routes)
+- [Advanced Features](/guides/advanced-features/bff)
+
+API
+
+- [Configuration](/configure/app/usage)
+- [Command](/apis/app/commands)
+- [Runtime](/apis/app/runtime/core/bootstrap)
+- [Conventions](/apis/app/hooks/src/app)
+
+Topic
+
+- [Module Federation](/guides/topic-detail/module-federation/introduce)
+- [Plugin System](/plugin/plugin-system)
+
+Help
+
+- [Changelog](https://github.com/web-infra-dev/modern.js/releases)
+- [GitHub Issues](https://github.com/web-infra-dev/modern.js/issues)
+- [Github Discussion](https://github.com/web-infra-dev/modern.js/discussions)
+