search

dwmkerr / chatgpt-diagrams-extension

A Chrome browser extension that renders diagrams in the ChatGPT website inline.
MIT License
13 stars 3 forks source link

readme

chatgpt-diagrams

main codecov

A Chrome browser extension that renders diagrams in the ChatGPT website inline:

Demo Recording of ChatGPT Diagrams Extension

Chrome Web Store: Install ChatGPT Diagrams

Quickstart

Clone, install dependencies and build the extension:

git clone git@github.com:dwmkerr/chatgpt-diagrams-extension.git
npm install
npm run build

Open Chrome Extensions, choose 'Load Unpacked' and select the ./dist folder. Now open https://chat.openai.com/ and enter a prompt such as:

Use mermaid.js to create a sequence diagram showing how state can be persisted for a chrome extension, and how state can be passed between files.

Press the 'Show Diagram' button in the code sample to render the diagram inline:

Screenshot of the 'Show Diagram' button and the inline diagram

Developer Guide

Node Version Manager is recommended to ensure that you are using the latest long-term support version of node.

Ensure you are using Node LTS, then install dependencies:

nvm use --lts
npm install

To run in local development mode, which will automatically reload when changes are made, use:

npm start

Load the unpacked extension in your browser from the ./dist folder.

Developer Commands

The following commands can be used to help development:

Command Description
npm start Run in development mode. Updates ./dist on changes to ./src.
npm run build Build the production bundle to ./dist.
npm run tsc Run the TypeScript compiler, verifies the correctness of the TypeScript code.
-------------------------- -------------------------------------------------------------------------------
npm test Run unit tests, output coverage to ./coverage.
npm run test:watch Run unit tests, coverage only on files that test run on, watch mode.
npm run test:debug Run unit tests, with the Chrome Inspector, initially 'break', watch mode.
npm run prettier Check formatting of all files.
npm run prettier:fix Fix formatting of all files.
npm run lint Check linting of all files.
npm run lint:fix Fix linting issues in all files.
-------------------------- -------------------------------------------------------------------------------
make build Create the release package.
make test Validate the code, running tsc and unit tests.

Code Structure

The code is structured in such a way that you should be able to immediately see the key files that make up the extension.

At root level are the essential files that make up an extension, all other code is kept in the ./lib folder.

manifest.json  # the extension definition and metadata
content.ts     # the content script, runs on chatgpt browser tabs, renders the diagrams
options.html   # the UI for the options page
options.ts     # the logic for the options page
setup-jest.js  # utility to configure testing environment
lib/           # bulk of the logic for the extension

Mermaid.js Hacks and Notes

When Mermaid.js encounters an error, it attempts to render error content visually in the DOM. It is possible to provide an HTML Element that will be the container for this output. However, it does not appear to be possible to set this container to an element created with the JSDOM virtual DOM.

This means that when Mermaid.js encounters rendering errors, we copy the raw HTML of the error content it writes from the global document object, and then move it into our own container - this works both in the browser and for unit tests.

You can see this approach by searching for the text 'Hack' in the ./src/lib/chatgpt-dom.ts code. There may be a better way but this managed to solve some issues like https://github.com/dwmkerr/chatgpt-diagrams-extension/issues/20 and others, quickly and without too much complexity in the tests.

Running the Sample Pages

The following command runs a local webserver, serving the content at ./samples. This makes it easy to test locally, without internet connectivity and without having to regularly log into ChatGPT:

make serve-samples

The sample page is served at http://localhost:3000.

Manifest

Note that the version field is omitted from manifest.json. The version in the manifest file is set to the current value in the package.json file as part of the build process.

Formatting and Code Quality Rules

Prettier is used for formatting. Pre-commit hooks are used to enforce code style.

ESLint is used for code-quality checks and rules.

To understand why both are used, check "Prettier vs Linters".

Pre-Commit Hooks

Husky and lint-staged are used to run formatting and code quality checks on staged changes before they are committed.

The configuration for lint-staged is in the package.json file.

Testing

Jest is used as the testing framework. ChatGPT sample pages are loaded into the environment using js-dom and we then verify that the ChatGPT code elements are identified and processed correctly.

Check the Developer Commands section to see the various test commands that can be run. It is possible to watch tests, run tests in the debugger, and so on.

Debugging

In development mode, open source maps by navigating to the "Sources > Content Scripts > chatgpt-diagrams" folder. These are inline source maps. You can also use "Command + P" and search for a file such as content.ts.

In production mode, source maps are generated as standalone files in the ./dist folder.

Reloading the Extension

There is no 'live reload' on file changes. The fastest way to reload is to run locally with npm start. Webpack will rebuild the extension on file changes. Then just press the "Refresh" button in the chrome://extensions page and reload the site you are debugging.

Verifying Pull Requests

To verify that the code builds, the tests pass and the release package can be created run the commands below:

make build
make test
make release

These commands will be executed for pull requests.

Versioning

The version of the extension is defined in the package.json file.

Releasing in managed via Release Please in the main.yaml workflow file.

If you need to manually trigger a release, run:

git commit --allow-empty -m "chore: release 2.0.0" -m "Release-As: 2.0.0"

Releasing

When uploading a new version, follow the steps below.

Extension Screenshots

If needed, update the screenshots. Screenshots should be 1280x800 pixels, set this in the Developer Tools (which can also be used to capture the screenshot to the Downloads folder.

Currently screenshots do not include a browser frame.

Screenshots do not have the ChatGPT sidebar, avoiding distractions.

Screenshots after the first one do not have the code sample, avoiding distractions.

Open Developer Tools, use the 'device size' button to set the responsive screen size, adjust the size to 1280x800, delete the sidebar from the nodes view, press Command+Shift+P and select 'Capture Screenshot'.

Prompts for screenshots so far are:

  1. Render a flowchart showing how a browser makes a web request and a server responds. Use mermaid.js.
  2. Create a UML class diagram showing relationships for the data model for a simple food delivery database. Use mermaid.js.
  3. Create an architecture diagram that would show the key components in an instant messaging application, use mermaidjs.
  4. Create a sequence diagram showing how retry logic with retry queues is typically implemented when using Apache Kafka, use mermaidjs for the diagram

Resize screenshots with:

brew install imagemagick

new_width=1280
for input in ./docs/screenshots/*.png; do
    [[ -f "$input" ]] || continue
    output="${input/\.png/-${new_width}.png}"
    echo "Convert: ${input} -> ${output}"
    convert "${input}" -resize "${new_width}x" "${output}"
done

Useful Resources

https://joshisa.ninja/2021/10/22/browser-extension-with-rollup-omnibox-chatter.html

Task List

A quick-and-dirty list of improvements and next steps:

Version 0.2 Features

Cosmetic Improvements

Performance Improvements / Developer Experience

Options Page

Extension Popup

Other