Skip to content

Developing

Jump to bottom
Bennett Wu edited this page May 4, 2025 · 5 revisions

Relevant Technologies

Resources

ReactJS

A JavaScript library for frontend development, but you can also think of it as a template for organizing code for a web page. You will want to become comfortable with JavaScript if you are not already.

  • The core idea of React is to separate code into components. For example, on most websites, a header is a component; a sidebar is a component; buttons can be components nested in other components, and so on. This is useful because it allows us to reuse code when we need the same type of components multiple times. It also allows us to render only one component at a time, using much less overhead than re-rendering a whole site. React handles component rendering automatically to optimize it for the page. For example, the Recognition component renders multiple times per second as it gets Speech Recognition results (because we keep updating the component's recognition variable). We don't want the whole page to re-render every time this happens so we split it into components.
  • React uses TSX for the actual elements on the page. TSX is a version of JSX which uses Typescript instead of Javascript. While Javascript and Typescript are similar I would definitely recommend having a good grasp on the differences between the two before trying to add code to this project.
  • State is generally maintained directly in components, except when a global state manager like Redux is used.
    • Data can be passed down from parent to child components through props, which are kind of like arguments or parameters passed to the child. However, data cannot be passed up from a child to a parent. This is why React is said to have a unidirectional data flow. One workaround is to pass a function down as a prop, which the child can call to be executed by the parent. This is done in Options, which passes functions to the OnOff, etc. components in order to reuse OnOff for different purposes if necessary.
    • Components can modify their own state (via the function setState), and they can modify their children's props, but they can't modify their own props.
  • Here is a look at the component tree for the site so far. If you expand the src/components folder of the code, you'll see the same structure. Of course, the component tree will change over time. 
    ├ App
├─── API
└─────── WebspeechRecognition
├─────── AzureRecognition
├─── SIDEBAR
├─────── Display
├─────── Phrase
├─────── SpeechToText
├─────── Visualization
├─── TOPBAR
├─────── PickApi
├─────── FullScreen
├─────── MenuHide

Redux

A JavaScript library used to store global state. It is particularly useful alongside React because it solves many of the difficulties created by React's unidirectional data flow.

  • Without a global state manager, state can only be stored in components and passed down from one component to another (recall React's unidirectional data flow). So in React alone, if you want to pass state up to a parent component, you have to declare a function in the parent component and pass it down to the child as a prop. This can get very tedious and lead to over-rendering when you have multiple levels of components. A common problem with this is prop drilling, which is when you have to pass props through many levels of components when the components in the middle have no need for the data. For example, the buttons are stored in OnOff, PlusMinus, and Record, but most of the data they control is needed across the entire page. Redux is a great tool to store state globally and avoid tedious/inefficient prop drilling.
  • In the site, Redux is only used for the options buttons as described above. You can check out the redux directory to see how it's set up. OnOff, PlusMinus, and Record set state. App and Captions use this state.
  • Keep in mind that Redux cannot be used directly in React class components. As a workaround, Captions (functional component) gets global state from Redux and passes it down to Recognition (class component) as props.
  • This video is a great resource for learning Redux in conjunction with React. Everything I know about Redux came from this video, so obviously I'm still at a beginner level with it. Still, the video covers everything you need to know to understand how the site currently uses Redux for global state. Use the video to try to understand what is going on in Options and its child components. Options does not invoke Redux but it does pass functions to its children to be used by Redux.

Setup

  1. Ensure Node.js and npm are installed on your computer.
    • Download from: https://nodejs.org/en.
    • Node comes with npm (Node Package Manager), which we will use for managing our dependencies.
    • The commands node -v and npm -v will return the version numbers of Node and npm respectively.
      • Make sure both commands run successfully. If they don't, make sure node and npm are in your system path configuration.
  2. Ensure Git is install on your computer. See: https://git-scm.com/
  3. Clone the repository and cd into it 
    git clone https://github.com/scribear/ScribeAR.github.io && cd ScribeAR.github.io
  4. Install dependencies 
    npm install
  5. Start up your local instance. This will start the development server and automatically update the page when you make changes. 
    npm start

Building

  • To build the app for production, run 
    npm run build
  • The build will be placed in the build folder.

File Structure

Here are some relevant files worth knowing about. These files are present in any React repository. Most of them are initialized automatically with the command npx create-react-app.

  • .gitignore
    • Lists files that should not be tracked by Git.
  • node_modules directory
    • Contains the project dependencies.
    • Managed by npm, you should not chance things in this folder directly unless you know what you're doing.
    • Will not be committed to Git.
  • package.json
    • Provides information that:
      • (a) npm uses to build the app,
      • (b) npm uses to manage dependencies, and
      • (c) metadata like home URL and version number
    • JSON stands for JavaScript Object Notation and is essentially a JS-style object with key-value pairs.
    • The most important parts of this file are:
      • dependencies, which specifies the dependencies and version numbers we are using in our project.
        • This is automatically updated when you install/remove a dependencies with npm.
      • scripts, which allows us to define shorthands for some common commands.
    • Note that package.json is committed to Git.
      • When you want to add a new dependency to the project, run npm install <dependencyname> and npm will automatically update node_modules and package.json.
      • When you push a commit, you will include this file with any dependencies and scripts that you added (i.e. it's not in .gitignore).
      • When you pull a commit, it may contain updated dependencies or scripts. This information will be stored in this file. Run npm update to apply these changes locally to your node_modules.
  • public directory
    • Contains static assets to be kept "as is" when building the app
      • For example, images, icons, etc.
      • Assets stored in the public directory and referenced in the project as though they are in the same folder (i.e. ./imgname.jpg).
    • coi-serviceworker.js
    • manifest.json
    • index.html
      • This is the raw HTML file of the page before React.js renders content into the <div id="root"></div> div.
      • Any external CSS libraries, scripts, font, etc. you want to use should be linked in the index.html file.
    • robots.txt
      • Instructions for which URLs a web crawler can access. No guarantees that it will be followed though :(.
  • src directory
    • Contains React.js source code for rendering the page.
    • App.tsx
      • The root component for React.
    • All components are stored in src/components and most of the code you write is somewhere in here.
  • Dockerfile
    • Defines how to build a Docker container for the application
  • nginx.conf
    • Configures Nginx in the Docker container to serve the application

Containerization

The application is containerized using Docker. Here's how you can build and run the container locally.

  1. Ensure Docker is installed on your computer. See https://www.docker.com/.
  2. Build the Docker container locally and give it the scribear-frontend tag. 
    docker build -t scribear-frontend .
  3. Run the Docker container and expose port 8080. 
    docker run -p 8080:80 scribear-frontend

Github Actions

  • Publish Version

  • Deploy

  • Docker

    • Builds the frontend Docker container and pushes to Dockerhub
    • Triggers:
      • On demand
      • Pull request
      • Push to the master or staging branch
      • Push with tag in the form v*.*.*
    • Images are tagged with pull request id, branch, and Github tags.

Additional Notes

  • Checkout the /Readme folder in the repository for some more notes regarding development.

Clone this wiki locally