ADR Viewer

A web-based viewer for Architecture Decision Records (ADRs) with filtering and navigation capabilities.

Quick Start

npx @maddin.no/adr-viewer

This will build and serve the ADR viewer on http://localhost:4173.

Installation

Global Installation

npm install -g @maddin.no/adr-viewer
adr-viewer

Local Project Usage

npm install @maddin.no/adr-viewer
npx adr-viewer

Usage

1. Place your ADR markdown files in an adrs-example/ directory in your project root
2. Run npx @maddin.no/adr-viewer or adr-viewer if installed globally
3. Open your browser to http://localhost:4173
4. Browse and filter your ADRs using the sidebar

ADR Format

Your ADR files should follow this format:

---
title: Your ADR Title
status: Draft|Accepted|Rejected|Deprecated
date: YYYY-MM-DD
author: Author Name
tags: []
---

# KEY-ID: Your ADR Title

## Status
Draft

## Context
Describe the context and problem statement.

## Decision
Describe the decision that was made.

## Consequences

### Positive
- List positive consequences

### Negative
- List negative consequences

## Alternatives Considered
1. **Alternative 1** - Description and why rejected

## Implementation Notes
- Implementation details

Features

• 📁 Automatic ADR discovery and parsing
• 🔍 Filter by status and project keys
• 📱 Responsive design
• 🎨 Clean, modern interface
• 🚀 Fast navigation between ADRs

Development

# Clone the repository
git clone <your-repo-url>
cd adr-viewer

# Install dependencies
npm install

# Start development server
npm run dev

# Build for production
npm run build

# Preview production build
npm run preview

Publishing to NPM

To publish this package to NPM under the @maddin.no organization, you'll need to:

1. Prerequisites:

   • Have an NPM account and be a member of the maddin.no organization
   • Be logged in to NPM: npm login

2. Manual package.json updates needed: Add these fields to your package.json:

   {
     "name": "@maddin.no/adr-viewer",
     "version": "1.0.0",
     "description": "A web-based viewer for Architecture Decision Records (ADRs)",
     "bin": {
       "adr-viewer": "./bin/adr-viewer.js"
     },
     "files": [
       "dist/",
       "bin/",
       "README.md"
     ],
     "keywords": ["adr", "architecture", "decision", "records", "viewer", "documentation"],
     "author": "Your Name",
     "license": "MIT",
     "repository": {
       "type": "git",
       "url": "https://github.com/yourusername/adr-viewer.git"
     },
     "scripts": {
       "prepublishOnly": "npm run build"
     }
   }

3. Verify organization access:

   npm org ls maddin.no

4. Build the project:

   npm run build

5. Publish:

   npm publish --access public

License

MIT