README.md

Monocle

Overview

Monocle is a Makefile visualizer for the web.

You can use it to view a Makefile as a graph of its targets and their dependencies—in your web browser.

Limitations

Monocle has the following limitations:

• It only parses a single Makefile (i.e. it does not follow include paths).

Technologies

Monocle is built upon the following technologies:

• Node 20
• Vite 4
• React 18
• TypeScript 5
• Bootstrap 5 (via react-bootstrap)
• Bootstrap Icons (via bootstrap-icons)
• Codemirror 6 (via @uiw/react-codemirror)
• Mermaid (via mdx-mermaid and patch-package)
• copy-to-clipboard for copying text to the clipboard
• file-saver for downloading files
• is-ios for detecting iOS devices
• Vitest for testing
• Prettier 3 for code formatting
• patch-package for patching NPM packages
• gh-pages for deploying the app

This code base was bootstrapped by running:

npx --yes create-vite monocle --template react-ts

The originally-generated README.md file has been archived to README.bak.md.

Favicon

The favicon (public/favicon.ico) was generated by favicon.io, using the following settings:

• Text: m
• Background: Rounded
• Font Family: Leckerli One
• Font Variant: Regular 400 Normal
• Font Size: 110
• Font Color: #FFFFFF
• Background Color: #212529 (i.e. the same color as Bootstrap's dark theme background; i.e. --bs-body-bg)

Development

Prerequisites

• Node 20 is installed

Quick start

1. Install NPM dependencies

   npm install

2. Start development server

   npm run dev

3. Visit: http://localhost:5173/monocle/

Testing

npm test

Tests are written using Vitest.

Formatting code

npm run prettier

Patches

There are two types of patches in this repository:

1. Those managed manually (these are all in src/patches/)
   1. src/patches/@kba/makefile-parser/index.d.ts: TypeScript information for the @kba/makefile-parser JavaScript package
2. Those managed using patch-package (these are all in patches/)
   1. patches/mdx-mermaid+2.0.0.patch: A patch file to work around the TypeScript#52363 issue for the mdx-mermaid package

The file, patches/mdx-mermaid+2.0.0.patch, was generated by performing the following steps:

1. Add "postinstall": "patch-package" to package.json's scripts object
2. Edit node_modules/mdx-mermaid/package.json (as documented in the patch file)
3. Run $ npx patch-package --exclude '^$' mdx-mermaid to generate the patch file

Deployment

Quick start

1. Bump version number in package.json and package-lock.json

   # Alternatively, you can specify `major` or `minor` instead of `patch`.
   npm version --git-tag-version false patch

   The version number will accessible via PACKAGE_VERSION at build time (more info)

2. (Optional) Generate and preview the production build

   npm run build
   npm run preview

   Then visit: http://localhost:4173/monocle/

3. Generate and deploy a production build

   npm run deploy

Roadmap

1. Apply syntax highlighting to the Makefile content (non-React example)
2. Allow the user to load a Makefile by entering its URL into a textbox (users can already enter it via query string)
3. Allow the user to upload a Makefile by browsing for it on their computer (users can already drag-and-drop one)
4. Allow user to choose the graph direction (TB versus LR) (users can already copy then edit the Mermaid code)
5. Allow user to choose whether to download "light" or "dark" diagram, regardless of current website theme
6. Style targets and non-targets distinctly from one another in the diagram
7. Implement a mode optimized for viewing (the diagram of) a Makefile loaded from a URL specified via query params
8. Maybe: Store current Makefile in browser storage (refreshing the page currently discards the Makefile content)
9. Maybe: Add SVG pan and zoom

FAQ

• Q: Why'd you name it "monocle?"
• A: I went with the word "monocle" because its "m", "k", and "l" sounds are in the same order as in the word "Makefile", and a monocle is a thing people use to see things in a different way.