@modern-js/main-doc 2.8.0 → 2.10.0

package/docs/zh/guides/topic-detail/monorepo/sub-project-interface.mdx

@@ -0,0 +1,179 @@
+---
+sidebar_position: 3
+---
+
+# 子项目联调
+
+本章将要介绍如何在 Monorepo 下进行子项目之间的联调使用。
+
+## 准备工作
+
+按照 [「创建子项目」](/guides/topic-detail/monorepo/create-sub-project) 章节的介绍（如果还没有看过，可以先了解一下），我们首先创建以下三个子项目：
+
+- 一个「应用」子项目
+- 一个「模块（内部）」子项目
+- 一个「模块」子项目
+
+执行 `pnpm run new`，并按照如下进行选择：
+
+**「应用」子项目：**
+
+```
+? 请选择你想创建的工程类型：Web 应用
+? 请填写子项目名称：app
+? 请填写子项目目录名称：app
+? 请选择开发语言：TS
+```
+
+**「模块（内部）」子项目：**
+
+```
+? 请选择你想创建的工程类型：Npm 模块（内部）
+? 请填写子项目名称：internal-lib
+? 请填写子项目目录名称：internal-lib
+? 请选择开发语言：TS
+```
+
+**「模块」子项目：**
+
+```
+? 请选择你想创建的工程类型：Npm 模块
+? 请填写子项目名称：components
+? 请填写子项目目录名称：components
+? 请选择开发语言：TS
+```
+
+创建成功后，会得到以下项目：
+
+- `./apps/app`
+- `./packages/components`
+- `./features/internal-lib`
+
+然后修改一下默认的代码和新增文件：
+
+**重命名 `./pakcages/components/src/index.tsx`**
+
+```tsx
+import './index.css';
+
+export default function ({ text }: { text: string }) {
+  return (
+    <div>
+      This is UI Components Log: <p className="log">{text}</p>
+    </div>
+  );
+}
+```
+
+**新增 `./pakcages/components/src/index.css`**
+
+```css
+.log {
+  color: gray;
+}
+```
+
+**修改 `./features/internal-lib/src/index.ts`**
+
+```tsx
+export default function (text: string) {
+  return text.toUpperCase();
+}
+```
+
+**修改 `./apps/app/src/App.tsx`**
+
+```tsx
+import { Switch, Route } from '@modern-js/runtime/router';
+import formatString from 'internal-lib';
+import Comp from 'components';
+
+import './App.css';
+
+const App = () => (
+  <Switch>
+    <Route exact={true} path="/">
+      <div className="container-box">
+        <Comp text={formatString('hello world')} />
+        {/* 省略... */}
+      </div>
+    </Route>
+    <Route path="*">
+      <div>404</div>
+    </Route>
+  </Switch>
+);
+
+export default App;
+```
+
+到此为止我们创建了一个可以被发布到外部的组件项目、一个转换字符串的内部模块项目以及一个使用组件和内部模块的应用项目，如果直接运行应用项目还暂时无法正常使用。接下来将要介绍如何让它们能够互相联调使用，成功的使应用子项目 `apps/app` 正常运行。
+
+:::info
+启动 `apps/app` 项目之前需要先构建（`pnpm run build`） `packages/component`。
+
+:::
+
+由于 Modern.js 支持 pnpm 与 Yarn 的 Monorepo 工程，接下来会从这两个方面分别介绍。
+
+## 在使用 pnpm 的 Monorepo 中进行项目联调
+
+在 pnpm 的 Monorepo 项目中，我们通过在 `apps/app` 子项目下分别执行：
+
+```
+pnpm add components
+```
+
+以及
+
+```
+pnpm add internal-lib -D
+```
+
+:::info
+注意这里将 internal-lib 作为 `apps/app` 项目的开发依赖，因为在构建环境会被打包到构建产物中。
+
+:::
+
+将 `packages/components` 与 `features/internal-lib` 子项目加入到应用的依赖列表当中。
+
+执行成功后，在 `apps/app/package.json` 会发生如下变化：
+
+```json
+{
+  "dependencies": {
+++  "components": "workspace:^0.1.0"
+  },
+  "devDependencies": {
+++  "internal-lib": "workspace:^0.1.0"
+  },
+}
+```
+
+:::info 补充信息
+`workspace:^0.1.0` 是一种 PNPM 提供的 [Workspace 协议](https://pnpm.io/workspaces#workspace-protocol-workspace)。
+
+:::
+
+当依赖安装成功之后，我们还需要将 `packages/components` 进行构建，因为需要使用其构建产物。
+
+到此为止，`app/apps` 应用子项目可以正常的运行了。在修改 `features/internal-lib` 的源码，或者修改 `packages/components` 的源码并构建之后都会触发应用子项目的热更新。
+
+## 在使用 Yarn 的 Monorepo 中进行项目联调
+
+在 Yarn 的 Monorepo 项目中，默认情况下可以直接在 `apps/app` 应用项目中直接使用组件项目和内部模块项目。
+
+:::info 补充信息
+之所以可以直接在应用中使用使用组件项目和内部模块项目，是因为 Yarn 将这些子项目模块提升到了顶层的 `node_modules`内。
+
+:::
+
+但是由于组件 `components` 是非内部模块，因此建议在 `apps/app/package.json` 中进行依赖声明：
+
+```json
+{
+  "dependencies": {
+++  "components": "0.1.0"
+  },
+}
+```

package/docs/zh/index.md

@@ -0,0 +1,4 @@
+---
+pageType: home
+---
+# Modern.js - 基于 React 的渐进式 Web 开发框架

package/modern.config.ts

@@ -0,0 +1,156 @@
+import path from 'path';
+import docTools, { defineConfig, type NavItem } from '@modern-js/doc-tools';
+import { pluginAutoSidebar } from '@modern-js/doc-plugin-auto-sidebar';
+
+const rootCategories = [
+  'tutorials',
+  'guides',
+  'apis/app',
+  'configure/app',
+  'blog',
+];
+
+const { version } = require('./package.json');
+
+const docPath = path.join(__dirname, 'docs');
+
+const getNavbar = (lang: string): NavItem[] => {
+  const cn = lang === 'zh';
+  const prefix = cn ? '' : '/en';
+  const getLink = (str: string) => `${prefix}${str}`;
+  const getText = (cnText: string, enText: string) => (cn ? cnText : enText);
+  return [
+    {
+      text: getText('指南', 'Guide'),
+      link: getLink('/guides/get-started/introduction'),
+      activeMatch: '/guides/',
+    },
+    {
+      text: getText('教程', 'Tutorials'),
+      link: getLink('/tutorials/foundations/introduction'),
+      activeMatch: '/tutorials/',
+    },
+    {
+      text: getText('配置', 'Configure'),
+      link: getLink('/configure/app/usage'),
+      activeMatch: '/configure/app',
+    },
+    {
+      text: getText('API', 'API'),
+      link: getLink('/apis/app/commands'),
+      activeMatch: '/apis/',
+    },
+    {
+      text: getText('博客', 'Blog'),
+      link: getLink('/blog/index'),
+      activeMatch: '/blog/',
+    },
+    {
+      text: `v${version}`,
+      items: [
+        {
+          text: 'Modern.js Module',
+          link: 'https://modernjs.dev/module-tools/en/',
+        },
+        {
+          text: 'Modern.js Doc',
+          link: 'https://modernjs.dev/doc-tools/',
+        },
+        {
+          text: 'Modern.js Builder',
+          link: 'https://modernjs.dev/builder/en/',
+        },
+        {
+          text: 'Modern.js v1',
+          link: 'https://modernjs.dev/v1/',
+        },
+      ],
+    },
+  ];
+};
+
+export default defineConfig({
+  doc: {
+    root: docPath,
+    base: '/',
+    logo: 'https://lf-cdn-tos.bytescm.com/obj/static/webinfra/modern-js-website/assets/images/images/modernjs-logo.svg',
+    icon: 'https://lf3-static.bytednsdoc.com/obj/eden-cn/uhbfnupenuhf/favicon.ico',
+    lang: 'zh',
+    themeDir: path.join(__dirname, 'src'),
+    markdown: {
+      checkDeadLinks: process.env.NODE_ENV === 'production',
+    },
+    head: [
+      `
+          <script>
+          ;(function (w, d, u, b, n, pc, ga, ae, po, s, p, e, t, pp) {pc = 'precollect';ga = 'getAttribute';ae = 'addEventListener';po = 'PerformanceObserver';s = function (m) {p = [].slice.call(arguments);p.push(Date.now(), location.href);(m == pc ? s.p.a : s.q).push(p)};s.q = [];s.p = { a: [] };w[n] = s;e = document.createElement('script');e.src = u + '?bid=' + b + '&globalName=' + n;e.crossorigin = u.indexOf('sdk-web') > 0 ? 'anonymous' : 'use-credentials';d.getElementsByTagName('head')[0].appendChild(e);if (ae in w) {s.pcErr = function (e) {e = e || w.event;t = e.target || e.srcElement;if (t instanceof Element || t instanceof HTMLElement) {if (t[ga]('integrity')) {w[n](pc, 'sri', t[ga]('href') || t[ga]('src'))} else {w[n](pc, 'st', { tagName: t.tagName, url: t[ga]('href') || t[ga]('src') })}} else {w[n](pc, 'err', e.error)}};s.pcRej = function (e) {e = e || w.event;w[n](pc, 'err', e.reason || (e.detail && e.detail.reason))};w[ae]('error', s.pcErr, true);w[ae]('unhandledrejection', s.pcRej, true);};if('PerformanceLongTaskTiming' in w) {pp = s.pp = { entries: [] };pp.observer = new PerformanceObserver(function (l) {pp.entries = pp.entries.concat(l.getEntries)});pp.observer.observe({ entryTypes: ['longtask', 'largest-contentful-paint','layout-shift'] })}})(window,document,'https://lf3-short.bytegoofy.com/slardar/fe/sdk-web/browser.cn.js','modernjs_dev','Slardar');
+
+          </script>
+          `,
+      `
+          <script>
+            window.Slardar('init', {
+              bid: 'modernjs_dev'
+            });
+            window.Slardar('start')
+          </script>
+          `,
+    ],
+    themeConfig: {
+      locales: [
+        {
+          lang: 'zh',
+          title: 'Modern.js',
+          description:
+            'A Progressive React Framework for modern web development.',
+          nav: getNavbar('zh'),
+          label: '简体中文',
+        },
+        {
+          lang: 'en',
+          title: 'Modern.js',
+          description:
+            'A Progressive React Framework for modern web development.',
+          nav: getNavbar('en'),
+          label: 'English',
+        },
+      ],
+      socialLinks: [
+        {
+          icon: 'github',
+          mode: 'link',
+          content: 'https://github.com/web-infra-dev/modern.js',
+        },
+      ],
+    },
+    route: {
+      exclude: ['scripts/**', '**/components/**'],
+    },
+    builderConfig: {
+      output: {
+        disableTsChecker: true,
+        svgDefaultExport: 'component',
+        dataUriLimit: 0,
+      },
+      dev: {
+        startUrl: true,
+      },
+      source: {
+        alias: {
+          '@site-docs': path.join(__dirname, './docs/zh'),
+          '@site-docs-en': path.join(__dirname, './docs/en'),
+          '@site': require('path').resolve(__dirname),
+        },
+      },
+    },
+    plugins: [
+      pluginAutoSidebar({
+        root: docPath,
+        categories: ['zh', 'en'].flatMap(lang =>
+          rootCategories.map(category => `${lang}/${category}`),
+        ),
+      }),
+    ],
+  },
+  plugins: [docTools()],
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@modern-js/main-doc",
-  "description": "Shared documentation of modern.js framework",
+  "description": "Documentation of modern.js framework",
   "homepage": "https://modernjs.dev",
   "bugs": "https://github.com/web-infra-dev/modern.js/issues",
   "repository": "web-infra-dev/modern.js",
@@ -11,23 +11,32 @@
     "modern",
     "modern.js"
   ],
-  "version": "2.8.0",
+  "version": "2.10.0",
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",
     "access": "public"
   },
   "peerDependencies": {
-    "@modern-js/builder-doc": "^2.8.0"
+    "@modern-js/builder-doc": "^2.10.0"
   },
   "devDependencies": {
+    "classnames": "^2",
+    "clsx": "^1.2.1",
+    "react": "^18",
+    "react-dom": "^18",
     "ts-node": "^10",
     "typescript": "^4",
     "fs-extra": "^10",
     "@types/node": "^16",
     "@types/fs-extra": "^9",
-    "@modern-js/builder-doc": "2.8.0"
+    "@modern-js/builder-doc": "2.10.0",
+    "@modern-js/doc-tools": "2.10.0",
+    "@modern-js/doc-plugin-auto-sidebar": "2.10.0"
   },
   "scripts": {
-    "build": "npx ts-node ./scripts/sync.ts"
+    "dev": "modern dev",
+    "build": "npx ts-node ./scripts/sync.ts",
+    "build:doc": "modern build",
+    "preview": "modern preview"
   }
 }

package/src/components/ContentCard/index.module.scss

@@ -0,0 +1,61 @@
+.card {
+  display: flex;
+  flex-direction: column;
+  background-color: transparent;
+  padding: 32px 32px 36px;
+  color: #fff;
+  font-weight: 500;
+  font-size: 20px;
+  box-sizing: border-box;
+  border-radius: 24px;
+  background-color: rgba(51, 194, 255, 0.08);
+  width: calc(50% - 16px);
+  cursor: pointer;
+  margin-bottom: 32px;
+  flex: 0 0 auto;
+  transition: all 0.3s ease;
+  text-decoration: none;
+
+  &:nth-child(2n) {
+    margin-left: 32px;
+  }
+
+  &:hover {
+    transition: all 0.3s ease;
+    color: #fff;
+    background-color: rgba(51, 194, 255, 0.2);
+  }
+}
+
+.title {
+  display: inline-block;
+  font-weight: 800;
+  font-size: 24px;
+  line-height: 1.4;
+}
+
+.desc {
+  display: inline-block;
+  margin-top: 16px;
+  font-size: 14px;
+  line-height: 1.4;
+  color: rgba(255, 255, 255, 0.65);
+}
+
+.icon {
+  width: 56px;
+  margin-top: 10px;
+  flex-shrink: 0;
+  height: 56px;
+  fill: #fff;
+}
+
+@media screen and (max-width: 768px) {
+  .card {
+    width: 100%;
+
+    &:nth-child(2n) {
+      margin-left: 0;
+    }
+  }
+}

package/src/components/ContentCard/index.tsx

@@ -0,0 +1,25 @@
+import React, { ComponentType, SVGProps } from 'react';
+import cl from 'classnames';
+import { withBase } from '@modern-js/doc-tools/runtime';
+import styles from './index.module.scss';
+
+export interface ContentCardProps {
+  title: string;
+  desc?: string;
+  img?: string | ComponentType<SVGProps<SVGSVGElement>>;
+  href: string;
+}
+
+const ContentCard: React.FC<ContentCardProps> = ({ title, desc, href }) => (
+  <a
+    href={withBase(href)}
+    target="_blank"
+    style={{ textDecoration: 'none' }}
+    className={cl(styles.card)}
+  >
+    <span className={styles.title}>{title}</span>
+    <span className={styles.desc}>{desc}</span>
+  </a>
+);
+
+export default ContentCard;

package/src/components/FeatureLayout/index.module.css

@@ -0,0 +1,8 @@
+.feature-layout {
+  display: flex;
+  flex-direction: column;
+  width: 80vw;
+  max-width: 1200px;
+  margin: 0 auto;
+  padding: 20vh 0 0;
+}

package/src/components/FeatureLayout/index.tsx

@@ -0,0 +1,8 @@
+import React from 'react';
+import styles from './index.module.css';
+
+export const FeatureLayout: React.FC<{ children: React.ReactNode }> = ({
+  children,
+}) => <div className={styles['feature-layout']}>{children}</div>;
+
+export default FeatureLayout;

package/src/components/Footer/index.tsx

@@ -0,0 +1,131 @@
+import React from 'react';
+import { useI18n, useUrl } from '../../i18n';
+import styles from './styles.module.scss';
+
+const isExternalUrl = (url: string) => {
+  return url.startsWith('http://') || url.startsWith('https://');
+};
+
+function FooterLink({ to, href, label, ...props }: any) {
+  return (
+    <a
+      className="linkItem"
+      target="_blank"
+      {...{ href: href || to }}
+      {...props}
+    >
+      {href && isExternalUrl(href) ? <span>{label}</span> : label}
+    </a>
+  );
+}
+
+export default function Footer() {
+  const t = useI18n();
+  const links = [
+    {
+      title: t('guide'),
+      items: [
+        {
+          label: t('quickStart'),
+          to: useUrl('/guides/get-started/quick-start'),
+        },
+        {
+          label: t('coreConcept'),
+          to: useUrl('/guides/concept/entries'),
+        },
+        {
+          label: t('basicFeatures'),
+          to: useUrl('/guides/basic-features/'),
+        },
+        {
+          label: t('advancedFeatures'),
+          to: useUrl('/guides/advanced-features/'),
+        },
+      ],
+    },
+    {
+      title: 'API',
+      items: [
+        {
+          label: t('configuration'),
+          to: useUrl('/configure/app/usage'),
+        },
+        {
+          label: t('command'),
+          to: useUrl('/apis/app/commands'),
+        },
+        {
+          label: t('runtime'),
+          to: useUrl('/apis/app/runtime/core/bootstrap'),
+        },
+        {
+          label: t('conventions'),
+          to: useUrl('apis/app/hooks/src/app'),
+        },
+      ],
+    },
+    {
+      title: t('topic'),
+      items: [
+        {
+          label: t('microFrontend'),
+          to: useUrl('/guides/topic-detail/micro-frontend/c01-introduction'),
+        },
+        {
+          label: t('stateManagement'),
+          to: useUrl('/guides/topic-detail/model/quick-start'),
+        },
+        {
+          label: t('pluginSystem'),
+          to: useUrl('/guides/topic-detail/framework-plugin/introduction'),
+        },
+        {
+          label: t('projectGenerator'),
+          to: useUrl('/guides/topic-detail/generator/project'),
+        },
+      ],
+    },
+    {
+      title: t('help'),
+      items: [
+        {
+          label: t('changelog'),
+          to: 'https://github.com/web-infra-dev/modern.js/releases',
+        },
+        {
+          label: 'GitHub Issues',
+          to: 'https://github.com/web-infra-dev/modern.js/issues',
+        },
+        {
+          label: t('githubDiscussion'),
+          to: 'https://github.com/web-infra-dev/modern.js/discussions',
+        },
+      ],
+    },
+  ];
+
+  const Links = links.map((linkItem, i) => (
+    <div className={styles.linkWrapper} key={i}>
+      <div className={styles.linkTitle}>{linkItem.title}</div>
+      <ul className={styles.items}>
+        {linkItem.items.map((item, key) => (
+          <li key={item.to || key} className={styles.link}>
+            <FooterLink {...item} />
+          </li>
+        ))}
+      </ul>
+    </div>
+  ));
+
+  return (
+    <footer className={styles.footer}>
+      <div className={styles.wrapper}>
+        <img
+          className={styles.logo}
+          src="https://lf3-static.bytednsdoc.com/obj/eden-cn/zq-uylkvT/ljhwZthlaukjlkulzlp/modern-logo-home-page-0209.svg"
+        />
+        <div className={styles.linksWrapper}>{Links}</div>
+      </div>
+    </footer>
+  );
+}

package/src/components/Footer/styles.module.scss

@@ -0,0 +1,49 @@
+.footer {
+  margin-top: 6vh;
+  display: flex;
+  justify-content: center;
+  padding: 10vh 0;
+}
+
+.logo {
+  width: 240px;
+  margin-bottom: 48px;
+}
+
+.wrapper {
+  width: 80vw;
+  max-width: 1200px;
+}
+
+.linksWrapper {
+  display: flex;
+  justify-content: space-between;
+  flex-wrap: wrap;
+}
+
+.linkTitle {
+  font-weight: bold;
+  font-size: 18px;
+  margin-bottom: 12px;
+  color: rgba(255, 255, 255, 0.9);
+}
+
+.linkWrapper {
+  margin-bottom: 24px;
+}
+
+.link {
+  line-height: 32px;
+  font-size: 15px;
+  color: rgba(255, 255, 255, 0.8);
+
+  &:hover {
+    color: rgba(255, 255, 255, 1);
+  }
+}
+
+@media (max-width: 768px) {
+  .linkWrapper {
+    width: 50%;
+  }
+}