@modern-js/main-doc 2.8.0 → 2.9.0

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # @modern-js/main-doc
 
+## 2.9.0
+
+### Patch Changes
+
+- 7035d5c22f: fix: doc info block not work
+
+  fix: 修复文档站 info 不生效问题
+
+  - @modern-js/builder-doc@2.9.0
+
 ## 2.8.0
 
 ### Patch Changes

package/README.md

@@ -1,26 +1,23 @@
-<p align="center">
-  <a href="https://modernjs.dev" target="blank"><img src="https://lf3-static.bytednsdoc.com/obj/eden-cn/ylaelkeh7nuhfnuhf/modernjs-cover.png" width="300" alt="Modern.js Logo" /></a>
-</p>
+# Modern.js Website
 
-<h1 align="center">Modern.js</h1>
+### Installation
 
-<p align="center">
-  A Progressive React Framework for modern web development.
-</p>
+```
+pnpm i
+```
 
-## Getting Started
+### Local Development
 
-Please follow [Quick Start](https://modernjs.dev/en/guides/get-started/quick-start) to get started with Modern.js.
+```
+$ pnpm run dev
+```
 
-## Documentation
+This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.
 
-- [English Documentation](https://modernjs.dev/en/)
-- [中文文档](https://modernjs.dev)
+### Build
 
-## Contributing
+```
+$ pnpm run build
+```
 
-Please read the [Contributing Guide](https://github.com/web-infra-dev/modern.js/blob/main/CONTRIBUTING.md).
-
-## License
-
-Modern.js is [MIT licensed](https://github.com/web-infra-dev/modern.js/blob/main/LICENSE).
+This command generates static content into the `build` directory and can be served using any static contents hosting service.

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

@@ -0,0 +1,57 @@
+---
+title: lambda/*.[tj]s
+sidebar_position: 1
+---
+# lambda/*.[tj]s
+
+Declaring API routing in BFF framework mode. Except [some files](/apis/app/hooks/api/framework/lambda#allow-list)，files in `api/` are registered as routes.
+
+:::info
+use `api/` need execute new command to enable the 「BFF」 feature.
+
+:::
+
+:::tip
+this file supports the use `js` or `ts`, but the functions must be exported using the ESM syntax.
+
+:::
+
+## Routing Rule
+
+### Default Route
+
+The files named `index` will be upper level routing:
+
+- `api/lambda/index.ts` -> `$BASENAME/`
+- `api/lambda/user/index.ts` -> `$BASENAME/user`
+
+### Multi Level Route
+
+The routing system also supports parsing multiple levels of files. and if you create a folder, the files will still be automatically parsed in the same way.
+
+- `api/lambda/hello.ts` -> `$BASENAME/hello`
+- `api/lambda/user/list.ts` -> `$BASENAME/user/list`
+
+### Dynamic Route
+
+Dynamic named routing parameters can be supported by creating folders or files with `[xxx]`.
+
+- `api/lambda/user/[username]/info.ts` -> `$BASENAME/user/:username/info`
+- `api/lambda/user/[username]/delete.ts` -> `$BASENAME/user/:username/delete`
+- `api/lambda/article/[id]/info.ts` -> `$BASENAME/article/:id/info`
+
+the `$BASENAME` can be configured in `modern.config.js`，the default value is `/api`.
+
+### Allow List
+
+By default, all files in the `api/` will be parsed as BFF function. but we also set a allow list, and these files will not be parsed:
+
+- file name start with `_`, for example: `_utils.ts`.
+- files in directory that name start with `_`, for example: `_utils/index.ts`、`_utils/cp.ts`.
+- test files, for example: `foo.test.ts`.
+- TypeScript define files, for example: `hello.d.ts`.
+- files in `node_module`.
+
+## Define Function
+
+the same as [Define Function](/apis/app/hooks/api/functions/api#define-function).

package/docs/en/apis/app/hooks/api/functions/api.mdx

@@ -0,0 +1,81 @@
+---
+title: '**/*.[tj]s'
+sidebar_position: 1
+---
+# **/*.[tj]s
+
+Declaring API routing in BFF function mode. Except [some files](/apis/app/hooks/api/functions/api#allow-list)，files in `api/` are registered as routes.
+
+:::info
+use `api/` need execute new command to enable the 「BFF」 feature.
+
+:::
+
+:::tip
+this file supports the use `js` or `ts`, but the functions must be exported using the ESM syntax.
+
+:::
+
+## Routing Rule
+
+### Default Route
+
+The files named `index` will be upper level routing:
+
+- `api/index.ts` -> `$BASENAME/`
+- `api/user/index.ts` -> `$BASENAME/user`
+
+### Multi Level Route
+
+The routing system also supports parsing multiple levels of files. and if you create a folder, the files will still be automatically parsed in the same way.
+
+- `api/hello.ts` -> `$BASENAME/hello`
+- `api/user/list.ts` -> `$BASENAME/user/list`
+
+### Dynamic Route
+
+Dynamic named routing parameters can be supported by creating folders or files with `[xxx]`.
+
+- `api/user/[username]/info.ts` -> `$BASENAME/user/:username/info`
+- `api/user/[username]/delete.ts` -> `$BASENAME/user/:username/delete`
+- `api/article/[id]/info.ts` -> `$BASENAME/article/:id/info`
+
+the `$BASENAME` can be configured in `modern.config.js`，the default value is `/api`.
+
+### Allow List
+
+By default, all files in the `api/` will be parsed as BFF function. but we also set a allow list, and these files will not be parsed:
+
+- file name start with `_`, for example: `_utils.ts`.
+- files in directory that name start with `_`, for example: `_utils/index.ts`、`_utils/cp.ts`.
+- test files, for example: `foo.test.ts`.
+- TypeScript define files, for example: `hello.d.ts`.
+- files in `node_module`.
+
+## Define Function
+
+In addition to the above routing rules, the function definition and export in the code also have conventions.
+
+function need named exports，and the name of the exported function is the HTTP Method:
+
+```ts
+export const get = async () => {
+  return {
+    name: 'Modern.js',
+    desc: 'Modern web Solutions',
+  };
+};
+```
+
+Export the function like above will generate a `POST` interface.
+
+App support 9 Method definitions: `GET`、`POST`、`PUT`、`DELETE`、`CONNECT`、`TRACE`、`PATCH`、`OPTION`、`HEAD`. so App can use these name as function export nane.
+
+The name is insensitive, whaterver `get`、`Get`、`GEt`、`GET`, can be accurately identified. And default export, `export default xxx` will be `Get` method.
+
+because `delete` is a keyword in JavaScript, use `del` or `DELETE` instead.
+
+Multiple functions of different Methods can be defined in one file, but if multiple functions of the same Method are defined, only the first can work.
+
+:::info
+It should be noted that the defined functions should be asynchronous, which is related to the type when the function is called.

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

@@ -0,0 +1,90 @@
+---
+title: routes/
+sidebar_position: 2
+---
+# routes/
+
+The entry identifier when the application uses file system-based routing.
+
+When the project structure is of type `Routes directory entry`, the files in the `src/routes` directory are parsed to get the client-side routing configuration. See [Routing by convention](/guides/basic-features/routes) for more details on usage.
+
+Any `layout.[tj]sx` and `page.[tj]sx` under `src/routes` will be used as a route to the application:
+
+```bash {3}
+.
+└── routes
+    ├── layout.tsx
+    ├── page.tsx
+    └── user
+        ├── layout.tsx
+        └── page.tsx
+```
+
+## basic example
+
+The directory names in the `routes` directory will be used as a mapping of the route url, where `layout.tsx` is used as the layout component and `page.tsx` as the content component, which is a leaf node of the whole route, for example the following directory structure:
+
+```bash
+.
+└── routes
+    ├── page.tsx
+    └── user
+        └── page.tsx
+```
+
+The following two routes are produced:
+
+- `/`
+- `/user`
+
+## Dynamic Route
+
+If the directory name of the route file is named with `[]`, the generated route will be used as a dynamic route. For example, the following file directories:
+
+```
+└── routes
+    ├── [id]
+    │   └── page.tsx
+    ├── blog
+    │   └── page.tsx
+    └── page.tsx
+```
+
+The `routes/[id]/page.tsx` file will be converted to a `/:id` route. All `/xxx` will match that route, except for the `/blog` route, which can be matched exactly.
+
+In the component, you can get the corresponding parameters by [useParams](/apis/app/runtime/router/router#useparams).
+
+In the loader, params will be used as input to [loader](/guides/basic-features/data-fetch#loader-function), and the corresponding parameters can be retrieved through the property `params`.
+
+## Layout component
+
+As in the example below, you can add a common layout component for all routing components by adding `layout.tsx`
+
+```bash
+.
+└── routes
+    ├── layout.tsx
+    ├── page.tsx
+    └── user
+        ├── layout.tsx
+        └── page.tsx
+```
+
+You can represent child components in layout components by using `<Outlet>`:
+
+```tsx title=routes/layout.tsx
+import { Link, Outlet, useLoaderData } from '@modern-js/runtime/router';
+
+export default () => {
+  return (
+    <>
+      <Outlet></Outlet>
+    </>
+  );
+};
+```
+
+:::note
+`<Outlet>` is a new API in React Router 6, see [Outlet] for details(https://reactrouter.com/en/main/components/outlet#outlet).
+
+:::

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

@@ -0,0 +1,34 @@
+---
+title: '*.[server|node].[tj]sx'
+sidebar_position: 8
+---
+# *.[server|node].[tj]sx
+
+Used in application projects to place server side code, it generally has the following two functions:
+
+1. When `*.tsx` and `*. [server|node].tsx` coexist, rendering on the server side will give preference to the `*. [server|node].tsx` file instead of the `*.tsx` file.
+
+2. When using [data loader](/guides/basic-features/data-fetch), the server-side dependencies need to be re-exported from this file
+
+```tsx
+// routes/user/avatar.tsx
+import { useLoaderData } from '@modern-js/runtime/router';
+import { readFile } from './utils.server';
+
+type ProfileData = {
+  /* some type declarations */
+};
+
+export const loader = async (): ProfileData => {
+  const profile = await readFile('profile.json');
+  return profile;
+};
+
+export default function UserPage() {
+  const profileData = useLoaderData() as ProfileData;
+  return <div>{profileData}</div>;
+}
+
+// routes/user/utils.server.ts
+export * from 'fs-extra';
+```

package/docs/en/apis/app/runtime/router/router.mdx

@@ -0,0 +1,262 @@
+---
+title: router
+sidebar_position: 1
+---
+# router
+
+:::info
+The router solution based on [react-router 6](https://reactrouter.com/).
+
+:::
+
+## hooks
+
+### useNavigate
+
+```ts
+declare function useNavigate(): NavigateFunction;
+
+interface NavigateFunction {
+  (
+    to: To,
+    options?: {
+      replace?: boolean;
+      state?: any;
+      relative?: RelativeRoutingType;
+    },
+  ): void;
+  (delta: number): void;
+}
+```
+
+The `useNavigate` hook returns a function that lets you navigate programmatically.
+
+```tsx
+import { useNavigate } from '@modern-js/runtime/router';
+
+export function HomeButton() {
+  let navigate = useNavigate();
+
+  function handleClick() {
+    navigate('/home');
+  }
+
+  return (
+    <button type="button" onClick={handleClick}>
+      Go home
+    </button>
+  );
+}
+```
+
+### useLocation
+
+```ts
+declare function useLocation(): Location;
+
+interface Location extends Path {
+  state: unknown;
+  key: Key;
+}
+```
+
+The `useLocation` hook returns the current [location](https://reactrouter.com/web/api/location) object. A new location object would be returned whenever the current location changes.
+
+```ts
+import { useLocation } from "@modern-js/runtime/router";
+
+function usePageViews() {
+  let location = useLocation();
+  React.useEffect(() => {
+    ga.send(["pageview", location.pathname]);
+  }, [location]);
+}
+
+function App() {
+  usePageViews();
+  return (
+    //...
+  );
+}
+```
+
+### useParams
+
+```ts
+declare function useParams<K extends string = string>(): Readonly<Params<K>>;
+```
+
+The `useParams` hook returns an object of key/value pairs of the dynamic params from the current URL that were matched by the `<Route path>`.
+
+```tsx
+import { Routes, Route, useParams } from '@modern-js/runtime/router';
+
+function BlogPost() {
+  const { slug } = useParams();
+  return <div>Now showing post {slug}</div>;
+}
+
+function App() {
+  return (
+    <Routes>
+      <Route path="/" element={<div>home</div>} />
+      <Route path="/blog/:slug" element={<BlogPost />} />
+    </Routes>
+  );
+}
+```
+
+## Components
+
+### Link
+
+```ts
+declare function Link(props: LinkProps): React.ReactElement;
+
+interface LinkProps
+  extends Omit<React.AnchorHTMLAttributes<HTMLAnchorElement>, 'href'> {
+  replace?: boolean;
+  state?: any;
+  to: To;
+  reloadDocument?: boolean;
+}
+
+type To = string | Partial<Path>;
+```
+
+A `<Link>` is an element that lets the user navigate to another page by clicking or tapping on it.
+
+```ts
+<Link to="/about">About</Link>
+```
+
+### NavLink
+
+```ts
+declare function NavLink(props: NavLinkProps): React.ReactElement;
+
+interface NavLinkProps
+  extends Omit<LinkProps, 'className' | 'style' | 'children'> {
+  caseSensitive?: boolean;
+  children?:
+    | React.ReactNode
+    | ((props: { isActive: boolean }) => React.ReactNode);
+  className?: string | ((props: { isActive: boolean }) => string | undefined);
+  end?: boolean;
+  style?:
+    | React.CSSProperties
+    | ((props: { isActive: boolean }) => React.CSSProperties);
+}
+```
+
+A `<NavLink>` is a special kind of `<Link>` that knows whether or not it is "active".
+
+### Outlet
+
+```ts
+interface OutletProps {
+  context?: unknown;
+}
+declare function Outlet(props: OutletProps): React.ReactElement | null;
+```
+
+An `<Outlet>` should be used in parent route elements to render their child route elements. This allows nested UI to show up when child routes are rendered.
+
+```tsx
+function Dashboard() {
+  return (
+    <div>
+      <h1>Dashboard</h1>
+
+      {/* This element will render either <DashboardMessages> when the URL is
+          "/messages", <DashboardTasks> at "/tasks", or null if it is "/"
+      */}
+      <Outlet />
+    </div>
+  );
+}
+
+function App() {
+  return (
+    <Routes>
+      <Route path="/" element={<Dashboard />}>
+        <Route path="messages" element={<DashboardMessages />} />
+        <Route path="tasks" element={<DashboardTasks />} />
+      </Route>
+    </Routes>
+  );
+}
+```
+
+### Route
+
+```ts
+interface RouteObject {
+  path?: string;
+  index?: boolean;
+  children?: React.ReactNode;
+  caseSensitive?: boolean;
+  id?: string;
+  loader?: LoaderFunction;
+  action?: ActionFunction;
+  element?: React.ReactNode | null;
+  errorElement?: React.ReactNode | null;
+  handle?: RouteObject['handle'];
+  shouldRevalidate?: ShouldRevalidateFunction;
+}
+```
+
+`Route` represents the route information. A `Route` object couples URL segments to components, data loading and data mutations.
+
+`Route` can be used as a plain object, passing to the router creation functions:
+
+```ts
+const router = createBrowserRouter([
+  {
+    // it renders this element
+    element: <Team />,
+
+    // when the URL matches this segment
+    path: 'teams/:teamId',
+
+    // with this data loaded before rendering
+    loader: async ({ request, params }) => {
+      return fetch(`/fake/api/teams/${params.teamId}.json`, {
+        signal: request.signal,
+      });
+    },
+
+    // performing this mutation when data is submitted to it
+    action: async ({ request }) => {
+      return updateFakeTeam(await request.formData());
+    },
+
+    // and renders this element in case something went wrong
+    errorElement: <ErrorBoundary />,
+  },
+]);
+```
+
+You can also declare your routes with JSX and `createRoutesFromElements`, the props to the element are identical to the properties of the route objects:
+
+```ts
+const router = createBrowserRouter(
+  createRoutesFromElements(
+    <Route
+      element={<Team />}
+      path="teams/:teamId"
+      loader={async ({ params }) => {
+        return fetch(`/fake/api/teams/${params.teamId}.json`);
+      }}
+      action={async ({ request }) => {
+        return updateFakeTeam(await request.formData());
+      }}
+      errorElement={<ErrorBoundary />}
+    />,
+  ),
+);
+```
+
+## More
+
+You can access to [React Router](https://reactrouter.com/) to get the full API information.