Я опублікувала пакет NPM!!! Опублікував Mermaid Enhancements як npm Package
Введение
Мій хлопець з інтернету нарешті зміг занурити свої пальці в світ пакетів npm Сирена.js досить незрозуміло і досить дивно, що я можу насправді доставити щось корисние ! Отож насолоджуйтесь
Після того, як я збудував деякі дійсно корисні покращення для Сирена .js діаграми ( інтерактивний пан МSK2 зйомок \ , світловий коробка на повному екрані | , | виведення до PNG |/ | SVG | МSK6 | і автоматичний перемикання тем ♫ ), | Я вирішив, що настав час їх упаковувати правильно та поділитися ними з громадою ♪ . | Цей пост показує, як Я створив @mostlylucid/mermaid-enhancements як виробництво- готовий npm пакетM SK1
NOTA: Я досі працюю над релізомM SK1 Тримайте на пульті ( мій перший пакет npm, так що це трохи забирає часу )
Чому пакет це?
Я вже деякий час користуюсь цими покращеннями на своєму блогі. МСК1 і вони стають невід 'ємними для роботи з складними діаграмами Сирени. МSK3
- Interactive Pan & Zoom - Рухати великими діаграмами плавно
- Світлоbox на повному екрані - Охоплююче відчуття перегляду
- Export to PNG/SVG - Wysoka МSK1Для загрузки діаграми
- Автоматичне перемикач тем - Безшовне світлоM SK1 підтримка в темному режимі
- Відповідальний дизайн - працює на мобільному та робочому столі
Оскільки я копіював один і той самий код між проектами,, було зрозуміло створити правильний пакет npm, який міг використовувати будь-хто
Структура проекту
Я створив професійну структуру пакетів з підтримкою TypeScript:
mostlylucid-mermaid/
├── src/
│ ├── index.ts # Main entry point
│ ├── enhancements.ts # Pan/zoom/export functionality
│ ├── theme-switcher.ts # Theme switching logic
│ ├── types.ts # TypeScript type definitions
│ └── styles.css # Complete styling
├── examples/
│ └── demo.html # Full-featured demo
├── dist/ # Built output (generated)
├── package.json
├── tsconfig.json
├── README.md
├── QUICKSTART.md
├── PUBLISHING.md
└── LICENSE
Пакет використовує TypeScript для безпеки шрифтів і кращого досвіду програмування,, але компілює до JavaScript для максимальної здатностіM SK1
Архітектура
Ось як складові з 'єднуються.
Це те, що виглядає як МСК0 .
Отже, ви бачите, що ' досить компактний і має деякі корисні функції, окрім просто статичних діаграм. МSK1 Мене завжди дратувало, наскільки MASSIVE вони були на сторінці, тому це здавалося розумним підходом до зниження розміру, водночас зберігаючи корисність.
graph TD
A[User Initializes] --> B[init Function]
B --> C[initMermaid]
B --> D[enhanceMermaidDiagrams]
C --> E[Theme Detection]
C --> F[Event Listeners]
C --> G[Mermaid Rendering]
E --> E1[Global State]
E --> E2[LocalStorage]
E --> E3[DOM Class]
E --> E4[OS Preference]
F --> F1[Custom Events]
F --> F2[Media Query]
G --> H[Apply Enhancements]
D --> H
H --> I[Wrap Diagrams]
H --> J[Init Pan/Zoom]
H --> K[Add Controls]
I --> L[Interactive Diagram]
J --> L
K --> L
L --> M[User Interactions]
M --> M1[Zoom In/Out]
M --> M2[Pan]
M --> M3[Fullscreen]
M --> M4[Export PNG/SVG]
style A stroke:#059669,stroke-width:3px,color:#10b981
style L stroke:#2563eb,stroke-width:3px,color:#3b82f6
style M stroke:#7c3aed,stroke-width:3px,color:#8b5cf6
Головне вdrożenie
Визначення типу
Перше, Я визначив цілковиті типи TypScriptM SK1
// src/types.ts
export interface PanZoomInstance {
zoom(scale: number): void;
zoomIn(): void;
zoomOut(): void;
reset(): void;
fit(): void;
center(): void;
resize(): void;
destroy(): void;
isPanEnabled(): boolean;
enablePan(enabled: boolean): void;
}
export type ExportFormat = 'png' | 'svg';
export type Theme = 'dark' | 'default';
export type ControlAction = 'fullscreen' | 'zoomIn' | 'zoomOut' |
'reset' | 'pan' | 'exportPng' | 'exportSvg';
export interface EnhancementConfig {
icons?: IconConfig;
controls?: {
fullscreen?: boolean;
zoom?: boolean;
pan?: boolean;
export?: boolean;
};
}
Головний пункт входу
Головний вхідний пункт мертво простий:
// src/index.ts
export {
enhanceMermaidDiagrams,
cleanupMermaidEnhancements
} from './enhancements.js';
export {
initMermaid
} from './theme-switcher.js';
export async function init() {
await initMermaid();
}
export default {
init,
initMermaid,
enhanceMermaidDiagrams,
};
Implementation Pan/Zoom
Логіка покращення обгортає кожну діаграму контролями і запускає svg-panM SK1zoom:
// src/enhancements.ts
import svgPanZoom from 'svg-pan-zoom';
import { toPng, toSvg } from 'html-to-image';
const panZoomInstances = new Map();
function initPanZoom(svgElement: SVGElement, diagramId: string) {
// Clean up existing instance if present
if (panZoomInstances.has(diagramId)) {
try {
panZoomInstances.get(diagramId).destroy();
} catch (e) {
console.warn('Failed to destroy existing pan-zoom instance:', e);
}
panZoomInstances.delete(diagramId);
}
try {
const panZoomInstance = svgPanZoom(svgElement, {
zoomEnabled: true,
controlIconsEnabled: false,
fit: true,
center: true,
minZoom: 0.1,
maxZoom: 10,
zoomScaleSensitivity: 0.3,
dblClickZoomEnabled: true,
mouseWheelZoomEnabled: true,
preventMouseEventsDefault: true,
contain: false
});
panZoomInstances.set(diagramId, panZoomInstance);
return panZoomInstance;
} catch (error) {
console.error('Failed to initialize pan-zoom:', error);
return null;
}
}
Кнопка управління створюється динамічно:
function createControlButtons(container: HTMLElement, diagramId: string) {
if (container.querySelector('.mermaid-controls')) {
return;
}
const controlsDiv = document.createElement('div');
controlsDiv.className = 'mermaid-controls';
const buttons = [
{ icon: 'bx-fullscreen', title: 'Fullscreen', action: 'fullscreen' },
{ icon: 'bx-zoom-in', title: 'Zoom In', action: 'zoomIn' },
{ icon: 'bx-zoom-out', title: 'Zoom Out', action: 'zoomOut' },
{ icon: 'bx-reset', title: 'Reset View', action: 'reset' },
{ icon: 'bx-move', title: 'Pan', action: 'pan' },
{ icon: 'bx-image', title: 'Export as PNG', action: 'exportPng' },
{ icon: 'bx-code-alt', title: 'Export as SVG', action: 'exportSvg' }
];
buttons.forEach(btn => {
const button = document.createElement('button');
button.className = `mermaid-control-btn bx ${btn.icon}`;
button.setAttribute('title', btn.title);
button.setAttribute('aria-label', btn.title);
button.setAttribute('data-action', btn.action);
button.setAttribute('data-diagram-id', diagramId);
controlsDiv.appendChild(button);
});
container.appendChild(controlsDiv);
}
Виведення функцій
Введення экспорту клонує SVG, зберігає viewBox, і використовує html -toMSC3imageM SK4
async function exportDiagram(
container: HTMLElement,
format: ExportFormat,
diagramId: string
) {
try {
const svgElement = container.querySelector('svg');
if (!svgElement) {
console.warn('No diagram found to export');
return;
}
// Clone to avoid modifying the original
const clonedSvg = svgElement.cloneNode(true) as SVGElement;
// Get or calculate viewBox
let viewBox = clonedSvg.getAttribute('viewBox');
if (!viewBox) {
const bbox = svgElement.getBBox();
viewBox = `${bbox.x} ${bbox.y} ${bbox.width} ${bbox.height}`;
clonedSvg.setAttribute('viewBox', viewBox);
}
// Set explicit dimensions for proper export
const [, , vbWidth, vbHeight] = viewBox.split(' ').map(Number);
clonedSvg.setAttribute('width', vbWidth.toString());
clonedSvg.setAttribute('height', vbHeight.toString());
// Remove pan-zoom transforms
clonedSvg.removeAttribute('style');
clonedSvg.style.backgroundColor = 'transparent';
clonedSvg.style.maxWidth = 'none';
// Create temporary container
const tempDiv = document.createElement('div');
tempDiv.style.position = 'absolute';
tempDiv.style.left = '-9999px';
tempDiv.appendChild(clonedSvg);
document.body.appendChild(tempDiv);
const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
const filename = `mermaid-diagram-${timestamp}`;
if (format === 'png') {
const dataUrl = await toPng(clonedSvg, {
backgroundColor: 'white',
pixelRatio: 2 // Higher quality
});
downloadFile(dataUrl, `${filename}.png`);
} else {
const dataUrl = await toSvg(clonedSvg, {
backgroundColor: 'transparent'
});
downloadFile(dataUrl, `${filename}.svg`);
}
document.body.removeChild(tempDiv);
console.log(`Diagram exported as ${format.toUpperCase()}`);
} catch (error) {
console.error('Failed to export diagram:', error);
}
}
Перемикання тем
Перемикач тем керує багатьма методами виявлення:
// src/theme-switcher.ts
export async function initMermaid() {
// Normalize code fences
normalizeMermaidCodeFences();
const mermaidElements = document.querySelectorAll(elementSelector);
if (mermaidElements.length === 0) return;
await saveOriginalData();
// Set up theme change handlers
const handleDarkThemeSet = async () => {
await resetProcessed();
await loadMermaid('dark');
};
const handleLightThemeSet = async () => {
await resetProcessed();
await loadMermaid('default');
};
// Listen for custom theme events
document.body.addEventListener('dark-theme-set', handleDarkThemeSet);
document.body.addEventListener('light-theme-set', handleLightThemeSet);
// OS theme change listener
if (typeof window.matchMedia === 'function') {
const mediaQuery = window.matchMedia('(prefers-color-scheme: dark)');
mediaQuery.addEventListener('change', async (e) => {
await resetProcessed();
await loadMermaid(e.matches ? 'dark' : 'default');
});
}
// Detect current theme with fallbacks
let isDarkMode = false;
if (typeof window.__themeState !== 'undefined') {
isDarkMode = window.__themeState === 'dark';
} else if (localStorage.theme) {
isDarkMode = localStorage.theme === 'dark';
} else if (document.documentElement.classList.contains('dark')) {
isDarkMode = true;
} else if (window.matchMedia?.('(prefers-color-scheme: dark)').matches) {
isDarkMode = true;
}
await loadMermaid(isDarkMode ? 'dark' : 'default');
}
Налагодження пакетів
пакет.json
Пакет.json визначає багато входних точок для різних випадків використанняM SK1
{
"name": "@mostlylucid/mermaid-enhancements",
"version": "1.0.0",
"description": "Enhance Mermaid.js diagrams with interactive pan/zoom, fullscreen lightbox, export to PNG/SVG, and automatic theme switching",
"main": "dist/index.js",
"module": "src/index.ts",
"types": "src/types.ts",
"exports": {
".": {
"types": "./src/types.ts",
"import": "./src/index.ts",
"require": "./dist/index.js"
},
"./min": {
"types": "./dist/index.d.ts",
"import": "./dist/index.min.js",
"require": "./dist/index.min.js"
},
"./styles.css": "./src/styles.css"
},
"unpkg": "dist/index.min.js",
"jsdelivr": "dist/index.min.js",
"scripts": {
"build": "tsc",
"minify": "node scripts/minify.js",
"build:all": "npm run build && npm run minify",
"prepublishOnly": "npm run build:all",
"dev": "cd examples && npx http-server -p 3000 -o"
},
"peerDependencies": {
"mermaid": "^10.0.0 || ^11.0.0"
},
"dependencies": {
"html-to-image": "^1.11.11",
"svg-pan-zoom": "^3.6.1"
}
}
Konfiguracja TypScript
{
"compilerOptions": {
"target": "ES2020",
"module": "ESNext",
"lib": ["ES2020", "DOM", "DOM.Iterable"],
"declaration": true,
"declarationMap": true,
"sourceMap": true,
"outDir": "./dist",
"rootDir": "./src",
"strict": true,
"esModuleInterop": true,
"skipLibCheck": true,
"moduleResolution": "node"
},
"include": ["src/**/*"],
"exclude": ["node_modules", "dist", "examples"]
}
Ось приклади використання
Початкове використання
Найпростіший спосіб використання пакету:
import mermaid from 'mermaid';
import { init } from '@mostlylucid/mermaid-enhancements';
import '@mostlylucid/mermaid-enhancements/styles.css';
await init();
З переключенням тематики
Для місць з світлом/темний режимM SK1
import { init } from '@mostlylucid/mermaid-enhancements';
// Initialize
await init();
// When theme changes
function toggleTheme() {
const isDark = document.body.classList.toggle('dark');
document.documentElement.classList.toggle('dark', isDark);
// Notify the enhancements
const event = new Event(isDark ? 'dark-theme-set' : 'light-theme-set');
document.body.dispatchEvent(event);
}
Реакційна інтеграція
import { useEffect } from 'react';
import { init, cleanupMermaidEnhancements } from '@mostlylucid/mermaid-enhancements';
import '@mostlylucid/mermaid-enhancements/styles.css';
function MermaidDiagram({ chart }: { chart: string }) {
useEffect(() => {
init();
return () => cleanupMermaidEnhancements();
}, [chart]);
return (
<div className="mermaid">
{chart}
</div>
);
}
Інтеграція Vue
<template>
<div class="mermaid">{{ chart }}</div>
</template>
<script setup>
import { onMounted, onUnmounted } from 'vue';
import { init, cleanupMermaidEnhancements } from '@mostlylucid/mermaid-enhancements';
import '@mostlylucid/mermaid-enhancements/styles.css';
const props = defineProps(['chart']);
onMounted(async () => {
await init();
});
onUnmounted(() => {
cleanupMermaidEnhancements();
});
</script>
Страница з демонстрацією
Я створив цілковиту демонстраційну сторінку, яка показує всі характеристики:
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Mermaid Enhancements Demo</title>
<!-- Boxicons for control button icons -->
<link href="https://unpkg.com/[email protected]/css/boxicons.min.css" rel="stylesheet">
<!-- Mermaid Enhancements CSS -->
<link rel="stylesheet" href="../src/styles.css">
</head>
<body>
<!-- Your diagrams -->
<div class="mermaid">
graph TD
A[Start] --> B{Is it working?}
B -->|Yes| C[Great!]
B -->|No| D[Check setup]
C --> E[Zoom & Pan]
D --> F[Read docs]
E --> G[Export to PNG/SVG]
</div>
<!-- Load Mermaid -->
<script type="module">
import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs';
window.mermaid = mermaid;
</script>
<!-- Initialize enhancements -->
<script type="module">
import { init } from '../dist/index.js';
await init();
</script>
</body>
</html>
Процес видавництва
Ось' робочий процес видавництва :
sequenceDiagram
participant Dev as Developer
participant Git as Git Repo
participant NPM as npm Registry
participant CDN as unpkg/jsdelivr
participant User as End User
Dev->>Dev: Write code
Dev->>Dev: npm run build:all
Dev->>Dev: Test locally
Dev->>Git: git commit & push
Dev->>Git: Create version tag
Dev->>NPM: npm login
Dev->>NPM: npm publish --access public
NPM-->>CDN: Sync package
User->>NPM: npm install
User->>CDN: Import from CDN
NPM-->>User: Deliver package
CDN-->>User: Serve files
Шаг
- Збудувати пакет:
npm run build:all # Compiles TypeScript and minifies
- Випробувати локально:
npm run dev # Opens demo at localhost:3000
- Версия bump:
npm version patch # or minor, or major
- Публикація:
npm login
npm publish --access public
Пакет доступний зараз через:
- npm:
npm install @mostlylucid/mermaid-enhancements - unpkg CDN:
https://unpkg.com/@mostlylucid/mermaid-enhancements - jsdelivr CDN:
https://cdn.jsdelivr.net/npm/@mostlylucid/mermaid-enhancements
Стратегія видобутку
Я додав скрипт мінізації, щоб зменшити розмір пакету:
// scripts/minify.js
const { minify } = require('terser');
const fs = require('fs');
const path = require('path');
async function minifyFile(inputPath, outputPath) {
const code = fs.readFileSync(inputPath, 'utf8');
const result = await minify(code, {
compress: {
dead_code: true,
drop_console: false,
drop_debugger: true,
keep_classnames: true,
keep_fnames: true,
},
mangle: {
keep_classnames: true,
keep_fnames: true,
},
format: {
comments: false,
},
});
fs.writeFileSync(outputPath, result.code);
const originalSize = fs.statSync(inputPath).size;
const minifiedSize = fs.statSync(outputPath).size;
const reduction = ((1 - minifiedSize / originalSize) * 100).toFixed(1);
console.log(`✓ ${path.basename(outputPath)}: ${originalSize} → ${minifiedSize} bytes (${reduction}% smaller)`);
}
// Minify main bundle
minifyFile(
path.join(__dirname, '../dist/index.js'),
path.join(__dirname, '../dist/index.min.js')
);
Результати:
- Regular: M SK1 KB
- Миніфіковане МСК0 МSK1 КБ (58.3% скорочення!)
Документація
Я створив цілковиту документацію:
- README.md - повна API-референція , приклади МSK2 розв 'язання проблем
- QUICKSTART.md МSK0 5-помічник для початку
- Публикація.md - npm - інструкції для публікації
- Зміна - Історія версії
У стилі
CSS повністю реагує і підтримує темний режим:
/* Diagram wrapper */
.mermaid-wrapper {
position: relative;
border-radius: 0.5rem;
overflow: hidden;
width: 100%;
margin: 1rem 0;
}
/* Control buttons */
.mermaid-controls {
position: absolute;
top: 0.5rem;
right: 0.5rem;
display: flex;
gap: 0.25rem;
z-index: 10;
background: rgba(255, 255, 255, 0.9);
border-radius: 0.5rem;
padding: 0.25rem;
box-shadow: 0 2px 8px rgba(0, 0, 0, 0.1);
}
.dark .mermaid-controls {
background: rgba(31, 41, 55, 0.95);
box-shadow: 0 2px 8px rgba(0, 0, 0, 0.3);
}
/* Individual buttons */
.mermaid-control-btn {
padding: 0.5rem;
border-radius: 0.25rem;
cursor: pointer;
transition: all 0.2s;
background: transparent;
border: none;
color: #4b5563;
font-size: 1.25rem;
}
.mermaid-control-btn:hover {
background: rgba(37, 99, 235, 0.1);
color: #2563eb;
transform: scale(1.1);
}
Уроки, отримані
1. Це вартий шрифта
Навіть для невеликої бібліотеки, TypeScript отримав декілька помилок під час розробки і надає чудову підтримку IDE для користувачів.
2. Множество входних точок важливо
Підтримуючи обидві import і require, плюс доступ до мініатюрної версії , робить пакет більш різноманітним
"exports": {
".": {
"types": "./src/types.ts",
"import": "./src/index.ts",
"require": "./dist/index.js"
},
"./min": {
"import": "./dist/index.min.js"
}
}
3. Демо дуже важливо
Ця демо-сторінка допоміг мені виявити баги і служить живим документом.
4. Чиszczenie важливо
Забезпечувати функцію очистки для управління пам 'яттю
export function cleanupMermaidEnhancements() {
panZoomInstances.forEach((instance, id) => {
try {
instance.destroy();
} catch (e) {
console.warn(`Failed to destroy pan-zoom instance ${id}:`, e);
}
});
panZoomInstances.clear();
}
5. Розпізнавання тематики потребує зворотнього зв 'язку
Різні сайти обробляють тему по-різному.
- Глобальний стан (
window.__themeState) - Lokalна вага (
localStorage.theme) - Клас DOM (
document.documentElement.classList) - preferensії ОС (
prefers-color-scheme)
Рівень ефективності
Пакет оптимізований для ефективності
- Відповідання про події - Одноразовий слухач подій для всіх кнопок управління
- Зачаток ліни - PanM SK1zoom інisiaлізується тільки тоді, коли необхідно
- Виczyszczenie instancji - Правильне управління пам 'яттю
- Найменші рендери - Diagrams only re-render on theme change
- Efektивні операції DOM - Використовується
requestAnimationFrameдля гладких анімації
Obsługа браузерів
Випробовували і працювали над:
- Chrome/Edge M SK1latest)
- Firefox (latest)
- Safari (старшийM SK1
- Мобільні браузери (iOS SafariM SK1 Chrome Mobile)
Дальне покращення
Ідеї для майбутніх версій:
- Конфигуровані значки кнопок управління (вsparcie для шрифта AwesomeM SK2 Іконки матеріалів)
- Короткі клавіатура (e.gM SK3 CtrlMSC4Plus для збільшення
- Рухливі рухи на мобільному телефоні
- Кнопка копії вихідного коду діаграми
- Funkція Share diagram URL
- Аннотації діаграми
- Множество форматів eksportу
Завершення
Упаковка покращень Сирена як модуль npm була чудовим досвідом для навчання. Пакет вже є
- Тип-безпечний з TypeScript
- Добре-документоване
- Легко використовувати
- Produkція- готова
- Cadre-agnostic
- В pełni перевірено
Якщо ви' використовуєте Mermaid(Mermaid) в проектах, то спробуйте це зробити. МSK3 інтерактивна панель(Pan) МSK4Zoom і экспорт роблять роботу з складними діаграмами набагато кращою
Ресурс
- Репозиторія GitHub: більшістьlucidweb/mostlylucid-mermaid
- Пакет npm: @влучнішийM SK1морська матка-усилення ( скоро прийдеM SK1
- Демо: Жива демонстрація ( скоро прийдеM SK1