|
| 1 | +<p align="center"> |
| 2 | + <img src ="./assets/readme-logo-svg.svg" width="300"/> |
| 3 | +</p> |
| 4 | + |
| 5 | +<h1 align="center">State Debugger for React</h1> |
| 6 | + |
| 7 | +[](https://github.com/oslabs-beta/reactime) [](https://travis-ci.com/oslabs-beta/reactime) [](http://badge.fury.io/js/reactime) [](https://david-dm.org/oslabs-beta/reactime#info=dependencies) [](https://david-dm.org/oslabs-beta/reactime?type=dev) [](https://snyk.io/test/github/oslabs-beta/reactime) |
| 8 | + |
| 9 | + |
| 10 | + |
| 11 | + |
| 12 | + |
| 13 | + |
| 14 | +Reactime is a debugging tool for React developers. It records state whenever it is changed and allows the user to jump to any previously recorded state. |
| 15 | + |
| 16 | +This tool is for React apps using stateful components and prop drilling, and has beta support for Context API, conditional state routing, Hooks (useState, useEffect) and functional components. |
| 17 | + |
| 18 | +The latest release extends the core functionality by including support for TypeScript applications, improving the user experience through more declarative titles in the actions panel, and extending support for components with conditional state fields. The testing suite has also been expanded with the inclusion of a Sandbox utility to aid future expansion as well as additional E2E and integration tests with Puppeteer and React Testing Library. |
| 19 | + |
| 20 | +After installing the Reactime, you can test its functionalities in the following demo repositories: |
| 21 | + |
| 22 | +- [Calculator](https://joshua0308.github.io/calculator/) |
| 23 | +- [Bitcoin Price Index](http://reactime-demo2.us-east-1.elasticbeanstalk.com) |
| 24 | + |
| 25 | +Reactime was nominated for the Productivity Booster award at [React Open Source Awards 2020](https://osawards.com/react/)! |
| 26 | + |
| 27 | +## Installation |
| 28 | + |
| 29 | +Two parts are required for this tool to function: a [**Chrome extension**](https://chrome.google.com/webstore/detail/react-time-travel/cgibknllccemdnfhfpmjhffpjfeidjga) and an [**NPM package**](https://www.npmjs.com/package/reactime). |
| 30 | + |
| 31 | +1. Install the Reactime [extension](https://chrome.google.com/webstore/detail/reactime/cgibknllccemdnfhfpmjhffpjfeidjga) from Chrome Web Store. Alternatively, use `src/extension/build/build.zip` for manual installation in [Developer mode](https://developer.chrome.com/extensions/faq#faq-dev-01). Turn on 'Allow access to file URLs' in extension details page if testing locally. |
| 32 | + |
| 33 | +2. Install the [NPM package](https://www.npmjs.com/package/reactime) in your application's root directory. |
| 34 | + |
| 35 | +``` |
| 36 | +npm i reactime |
| 37 | +``` |
| 38 | + |
| 39 | +3. Call the library method on your root container after rendering your App. |
| 40 | + |
| 41 | +``` |
| 42 | +import reactime from 'reactime'; |
| 43 | +
|
| 44 | +const rootContainer = document.getElementById('root'); |
| 45 | +ReactDOM.render(<App />, rootContainer); |
| 46 | +
|
| 47 | +reactime(rootContainer); |
| 48 | +``` |
| 49 | + |
| 50 | +4. For experimental concurrent mode support. |
| 51 | + |
| 52 | +``` |
| 53 | +import reactime from 'reactime'; |
| 54 | +
|
| 55 | +const rootContainer = ReactDOM.createRoot(document.getElementById('root')); |
| 56 | +rootContainer.render(<App />); |
| 57 | +reactime(rootContainer); |
| 58 | +``` |
| 59 | + |
| 60 | +5. Done! That's all you have to do to link your React project to our library. |
| 61 | + |
| 62 | +## How to Use |
| 63 | + |
| 64 | +After installing both the Chrome extension and the NPM package, just open up your project in the browser. |
| 65 | + |
| 66 | +Then open up your Chrome DevTools and navigate to the Reactime tab. |
| 67 | + |
| 68 | +## Features |
| 69 | + |
| 70 | +### Recording |
| 71 | + |
| 72 | +Whenever state is changed (whenever setState or useState is called), this extension will create a snapshot of the current state tree and record it. Each snapshot will be displayed in Chrome DevTools under the Reactime panel. |
| 73 | + |
| 74 | +### Viewing |
| 75 | + |
| 76 | +You can click on a snapshot to view your app's state. State can be visualized in a JSON or a tree. Also, snapshots can be diffed with the previous snapshot, which can be viewed under the Diff tab. |
| 77 | + |
| 78 | +### Jumping |
| 79 | + |
| 80 | +Jumping is the most important feature of all. It allows you to jump to any previous recorded snapshots. Hitting the jump button on any snapshot will change the DOM by setting their state. |
| 81 | + |
| 82 | +### TypeScript Support |
| 83 | + |
| 84 | +Reactime offers beta support for TypeScript applications using stateful class components and functional components with useState hooks. Further testing and development is required for custom hooks, Context API, and Concurrent Mode. |
| 85 | + |
| 86 | +### Additional Features |
| 87 | + |
| 88 | +- multiple tree graph branches depicting state changes |
| 89 | +- tree graph hover functionality to view state changes |
| 90 | +- ability to pan and zoom tree graph |
| 91 | +- multiple tabs support |
| 92 | +- a slider to move through snapshots quickly |
| 93 | +- a play button to move through snapshots automatically |
| 94 | +- a pause button, which stops recording each snapshot |
| 95 | +- a lock button to freeze the DOM in place. setState will lose all functionality while the extension is locked |
| 96 | +- a persist button to keep snapshots upon refresh (handy when changing code and debugging) |
| 97 | +- export/import the current snapshots in memory |
| 98 | +- declarative titles in the actions panel |
| 99 | +- extended support for components with conditional state fields |
| 100 | +- a Sandbox utility to aid future expansion |
| 101 | + |
| 102 | +## Authors |
| 103 | +- **Carlos Perez** - [@crperezt](https://github.com/crperezt) |
| 104 | +- **Edwin Menendez** - [@edwinjmenendez](https://github.com/edwinjmenendez) |
| 105 | +- **Gabriela Jardim Aquino** - [@aquinojardim](https://github.com/aquinojardim) |
| 106 | +- **Gregory Panciera** - [@gpanciera](https://github.com/gpanciera) |
| 107 | +- **Nathanael Wa Mwenze** - [@nmwenz90](https://github.com/nmwenz90) |
| 108 | +- **Ryan Dang** - [@rydang](https://github.com/rydang) |
| 109 | +- **Bryan Lee** - [@mylee1995](https://github.com/mylee1995) |
| 110 | +- **Josh Kim** - [@joshua0308](https://github.com/joshua0308) |
| 111 | +- **Sierra Swaby** - [@starkspark](https://github.com/starkspark) |
| 112 | +- **Ruth Anam** - [@peachiecodes](https://github.com/peachiecodes) |
| 113 | +- **David Chai** - [@davidchaidev](https://github.com/davidchai717) |
| 114 | +- **Yujin Kang** - [@yujinkay](https://github.com/yujinkay) |
| 115 | +- **Andy Wong** - [@andywongdev](https://github.com/andywongdev) |
| 116 | +- **Chris Flannery** - [@chriswillsflannery](https://github.com/chriswillsflannery) |
| 117 | +- **Rajeeb Banstola** - [@rajeebthegreat](https://github.com/rajeebthegreat) |
| 118 | +- **Prasanna Malla** - [@prasmalla](https://github.com/prasmalla) |
| 119 | +- **Rocky Lin** - [@rocky9413](https://github.com/rocky9413) |
| 120 | +- **Abaas Khorrami** - [@dubalol](https://github.com/dubalol) |
| 121 | +- **Ergi Shehu** - [@Ergi516](https://github.com/ergi516) |
| 122 | +- **Raymond Kwan** - [@rkwn](https://github.com/rkwn) |
| 123 | +- **Joshua Howard** - [@Joshua-Howard](https://github.com/joshua-howard) |
| 124 | + |
| 125 | +## License |
| 126 | + |
| 127 | +This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details |
| 128 | + |
0 commit comments