svelte-tier

English · Русский

Layered file-tree composition for SvelteKit — собирайте проект из нескольких слоёв-источников в одно материализованное дерево.

svelte-tier позволяет описывать SvelteKit-проект слоями: базовый слой (брендовая основа, дизайн-система, общие маршруты), поверх него — слои-надстройки, а сверху — src/ самого проекта. Все слои сливаются в одну папку (по умолчанию .svelte-tier/src), которую и собирает SvelteKit.

Зачем это нужно

Представьте монорепу или семейство сайтов, где десятки проектов делят общую основу. Без слоёв общий код приходится копировать или прятать в библиотеку, теряя возможность переопределять отдельные маршруты и файлы.

С svelte-tier:

sveltetier-base/        ← общий слой: маршруты, lib, шаблоны
  src/...
brand-acme/             ← слой бренда: переопределяет часть базового
  src/...
my-project/             ← конечный проект
  src/...               ← перекрывает всё, что нужно именно здесь
  .svelte-tier/src/...  ← РЕЗУЛЬТАТ слияния (генерируется автоматически)

Файл с одинаковым путём в верхнем слое перекрывает файл нижнего. Проектный src/ всегда имеет наивысший приоритет.

Установка

npm install -D svelte-tier

Требования: Node >= 18, Vite 4/5/6, SvelteKit.

Быстрый старт

1. Создайте инстанс (в базовом слое)

Инстанс создаётся один раз и реэкспортируется по цепочке слоёв.

// sveltetier-base/index.js
import { createSvelteTier } from 'svelte-tier';

export const { merge, plugin, files } = createSvelteTier();

// базовый слой добавляет своё дерево
merge('./src');

2. Подключите слои

Каждый слой импортирует инстанс из слоя ниже и добавляет свой merge:

// brand-acme/index.js
import { merge } from 'sveltetier-base';

merge('./src'); // переопределит совпадающие файлы базового слоя

export * from 'sveltetier-base';

3. Подключите в проекте

// my-project/svelte.config.js
import adapter from '@sveltejs/adapter-auto';
import { files } from 'brand-acme';

export default {
  kit: {
    adapter: adapter(),
    files: files(), // ← конфигурирует пути SvelteKit на .svelte-tier/src
  },
};

// my-project/vite.config.js
import { sveltekit } from '@sveltejs/kit/vite';
import { plugin } from 'brand-acme';

export default {
  plugins: [
    plugin(),     // ← материализует дерево и следит за изменениями
    sveltekit(),
  ],
};

Готово. При dev и build дерево соберётся в .svelte-tier/src.

API

createSvelteTier()

Создаёт инстанс с общим состоянием. Возвращает { merge, plugin, files }. Вызывается один раз — обычно в самом нижнем (базовом) слое.

const { merge, plugin, files } = createSvelteTier();

merge(path, level?)

Добавляет слой в дерево. Путь резолвится относительно файла, где вызван merge.

| Аргумент | Тип | По умолчанию | Описание | |----------|-----|--------------|----------| | path | string | — | путь к папке (или файлу) слоя | | level | 'deep' \| number | 'deep' | стратегия слияния |

Стратегии:

• 'deep' — пофайловое слияние. Перекрываются только совпадающие файлы, остальное из нижних слоёв сохраняется.
• number — узлы на заданной глубине заменяются целиком. Удобно, когда слой должен полностью переопределить раздел, а не дополнять его.

merge('./src');           // глубокое слияние (по умолчанию)
merge('./src', 1);        // разделы первого уровня заменяются целиком

Пример level: 1:

нижний слой:  src/routes/blog/+page.svelte
              src/routes/blog/list.js
верхний слой: src/routes/blog/+page.svelte   (merge('./src', 1))

результат:    весь узел src/routes/blog взят из верхнего слоя,
              list.js нижнего слоя УДАЛЁН

files(overrides?)

Возвращает объект для kit.files в svelte.config.js. Единственное место, где задаётся outDir — плагин потом читает его автоматически.

| Поле | По умолчанию | Описание | |------|--------------|----------| | outDir | '.svelte-tier' | папка материализации | | routes | <outDir>/src/routes | | | lib | <outDir>/src/lib | | | params | <outDir>/src/params | | | appTemplate | <outDir>/src/app.html | | | errorTemplate | <outDir>/src/error.html | | | hooks.client | <outDir>/src/hooks.client | | | hooks.server | <outDir>/src/hooks.server | | | hooks.universal | <outDir>/src/hooks | |

files();                          // папка по умолчанию .svelte-tier
files({ outDir: '.generated' });  // своя папка
files({ routes: '.svelte-tier/src/pages' }); // переопределить отдельный путь

plugin(options?)

Vite-плагин. Материализует дерево при старте и следит за изменениями в dev.

| Опция | Тип | По умолчанию | Описание | |-------|-----|--------------|----------| | debug | boolean | false | логировать sync/prune/materialize | | cleanup | boolean | false | удалять outDir после сборки |

plugin({ debug: true });
plugin({ cleanup: true }); // не оставлять артефакты после build

outDir плагин берёт из files(). Если files() не был вызван (например, использование без SvelteKit), плагин падает на .svelte-tier и выводит предупреждение.

Как это работает

1. Каждый merge() регистрирует слой в общем состоянии инстанса.
2. files() задаёт outDir и настраивает пути SvelteKit на эту папку.
3. plugin() при старте Vite:
   • собирает дерево: слои снизу вверх, затем проектный src/ поверх;
   • материализует результат в outDir/src, копируя только изменённые файлы;
   • в dev следит за src/: правка файла — точечная синхронизация (мгновенный HMR), добавление/удаление — полная пересборка дерева + reload.
4. outDir добавляется в .gitignore автоматически.

Приоритет (от низшего к высшему):

базовый слой → слои-надстройки → проектный src/

Порядок выполнения

files() в svelte.config.js выполняется до плагина в Vite, поэтому outDir к моменту материализации уже известен. Использование плагина без SvelteKit поддерживается с фолбэком на .svelte-tier.

Лицензия

MIT © HeadMad