From 433970dd298daf9249c257b4327b743e9129ef3c Mon Sep 17 00:00:00 2001 From: zthxxx Date: Tue, 7 Nov 2023 08:42:00 +0800 Subject: [PATCH] docs: update basic README for packages, update docs of compiler plugin --- docs/pages/docs/compiler-plugin.mdx | 67 ++++++++++++++--- docs/pages/docs/integration/vite.mdx | 2 +- packages/babel-plugin/README.md | 23 +++++- packages/inspector/README.md | 107 ++++++++++++++++++++++++++- packages/inspector/package.json | 3 +- packages/middleware/README.md | 15 ++++ packages/umi4-plugin/README.md | 5 ++ packages/vite-plugin/README.md | 4 + 8 files changed, 212 insertions(+), 14 deletions(-) mode change 120000 => 100644 packages/inspector/README.md diff --git a/docs/pages/docs/compiler-plugin.mdx b/docs/pages/docs/compiler-plugin.mdx index 51d00040..2d8b543f 100644 --- a/docs/pages/docs/compiler-plugin.mdx +++ b/docs/pages/docs/compiler-plugin.mdx @@ -37,15 +37,65 @@ or read from React's `fiber._debugSource`, some compiler with plugins can provid ## Babel -There are two supported Babel plugins available should you need them: +There are some supported Babel plugins available should you need them to record source path information into React components during the development phase: -### `@babel/plugin-transform-react-jsx-source` +### `@babel/preset-react` ```bash npm2yarn -npm i -D @babel/plugin-transform-react-jsx-source +npm i -D @babel/preset-react ``` -[`@babel/plugin-transform-react-jsx-source`](https://babeljs.io/docs/babel-plugin-transform-react-jsx-source) could inject `__source` props to JSX Elements, +[`@babel/preset-react`](https://babeljs.io/docs/babel-preset-react) is a Babel preset that compiles JSX and other stuff to React, +and most React frameworks used it as **built-in preset**, so maybe you don't have to install it. + +If you are already using `@babel/preset-react`, **make sure it have enabled the `development` option**, that will provide precise code location information for debugging React apps. + +```ts showLineNumbers {7} +{ + presets: [ + [ + '@babel/preset-react', + { + runtime: 'automatic', // for react >= 16.14.0 + development: process.env.NODE_ENV === 'development', + }, + ], + ], +} +``` + + +With `development` and `runtime: 'automatic'` options enabled, it will append `@babel/plugin-transform-react-jsx-development` into plugins. + +> while set `runtime: 'classic'` _(for react < 16.14.0)_, it will append legacy `@babel/plugin-transform-react-jsx-source` as instead. + +Furthermore, you can also manually add these plugins to your Babel configuration if required. + + +#### `@babel/plugin-transform-react-jsx-development` + +If you are already using `@babel/preset-react`, it will be automatically enabled by the `development` option so you don't have to install it. + +[`@babel/plugin-transform-react-jsx-development`](https://babeljs.io/docs/babel-plugin-transform-react-jsx-development) could inject the `source` params to `_jsxDEV` function, +which will be transform to `fiber._debugSource` by React. + +```tsx +// Input +
+ +// Output +_jsxDEV("div", {}, void 0, false, { + fileName: '/absolute/path/Component.tsx', + lineNumber: 10, + columnNumber: 6 + }, +) +``` + + +#### `@babel/plugin-transform-react-jsx-source` + +The legacy plugin [`@babel/plugin-transform-react-jsx-source`](https://babeljs.io/docs/babel-plugin-transform-react-jsx-source) could inject `__source` props to JSX Elements, which will be transform to `fiber._debugSource` by React. ```tsx @@ -56,10 +106,6 @@ which will be transform to `fiber._debugSource` by React.
``` - - **Note:** Most React frameworks used `@babel/plugin-transform-react-jsx-source` plugin as **built-in preset**, - includes Vite / Next.js / Remix / Gatsby / Umijs / create-react-app / ... - ### `@react-dev-inspector/babel-plugin` @@ -81,8 +127,9 @@ which will eventually appear on the DOM element. ``` - The difference is that `@react-dev-inspector/babel-plugin` will inject the **relative path** for aesthetic reasons, - while the `@babel/plugin-transform-react-jsx-source` injects the **absolute path**. + The difference is that **`@react-dev-inspector/babel-plugin`** will inject the **relative path** for aesthetic reasons, + while the [`@babel/plugin-transform-react-jsx-development`](https://react-dev-inspector.zthxxx.me/docs/compiler-plugin#babelplugin-transform-react-jsx-development) + injects the **absolute path**. ### Setup Examples diff --git a/docs/pages/docs/integration/vite.mdx b/docs/pages/docs/integration/vite.mdx index 5f3557fd..7d7aae01 100644 --- a/docs/pages/docs/integration/vite.mdx +++ b/docs/pages/docs/integration/vite.mdx @@ -14,7 +14,7 @@ At first install the plugin package: npm i -D @react-dev-inspector/vite-plugin ``` -The `@react-dev-inspector/vite-plugin{:ts}` now export a `inspectorServer` that compatible with `vite@4` / `vite@3` / `vite@2`, +The `@react-dev-inspector/vite-plugin{:ts}` now export a `inspectorServer` that compatible with `vite@5` / `vite@4` / `vite@3` / `vite@2`, just add it into `vite.config.ts` and that's all done. diff --git a/packages/babel-plugin/README.md b/packages/babel-plugin/README.md index 40a4713c..3d96b86a 100644 --- a/packages/babel-plugin/README.md +++ b/packages/babel-plugin/README.md @@ -1,3 +1,24 @@ -Babel plugin for `react-dev-inspector` +## `@react-dev-inspector/babel-plugin` + +NPM Version + +Babel plugin for [`react-dev-inspector`](https://www.npmjs.com/package/react-dev-inspector) Docs see: https://react-dev-inspector.zthxxx.me/docs/compiler-plugin + + +```bash npm2yarn +npm i -D @react-dev-inspector/babel-plugin +``` + +`@react-dev-inspector/babel-plugin` could inject some custom data attributes start with `data-inspector-`, +which will eventually appear on the DOM element. + + +```tsx +// Input +
+ +// Output +
+``` diff --git a/packages/inspector/README.md b/packages/inspector/README.md deleted file mode 120000 index fe840054..00000000 --- a/packages/inspector/README.md +++ /dev/null @@ -1 +0,0 @@ -../../README.md \ No newline at end of file diff --git a/packages/inspector/README.md b/packages/inspector/README.md new file mode 100644 index 00000000..3d254dc5 --- /dev/null +++ b/packages/inspector/README.md @@ -0,0 +1,106 @@ +

React Dev Inspector

+ +

+ NPM Version + NPM Downloads + Node.js + License +

+ +## Introduction + +**react-dev-inspector** is the tool for seamlessly code navigation from browser to IDE. + +With **just a simple click**, you can jump from a React component on the browser to its source code in your local IDE instantly. +Think of it as a more advanced version of Chrome's Inspector. + +See the document on: https://react-dev-inspector.zthxxx.me + +#### Why React Dev Inspector + +Have you ever run into any of these issues 🤔: + +- You've got to fix some bugs in your team's project, but you have no idea where the heck page/component's code is located. +- You're eager to dive into an open-source project that interests you, but it's hard to find where the code for the page/component is implemented. +- You may thinking about a component and want to quickly peek at its code, but don't want to memorize or manually expand those never-ending deep file paths. + +That's exactly why react-dev-inspector was created. + +
+ +### Quick Look + +Just check out this demo below and you'll get it in a snap. + +> screen record gif (8M size): + +Showcase: https://react-dev-inspector.zthxxx.me/showcase + +[![inspector-gif](https://github.com/zthxxx/react-dev-inspector/raw/master/docs/images/inspect.gif)](https://react-dev-inspector.zthxxx.me/showcase) + +Wanna try out the demo right now? Sure, here is the online demo: + +[ + ![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg) +](https://stackblitz.com/edit/github-x3rkzl?file=package.json,vite.config.ts%3AL17) + +
+ +## How to Use and Configure + +According to the working pipeline [below](#how-it-works), the **Part.1** and **Part.2** are what you need configure to use. + +Basically, it's includes: +1. [add the `` component in your page](https://react-dev-inspector.zthxxx.me/docs/inspector-component) +2. [integrate the middleware in your framework's dev-server](https://react-dev-inspector.zthxxx.me/docs/integration) + +Check the [Documentation Site](https://react-dev-inspector.zthxxx.me/docs) for more details + +
+ +## How It Works + +Here is the working pipeline of `react-dev-inspector`: + +[ + ![Working Pipeline](https://github.com/zthxxx/react-dev-inspector/raw/dev/docs/images/working-pipeline.svg) +](https://react-dev-inspector.zthxxx.me/docs#how-it-works) + +
+ +### 0. Inject JSX Source + +The compiler's [`plugin`](https://react-dev-inspector.zthxxx.me/docs/compiler-plugin) +records source path info into React components during development stage. + +> **Note:** The **0** of _Part.0_ implies that this section is generally **OPTIONAL**. +> Most React frameworks offer this feature **_out-of-the-box_**, +> which means you usually **don't** need to manually configure it additionally. + +### 1. Inspector Component + +The react-dev-inspector provide a [``](https://react-dev-inspector.zthxxx.me/docs/inspector-component) component to reads the source info, +and sends it to the dev-server when you inspect elements on browser. + +### 2. Dev Server Middleware + +The react-dev-inspector provide some [middlewares](https://react-dev-inspector.zthxxx.me/docs/integration) for dev-server in most frameworks to receives source path info from API, +then call your local IDE/Editor to open the source file. + +
+ +--- + +## Articles about it + +- [chinese] [🎉 我点了页面上的元素，VSCode 乖乖打开了对应的组件？原理揭秘](https://juejin.cn/post/6901466406823575560) + +
+ +--- + +## License + +[MIT LICENSE](./LICENSE) + +> Thanks for @zthxxx @sonacy @sl1673495 diff --git a/packages/inspector/package.json b/packages/inspector/package.json index 453e083d..d69e9c52 100644 --- a/packages/inspector/package.json +++ b/packages/inspector/package.json @@ -11,10 +11,11 @@ "test:watch": "vitest watch", "clean": "rimraf coverage dist es lib build", "dev": "storybook dev -p 6006", + "sync:readme": "cp -f ../../README.md README.md", "build:storybook": "storybook build", "build:esm": "tsc -p tsconfig.esm.json", "build:cjs": "tsc -p tsconfig.cjs.json", - "build": "npm-run-all clean --parallel build:esm build:cjs" + "build": "npm-run-all clean --parallel sync:readme build:esm build:cjs" }, "repository": "https://github.com/zthxxx/react-dev-inspector/tree/master/packages/inspector", "publishConfig": { diff --git a/packages/middleware/README.md b/packages/middleware/README.md index 80ee45b9..df34514e 100644 --- a/packages/middleware/README.md +++ b/packages/middleware/README.md @@ -1,3 +1,18 @@ +## `@react-dev-inspector/middleware` + +NPM Version + Dev-Server middleware for `react-dev-inspector` Docs see: https://react-dev-inspector.zthxxx.me/docs/integration#inspector-middleware + +This package mainly just provides a **`launchEditorMiddleware`**, +that is an [Express.js](https://github.com/expressjs/express) / [Connect.js](https://github.com/senchalabs/connect) **compatible** request middleware. + +```bash +npm i -D @react-dev-inspector/middleware +``` + +```ts +import { launchEditorMiddleware } from '@react-dev-inspector/middleware' +``` diff --git a/packages/umi4-plugin/README.md b/packages/umi4-plugin/README.md index 81643b12..3709b019 100644 --- a/packages/umi4-plugin/README.md +++ b/packages/umi4-plugin/README.md @@ -1,3 +1,8 @@ +## `@react-dev-inspector/umi4-plugin` + +NPM Version + + Umi4 plugin for `react-dev-inspector` Docs see: https://react-dev-inspector.zthxxx.me/docs/integration/umijs diff --git a/packages/vite-plugin/README.md b/packages/vite-plugin/README.md index ad6cc3ad..0cc19365 100644 --- a/packages/vite-plugin/README.md +++ b/packages/vite-plugin/README.md @@ -1,3 +1,7 @@ +## `@react-dev-inspector/vite-plugin` + +NPM Version + Vite plugin for `react-dev-inspector` Docs see: https://react-dev-inspector.zthxxx.me/docs/integration/vite