package.json и стек
Что такое package.json
package.json — главный манифест зависимостей Node-проекта в формате JSON. В нём записаны имя пакета, версия, npm-скрипты, списки зависимостей и требования к Node. Менеджер npm читает файл при npm install и выполняет команды из секции scripts.
Для "Вселенной IT" package.json описывает весь жизненный цикл сайта — от генерации JSON-индекса до сборки Docusaurus 3.10 на React 19. Файл лежит в корне репозитория рядом с docusaurus.config.js.
Метаданные пакета
{
"name": "it-knowledge-base",
"version": "0.0.0",
"private": true,
"engines": {
"node": ">=20.0"
}
}
| Поле | Значение | Смысл |
|---|---|---|
name | it-knowledge-base | Идентификатор пакета в workspace |
version | 0.0.0 | Версионность по SemVer — сайт не публикуется в registry |
private | true | Приватный пакет, запрет случайного npm publish |
engines.node | >=20.0 | Минимальная версия Node для CLI и ESM-скриптов |
Метаданные — "паспорт" проекта. Мета в широком смысле — любая служебная информация о данных (здесь — о самом репозитории и среде запуска).
Скрипты жизненного цикла
Секция "scripts" связывает короткие команды терминала с цепочками задач.
| Скрипт | Что делает |
|---|---|
npm start | wiki-index → search-index → redirects → docusaurus start |
npm run build | collection-titles → wiki → search → redirects → docusaurus build |
npm run serve | Локальный просмотр production-сборки |
npm run clear | Очистка кэша .docusaurus |
npm start и память
"start": "... cross-env NODE_OPTIONS=--max-old-space-size=16384 docusaurus start"
npm start — точка входа разработчика. Перед dev-сервером гоняются обязательные docs:* (wiki, поиск, редиректы). NODE_OPTIONS=--max-old-space-size=16384 поднимает лимит heap V8 до 16 ГБ — иначе webpack-граф зависимостей на ~3000 MDX-файлов может оборвать процесс.
npm run build добавляет docs:collection-titles — заголовки для подборок в продакшене.
Команды запускают через npm из терминала (PowerShell, bash). См. CLI экосистемы JavaScript.
Пайплайн контента (docs:*)
Папка scripts/ — ESM-модули .mjs на Node. Это пайплайн генерации данных перед сборкой сайта, отдельно от runtime браузера.
Запускаются автоматически
| npm script | Файл | Результат |
|---|---|---|
docs:wiki-links | build-wiki-link-index.mjs | wikiLinkIndex.json |
docs:search-index | build-doc-search-index.mjs | doc-search-index.json (поиск) |
docs:redirects | build-doc-redirects.mjs | docLegacyRedirects.json |
docs:collection-titles | generate-collection-doc-titles.mjs | collectionDocTitles.json (collection-titles) |
Скрипт поиска обходит docs/, читает frontmatter через gray-matter (транзитивная зависимость Docusaurus) и пишет JSON-индекс в static/.
Ручные и периодические
| npm script | Назначение |
|---|---|
docs:demo-registry | Реестр демо → info/demo-registry.md |
docs:collection-crosslinks | Перекрёстные ссылки в подборках |
docs:context-crosslinks | Связи контекст ↔ энциклопедия |
docs:toc | Оглавление docs/toc.md |
docs:fix-mdx-imports | Правка import после frontmatter |
docs:fix-frontmatter-blank | Пустая строка после --- |
docs:check-article-structure | Валидация структуры статей |
docs:normalize-tags | Нормализация тегов |
docs:tech-icon-paths | SVG-пути иконок из simple-icons |
Эти команды — инструменты автора контента, они не попадают в продакшен-бандл сайта.
dependencies — разбор по пакетам
Секция dependencies — пакеты, которые могут попасть в клиентский бандл или нужны runtime сборки Docusaurus.
"dependencies": {
"@docusaurus/core": "^3.10.0",
"@docusaurus/faster": "^3.10.0",
"@docusaurus/preset-classic": "^3.10.0",
"@docusaurus/theme-live-codeblock": "^3.10.0",
"@docusaurus/theme-mermaid": "^3.10.0",
"@mdx-js/react": "^3.0.0",
"clsx": "^2.0.0",
"html2canvas": "^1.4.1",
"jspdf": "^4.2.1",
"prism-react-renderer": "^2.3.0",
"qrcode": "^1.5.4",
"react": "^19.0.0",
"react-dom": "^19.0.0",
"uuid": "^11.1.1"
}
Символ ^ в версии — допуск обновлений по SemVer в пределах минорной ветки (см. npm и lock-файлы).
Ядро Docusaurus и React
| Пакет | Роль в проекте | Энциклопедия / контекст |
|---|---|---|
@docusaurus/core | CLI, dev/build сервер, плагины, роутинг | Docusaurus config |
@docusaurus/preset-classic | Пресет classic "из коробки" — docs, тема, CSS | Микрофреймворк |
@docusaurus/faster | Rspack + SWC ускорение | Webpack и Vite |
@mdx-js/react | Связка MDX → React-компоненты в статьях | Markdown |
react | Библиотека UI, Virtual DOM, компоненты | React |
react-dom | Рендер React в DOM (гидратация) | Справочник React |
Темы @docusaurus/theme-*
| Пакет | Роль |
|---|---|
@docusaurus/theme-mermaid | Диаграммы Mermaid в markdown без ручного импорта |
@docusaurus/theme-live-codeblock | Live code — исполняемые блоки в статье (используется точечно) |
Обе темы расширяют визуальный слой поверх @docusaurus/theme-classic (входит в preset).
Подсветка и утилиты
| Пакет | Роль | Где в коде |
|---|---|---|
prism-react-renderer | Рендер подсветки Prism в React | Блоки кода в статьях, связка с Infima/Prism |
clsx | Склейка условных строк для className | src/theme/, компоненты |
html2canvas | Снимок DOM в canvas (растр) | exportArticlePdf.js |
jspdf | Сборка PDF из изображений/страниц | Кнопка "Скачать PDF" в layout |
qrcode | Генерация QR-кода | Точечно в UI |
uuid | Уникальные строковые id | Внутренние виджеты |
PDF-экспорт — клиентская фича без сервера. QR-код кодирует URL или текст в матрицу для сканирования.
devDependencies
Пакеты для сборки, типов и скриптов — обычно не отдаются посетителю сайта как отдельный бандл.
"devDependencies": {
"@docusaurus/module-type-aliases": "^3.10.0",
"@docusaurus/plugin-client-redirects": "^3.10.0",
"@docusaurus/types": "^3.10.0",
"@types/node": "^25.3.5",
"@types/react": "^19.2.14",
"@types/react-dom": "^19.2.3",
"cross-env": "^10.1.0",
"simple-icons": "^14.15.0",
"typescript": "^5.9.3"
}
| Пакет | Роль |
|---|---|
@docusaurus/plugin-client-redirects | Плагин редиректов (подключается в config) |
@docusaurus/module-type-aliases | Типы путей @theme/*, @site/* |
@docusaurus/types | Типы конфига и API Docusaurus |
@types/node | Типы Node API для TS |
@types/react, @types/react-dom | Типы React для проверки типов |
typescript | Компилятор / language service TS |
cross-env | Единый синтаксис env-переменных в Windows и Unix |
simple-icons | Исходные бренд-SVG для docs:tech-icon-paths |
browserslist
"browserslist": {
"production": [">0.5%", "not dead", "not op_mini all"],
"development": ["last 3 chrome version", "last 3 firefox version", "last 5 safari version"]
}
Список целевых браузеров для Babel/PostCSS. Таргетирование влияет на полифиллы и минификацию CSS.
Стек в одном абзаце
Статический сайт на Docusaurus 3 (React 19, MDX 3, Webpack или Rspack), кастомная тема через swizzle, remark-плагины на этапе компиляции markdown, клиентский поиск по JSON-индексу, внешние iframe для кода и интерактива. TypeScript — в theme и utils; контент — YAML frontmatter и Node ESM в scripts/.
Добавление зависимости
- UI-библиотека в статьях увеличивает бандл; тяжёлое лучше на play.spirzen.ru.
- Dev-only пакеты — в
devDependencies, если нет импорта изsrc/. - После обновления Docusaurus — проверить
future.v4и major-версию в changelog. npm run clear && npm run buildпосле смены major.
Установка — npm install <пакет> (npm).
Глоссарий
package.json
См. Что такое package.json. Стандартный манифест npm-проекта в JSON.
Пакет
Единица распространения в npm — модуль с package.json, версией и зависимостями. it-knowledge-base — один приватный пакет.
Жизненный цикл
Этапы от npm install → разработка (start) → сборка (build) → деплой. Скрипты в manifest описывают переходы.
npm
Node Package Manager — установка зависимостей, запуск скриптов. Практический разбор.
Зависимости
Внешние библиотеки, без которых проект не собирается или не работает. В manifest — dependencies и devDependencies.
PDF
Portable Document Format. В проекте — экспорт статьи через html2canvas + jspdf.
QR-код
Двумерный штрихкод; библиотека qrcode генерирует изображение из строки.
Генерация данных
Скрипты docs:* создают JSON/правки в docs/ перед Docusaurus.
Сборка
Преобразование исходников в артефакты (build/). npm run build — production сборка.
Зависимость
Один пакет, требуемый другим. Прямая — в package.json; транзитивная — зависимость зависимости.
Метаданные
Данные о данных — name, version, engines в manifest; в статьях — frontmatter.
Мета и метаинформация
Мета — префикс "над" (метаданные, метаязык). Здесь — служебные поля описания проекта и статей.
Приватные пакеты
"private": true — запрет публикации в npm registry.
Node
Среда выполнения JavaScript вне браузера. Node.js, требование >=20.
npm registry
Публичный каталог пакетов npmjs.com. Проект туда не публикуется.
ESM и ESM-скрипты
ECMAScript Modules — import/export. Файлы scripts/*.mjs и современный toolchain Docusaurus. См. модули в JS.
scripts/
Папка Node-скриптов генерации контента и обслуживания репозитория.
npm start
Команда npm start → подготовка индексов → docusaurus start (dev-сервер).
Скрипт
Команда в "scripts" manifest или файл .mjs/.js в scripts/.
Команды и терминал
Интерфейс оболочки (PowerShell, bash) для npm run …. Справочник CLI.
Локальный просмотр
npm run serve — отдача папки build/ после production-сборки на localhost.
Поиск
docs:search-index → static/doc-search-index.json для DocSearch (Ctrl+K).
collection-titles
docs:collection-titles → collectionDocTitles.json — заголовки статей в подборках.
Кэш и его очистка
Docusaurus кэширует инкрементальную сборку в .docusaurus/. npm run clear сбрасывает кэш при странных ошибках.
heap и куча
Область памяти V8 для объектов. --max-old-space-size=16384 — лимит 16 ГБ для большого графа зависимостей.
MDX
Markdown + JSX — статьи с import React-компонентов. Расширение .mdx в docs/.
MD и отличие от MDX
MD (.md) — чистый Markdown. MDX добавляет JSX и импорт компонентов. Оба поддерживает Docusaurus.
Webpack
Сборщик JS/CSS/assets. См. экосистему JS.
Граф зависимостей
Дерево импортов модулей, которое webpack обходит при сборке. Тысячи MDX раздувают граф.
Контент
Текстовые материалы в docs/ — статьи, подборки, разделы.
Пайплайн
Цепочка шагов — docs:wiki-links → … → docusaurus build.
build
npm run build — production-команда Docusaurus; синоним сборки в контексте npm.
Перекрёстная ссылка
Ссылка между статьями/разделами; скрипты docs:*-crosslinks обогащают related и wiki.
Реестр демо
docs:demo-registry — каталог интерактива в info/demo-registry.md.
frontmatter
YAML-блок --- в начале статьи (title, description, tags).
Нормализация
Приведение к единому виду — docs:normalize-tags, единый формат тегов.
SVG
Векторная графика; docs:tech-icon-paths вытаскивает path из simple-icons.
Путь
Строка маршрута файла (docs/encyclopedia/...) или SVG path в иконке.
icon (иконка)
Глиф технологии на карточках и hero; данные в techIconRegistry.js / techIconPaths.js.
Продакшен
Боевая среда spirzen.ru после деплоя build/. См. DevOps.
Бандл
Итоговый JS/CSS-файл(ы) для браузера. dependencies влияют на размер бандла.
Ядро
@docusaurus/core + preset + React — минимальный каркас без утилит PDF/QR.
CLI
Command Line Interface — docusaurus, npm в терминале.
Плагин
Расширение Docusaurus (редиректы, mermaid). Часть пакетов @docusaurus/plugin-*.
Роутинг
Сопоставление URL ↔ страница; ядро Docusaurus строит маршруты из docs/ и src/pages/.
Коробка
Готовый набор "из коробки" — preset-classic с docs и темой без ручной сборки плагинов.
SWC
Speedy Web Compiler — быстрая транспиляция TS/JS; используется с @docusaurus/faster.
UI
User Interface — всё, что видит пользователь; React + CSS.
Диаграмма
Mermaid-схемы в markdown через @docusaurus/theme-mermaid. Основы диаграмм.
Live code
Исполняемый блок кода в статье — @docusaurus/theme-live-codeblock.
Синтаксис
Грамматика языка в code fence; подсвечивается Prism.
Infima
CSS-фреймворк темы Docusaurus (--ifm-*).
Prism
Движок подсветки кода; связка с prism-react-renderer.
Рендер
Отрисовка React-дерева в DOM (react-dom).
CSS
Каскадные стили; глобально в src/css/, локально — CSS modules.
CSS-классы
Имена классов в разметке; clsx собирает условные комбинации.
cross-env
Пакет для NODE_OPTIONS=... одинаково на Windows и Linux/macOS.
types
Пакеты @types/* — описания типов для JS-библиотек в TypeScript.
TypeScript
Язык с типами; экосистема TS.
Проверка типов
Анализ TS без emit (tsc --noEmit, IDE) — ловит ошибки до runtime. См. TypeScript.
Тип данных
Категория значений (число, строка, boolean, объект). В TS — аннотации и inference. Типы в вычислительных системах, типизация в TS.
gray-matter
Парсер YAML frontmatter в markdown; используется в build-doc-search-index.mjs (транзитивно через Docusaurus).
Транзит и транзитивность
Транзитивная зависимость — пакет A → B → C; gray-matter может не быть в корневом manifest, но установлен в node_modules.
browserslist
Конфиг целевых браузеров для Babel/PostCSS.
Таргет и таргетирование
Выбор целевых сред (браузеры, ES-версия) при транспиляции.
Минификация
Сжатие JS/CSS (удаление пробелов, короткие имена) в production сборке.
Полифилл
Подстановка API для старых браузеров; выбор через browserslist.
Babel/PostCSS
Babel — транспиляция JS; PostCSS — обработка CSS (autoprefixer и др.).
Статический сайт
HTML/JS/CSS генерируются при build, сервер отдаёт файлы. См. Архитектура.
Кастомность
Отличия от шаблона — swizzle, src/, remark, DocSearch.
swizzle
Копирование компонентов темы в src/theme/ для правок.
remark-плагины
Обработчики markdown на этапе компиляции (wikiLink, lazyMdxDemoImports).
Компиляция markdown
Преобразование .md/.mdx в JS-модули и HTML при start/build.
JSON-индекс
Файл JSON с записями для поиска или wiki (doc-search-index.json).
YAML
Формат конфигурации и frontmatter; отступы важны.
UI-библиотека
Готовый набор React-компонентов (Material, Chakra…). Каждая тянет бандл — в энциклопедии используются точечно.
Версионность
Схема версий пакета (SemVer major.minor.patch). ^3.10.0 допускает 3.10.x и 3.11.0, но не 4.0.0.
major-версия
Первая цифра SemVer — возможны breaking changes (Docusaurus 3 → 4).
Импорт
Подключение модуля — import (ESM) или require (CJS).
React и react-dom
См. таблицу ядра выше; react-dom монтирует дерево в страницу.
clsx, html2canvas, jspdf, qrcode, uuid
Мелкие библиотеки для CSS-классов, PDF, QR, id — см. разбор dependencies.
Связь с другими главами
- Архитектура — сервисы, бандл, продакшен.
- docusaurus.config.js — как пакеты подключаются в config.
- Данные и скрипты — детали
docs:*. - TypeScript —
tsconfigи проверка типов.