Middle-Aware

A call stack vizualization tool for Express developers!

Middle-Aware is developer tool that visualizes the request and response cycle, and the middleware of a full stack project that uses Express. Middle-Aware will instrument source code, run the project, and trace requests through middleware chains. The tools allows developers to debug, troubleshoot, or understand their project. You can find more information on our Medium article.

Installing

The latest stable version can be found here.

Requirements

Middle-Aware currently requires a local or remote MongoDB database. Please read through MongoDB instructions to acquire one and retrieve a URI.

Getting Started

Once Middle-Aware is installed, create a JSON configuration file that will help Middle-Aware run. Every property in the table below is required. Please see an example of a configuration file below as well.

Property	Type	Description
MONGODB_URI	String	This should be the URI to the MongoDB databse acquired as mentioned under the Requirements section. This can be a local or remote MongoDB instance.
proxyPort	Integer	User-defined port that the Middle-Aware proxy server should run on.
backEndPort	Integer	This tells Middle-Aware which port your project's backend is using. This port should match the port your Express server will be listening on.
frontEndPort	Integer	This tells Middle-Aware which port your project's frontend is using. This port should match the port your frontend will be running on.
targetDir	String	This must be an absolute path. This tells Middle-Aware where to run a copy of the your project (shadow directory). Middle-Aware does not create a directory at this path. So, you may want to target an empty directory like in the example above.
rootDir	String	This must be an absolute path. This tells Middle-Aware where your project is located and this must be the root level of the project.
backEnd	String	This must be an absolute path. This tells Middle-Aware where your project's backend is located. This must be the top most level of the backend to be instrumented by the tool.
frontEnd	String	This must be an absolute path. This tells Middle-Aware where your project's frontend is located and this must be the root level of the frontend.
startScript	String	Provide the scripts that will run your project, both frontend and backend. If Webpack Dev Server is configured in your project, we recommend providing the script that will start it. Additionally if using TypeScript, compiling will be required first. See examples below.
projectName	String	Provide the name of your project here.

{
    "MONGODB_URI":"mongodb+srv://user:password@cluster.mongodb.net/",
    "proxyPort":9001, 
    "backEndPort":3000, 
    "frontEndPort":8080, 
    "targetDir": "/Users/exampleUser/Documents/exampleDirectory", 
    "rootDir":"/Users/exampleUser/Documents/exampleProject", 
    "backEnd":"/Users/exampleUser/Documents/exampleProject/backend", 
    "frontEnd":"/Users/exampleUser/Documents/exampleProject/frontend", 
    "startScript":"tsc && npm start", 
    "projectName":"Example Project Name"
}

If using Webpack Dev Server, refactor your proxy rules to forward all requests to the Middle-Aware proxy server.

devServer: {
    port: 8080,
    static: { directory: './dist' },
    watchFiles: {
      paths: ['./frontend/**/*'],
    },
    historyApiFallback: true,
    proxy: {
      '/api': 'http://localhost:[insert proxyPort value here]',
    },
  }

After the above have been completed...

Open Middle-Aware.
Once open, click on the "Config File" button to load your configuration file.
Once loaded, click on the "Start" button.
Once started, you can go to your frontend (localhost:frontEndPort) in your browser and interact with your project.
After some interaction, click on "Fetch Tests" in Middle-Aware or use the toggle for automatic fetching, to get your instrumentation data.
If you decide to make changes to your source code, repeat steps 3-6 as needed.

The Team

Legal

License

MIT License

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.