tarojs-plugin-chucker 1.0.0

package/README.md

@@ -0,0 +1,155 @@
+# tarojs-plugin-chucker
+
+A Chucker-like debugger plugin for Taro JS miniapps. It intercepts, logs, and displays network requests and native plugin calls (`wx.invokeNativePlugin`) directly in your miniapp during Runtime.
+
+It automatically injects a floating trigger button into every page at build-time, which opens a dedicated full-screen debugger console.
+
+---
+
+## Features
+
+- 🛰️ **API Request Interception**: Automatically hooks into `Taro.request`, `Taro.uploadFile`, and `Taro.downloadFile`.
+- 🔌 **WeChat Native Plugins Tracker**: Intercepts `wx.invokeNativePlugin` parameters, callbacks, and Promise resolutions.
+- 🛠️ **Build-time Injection**: Automatically injects the WXML floating debugger button and layout styling onto every compiled page, and registers `/pages/chucker/index` in-memory.
+- 📋 **Copy to cURL**: Formats network calls into standard shell cURL commands and copies them to the clipboard with one tap.
+- 🔍 **Interactive Console**: Beautiful dark-mode UI overlay with tabs (Overview, Request, Response), search, filters (All, Network, Native), and JSON pretty-printing.
+
+---
+
+## Installation
+
+Install the package via `pnpm`, `yarn`, or `npm`:
+
+```bash
+pnpm add tarojs-plugin-chucker --save-dev
+# or
+yarn add tarojs-plugin-chucker --dev
+# or
+npm install tarojs-plugin-chucker --save-dev
+```
+
+---
+
+## Configuration
+
+### 1. Register Compile-Time Plugin
+
+Add `tarojs-plugin-chucker` to the `plugins` array in your Taro project configuration:
+
+```javascript
+// config/index.js
+const config = {
+  // ...
+  plugins: [
+    [
+      "tarojs-plugin-chucker",
+      {
+        // By default, only enabled in development. Set true to force enable.
+        enabled: process.env.NODE_ENV === "development",
+      },
+    ],
+  ],
+};
+```
+
+## Dedicated Debugger Page
+
+To navigate to the debugger manually (e.g., from custom menus or gestures):
+
+```typescript
+import Taro from "@tarojs/taro";
+
+Taro.navigateTo({ url: "/pages/chucker/index" });
+```
+
+---
+
+## Custom Logging
+
+Beyond the automatic network interception, you can log **any custom event** into the Chucker console using the `chuckerStore` API. All custom entries appear alongside network logs in the same debugger UI.
+
+### Import
+
+```typescript
+import { chuckerStore } from "tarojs-plugin-chucker/runtime";
+```
+
+### One-shot logging — `chuckerStore.log()`
+
+Use `log()` to record a complete event in a single call. An `id` and `startTime` are auto-generated if omitted.
+
+```typescript
+// Log a WebSocket message
+chuckerStore.log({
+  type: "websocket",
+  method: "MESSAGE",
+  url: "wss://example.com/ws",
+  requestData: { event: "ping" },
+  status: "success",
+  responseData: { event: "pong" },
+});
+
+// Log a custom analytics event
+chuckerStore.log({
+  type: "analytics",
+  method: "TRACK",
+  url: "page_view",
+  requestData: { page: "/home", userId: "abc123" },
+  status: "sent",
+});
+```
+
+### Async tracking — `startTracking()` / `completeTracking()`
+
+For operations that have a measurable duration (e.g., GraphQL queries, RPC calls), use the tracking pair. Duration is calculated automatically.
+
+```typescript
+// Start tracking a GraphQL mutation
+const id = chuckerStore.startTracking({
+  type: "graphql",
+  method: "MUTATION",
+  url: "https://api.example.com/graphql",
+  requestData: { query: "mutation { createUser(name: \"Alice\") { id } }" },
+});
+
+// ... later when the response arrives
+chuckerStore.completeTracking(id, {
+  status: 200,
+  responseData: { data: { createUser: { id: 1 } } },
+});
+
+// You can also provide an explicit duration (in ms)
+chuckerStore.completeTracking(id, {
+  status: 200,
+  responseData: result,
+  duration: 350,
+});
+```
+
+### API Reference
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `chuckerStore.log(input)` | `string` (id) | Add a complete log entry in one call |
+| `chuckerStore.startTracking(input)` | `string` (id) | Begin tracking an async operation |
+| `chuckerStore.completeTracking(id, result?)` | `void` | Finalize a tracked operation |
+| `chuckerStore.getLogs()` | `ChuckerLog[]` | Get all current log entries |
+| `chuckerStore.clear()` | `void` | Clear all log entries |
+| `chuckerStore.subscribe(listener)` | `() => void` | Subscribe to log changes, returns unsubscribe function |
+
+### `CustomLogInput` fields
+
+| Field | Type | Required | Default |
+|-------|------|----------|---------|
+| `type` | `"network" \| "native" \| string` | ✅ | — |
+| `method` | `string` | ✅ | — |
+| `url` | `string` | ✅ | — |
+| `id` | `string` | ❌ | Auto-generated (`usr_xxxxx`) |
+| `startTime` | `number` | ❌ | `Date.now()` |
+| `requestHeaders` | `Record<string, string>` | ❌ | — |
+| `requestData` | `any` | ❌ | — |
+| `status` | `string \| number` | ❌ | — |
+| `responseHeaders` | `Record<string, string>` | ❌ | — |
+| `responseData` | `any` | ❌ | — |
+| `error` | `string` | ❌ | — |
+| `duration` | `number` | ❌ | — |

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+import { IPluginContext } from "@tarojs/service";
+export interface ChuckerPluginOptions {
+    enabled?: boolean;
+}
+declare const _default: (ctx: IPluginContext, options?: ChuckerPluginOptions) => void;
+export default _default;

package/dist/index.js

@@ -0,0 +1,206 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+const path = __importStar(require("path"));
+const fs = __importStar(require("fs"));
+exports.default = (ctx, options = {}) => {
+    ctx.modifyAppConfig(({ appConfig }) => {
+        const isDev = process.env.NODE_ENV === "development";
+        const enabled = options.enabled !== undefined ? options.enabled : isDev;
+        if (!enabled)
+            return;
+        if (appConfig && appConfig.pages) {
+            if (!appConfig.pages.includes("pages/chucker/index")) {
+                appConfig.pages.push("pages/chucker/index");
+                console.log('[Taro Chucker] Dynamically registered "pages/chucker/index" page');
+            }
+        }
+    });
+    ctx.modifyWebpackChain(({ chain }) => {
+        const isDev = process.env.NODE_ENV === "development";
+        const enabled = options.enabled !== undefined ? options.enabled : isDev;
+        chain.plugin("definePlugin").tap((args) => {
+            if (args && args[0]) {
+                args[0]["process.env.CHUCKER_ENABLED"] = JSON.stringify(enabled);
+            }
+            return args;
+        });
+        if (enabled) {
+            // Find the actual app entry file under sourcePath
+            const sourcePath = ctx.paths.sourcePath;
+            const entryFiles = ["app.ts", "app.tsx", "app.js", "app.jsx"];
+            let appEntryFile = "";
+            for (const file of entryFiles) {
+                const fullPath = path.join(sourcePath, file);
+                if (fs.existsSync(fullPath)) {
+                    appEntryFile = fullPath;
+                    break;
+                }
+            }
+            // Setup Webpack aliases to virtualize pages/chucker/index page resolution
+            const userPagePathWin = path.join(ctx.paths.sourcePath, "pages", "chucker", "index");
+            const userPagePathUnix = userPagePathWin.replace(/\\/g, "/");
+            const templatePath = path.resolve(__dirname, "runtime", "page.js");
+            chain.resolve.alias
+                .set("pages/chucker/index", templatePath)
+                .set(userPagePathWin, templatePath)
+                .set(userPagePathWin + ".tsx", templatePath)
+                .set(userPagePathWin + ".ts", templatePath)
+                .set(userPagePathWin + ".js", templatePath)
+                .set(userPagePathWin + ".jsx", templatePath)
+                .set(userPagePathUnix, templatePath)
+                .set(userPagePathUnix + ".tsx", templatePath)
+                .set(userPagePathUnix + ".ts", templatePath)
+                .set(userPagePathUnix + ".js", templatePath)
+                .set(userPagePathUnix + ".jsx", templatePath);
+            // Force resolve React, Taro, and Taro components from the host project's node_modules
+            // to prevent duplicate library instances (e.g. invalid hook call with useState).
+            const hostNodeModules = ctx.paths.nodeModulesPath || path.resolve(ctx.paths.appPath, "node_modules");
+            if (hostNodeModules) {
+                const reactPath = path.resolve(hostNodeModules, "react");
+                if (fs.existsSync(reactPath)) {
+                    chain.resolve.alias.set("react", reactPath);
+                }
+                const taroPath = path.resolve(hostNodeModules, "@tarojs/taro");
+                if (fs.existsSync(taroPath)) {
+                    chain.resolve.alias.set("@tarojs/taro", taroPath);
+                }
+                const componentsPath = path.resolve(hostNodeModules, "@tarojs/components");
+                if (fs.existsSync(componentsPath)) {
+                    chain.resolve.alias.set("@tarojs/components", componentsPath);
+                }
+            }
+            chain.module
+                .rule("chucker-app-injector")
+                .test((resourcePath) => {
+                if (!resourcePath || !appEntryFile)
+                    return false;
+                const absoluteResource = path.resolve(resourcePath);
+                const normalizedResource = absoluteResource.replace(/\\/g, "/");
+                const normalizedEntryPath = appEntryFile.replace(/\\/g, "/");
+                const resPathNoExt = normalizedResource.replace(/\.[a-zA-Z0-9]+$/, "");
+                const entryPathNoExt = normalizedEntryPath.replace(/\.[a-zA-Z0-9]+$/, "");
+                const isJsOrTs = /\.(ts|tsx|js|jsx)$/.test(resourcePath);
+                const isMatch = resPathNoExt === entryPathNoExt && isJsOrTs;
+                if (normalizedResource.includes("app.") || isMatch) {
+                    console.log(`[Taro Chucker] Matching: ${normalizedResource} vs ${normalizedEntryPath} -> ${isMatch}`);
+                }
+                return isMatch;
+            })
+                .use("chucker-loader")
+                .loader(path.resolve(__dirname, "loader.js"))
+                .end();
+        }
+    });
+    ctx.modifyBuildAssets(({ assets }) => {
+        const isDev = process.env.NODE_ENV === "development";
+        const enabled = options.enabled !== undefined ? options.enabled : isDev;
+        if (!enabled)
+            return;
+        Object.keys(assets).forEach((filename) => {
+            // 1. Inject page configuration dynamically into pages/chucker/index.json
+            if (filename === "pages/chucker/index.json") {
+                const asset = assets[filename];
+                const originalSource = asset.source();
+                const content = typeof originalSource === "string" ? originalSource : originalSource.toString();
+                try {
+                    const config = JSON.parse(content);
+                    config.navigationBarTitleText = "Chucker";
+                    config.navigationBarBackgroundColor = "#121212";
+                    config.navigationBarTextStyle = "white";
+                    config.backgroundColor = "#121212";
+                    const newContent = JSON.stringify(config);
+                    assets[filename] = {
+                        source: () => newContent,
+                        size: () => newContent.length,
+                    };
+                }
+                catch (err) {
+                    console.error("🚀 [Taro Chucker] Failed to modify chucker page config:", err);
+                }
+            }
+            // 2. Inject WXML float button to all page templates (except Chucker page itself)
+            const isPageTemplate = filename.startsWith("pages/") &&
+                /\.(wxml|axml|ttml|swan|qml)$/.test(filename) &&
+                !filename.includes("pages/chucker/");
+            if (isPageTemplate) {
+                const asset = assets[filename];
+                const originalSource = asset.source();
+                const content = typeof originalSource === "string" ? originalSource : originalSource.toString();
+                if (!content.includes("chucker-float-btn")) {
+                    const wxmlSnippet = '\n<view class="chucker-float-btn" bindtap="chuckerTap">C</view>\n';
+                    const newContent = content + wxmlSnippet;
+                    assets[filename] = {
+                        source: () => newContent,
+                        size: () => newContent.length,
+                    };
+                }
+            }
+            // 2. Inject styles to main style sheets (app.wxss / app.acss / etc.)
+            const isAppStylesheet = /^app\.(wxss|acss|css|ttss|qss)$/.test(filename);
+            if (isAppStylesheet) {
+                const asset = assets[filename];
+                const originalSource = asset.source();
+                const content = typeof originalSource === "string" ? originalSource : originalSource.toString();
+                if (!content.includes(".chucker-float-btn")) {
+                    const styles = `
+.chucker-float-btn {
+  position: fixed !important;
+  bottom: calc(env(safe-area-inset-bottom) + 135rpx) !important;
+  right: 15px !important;
+  width: 46px !important;
+  height: 46px !important;
+  border-radius: 23px !important;
+  color: white;
+  background-color: rgba(30, 30, 30, 0.85) !important;
+  border: 1px solid rgba(255, 255, 255, 0.15) !important;
+  box-shadow: 0 4px 16px rgba(0, 0, 0, 0.3) !important;
+  display: flex !important;
+  align-items: center !important;
+  justify-content: center !important;
+  z-index: 99999 !important;
+  font-size: 20px !important;
+}
+`;
+                    const newContent = content + styles;
+                    assets[filename] = {
+                        source: () => newContent,
+                        size: () => newContent.length,
+                    };
+                }
+            }
+        });
+    });
+};

package/dist/loader.d.ts

@@ -0,0 +1,2 @@
+declare function chuckerAppLoader(this: any, source: string): string;
+export = chuckerAppLoader;

package/dist/loader.js

@@ -0,0 +1,14 @@
+"use strict";
+function chuckerAppLoader(source) {
+    // Only inject if in dev/build or check for custom environment variables if needed
+    const injection = `
+import { initChucker } from 'tarojs-plugin-chucker/runtime';
+try {
+  initChucker();
+} catch (e) {
+  console.error('Chucker auto-initialization error:', e);
+}
+`;
+    return injection + source;
+}
+module.exports = chuckerAppLoader;

package/dist/runtime/components/Chucker.d.ts

@@ -0,0 +1,2 @@
+import React from "react";
+export declare const Chucker: React.FC;