react-native-kookit 0.1.3 → 0.1.4

package/README_NEW.md

@@ -112,6 +112,16 @@ export default function App() {
 
 A: 插件需要修改原生 Android 代码，prebuild 会应用所有插件修改。
 
+### Q: 遇到 "Plugin is an unexpected type: undefined" 错误怎么办？
+
+A:
+
+1. 确保已正确安装：`npm install react-native-kookit`
+2. 清理重装：`rm -rf node_modules && npm install`
+3. 重新预构建：`npx expo prebuild --clean`
+
+详细故障排除请查看 [TROUBLESHOOTING.md](./TROUBLESHOOTING.md)
+
 ### Q: 音量键无响应怎么办？
 
 A:

package/RELEASE_CHECKLIST.md

@@ -0,0 +1,115 @@
+# React Native Kookit - 发布前检查
+
+## 修复的主要问题
+
+✅ **Plugin undefined 错误**
+
+- 修复了 package.json 中插件配置位置
+- 添加了 @expo/config-plugins 依赖
+- 改进了 app.plugin.js 的错误处理
+
+✅ **插件导出问题**
+
+- 确保插件正确导出为 ConfigPlugin 函数
+- 添加了fallback处理
+
+## 当前文件结构
+
+```
+react-native-kookit/
+├── package.json                 # 主包配置，包含插件配置
+├── app.plugin.js               # 插件入口文件
+├── plugin/                     # 插件源码目录
+│   ├── package.json           # 插件依赖
+│   ├── tsconfig.json          # TypeScript 配置
+│   ├── src/
+│   │   └── withVolumeKeyIntercept.ts  # 插件实现
+│   └── build/                 # 编译后的插件
+│       └── withVolumeKeyIntercept.js
+├── README_NEW.md              # 更新的文档
+├── TROUBLESHOOTING.md         # 故障排除指南
+└── EXPO_PLUGIN_README.md      # 插件详细说明
+```
+
+## 测试步骤
+
+### 1. 本地测试插件加载
+
+```bash
+cd /path/to/react-native-kookit
+node -e "
+const plugin = require('./app.plugin.js');
+console.log('Plugin type:', typeof plugin);
+console.log('Plugin loaded:', typeof plugin === 'function' ? '✅ Success' : '❌ Failed');
+"
+```
+
+### 2. 在测试项目中验证
+
+1. 创建新的 Expo 项目：
+
+```bash
+npx create-expo-app TestKookit
+cd TestKookit
+```
+
+2. 添加本地模块：
+
+```bash
+npm install ../react-native-kookit
+```
+
+3. 配置 app.json：
+
+```json
+{
+  "expo": {
+    "plugins": ["react-native-kookit"]
+  }
+}
+```
+
+4. 预构建：
+
+```bash
+npx expo prebuild --clean
+```
+
+5. 检查生成的 MainActivity 是否包含必要代码
+
+### 3. 发布验证
+
+```bash
+# 构建插件
+npm run build-plugin
+
+# 检查文件
+ls -la plugin/build/
+
+# 发布（测试版本）
+npm publish --tag beta
+```
+
+## 用户使用流程验证
+
+### 正确的用户步骤：
+
+1. ✅ `npm install react-native-kookit`
+2. ✅ 在 app.json 添加 `"plugins": ["react-native-kookit"]`
+3. ✅ `npx expo prebuild --clean`
+4. ✅ `npx expo run:android`
+
+### 预期结果：
+
+- MainActivity 自动包含 VolumeKeyInterceptActivity 接口
+- 音量键监听功能正常工作
+- 无需手动修改原生代码
+
+## 发布清单
+
+- [ ] 插件本地测试通过
+- [ ] 在新项目中端到端测试
+- [ ] 文档更新完成
+- [ ] 版本号更新
+- [ ] README 更新为 README_NEW.md
+- [ ] 发布到 npm

package/TROUBLESHOOTING.md

@@ -0,0 +1,132 @@
+# react-native-kookit 配置示例
+
+## 正确的 app.json 配置
+
+```json
+{
+  "expo": {
+    "name": "Your App Name",
+    "slug": "your-app-slug",
+    "version": "1.0.0",
+    "orientation": "portrait",
+    "icon": "./assets/icon.png",
+    "userInterfaceStyle": "light",
+    "splash": {
+      "image": "./assets/splash.png",
+      "resizeMode": "contain",
+      "backgroundColor": "#ffffff"
+    },
+    "plugins": ["react-native-kookit"],
+    "android": {
+      "adaptiveIcon": {
+        "foregroundImage": "./assets/adaptive-icon.png",
+        "backgroundColor": "#ffffff"
+      }
+    },
+    "web": {
+      "favicon": "./assets/favicon.png"
+    }
+  }
+}
+```
+
+## 故障排除
+
+### 错误：Plugin is an unexpected type: undefined
+
+**原因：** 插件未正确安装或构建
+
+**解决方案：**
+
+1. 确保 react-native-kookit 已正确安装：
+
+```bash
+npm install react-native-kookit
+# 或
+yarn add react-native-kookit
+```
+
+2. 清理并重新安装依赖：
+
+```bash
+rm -rf node_modules package-lock.json
+npm install
+```
+
+3. 重新预构建：
+
+```bash
+npx expo prebuild --clean
+```
+
+### 其他常见错误
+
+#### 错误：Cannot find module '@expo/config-plugins'
+
+**解决方案：**
+
+```bash
+npm install @expo/config-plugins
+```
+
+#### 错误：Plugin configuration is invalid
+
+检查 app.json 格式是否正确，确保 plugins 数组正确配置。
+
+## 验证插件是否工作
+
+运行以下命令检查插件是否正确加载：
+
+```bash
+node -e "
+const plugin = require('react-native-kookit/app.plugin.js');
+console.log('Plugin loaded successfully:', typeof plugin === 'function');
+"
+```
+
+如果输出 `Plugin loaded successfully: true`，说明插件正确安装。
+
+## 完整的使用流程
+
+1. **安装模块**
+
+```bash
+npm install react-native-kookit
+```
+
+2. **配置 app.json**
+
+```json
+{
+  "expo": {
+    "plugins": ["react-native-kookit"]
+  }
+}
+```
+
+3. **预构建项目**
+
+```bash
+npx expo prebuild --clean
+```
+
+4. **运行项目**
+
+```bash
+npx expo run:android
+```
+
+5. **在代码中使用**
+
+```javascript
+import ReactNativeKookit from "react-native-kookit";
+
+const subscription = ReactNativeKookit.addListener(
+  "onVolumeButtonPressed",
+  (event) => {
+    console.log("Volume button:", event.key);
+  }
+);
+
+ReactNativeKookit.enableVolumeKeyInterception();
+```

package/app.plugin.js

@@ -1 +1,8 @@
-module.exports = require('./plugin/build/withVolumeKeyIntercept').default;
+try {
+  const plugin = require('./plugin/build/withVolumeKeyIntercept');
+  module.exports = plugin.default || plugin;
+} catch (error) {
+  console.error('Failed to load react-native-kookit plugin:', error.message);
+  // Return a no-op plugin as fallback
+  module.exports = (config) => config;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-native-kookit",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "React Native module for intercepting volume button presses on iOS and Android",
   "main": "build/index.js",
   "types": "build/index.d.ts",
@@ -32,7 +32,9 @@
   "author": "troyeguo <13820674+troyeguo@users.noreply.github.com> (https://github.com/troyeguo)",
   "license": "MIT",
   "homepage": "https://github.com/troyeguo/react-native-kookit#readme",
-  "dependencies": {},
+  "dependencies": {
+    "@expo/config-plugins": "^8.0.0"
+  },
   "devDependencies": {
     "@types/react": "~19.0.0",
     "expo-module-scripts": "^4.1.10",
@@ -45,10 +47,8 @@
     "react-native": "*"
   },
   "expo": {
-    "android": {
-      "configPlugins": [
-        "./app.plugin.js"
-      ]
-    }
+    "configPlugins": [
+      "./app.plugin.js"
+    ]
   }
 }