ADR Manager Apps

ADR Manager Apps is the monorepo for the web-based ADR Manager and the ADR Manager VS Code extension. Both apps help teams create, edit, validate, and manage Architectural Decision Records (ADRs) written in Markdown with the MADR template.

• Web app: manage MADRs in GitHub repositories, live at https://adr.github.io/adr-manager-apps/
• VS Code extension: manage MADRs in local workspaces, on the VS Code Marketplace

The apps share a common core and tooling, and are developed, tested, versioned, and released together from one pnpm workspace.

Packages

Package	Path	Description
adr-manager	apps/adr-manager	Web app (Vue 3, Vite, TypeScript, CodeMirror 6) for managing MADRs in GitHub repositories via GitHub OAuth
adr-manager-vscode	apps/vscode-adr-manager	VS Code extension for managing MADRs in single-root, multi-root, and folder-based workspaces, with commands, context menus, snippets, and diagnostics
@adr-manager/core	packages/core	Shared MADR parser (ANTLR4), ADR domain model, and utilities used by both apps
@adr-manager/eslint-config	packages/eslint-config	Shared ESLint flat configs (base, vue, node)
@adr-manager/prettier-config	packages/prettier-config	Shared Prettier configuration
@adr-manager/tsconfig	packages/tsconfig	Shared TypeScript configs (base, vue, node, commonjs)

The two apps are the deliverables. The @adr-manager/* packages are private workspace packages and are not published anywhere.

Package-specific usage details live in the package docs:

• Web app README
• VS Code extension README and CHANGELOG

Architecture

• @adr-manager/core is consumed directly as TypeScript source (its exports point at src/index.ts), so there is no build step and no stale artifacts between the core and the apps.
• @adr-manager/eslint-config, @adr-manager/prettier-config, and @adr-manager/tsconfig centralize tooling so every package extends the same rules.
• Shared dependency versions are pinned once in the catalog: section of pnpm-workspace.yaml and referenced from packages with the catalog: protocol.
• The workspace uses pnpm's nodeLinker: hoisted (flat node_modules) because the Vue and VS Code packaging toolchains expect flat dependency resolution.

Prerequisites

• Node.js >= 22.13
• pnpm 11.5.1, pinned via the packageManager field so recent pnpm versions (or corepack enable) switch to it automatically
• Git
• Visual Studio Code when developing or testing the extension

Getting started

git clone https://github.com/adr/adr-manager-apps.git
cd adr-manager-apps
pnpm install

Installs are hardened in pnpm-workspace.yaml: newly published dependency versions are delayed for five days, and only reviewed build scripts (esbuild, cypress, core-js) are allowed to run. If pnpm reports blocked dependency build scripts, review and approve them with pnpm approve-builds.

Development

Run both apps at once (Vite dev server plus the extension watchers):

pnpm dev

Or run them individually as described below.

Web app

pnpm dev:web

The Vite dev server runs at http://localhost:8000/adr-manager-apps/ (the /adr-manager-apps/ base path matches the GitHub Pages deployment). The main manager route is http://localhost:8000/adr-manager-apps/#/manager.

The web app connects to GitHub through OAuth and stores the active authId and local ADR changes in browser local storage. You need a GitHub account with access to a repository that contains MADRs, normally under docs/adr.

VS Code extension

There are two ways to run the extension locally:

• Debug with F5: open the apps/vscode-adr-manager folder in VS Code (the Run Extension launch configuration lives in that folder) and press F5. This builds the extension and opens an Extension Development Host.
• Watch mode: run pnpm watch:ext from the workspace root. This watches the extension host bundle (esbuild), the webview bundles (Vite), and the type checker (tsc) in parallel and writes output to apps/vscode-adr-manager/dist.

In the Extension Development Host, open a folder that contains an ADR directory and run Open ADR Manager from the Command Palette. The extension defaults to docs/decisions for the ADR directory. Change it with the adrManager.adrDirectory setting or the Change ADR Directory command.

Build and package

pnpm build      # build every package
pnpm build:web  # web app only: vue-tsc type check + Vite build -> apps/adr-manager/dist
pnpm build:ext  # extension only: esbuild (host) + Vite (webviews) -> apps/vscode-adr-manager/dist

Package the extension as a VSIX file and install it into VS Code:

pnpm vsix
code --install-extension apps/vscode-adr-manager/vscode-adr-manager-<version>.vsix

Replace <version> with the version from apps/vscode-adr-manager/package.json.

Testing and code quality

Command	What it runs
pnpm test	All package test suites (Vitest)
pnpm test:web	Web app unit tests
pnpm test:ext	Extension tests (pretest typechecks, compiles, and lints first)
pnpm e2e:web	Web app end-to-end tests (Cypress)
pnpm lint	Linting (ESLint) in every package with a lint script
pnpm typecheck	Type checks in every package with a typecheck script
pnpm lint:ext	Extension linting (ESLint)
pnpm format / pnpm format:check	Prettier write / check across the whole repository

End-to-end tests

The Cypress tests run against mocked GitHub and GitLab provider APIs. They need the web app dev server running, but do not need OAuth tokens, provider credentials, or live repositories:

pnpm dev:web   # in a separate terminal
pnpm e2e:web

Releases and CI

Releases are coordinated with Changesets:

For the complete extension publishing procedure, see the VS Code Marketplace Release Guide.

1. Add a changeset alongside any change that should be released: pnpm changeset.
2. On every push to main, the Release workflow opens or updates a Version Packages (joint release) PR that applies pending changesets (version bumps and changelogs, via pnpm version-packages).
3. Merging that PR lands the bumped versions on main. Neither package is published to npm. Instead:
   • the web app deploys to GitHub Pages automatically (Web · Build & Publish pushes apps/adr-manager/dist to the gh-pages branch), and
   • a maintainer publishes the extension locally with Microsoft Entra authentication after signing in through the Azure CLI.

Workflow	Trigger	What it does
Repo · Checks	Every push, manual	Prettier check, type checks, and linting across the repo
Extension · CI	Push touching the extension or shared packages, manual	Compiles, lints, tests, and uploads a VSIX artifact
Web · Tests	Push touching the web app or shared packages, manual	Vitest unit tests and Cypress e2e tests (Chrome)
Release	Push to main	Opens/updates the Changesets "Version Packages" PR
Web · Build & Publish	Push to main touching the web app or shared packages, manual	Builds the web app and deploys it to the gh-pages branch

Repository structure

.
|-- .changeset/                  # changesets config and pending release notes
|-- .github/workflows/           # CI, release, and publish pipelines
|-- apps/
|   |-- adr-manager/             # web app (src, tests, cypress)
|   `-- vscode-adr-manager/      # VS Code extension (src, webviews in web/)
|-- packages/
|   |-- core/                    # shared MADR parser and ADR domain model
|   |-- eslint-config/           # shared ESLint flat configs
|   |-- prettier-config/         # shared Prettier config
|   `-- tsconfig/                # shared TypeScript configs
|-- .nvmrc                       # Node version used by CI (and nvm users)
|-- package.json                 # root orchestration scripts
|-- pnpm-workspace.yaml          # workspace layout, dependency catalog, install hardening
`-- README.md

Contributing

Contributions are welcome. Before opening a pull request:

1. Create an issue or comment on an existing issue when the change affects behavior or public workflows.
2. Keep changes focused and describe the user-facing effect.
3. Add or update tests when changing behavior.
4. Run the relevant checks from the workspace root.
5. Add a changeset with pnpm changeset when the change should be released.

For a full validation pass, run:

pnpm build
pnpm test
pnpm typecheck
pnpm lint
pnpm format:check

If the extension package is affected, also run pnpm vsix.

Reporting issues

Open a GitHub issue with:

• The package that is affected
• Your operating system
• Your Node.js and pnpm versions
• Steps to reproduce the issue
• Expected and actual behavior
• Screenshots or logs when they help explain the problem

Do not include private GitHub tokens, OAuth session values, or repository secrets in issues.

License

This project is licensed under the Apache License 2.0.

Acknowledgements

• The web-based ADR Manager started as an undergraduate research project at the Institute of Software Engineering of the University of Stuttgart and was submitted to the ICSE Score Contest 2021.
• The VS Code extension was created by Steven Chen as part of a Bachelor thesis at the University of Stuttgart.
• Both apps build on the MADR template from the adr organization.