Building a Web App Debug Tool with Lit to Standardize Issue Reporting Granularity for Everyone

I created something I personally thought would be useful to have, so I'm introducing it here.

About the library created

https://github.com/uuki/lit-issue-reporter

Its main feature is adding functionality that allows you to report GitHub Issues directly from a Web application.
When reporting, you can select the Issue Templates configured in the repository, and the assignees and labels defined in the templates are automatically set.

At the same time, it automatically appends the browsing environment to the body of the issue and allows for optional screenshot attachment^[1].

Usage

1. Install the library from npm

https://www.npmjs.com/package/lit-issue-reporter

2. Issue a PAT (Personal access token) with the necessary scopes from settings/tokens
3. Insert the following process into any JS file

if (process.env.NODE_ENV !== 'production') {
  import('lit-issue-reporter').then(({ createReporter }) => {
    createReporter({
      token: process.env.GITHUB_TOKEN,
      owner: '<GITHUB_USER_NAME>',
      repository: '<GITHUB_REPOSITORY_NAME>',
    })
  })
}

4. Place <issue-reporter></issue-reporter> at any location on the View side

After this, a toggle button for the reporting form will be displayed at the bottom left of the screen by default.
The text displayed in the form supports i18n, and most of the text, including the UI, can be replaced via options.

Why it was necessary

The reason I went to the effort of creating a feature that allows reporting from outside of GitHub was due to the following reasons in my environment:

• Not all project members (including non-engineers) are necessarily familiar with development or using GitHub.
• Information such as the browsing environment often had to be verified when issues were reported during client confirmation phases.

Regarding the first point, project management at my workplace is primarily done on GitHub, and even designers and PMs who are not familiar with the UI use Issues for communication and discussion.^[2]

In these situations, the granularity of information—such as the description of the affected area or whether a screenshot was attached—sometimes varied from person to person, including engineers.

While unique operational rules are documented, they can become a one-time cost, especially for external partners. I thought it would be better if these points could be handled by the tool itself rather than sharing instructions every time.

Regarding the second point, which partially overlaps with the previous benefit, when communicating with customers, we typically have them record information in a project management tool or spreadsheet, and then a PM or engineer re-creates the issue.

At that point, cases would occur where we had to ask additional questions about target information such as URLs and elements, or the situation and environment.

Since information such as the browser version, OS, and resolution can be retrieved automatically while browsing, I thought this approach would be a more reliable solution than the spreadsheet templates we were previously using, as it saves the customer the trouble of checking these separately.

Concept and Technology Selection

It's been about five years now, but I was inspired by a mechanism called "ZELDA_ERROR" introduced in the article "The reason why The Legend of Zelda: BotW has so few bugs", which came out around the time of CEDEC 2017.

The article explained how they improved efficiency by integrating a tool that allowed reporting by pressing a "Post" button from within the game while playing. The idea that a similar approach could be applied to the web to solve the challenges I was facing was the trigger for creating this.

Regarding the technology stack, due to the nature of its purpose, I proceeded on the premise of not depending on any specific framework or library, and chose to use Lit to create Web Components.

Ultimately, it is output as an ES Module, and it's designed to be easy to use with Vanilla JS, as well as React, Vue, Svelte, and others.

For screenshots, I adopted the native MediaStream API to ensure that there are no layout breaks or inconsistencies when capturing the image.

I'm using the GitHub API v4 to retrieve Issue Templates and repository information, which also serves as a way for me to learn GraphQL.

I haven't been able to write tests yet...

Notes on handling

As you might have noticed since authentication is handled via PAT, because I made it a requirement for this to be entirely client-side, it is necessary to embed a PAT with repo scope into the application. If this were to be extracted by a malicious actor, there is a risk that the repository could be manipulated within the scope of the access rights.

Due to these security concerns, use in a restricted environment is an absolute requirement at this point. I am planning to first use it in a limited internal environment and then consider expanding the scope of use once the authentication features are properly established.

Regarding authentication, it seems possible to narrow the scope to Issue management (without source code access) by using GitHub Apps, so I would like to look into that when I have the chance.

Conclusion

While there might be better ways for the workflow itself, I created this as a prototype because there didn't seem to be anything exactly as I imagined it.

Although it's just a quick piece of work created during my summer vacation, I would be happy if it helps in some way. Also, if anyone is interested, contributions are welcome, so thank you.

脚注

1. Since it seemed difficult to upload images directly via GitHub API v4 for security reasons, they are embedded as Data URIs. (I might not have researched this thoroughly enough).

2. This refers to specific situations within the company rather than a general public context.