@linyjs/plugin-docs 0.1.0

package/docs/getting-started/installation.md

@@ -0,0 +1,244 @@
+# 安装指南
+
+本指南将帮助你正确安装和配置 linyjs 框架及插件开发环境。
+
+## 前置要求
+
+在开始之前,请确保你的系统已安装以下软件:
+
+- **Node.js** >= 18.0 ([下载地址](https://nodejs.org/))
+- **npm** >= 9.0 (通常随 Node.js 一起安装)
+- **Git** (用于版本控制)
+
+### 验证安装
+
+```bash
+# 检查 Node.js 版本
+node --version
+# 应显示: v18.x.x 或更高
+
+# 检查 npm 版本
+npm --version
+# 应显示: 9.x.x 或更高
+
+# 检查 Git
+git --version
+```
+
+## 安装 linyjs 核心包
+
+linyjs 框架由多个 NPM 包组成。根据你的需求,可以选择性安装:
+
+### 1. 安装接口包(必需)
+
+这些包定义了插件开发的接口规范:
+
+```bash
+npm install @linyjs/server-module-interface
+npm install @linyjs/client-module-interface
+npm install @linyjs/ui-slots-interface
+```
+
+### 2. 安装 CLI 工具(推荐)
+
+CLI 工具提供零配置的插件打包功能:
+
+```bash
+# 全局安装
+npm install -g @linyjs/cli
+
+# 或在项目中使用
+npx @linyjs/cli <command>
+```
+
+### 3. 安装文档包(推荐)
+
+文档包包含完整的教程和示例:
+
+```bash
+npm install @linyjs/plugin-docs
+```
+
+安装后,文档位于 `node_modules/@linyjs/plugin-docs/docs/`。
+
+### 4. 安装其他可选包
+
+```bash
+# MongoDB 服务(数据持久化)
+npm install @linyjs/mongodb
+
+# 权限管理
+npm install @linyjs/permission
+
+# 管理后台
+npm install @linyjs/admin
+```
+
+## 初始化插件项目
+
+### 方法 1: 使用 CLI 工具(推荐)
+
+```bash
+# 创建新项目
+npx @linyjs/cli init my-plugin
+
+# 进入项目目录
+cd my-plugin
+
+# 安装依赖
+npm install
+```
+
+### 方法 2: 手动创建
+
+```bash
+# 创建项目目录
+mkdir my-plugin && cd my-plugin
+
+# 初始化 npm
+npm init -y
+
+# 安装依赖
+npm install @linyjs/server-module-interface @linyjs/client-module-interface react
+npm install -D typescript @types/react
+
+# 创建 TypeScript 配置
+cat > tsconfig.json << 'EOF'
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "ESNext",
+    "lib": ["ES2020", "DOM"],
+    "jsx": "react-jsx",
+    "declaration": true,
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "moduleResolution": "node"
+  },
+  "include": ["src/**/*"]
+}
+EOF
+
+# 创建目录结构
+mkdir -p src/{server,client}
+```
+
+## 配置开发环境
+
+### VS Code 推荐扩展
+
+- **TypeScript and JavaScript Language Features** (内置)
+- **ESLint** - 代码质量检查
+- **Prettier** - 代码格式化
+- **React Developer Tools** - React 调试
+
+### ESLint 配置(可选)
+
+```bash
+npm install -D eslint @typescript-eslint/parser @typescript-eslint/eslint-plugin
+```
+
+创建 `.eslintrc.json`:
+
+```json
+{
+  "parser": "@typescript-eslint/parser",
+  "plugins": ["@typescript-eslint"],
+  "extends": [
+    "eslint:recommended",
+    "plugin:@typescript-eslint/recommended"
+  ],
+  "rules": {
+    "@typescript-eslint/explicit-function-return-type": "off",
+    "@typescript-eslint/no-explicit-any": "warn"
+  }
+}
+```
+
+## 验证安装
+
+创建一个简单的测试文件来验证安装是否正确:
+
+**src/server/test.ts:**
+
+```typescript
+import type { IModule } from '@linyjs/server-module-interface';
+
+console.log('✓ Server module interface imported successfully');
+
+export const testModule: IModule = {
+  name: 'test',
+  serviceDefs: []
+};
+```
+
+**src/client/test.tsx:**
+
+```typescript
+import type { IModule } from '@linyjs/client-module-interface';
+import React from 'react';
+
+console.log('✓ Client module interface imported successfully');
+
+export const testModule: IModule = {
+  name: 'test',
+  serviceDefs: []
+};
+```
+
+编译测试:
+
+```bash
+npx tsc
+```
+
+如果编译成功且无错误,说明安装正确!
+
+## 常见问题
+
+### Q: 安装时遇到权限错误?
+
+**A:** 尝试使用 `sudo`(macOS/Linux)或以管理员身份运行命令提示符(Windows):
+
+```bash
+sudo npm install -g @linyjs/cli
+```
+
+或者配置 npm 使用用户目录:
+
+```bash
+npm config set prefix ~/.npm-global
+echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
+source ~/.bashrc
+```
+
+### Q: TypeScript 编译错误?
+
+**A:** 确保安装了正确的 TypeScript 版本:
+
+```bash
+npm install -D typescript@^5.7.0
+```
+
+### Q: 如何更新到最新版本?
+
+**A:** 使用 npm update:
+
+```bash
+npm update @linyjs/server-module-interface
+npm update @linyjs/client-module-interface
+npm update @linyjs/cli
+```
+
+## 下一步
+
+- 🎯 阅读 [快速开始](./quick-start.md) 创建你的第一个插件
+- 📖 查看 [第一个插件教程](./first-plugin.md) 深入学习
+- 💡 浏览 [示例项目](../../examples/) 获取完整代码参考
+
+---
+
+**上一篇**: [快速开始](./quick-start.md) | **下一篇**: [第一个插件教程](./first-plugin.md)

package/docs/getting-started/quick-start.md

@@ -0,0 +1,174 @@
+# 快速开始
+
+## 📖 导航目录
+
+- [快速开始](./quick-start.md) - 本文档
+- [安装指南](./installation.md) - 详细安装说明
+- [第一个插件教程](./first-plugin.md) - 深入学习插件开发
+
+## 相关文档
+
+- [服务端模块开发](../guides/server-module.md)
+- [客户端模块开发](../guides/client-module.md)
+- [创建示例项目](../../examples/hello-world/)
+
+## 5分钟创建你的第一个 linyjs 插件
+
+本教程将带你从零开始,在5分钟内创建一个简单的 "Hello World" 插件。
+
+### 前置要求
+
+- Node.js >= 18.0
+- npm 或 yarn
+- 基本的 TypeScript 和 React 知识
+
+### 步骤 1: 初始化项目
+
+```bash
+# 创建项目目录
+mkdir hello-plugin && cd hello-plugin
+
+# 初始化 npm 项目
+npm init -y
+
+# 安装依赖
+npm install @linyjs/server-module-interface @linyjs/client-module-interface react
+npm install -D typescript @types/react
+```
+
+### 步骤 2: 创建项目结构
+
+```
+hello-plugin/
+├── package.json
+├── tsconfig.json
+└── src/
+    ├── server/
+    │   └── index.ts      # 服务端入口
+    └── client/
+        └── index.tsx     # 客户端入口
+```
+
+**创建 tsconfig.json:**
+
+```json
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "ESNext",
+    "lib": ["ES2020", "DOM"],
+    "jsx": "react-jsx",
+    "declaration": true,
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "moduleResolution": "node"
+  },
+  "include": ["src/**/*"]
+}
+```
+
+### 步骤 3: 编写服务端代码
+
+创建 `src/server/index.ts`:
+
+```typescript
+import type { IModule } from '@linyjs/server-module-interface';
+
+class HelloController {
+  getRoutes() {
+    return [{
+      method: 'GET' as const,
+      path: '/api/hello',
+      middlewares: [],
+      responseType: 'json' as const,
+      handler: async () => {
+        return { message: 'Hello from plugin!' };
+      }
+    }];
+  }
+}
+
+export const helloServerModule: IModule = {
+  name: 'helloServer',
+  serviceDefs: [{
+    serviceTag: 'helloController',
+    serviceImpl: HelloController,
+    meta: { usageType: 'controller' }
+  }]
+};
+```
+
+### 步骤 4: 编写客户端代码
+
+创建 `src/client/index.tsx`:
+
+```typescript
+import type { IModule } from '@linyjs/client-module-interface';
+import React from 'react';
+
+function HelloPage() {
+  return (
+    <div style={{ padding: '20px' }}>
+      <h1>Hello from Plugin!</h1>
+      <p>This is your first linyjs plugin.</p>
+    </div>
+  );
+}
+
+export const helloClientModule: IModule = {
+  name: 'helloClient',
+  serviceDefs: [{
+    serviceTag: 'helloRoute',
+    serviceImpl: class {
+      basePath = '/hello';
+      getRoutes() {
+        return [{
+          path: '/',
+          component: HelloPage,
+          key: 'hello-page',
+          meta: { title: 'Hello' }
+        }];
+      }
+    },
+    meta: { usageType: 'route' }
+  }]
+};
+```
+
+### 步骤 5: 构建和打包
+
+```bash
+# 编译 TypeScript
+npx tsc
+
+# 使用 CLI 打包为 .mpk 文件
+npx @linyjs/cli pack
+```
+
+你会得到 `hello-plugin.mpk` 文件!
+
+### 步骤 6: 测试插件
+
+```bash
+# 将插件复制到 extensions 目录
+cp hello-plugin.mpk /path/to/linyjs/packages/ssr/extensions/
+
+# 启动 SSR 服务器
+cd /path/to/linyjs/packages/ssr
+npx tsx src/demo/dev-server-with-pkg.tsx
+```
+
+访问 `http://localhost:3000/hello` 查看你的插件!
+
+### 下一步
+
+- 📖 阅读 [安装指南](./installation.md) 了解详细的安装步骤
+- 🎯 查看 [第一个插件教程](./first-plugin.md) 深入学习插件开发
+- 💡 浏览 [示例项目](../../examples/) 获取完整代码参考
+
+---
+
+**上一篇**: [返回目录](../README.md) | **下一篇**: [安装指南](./installation.md)