-
-
Notifications
You must be signed in to change notification settings - Fork 1
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #38 from oslabs-beta/austin/readme
added readme for npm package
- Loading branch information
Showing
11 changed files
with
192 additions
and
84 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,61 @@ | ||
| # React Query Rewind | ||
| See https://github.com/oslabs-beta/react-query-rewind/blob/main/README.md for a complete overview. | ||
|
|
||
| This document details setting up the package and examples for a testing environment. | ||
|
|
||
| ## Production Installation and Set-Up | ||
| Install the pacakage with: | ||
| `npm i -D react-query-rewind` | ||
|
|
||
| Import the ReactQueryRewind component and place it as close as possible to the root of your app. | ||
|
|
||
| Download the chrome extension from ***insert url here*** in order to time travel state in a developer toosl panel within your chrome browser. | ||
|
|
||
| ## Example | ||
|
|
||
| ```javascript | ||
| import React from 'react'; | ||
| import ReactDOM from 'react-dom/client'; | ||
| import App from './App'; | ||
| import { QueryClient, QueryClientProvider } from '@tanstack/react-query'; | ||
| import { ReactQueryDevtools } from '@tanstack/react-query-devtools'; | ||
|
|
||
| const queryClient = new QueryClient(); | ||
|
|
||
| ReactDOM.createRoot(document.getElementById('root')!).render( | ||
| <QueryClientProvider client={queryClient}> | ||
| <ReactQueryRewind/> | ||
| <App /> | ||
| <ReactQueryDevtools /> | ||
| </QueryClientProvider> | ||
| ); | ||
| ``` | ||
|
|
||
| ## Set-Up Examples | ||
| **From the package directory:** | ||
| Run with "1" or "2" depending on which example you'd like to set up | ||
| 1. `npm run install-all` | ||
| 1. Installs all dependencies for the package and both example apps | ||
| 2. `npm run link-dependencies-1` or `npm run link-dependencies-2` | ||
| 1. Installs all peer dependencies in our package to ensure there are no duplicates | ||
| 2. Can see all packages currently linked with *`npm ls -g --depth=0 --link=tr`* | ||
| 3. `npm run watch` | ||
| 1. Starts rollup in watch mode and creates dist folder | ||
| 4. `npm run link-package-1` *or* `npm run link-package-2` | ||
| 1. Links React Query Rewind | ||
| 5. `npm run example-1` *or* `npm run example-2` | ||
| 1. Starts the example server with webpack. Note: this is a hot reload, but it does not always pick up changes to the npm package | ||
|
|
||
| # Publishing | ||
| 1. `npm login` to login to the npm site. Follow the instructions to publish your npm package | ||
| 2. `npm publish` | ||
|
|
||
| # Development | ||
| Contributions are always welcome. Please create a fork from https://github.com/oslabs-beta/react-query-rewind. | ||
|
|
||
|
|
||
| ### Future Development Needs | ||
| - Rollup currently does not build on older macs or on Linux (we have not confirmed the issue on Windows yet) | ||
| - Some developers on older macs need to install @rollup/rollup-darwin-x64 to get the build working | ||
| - Github actions uses linux and as a result, our test.yml script installs @rollup/rollup-darwin-x64 to ensure the build works properly | ||
| - Future development should ensure that builds work correclty regardless of the developer's machine and remove the installation of @rollup/rollup-darwin-x64 from the tests.yml file |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,61 +1,106 @@ | ||
| # React Query Rewind | ||
| See https://github.com/oslabs-beta/react-query-rewind/blob/main/README.md for a complete overview. | ||
|
|
||
| This document details setting up the package and examples for a testing environment. | ||
|
|
||
| ## Production Installation and Set-Up | ||
| Install the pacakage with: | ||
| `npm i -D react-query-rewind` | ||
|
|
||
| Import the ReactQueryRewind component and place it as close as possible to the root of your app. | ||
|
|
||
| Download the chrome extension from ***insert url here*** in order to time travel state in a developer toosl panel within your chrome browser. | ||
|
|
||
| ## Example | ||
|
|
||
| ```javascript | ||
| import React from 'react'; | ||
| import ReactDOM from 'react-dom/client'; | ||
| import App from './App'; | ||
| import { QueryClient, QueryClientProvider } from '@tanstack/react-query'; | ||
| import { ReactQueryDevtools } from '@tanstack/react-query-devtools'; | ||
|
|
||
| const queryClient = new QueryClient(); | ||
|
|
||
| ReactDOM.createRoot(document.getElementById('root')!).render( | ||
| <QueryClientProvider client={queryClient}> | ||
| <ReactQueryRewind/> | ||
| <App /> | ||
| <ReactQueryDevtools /> | ||
| </QueryClientProvider> | ||
| ); | ||
| ``` | ||
|
|
||
| ## Set-Up Examples | ||
| **From the package directory:** | ||
| Run with "1" or "2" depending on which example you'd like to set up | ||
| 1. `npm run install-all` | ||
| 1. Installs all dependencies for the package and both example apps | ||
| 2. `npm run link-dependencies-1` or `npm run link-dependencies-2` | ||
| 1. Installs all peer dependencies in our package to ensure there are no duplicates | ||
| 2. Can see all packages currently linked with *`npm ls -g --depth=0 --link=tr`* | ||
| 3. `npm run watch` | ||
| 1. Starts rollup in watch mode and creates dist folder | ||
| 4. `npm run link-package-1` *or* `npm run link-package-2` | ||
| 1. Links React Query Rewind | ||
| 5. `npm run example-1` *or* `npm run example-2` | ||
| 1. Starts the example server with webpack. Note: this is a hot reload, but it does not always pick up changes to the npm package | ||
|
|
||
| # Publishing | ||
| 1. `npm login` to login to the npm site. Follow the instructions to publish your npm package | ||
| 2. `npm publish` | ||
|
|
||
| # Development | ||
| Contributions are always welcome. Please create a fork from https://github.com/oslabs-beta/react-query-rewind. | ||
|
|
||
|
|
||
| ### Future Development Needs | ||
| - Rollup currently does not build on older macs or on Linux (we have not confirmed the issue on Windows yet) | ||
| - Some developers on older macs need to install @rollup/rollup-darwin-x64 to get the build working | ||
| - Github actions uses linux and as a result, our test.yml script installs @rollup/rollup-darwin-x64 to ensure the build works properly | ||
| - Future development should ensure that builds work correclty regardless of the developer's machine and remove the installation of @rollup/rollup-darwin-x64 from the tests.yml file | ||
| <a id="readme-top"></a> | ||
|
|
||
| <p align="center"> | ||
| <img src="./assets/icon.png" alt="Logo" width="250"/> | ||
| </p> | ||
|
|
||
| # Technologies | ||
|
|
||
| [](https://www.javascript.com/) | ||
| [](https://www.typescriptlang.org/) | ||
| [](https://reactjs.org/) | ||
| [](https://html.com/html5/) | ||
| [](https://webpack.js.org/) | ||
| [](https://d3js.org/) | ||
| [](https://eslint.org/) | ||
| [](https://mui.com/) | ||
| [](https://jestjs.io/) | ||
| [](https://babeljs.io/) | ||
|
|
||
| # Overview | ||
|
|
||
| React Query Rewind introduces a powerful DevTool extension designed to work in conjunction with React Query's built-in DevTools in order to optimize time-traveling through state changes in an application. This open-source extension is tailored to enhance the debugging experience for React Query users, allowing them to explore state changes and component relationships with ease. | ||
|
|
||
| # Getting Started | ||
|
|
||
| ## Prerequisites | ||
|
|
||
| 1. React Query installed and in use in your application. | ||
|
|
||
| 2. Install RQRewind Chrome Extension. | ||
|
|
||
| <!-- _link / picture of Extension in Chrome Store_ --> | ||
|
|
||
| ## Installation | ||
|
|
||
| 1. Download npm package into your application. | ||
|
|
||
| ```sh | ||
| npm i react-query-rewind | ||
| ``` | ||
|
|
||
| 2. Import the ReactQueryRewind component into the root of your applicaiton. | ||
|
|
||
| _picture of importing the component_ | ||
|
|
||
| ```javascript | ||
| import ReactQueryRewind from 'react-query-rewind'; | ||
| ``` | ||
|
|
||
| 3. Place ReactQueryRewind next to the root of your application inside the QueryClientProvider component. | ||
|
|
||
| ```javascript | ||
| ReactDOM.createRoot(document.getElementById('root')!).render( | ||
| <QueryClientProvider client={queryClient}> | ||
| <App /> | ||
| <ReactQueryRewind /> | ||
| </QueryClientProvider> | ||
| ); | ||
| ``` | ||
|
|
||
| 4. Open the Chrome DevTool Extension and start coding! | ||
|
|
||
| <p align="left"> | ||
| <img src="./assets/chrome-devtool.png" alt="Component Placement" width="600"/> | ||
| </p> | ||
|
|
||
| # Features | ||
|
|
||
| - <b>Query States: </b>Upon opening RQRewind in Chrome Dev Tools, you will see the Queries tab open with a drop down menu listing the query keys of all the incoming queries. Select the queries that you want to monitor, make changes on the web app, and the changes of query states will be logged as reflected by the growing number above the play bar. Use the play bar to navigate to a particular state snapshot that you would like to inspect. | ||
|
|
||
| <p align="center"><img src="./assets/query-states.gif" width='800' style="margin-top: 1em; margin-bottom: 1em;"></p> | ||
|
|
||
| - <b>State Diff: </b>Toggle on the Diff button to see state changes between each snapshot highlighted. Turn on the switch on top of the page to show only parts of the state that are changed. | ||
|
|
||
| <p align="center"><img src="./assets/state-diff.gif" width='800' style="margin-top: 1em; margin-bottom: 1em;"></p> | ||
|
|
||
| - <b>Live UI Change: </b>As you review the state change history, there is also the option to turn on the time travel mode by clicking on the clock icon button. Under time travel mode, when visiting a logged state snapshot on RQRewindl, the UI of the app will change accordingly. Turn off time travel mode for RQRewind to continue logging future state changes. | ||
|
|
||
| <p align="center"><img src="./assets/UI-change.gif" width='800' style="margin-top: 1em; margin-bottom: 1em;"></p> | ||
|
|
||
| - <b>Component Tree: </b> Click on the Component Tree tab and turn on the Start Profiling switch. Click on any component on the app, and view the component tree that is rendered on the dev tools panel. | ||
|
|
||
| <p align="center"><img src="./assets/component-tree.gif" width='800' style="margin-top: 1em; margin-bottom: 1em;"></p> | ||
|
|
||
| # Contact Information | ||
|
|
||
| Austin Cavanagh - [GitHub](https://github.com/austin-cavanagh) - [LinkedIn](https://www.linkedin.com/in/austincavanagh/) - austin.cavanagh.cs@gmail.com | ||
|
|
||
| Emma Teering - [GitHub](https://github.com/eteering) - [LinkedIn](https://www.linkedin.com/in/emma-teering/) - teeringe@gmail.com | ||
|
|
||
| John Dunn - [GitHub](https://github.com/johnwdunn20) - [LinkedIn](https://www.linkedin.com/in/johnwdunn/) - johnwdunn20@gmail.com | ||
|
|
||
| Rui Fan - [GitHub](https://github.com/ruifan-IU) - [LinkedIn](https://www.linkedin.com/in/rui-fan-868231299/) - rfan1986@gmail.com | ||
|
|
||
| # Links | ||
|
|
||
| [](https://medium.com/@teeringe/react-query-rewind-time-travel-debugging-made-simple-46aaeeafd497) | ||
| [](https://www.linkedin.com/company/react-query-rewind/) | ||
|
|
||
| Project Link: [React Query Rewind](https://github.com/oslabs-beta/react-query-rewind-chrome) | ||
|
|
||
| # License | ||
|
|
||
| _MIT Link_ | ||
|
|
||
| <p align="right">(<a href="#readme-top">back to top</a>)</p> |
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
File renamed without changes
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters