Skip to content

Latest commit

 

History

History
256 lines (179 loc) · 15.8 KB

README.md

File metadata and controls

256 lines (179 loc) · 15.8 KB
Raw

Developer README

Brief

Our mission at Reactime is to maintain and iterate constantly, but never at the expense of future developers. We know how hard it is to quickly get up to speed and onboard in a new codebase. So here are some helpful pointers to help you hit the ground running. 🏃🏾💨

Building from source

  1. Download React Dev Tools from the Chrome Webstore Here

  2. Clone down the Reactime repo onto your machine.

git clone https://github.com/open-source-labs/reactime.git
  1. Install dependencies and build.
cd reactime
npm install --force
npm run dev

With release of Node v18.12.1 (LTS) on 11/4/22, the script has been updated to 'npm run dev' || 'npm run build' for backwards compatibility.
For version Node v16.16.0, please use script 'npm run devlegacy' || 'npm run buildlegacy'

  1. Spin up the demo application.
cd demo-app
npm install
npm run dev

Similar approach for Next.js and Remix demo apps

  1. Add Reactime to your Chrome extensions.
  • Navigate to chrome://extensions
  • Select “Load Unpacked”
  • Choose reactime > src > extension > build
  • Navigate to http://localhost:8080/ to inspect the demo application using Reactime!

extension

Linting

Before beginning development, especially on teams, make sure to configure your linter and code formatting to conform to one unified setting (We recommend the Airbnb style guide!) This will make reviewing PRs much more readable and less error-prone.  
 

Possible Avenues for Future Iterators

Here are some notes on the current state of Reactime and considerations for future development.

Including Support for Hooks Beyond useState

Reactime currently shows data stored via useState, but does not show data stored via other hooks such as useContext or useReducer. While showing this data would be simple, maintaining the time travel functionality of Reactime with these hooks would not. Please see file demo-app/src/client/Components/ButtonsWithMoreHooks.jsx for more details.

To see how hook data is stored on the fiber tree:

  1. Change demo-app/src/client/Router.tsx to use utilize the ButtonsWithMoreHooks component
  2. Have the “Load Unpacked” version of Reactime in your chrome extension.
  3. Add console.logs in src/backend/routers/linkFiber.ts to log the fiber tree captured for a running app. In this case it'll be the demo-app
  4. Run Reactime on your computer via "npm run dev", which links your local Reactime to the “Load Unpacked” chrome extension.
  5. Run the demo-app from a separate terminal that's currently in the demo-app directory via "npm run dev"
  6. Navigate through the fiber tree in the console until you find the tree node for demo-app/src/client/Components/IncrementWithMoreHooks.jsx to see hook data.

Any changes to console.logs in Reactime can be seen by refreshing the browser the app is running in.

Replace Functionality for Outdated Packages

Material-ui/core hasn't been updated to use React 18. This is the reason npm install --force is necessary when installing the dependencies of Reactime. Replacing the functionality this package performs and removing it from Reactime would ensure compatibility moving forward.

React Developer Tools has deprecated __REACT_DEVTOOLS_GLOBAL_HOOK__, which Reactime uses to extract a running application's fiber tree. At the time of the release of Reactime 20 (June 2023), this tool still works reliably to deliver said fiber tree. This will likely be the case until the React version (React version 18.2 at time of writing) undergoes updates that diverge beyond compatibility with __REACT_DEVTOOLS_GLOBAL_HOOK__. At this time, Reactime will need to change how it extracts an application's fiber tree.

Changing how Reactime extracts the fiber tree before said React version update may yield diminishing result, as whatever method will also need to be updated to match React's breaking updates.

Redux

Can Reactime be integrated with Redux compatibility so applications using Redux can track state in Reactime?

Yes, but it would be very time-consuming and not the most feasible option while Redux devtools exists already. With how Redux devtools is currently set up, a developer is unable to use Redux devtools as a third-party user and integrate its functionality into their own application, as Redux devtools is meant to be used directly on an application using Redux for state-tracking purposes. Since the devtools do not appear to have a public API for integrated use in an application or it simply does not exist, Redux devtools would need to be rebuilt from the ground up and then integrated into Reactime, or built into Reactime directly still from scratch.

File Structure

In the src folder, there are three directories we care about: app, backend, and extension.

src/
├── app/                          # Frontend code
│   ├── __tests__/                # React Testing Library
│   ├── actions/                  # Redux action creators
│   ├── components/               # React components
│   ├── constants/                #
│   ├── containers/               # More React components
│   ├── reducers/                 # Redux mechanism for updating state
│   ├── styles/                   #
│   ├── FrontendTypes.ts          # Library of typescript interfaces
│   ├── index.tsx                 # Starting point for root App component
│   ├── module.d.ts               #
│   └── store.tsx                 #
│
├── backend/                      # "Backend" code (injected into target app)
│   │                             # Focus especially on linkFiber, timeJump, tree, and helpers
│   ├── __tests__/                #
│   ├── controllers/              #
│       ├── createComponentActionsRecord.ts # Update the componentActionsRecord with new bound state-update methods
│       ├── createTree.ts         # Construct a tree snapshot from the FiberRoot tree given by ReactFiber.
│       ├── statePropExtractor.ts # Helper functions to extract & format prop, state, and context data
│       ├── throttle.ts           #
│       ├── timeJump.ts           # Rerenders DOM based on snapshot from background script
│   ├── models/
│       ├── filterConditions.ts   #
│       ├── masterState.ts        # Component action record interface
│       ├── routes.ts             # Interfaces with the browser history stack
│       ├── tree.ts               # Custom structure to send to background
│   ├── routers/
│       ├── linkFiber.ts          # Check for all requirement to start Reactime and
│       ├── snapShot.ts           #
│   ├── types/                    # Typescript interfaces
│   ├── index.ts                  # Starting point for backend functionality
│   ├── index.d.ts                # Definitely Type file for Index
│   ├── module.d.ts               #
│   ├── puppeteerServer.ts        #
│
├── extension/                    # Chrome Extension code
│   ├── build/                    # Destination for bundles and manifest.json (Chrome config file)
│   │                             #
│   ├── background.js             # Chrome Background Script
│   └── contentScript.ts          # Chrome Content Script
└──

Diagrams

All the diagrams of data flows are available on MIRO

  1. The app folder is responsible for the Single Page Application that you see when you open the chrome dev tools under the Reactime tab.

FRONTEND DATA FLOW

  1. The backend folder contains the set of all scripts that we inject into our "target" application via background.js
    • In Reactime, its main role is to generate data and handle time-jump requests from the background script in our extension folder.

BACKEND RECORD SNAPSHOT DATA FLOW

BACKEND TIME TRAVEL DATA FLOW

  1. The extension folder is where the contentScript.js and background.js are located.
    • Like regular web apps, Chrome Extensions are event-based. The background script is where one typically monitors for browser triggers (e.g. events like closing a tab, for example). The content script is what allows us to read or write to our target web application, usually as a result of messages passed from the background script.
    • These two files help us handle requests both from the web browser and from the Reactime extension itself

Data Flow Architecture

The general flow of data is described in the following steps:

GENERAL DATA FLOW

  1. When the background bundle is loaded by the browser, it executes a script injection into the dom. (see section on backend). This script uses a technique called throttle to send state data from the app to the content script every specified milliseconds (in our case, this interval is 70ms).

  2. The content script (now contentScript.ts) always listens for messages being passed from the extension's target application. Upon receiving data from the target app, the content script will immediately forward this data to the background script which then updates an object called tabsObj. Each time tabsObj is updated, its latest version will be passed to Reactime, where it is processed for displaying to the user by the app folder scripts.

  3. Likewise, when Reactime emits an action due to user interaction -- a "jump" request for example -- a message will be passed from Reactime via the background script to the content script. Then, the content script will pass a message to the target application containing a payload that represents the state the user wants the DOM to reflect or "jump" to.

    • One important thing to note here is that this jump action must be dispatched in the target application (i.e. backend land), because only there do we have direct access to the DOM.

Reacti.me Website:

See Reacti.me README for instruction of how to update the website

Console logs

Navigation between different console.log panels can be confusing when running Reactime. We created a short instruction where you can find the results for your console.log

/src/extension

Console.logs from the Extension folder you can find here:

  • Chrome Extension (Developer mode)
  • Background page

extension

/src/app

Console.logs from the App folder you can find here:

  • Chrome Browser
  • Inspect

frontend

/src/backend

Console.logs from the App folder you can find here:

  • Open the Reactime extension in Chrome
  • Click "Inspect" on Reactime

backend

Chrome Developer Resources

Still unsure about what content scripts and background scripts do for Reactime, or for a chrome extensions in general?

Some relevant sections are reproduced below:

Content scripts are files that run in the context of web pages.

By using the standard Document Object Model (DOM), they are able to read details of the web pages the browser visits, make changes to them and pass information back to their parent extension. (Source)

  • One helpful way to remember a content script's role in the Chrome ecosystem is to think: a content script is used to read and modify a target web page's rendered content.

A background page is loaded when it is needed, and unloaded when it goes idle.

Some examples of events include: The extension is first installed or updated to a new version. The background page was listening for an event, and the event is dispatched. A content script or other extension sends a message. Another view in the extension, such as a popup, calls runtime.getBackgroundPage.

Once it has been loaded, a background page will stay running as long as it is performing an action, such as calling a Chrome API or issuing a network request.

Additionally, the background page will not unload until all visible views and all message ports are closed. Note that opening a view does not cause the event page to load, but only prevents it from closing once loaded. (Source)

  • You can think of background scripts serving a purpose analogous to that of a server in the client/server paradigm. Much like a server, our background.js listens constantly for messages (i.e. requests) from two main places:
    1. The content script
    2. The chrome extension "front-end" (NOT the interface of the browser, this is an important distinction.)
  • In other words, a background script works as a sort of middleman, directly maintaining connection with its parent extension, and acting as a proxy enabling communication between it and the content script.

Launching to Chrome Web Store

Once you are ready for launch, follow these steps to simplify deployment to the Chrome Web Store:

  1. Run npm run build in Reactime to build the production version of Reactime
  2. Right click on the build folder and click “compress” to make a compressed zip version of the build folder. The compressed zip is what you will upload to the Chrome Web Store
  3. Navigate to the Chrome Web Store Developer Dashboard (logged in with Reactime credentials). Go to Build > Package > Upload new package, and when prompted, upload the build.zip file
  4. Update the Store Listing and that’s it! Click “Submit for review” and wait for the Chrome store to process your request

Past Medium Articles for Reference