IssueMint

Build GitHub Issue Forms without fighting YAML.

A free, open-source, local-first visual builder for creating, previewing, validating, and exporting GitHub Issue Forms.

Live Demo · Report an issue

中文简介：IssueMint 是一个免费、开源、本地优先的 GitHub Issue Form 可视化编辑器。它在浏览器内完成编辑、校验和导出，不上传你的表单内容。

Features

• Start from complete Bug Report, Feature Request, or Documentation Issue presets.
• Build forms visually and reorder fields with drag and drop or keyboard-friendly move buttons.
• Edit form metadata, labels, assignees, field attributes, options, and required rules.
• See a GitHub-style live preview alongside stable, parseable YAML.
• Catch missing metadata, unsafe filenames, invalid or duplicate IDs, empty options, and unknown field types before export.
• Import .yml or .yaml by file picker, drag and drop, or pasted YAML without replacing the current form when parsing fails.
• Copy or download one YAML file, or export a repository-ready ZIP with Issue Form configuration.
• Undo and redo at least 50 edits; restore the current form, language, theme, and repository settings after a refresh.
• Use the complete editor in English or Chinese, in light or dark mode, on desktop or mobile.

Privacy

IssueMint is local-first. Form content is parsed, edited, validated, and packaged entirely in your browser. The app has no backend, account system, GitHub API integration, AI service, analytics, advertising, telemetry, or network sync. It does not upload form data or execute imported code.

Your current form and preferences are saved only in your browser's localStorage so they can survive a refresh. Use Reset to remove that saved editor state. Hosting the static app still requires the browser to download IssueMint's own HTML, CSS, JavaScript, and image assets; after those assets load, editing and exporting do not require an application data service.

Supported field types

Type	Supported properties	Preview behavior
markdown	attributes.value	Safe rendered Markdown; raw HTML is not executed
input	id, label, description, placeholder, value, required	GitHub-style single-line input
textarea	id, label, description, placeholder, value, render, required	Text area or rendered code-entry surface
dropdown	id, label, description, options, multiple, required	Single- or multiple-choice selection
checkboxes	id, label, description, option labels, per-option required rules, field validation	Interactive checkbox list

The serializer emits only properties that GitHub supports for the selected field type.

Quick start

Requirements: Node.js 20 or newer and pnpm 11.

git clone https://github.com/KanadeK/issue-mint.git
cd issue-mint
pnpm install --frozen-lockfile
pnpm dev

Open the local URL printed by Vite. The first visit loads a complete Bug Report form, ready to edit.

Usage

1. Choose a preset, or keep the initial Bug Report example. If the current form has changed, IssueMint asks before replacing it.
2. Edit the file name and top-level form metadata in the properties panel.
3. Add markdown, input, textarea, dropdown, or checkboxes fields from the field library.
4. Select a field to edit it. Reorder, duplicate, collapse, or delete fields from the field card controls.
5. Review Validation. Selecting an error focuses the affected field; errors block export, while warnings remain exportable.
6. Inspect and copy the live YAML, download the current Issue Form, or export the repository ZIP.

Use Ctrl/Cmd+Z to undo. Redo with Ctrl/Cmd+Shift+Z or Ctrl/Cmd+Y. On narrow screens, switch among the Builder, Preview, and YAML tabs.

Import and export

Import

Choose or drop a .yml/.yaml file, or paste YAML into the import dialog. IssueMint first parses and validates the candidate in isolation. A failed import reports the problem and leaves the current editor state unchanged.

Import is semantic, not text-preserving: YAML comments and the original whitespace, quoting style, key order, and line wrapping are not retained. After import, IssueMint serializes a stable canonical layout. Importing an exported form again preserves its supported Issue Form meaning.

Export

• Copy YAML places the current parseable YAML on the clipboard.
• Download YAML saves the current configured filename.
• Export ZIP validates the full form and repository settings, then downloads issue-mint-template.zip.

Repository settings cover blank_issues_enabled and GitHub contact_links. The ZIP has this repository-ready layout (using bug-report.yml as an example configured filename):

.github/
└── ISSUE_TEMPLATE/
    ├── bug-report.yml
    └── config.yml

Copy the extracted .github directory into the root of a GitHub repository and commit it there.

Known limitations

• The preview is a GitHub-style live preview, not a pixel-perfect replica of GitHub. GitHub can change its production rendering independently.
• Version 0.1 edits one Issue Form at a time.
• YAML comments and original text formatting are intentionally not preserved after import.
• The Markdown preview is deliberately safe: imported raw HTML and code are not executed, so some GitHub-rendered constructs can appear differently.
• IssueMint does not read from or write to a GitHub repository and does not call the GitHub API. Repository import is a possible future, opt-in feature.
• GitHub may add Issue Form schema features before IssueMint supports them; unknown field types are rejected explicitly instead of being silently changed.

Development

The app is a static React + TypeScript + Vite project with strict type checking. Domain models, presets, YAML conversion, validation, state/history, previews, and import/export logic are kept in separate modules. There are no server-side components.

pnpm dev          # development server
pnpm build        # production build in dist/
pnpm preview      # preview the production build locally
pnpm format       # apply Prettier formatting
pnpm lint         # ESLint
pnpm typecheck    # strict TypeScript checking

The Vite build uses relative asset paths so the same dist output works at the GitHub Pages project path /issue-mint/ and in a local static preview.

Testing

pnpm test            # Vitest unit and component tests
pnpm test:coverage   # coverage report
pnpm test:e2e        # Playwright end-to-end tests
pnpm test:preview    # production dist at a Pages-style subpath
pnpm verify          # format check, lint, types, tests, then build

The test suites cover parsing and serialization of every supported field, YAML round trips and edge cases, validation, ZIP contents, persistence, history, real editor flows, downloads, mobile tabs, and unexpected network requests.

Deployment

The repository includes a deliberately manual GitHub Pages workflow. It never deploys on push.

1. In the GitHub repository settings, choose GitHub Actions as the Pages source.
2. Open Actions → Deploy GitHub Pages → Run workflow.
3. Review the github-pages environment and deployment result.

The expected project URL is https://kanadek.github.io/issue-mint/. No deployment command or workflow is triggered by the application itself.

Roadmap

• v0.2: edit multiple Issue Forms together.
• v0.3: share editor state with a compressed URL.
• v0.4: add more languages.
• v0.5: optionally import from a GitHub repository.

See ROADMAP.md for the intentionally date-free roadmap.

Publishing notes

For a public repository, set these GitHub Topics so IssueMint is discoverable:

github, issue-forms, yaml, form-builder, developer-tools, react, typescript, github-pages, open-source

Before tagging v0.1.0, run pnpm install --frozen-lockfile, pnpm verify, and pnpm test:e2e, then review CHANGELOG.md, the security policy, generated YAML, and the production preview. Publishing, pushing, creating a release, and deploying Pages remain explicit maintainer actions.

Contributing

Bug reports, feature proposals, documentation improvements, tests, translations, and focused pull requests are welcome. Read CONTRIBUTING.md and follow the Code of Conduct. Please report vulnerabilities privately as described in SECURITY.md.

License

IssueMint is available under the MIT License.