mirror of
https://github.com/gromlab-ru/svg-sprites.git
synced 2026-07-22 04:40:17 +03:00
feat: добавить поддержку 20 framework exact modes
Добавлены exact modes: - vue@vite и vue@webpack - nuxt@vite и nuxt@webpack - svelte@vite, svelte@webpack и sveltekit@vite - angular@application и angular@webpack - astro@vite - solid@vite, solid@webpack и solid-start@vite - preact@vite и preact@webpack - qwik@vite - lit@vite и lit@webpack - alpine@vite и alpine@webpack Для каждого mode реализованы изолированный adapter, нативный framework-компонент, declarations, manifest, CSS и внешний asset URL. Добавлены production integration-стенды с генерацией, typecheck, сборкой и Playwright-проверкой рендера спрайта и Viewer. Обновлены Viewer, RU/EN-гайды, README, technical reference и AI skills. Итоговая матрица включает 29 exact modes. Проверки: - 48 unit-тестов - 29 integration E2E-тестов
This commit is contained in:
@@ -48,7 +48,7 @@ const russianDocumentation = [
|
||||
export default [
|
||||
{
|
||||
name: 'svg-sprites',
|
||||
description: 'Use only when configuring, generating, or troubleshooting @gromlab/svg-sprites. Triggers: @gromlab/svg-sprites, svg-sprite.config.json, svg-sprite.config.ts, defineSpriteConfig, generateSprite, standalone, standalone@vite, standalone@webpack, react@vite, react@webpack, next@app, next@pages, SpriteConfig.input, --input, SpriteViewer, or --icon-color-N. Do NOT use for custom SVG sprites, favicons, raster images, icon fonts, choosing an icon set, or inline SVG without this package.',
|
||||
description: 'Use only when configuring, generating, or troubleshooting @gromlab/svg-sprites. Triggers: @gromlab/svg-sprites, svg-sprite.config.json, defineSpriteConfig, generateSprite, exact modes for standalone, React, Next.js, Vue, Nuxt, Svelte, Angular, Astro, Solid, Preact, Qwik, Lit, or Alpine.js, SpriteConfig.input, --input, SpriteViewer, or --icon-color-N. Do NOT use for custom SVG sprites, favicons, raster images, icon fonts, choosing an icon set, or inline SVG without this package.',
|
||||
output: '../artifacts/svg-sprites',
|
||||
maxSkillBytes: 48_000,
|
||||
documents: documents('en'),
|
||||
@@ -56,7 +56,7 @@ export default [
|
||||
},
|
||||
{
|
||||
name: 'svg-sprites-ru',
|
||||
description: 'Используй только при настройке, изменении или диагностике @gromlab/svg-sprites. Триггеры: @gromlab/svg-sprites, svg-sprite.config.json, svg-sprite.config.ts, defineSpriteConfig, generateSprite, standalone, standalone@vite, standalone@webpack, react@vite, react@webpack, next@app, next@pages, SpriteConfig.input, --input, SpriteViewer и --icon-color-N. НЕ используй для самописных SVG-спрайтов, inline SVG, favicon, растровых изображений, icon fonts или выбора библиотеки иконок.',
|
||||
description: 'Используй только при настройке, изменении или диагностике @gromlab/svg-sprites. Триггеры: @gromlab/svg-sprites, svg-sprite.config.json, defineSpriteConfig, generateSprite, exact modes для standalone, React, Next.js, Vue, Nuxt, Svelte, Angular, Astro, Solid, Preact, Qwik, Lit или Alpine.js, SpriteConfig.input, --input, SpriteViewer и --icon-color-N. НЕ используй для самописных SVG-спрайтов, inline SVG, favicon, растровых изображений, icon fonts или выбора библиотеки иконок.',
|
||||
output: '../artifacts/svg-sprites-ru',
|
||||
maxSkillBytes: 48_000,
|
||||
documents: documents('ru'),
|
||||
|
||||
@@ -2,15 +2,15 @@
|
||||
|
||||
## What the package does
|
||||
|
||||
`@gromlab/svg-sprites` is a CLI generator that builds SVG sprites from user-provided SVG files. The package does not include its own icon set: it compiles project SVGs into an external sprite asset, creates a native typed Web Component for standalone bundler modes, and creates a React component for React/Next.js.
|
||||
`@gromlab/svg-sprites` is a CLI generator that builds SVG sprites from user-provided SVG files. The package does not include its own icon set: it compiles project SVGs into an external sprite asset and creates a typed native component for the selected exact framework and bundler mode.
|
||||
|
||||
The package supports multiple independent sprites in one project. Each explicitly selected config file or config-less directory describes one sprite and gets its own:
|
||||
|
||||
- SVG asset;
|
||||
- mode-specific manifest data;
|
||||
- icon name types and production entry `.svg-sprite/index.js` for bundler modes;
|
||||
- icon name types and production entry `.svg-sprite/index.js` for every mode except bare `standalone`;
|
||||
- an isolated framework-native component and declarations for framework modes;
|
||||
- a native Web Component with an explicit registration function for `standalone@vite`/`standalone@webpack`;
|
||||
- a React component only for React/Next.js;
|
||||
- a deployment-neutral JSON manifest without a public URL for bare `standalone`.
|
||||
|
||||
The project determines how many sprite directories exist and where they live. For example, `name: 'file-manager'` produces `FileManagerIcon`, `FileManagerIconName`, and `fileManagerIconNames`, while another directory with `name: 'navigation'` produces a separate `NavigationIcon`. These are examples of per-sprite APIs, not fixed package exports.
|
||||
@@ -28,6 +28,26 @@ Select exactly one supported mode key:
|
||||
| Standalone + Webpack 5 | `standalone@webpack` |
|
||||
| React + Vite | `react@vite` |
|
||||
| React + Webpack 5 | `react@webpack` |
|
||||
| Vue + Vite | `vue@vite` |
|
||||
| Vue + Webpack | `vue@webpack` |
|
||||
| Nuxt + Vite | `nuxt@vite` |
|
||||
| Nuxt + Webpack | `nuxt@webpack` |
|
||||
| Svelte + Vite | `svelte@vite` |
|
||||
| Svelte + Webpack | `svelte@webpack` |
|
||||
| SvelteKit + Vite | `sveltekit@vite` |
|
||||
| Angular application builder | `angular@application` |
|
||||
| Angular + Webpack | `angular@webpack` |
|
||||
| Astro + Vite | `astro@vite` |
|
||||
| Solid + Vite | `solid@vite` |
|
||||
| Solid + Webpack | `solid@webpack` |
|
||||
| SolidStart + Vite | `solid-start@vite` |
|
||||
| Preact + Vite | `preact@vite` |
|
||||
| Preact + Webpack | `preact@webpack` |
|
||||
| Qwik + Vite | `qwik@vite` |
|
||||
| Lit + Vite | `lit@vite` |
|
||||
| Lit + Webpack | `lit@webpack` |
|
||||
| Alpine.js + Vite | `alpine@vite` |
|
||||
| Alpine.js + Webpack | `alpine@webpack` |
|
||||
| Next.js App Router + Turbopack | `next@app/turbopack` |
|
||||
| Next.js App Router + Webpack 5 | `next@app/webpack` |
|
||||
| Next.js Pages Router + Turbopack | `next@pages/turbopack` |
|
||||
@@ -48,7 +68,7 @@ The CLI accepts exactly one path. A `.ts`, `.js`, or `.json` file loads that exa
|
||||
}
|
||||
```
|
||||
|
||||
Generation through `npx` does not add the package to the project. Do not use incomplete `react`, `next@app`, `next@pages`, or `standalone@` keys, or the removed `legacy` mode. Use bare `standalone` only when the application publishes the SVG itself; use the complete Vite/Webpack key otherwise. Create one command per config file or directory when the project has multiple sprites.
|
||||
Generation through `npx` does not add the package to the project. Do not invent shortened or generic mode keys, and do not use the removed `legacy` mode. Select one complete key from the table. Use bare `standalone` only when the application publishes the SVG itself. Create one command per config file or directory when the project has multiple sprites.
|
||||
|
||||
## Inspecting the project
|
||||
|
||||
@@ -56,7 +76,7 @@ Establish the project's actual contract before making changes:
|
||||
|
||||
1. Read the root `package.json`, lockfile, and workspace configuration; identify the framework, bundler, and existing commands.
|
||||
2. Find config files, commands containing `svg-sprites`, and imports of generated components. Config names are arbitrary; use the explicit CLI path and object fields.
|
||||
3. For React, determine whether the project uses Vite or Webpack 5 from its scripts and configuration. For Next.js, separately determine the App/Pages Router and the bundler used by the actual `dev`/`build` commands.
|
||||
3. Determine the framework, router when applicable, and actual bundler from scripts and configuration. For Next.js, separately determine the App/Pages Router and the bundler used by the real `dev`/`build` commands.
|
||||
4. Check existing `predev`, `prebuild`, `pretypecheck`, and orchestration scripts. Do not overwrite them.
|
||||
5. For a new sprite, choose a target directory without imposing a particular application layer or architecture.
|
||||
6. Check TypeScript and alias settings. Package subpath exports require TypeScript 5+ with `moduleResolution: 'bundler'`, `'node16'`, or `'nodenext'`.
|
||||
@@ -88,13 +108,13 @@ Work in this order:
|
||||
7. If the application imports the sprite-module directory, create a user-owned `index.ts` next to `.svg-sprite`; do not place user files inside the generated directory.
|
||||
8. Run the first generation before typecheck or application startup, then inspect the mode-specific output and the actual component import.
|
||||
|
||||
Do not add the Viewer automatically. Connect it only when requested or when visual verification of the set, colors, or complex SVGs is needed. Get the production isolation pattern from the exact guide: Vite, Webpack, App Router, and Pages Router use different boundaries.
|
||||
Do not add the Viewer automatically. Connect it only when requested or when visual verification of the set, colors, or complex SVGs is needed. Get the production isolation pattern from the exact guide: frameworks, bundlers, and routers use different boundaries.
|
||||
|
||||
Do not copy snippets between exact modes even when their APIs look similar. Asset URLs, generated files, CSS handling, router boundaries, and debug-tool setup differ.
|
||||
|
||||
## Generated directory contract
|
||||
|
||||
After generation, a React/Next.js directory has this structure:
|
||||
For example, after generation a React/Next.js directory has this structure:
|
||||
|
||||
```text
|
||||
svg-sprite/
|
||||
@@ -126,14 +146,14 @@ export * from './.svg-sprite/index.js'
|
||||
|
||||
The generator owns the complete `.svg-sprite` directory and replaces it on every run. Never put user files inside it. The generator also owns `.gitignore` when the selected mode creates it. Bare `standalone` preserves a user-owned `.gitignore`, but removes a managed `.gitignore` left by another mode. Generated paths must not contain symlinks.
|
||||
|
||||
In React/Next modes, the internal `index.js` exports the component from `react/react-component.js` and the readonly name array; `index.d.ts` adds props/style types and the icon-name union. Standalone bundler modes export Web Component helpers and types without `react/`; bare `standalone` does not create a facade. Bundler-mode manifest declarations define their types locally and do not import the generator package. The manifest contains mode, target, icon list, and icon metadata for debug tools; bundler manifests also contain a URL and are not imported by the production component.
|
||||
Every exact-mode adapter owns its facade, framework directory, native component runtime, declarations, manifest source, styles, and asset URL. React/Next use `react/`; other framework modes use their own generated contract documented by the matching guide. Standalone bundler modes export Web Component helpers and types; bare `standalone` does not create a facade. Manifest declarations define their types locally and do not import the generator package.
|
||||
|
||||
In bundler modes, the sprite remains a separate asset and SVG path data is not embedded in JavaScript. The content hash depends on bundler settings. Bare `standalone` creates a fixed filename, and the application owns its public name and versioning:
|
||||
|
||||
- `react@vite` generates a static `sprite.svg?no-inline` import, preventing Vite from inlining it;
|
||||
- Vite-based adapters use a mode-owned static asset import that keeps the sprite external;
|
||||
- `standalone@vite` uses the same Vite asset mechanism and exports an href helper plus a native Web Component without React;
|
||||
- `standalone@webpack` uses Webpack Asset Modules and exports the same mode-local Web Component without React;
|
||||
- React Webpack 5 and all Next modes obtain the asset through `new URL(..., import.meta.url).href`, which must be processed by the selected bundler;
|
||||
- Webpack-based adapters and all Next modes use their adapter-owned external asset mechanism, commonly `new URL(..., import.meta.url).href`;
|
||||
- a custom Webpack SVG loader must not intercept the generated `sprite.svg`;
|
||||
- in Next mode, the generated component does not contain `'use client'` and works in Server Components, SSR, and SSG; do not add a client boundary solely for an icon;
|
||||
- the Next build command and mode key must agree: Turbopack with `.../turbopack`, Webpack with `.../webpack`.
|
||||
@@ -156,7 +176,7 @@ defineFileManagerIconElement()
|
||||
|
||||
The native element has no runtime dependencies, selects the generated ID and `viewBox`, obtains the URL through the bundler, and renders `<svg><use>` in Shadow DOM. Its `icon` property is typed with the exact name union, while plain HTML attribute values are validated only at runtime. It defaults to `1em × 1em`; resize the host with CSS. Bare `standalone` does not generate a Web Component.
|
||||
|
||||
In React/Next.js, the same `name: 'file-manager'` creates the `FileManagerIcon` React component. For `name: 'navigation'`, use the generated `NavigationIcon`.
|
||||
In component modes, the same `name: 'file-manager'` creates a native `FileManagerIcon` component. Its syntax and props follow the exact-mode guide. For React/Next.js, `name: 'navigation'` creates `NavigationIcon`.
|
||||
|
||||
Import the component from the root of its sprite directory. `width` and `height` are optional: ordinary CSS classes can control the size.
|
||||
|
||||
@@ -201,7 +221,7 @@ Automatic replacement targets `fill`/`stroke` attributes and inline `style`. The
|
||||
|
||||
`SpriteViewer` is optional. Install `@gromlab/svg-sprites` as a development dependency only when the project needs the Viewer. It accepts manifests or statically discoverable loaders and provides search, themes, colors, and examples, but production components do not depend on it.
|
||||
|
||||
Open the exact guide before connecting the Viewer. Vite uses a separate HTML entry, plain Webpack uses a development-only entry, Next.js uses a debug route, and the App Router additionally requires a separate Client Component boundary. Do not transfer setup between modes.
|
||||
Open the exact guide before connecting the Viewer. Frameworks, bundlers, and routers require different debug entries or client boundaries. Do not transfer setup between modes.
|
||||
|
||||
## Verifying the result
|
||||
|
||||
@@ -211,7 +231,7 @@ After changing a config or SVG, perform these required checks:
|
||||
2. Inspect the output for the selected exact mode:
|
||||
- bare `standalone` creates `sprite.svg` and `svg-sprite.manifest.json`;
|
||||
- `standalone@vite` and `standalone@webpack` additionally create `index.*`, `icon-data.*`, and a JS manifest, but no `react/` directory;
|
||||
- React and Next.js modes also create `react/react-component.js`, its declaration, and its CSS Module.
|
||||
- framework modes also create their adapter-owned native component runtime, declaration, and styles.
|
||||
3. For modes with a public facade, inspect `.svg-sprite/index.js`, the adjacent `index.d.ts`, the name list, and the actual import through the user-owned barrel.
|
||||
4. Inspect the manifest: mode and target must match the selected adapter, and the icon list must match the source SVGs. In bundler modes the URL must use the mode-specific mechanism; the bare JSON manifest intentionally has no public `spriteUrl`.
|
||||
5. Run the project's existing typecheck when the mode creates types or user-owned TypeScript changed.
|
||||
@@ -254,7 +274,7 @@ References are included in the built skill. Open only the documents relevant to
|
||||
|
||||
### Overview
|
||||
|
||||
- [Package README](./references/README.md) covers capabilities, the primary React/Next.js scenario, and documentation links.
|
||||
- [Package README](./references/README.md) covers capabilities, the primary React/Next.js example, all supported families, and documentation links.
|
||||
|
||||
### Configuration
|
||||
|
||||
@@ -267,6 +287,26 @@ References are included in the built skill. Open only the documents relevant to
|
||||
- [`standalone@webpack`](./references/docs/en/guides/standalone-webpack.md) covers a vanilla Webpack 5 application and the Web Component.
|
||||
- [`react@vite`](./references/docs/en/guides/react-vite.md) covers React with Vite.
|
||||
- [`react@webpack`](./references/docs/en/guides/react-webpack.md) covers React with Webpack 5.
|
||||
- [`vue@vite`](./references/docs/en/guides/vue-vite.md) covers Vue with Vite.
|
||||
- [`vue@webpack`](./references/docs/en/guides/vue-webpack.md) covers Vue with Webpack.
|
||||
- [`nuxt@vite`](./references/docs/en/guides/nuxt-vite.md) covers Nuxt with Vite.
|
||||
- [`nuxt@webpack`](./references/docs/en/guides/nuxt-webpack.md) covers Nuxt with Webpack.
|
||||
- [`svelte@vite`](./references/docs/en/guides/svelte-vite.md) covers Svelte with Vite.
|
||||
- [`svelte@webpack`](./references/docs/en/guides/svelte-webpack.md) covers Svelte with Webpack.
|
||||
- [`sveltekit@vite`](./references/docs/en/guides/sveltekit-vite.md) covers SvelteKit with Vite.
|
||||
- [`angular@application`](./references/docs/en/guides/angular-application.md) covers the Angular application builder.
|
||||
- [`angular@webpack`](./references/docs/en/guides/angular-webpack.md) covers Angular with Webpack.
|
||||
- [`astro@vite`](./references/docs/en/guides/astro-vite.md) covers Astro with Vite.
|
||||
- [`solid@vite`](./references/docs/en/guides/solid-vite.md) covers Solid with Vite.
|
||||
- [`solid@webpack`](./references/docs/en/guides/solid-webpack.md) covers Solid with Webpack.
|
||||
- [`solid-start@vite`](./references/docs/en/guides/solid-start-vite.md) covers SolidStart with Vite.
|
||||
- [`preact@vite`](./references/docs/en/guides/preact-vite.md) covers Preact with Vite.
|
||||
- [`preact@webpack`](./references/docs/en/guides/preact-webpack.md) covers Preact with Webpack.
|
||||
- [`qwik@vite`](./references/docs/en/guides/qwik-vite.md) covers Qwik with Vite.
|
||||
- [`lit@vite`](./references/docs/en/guides/lit-vite.md) covers Lit with Vite.
|
||||
- [`lit@webpack`](./references/docs/en/guides/lit-webpack.md) covers Lit with Webpack.
|
||||
- [`alpine@vite`](./references/docs/en/guides/alpine-vite.md) covers Alpine.js with Vite.
|
||||
- [`alpine@webpack`](./references/docs/en/guides/alpine-webpack.md) covers Alpine.js with Webpack.
|
||||
- [`next@app/turbopack`](./references/docs/en/guides/next-app-turbopack.md) covers the Next.js App Router with Turbopack.
|
||||
- [`next@app/webpack`](./references/docs/en/guides/next-app-webpack.md) covers the Next.js App Router with Webpack.
|
||||
- [`next@pages/turbopack`](./references/docs/en/guides/next-pages-turbopack.md) covers the Next.js Pages Router with Turbopack.
|
||||
|
||||
@@ -2,15 +2,15 @@
|
||||
|
||||
## Что делает пакет
|
||||
|
||||
`@gromlab/svg-sprites` — CLI-генератор SVG-спрайтов для пользовательских SVG-файлов. Пакет не содержит собственного набора иконок: он собирает SVG проекта во внешний sprite asset, создаёт нативный типизированный Web Component для standalone bundler modes и React-компонент для React/Next.js.
|
||||
`@gromlab/svg-sprites` — CLI-генератор SVG-спрайтов для пользовательских SVG-файлов. Пакет не содержит собственного набора иконок: он собирает SVG проекта во внешний sprite asset и создаёт типизированный нативный компонент для выбранного exact framework/bundler mode.
|
||||
|
||||
Пакет рассчитан на несколько независимых спрайтов в одном проекте. Каждый явно выбранный config-файл или config-less каталог описывает один спрайт и получает собственные:
|
||||
|
||||
- SVG asset;
|
||||
- mode-specific manifest data;
|
||||
- для bundler modes — типы имён и production entry `.svg-sprite/index.js`;
|
||||
- для всех modes, кроме bare `standalone`, — типы имён и production entry `.svg-sprite/index.js`;
|
||||
- для framework modes — изолированный нативный компонент и declarations;
|
||||
- для `standalone@vite`/`standalone@webpack` — нативный Web Component с явной функцией регистрации;
|
||||
- только для React/Next.js — React-компонент;
|
||||
- для bare `standalone` — deployment-neutral JSON manifest без публичного URL.
|
||||
|
||||
Количество и расположение каталогов определяет проект. Например, `name: 'file-manager'` создаёт `FileManagerIcon`, `FileManagerIconName` и `fileManagerIconNames`, а другой каталог с `name: 'navigation'` создаст отдельный `NavigationIcon`. Это примеры API отдельных спрайтов, а не фиксированные экспорты пакета.
|
||||
@@ -28,6 +28,26 @@ Generated production runtime и declarations не импортируют `@groml
|
||||
| Standalone + Webpack 5 | `standalone@webpack` |
|
||||
| React + Vite | `react@vite` |
|
||||
| React + Webpack 5 | `react@webpack` |
|
||||
| Vue + Vite | `vue@vite` |
|
||||
| Vue + Webpack | `vue@webpack` |
|
||||
| Nuxt + Vite | `nuxt@vite` |
|
||||
| Nuxt + Webpack | `nuxt@webpack` |
|
||||
| Svelte + Vite | `svelte@vite` |
|
||||
| Svelte + Webpack | `svelte@webpack` |
|
||||
| SvelteKit + Vite | `sveltekit@vite` |
|
||||
| Angular application builder | `angular@application` |
|
||||
| Angular + Webpack | `angular@webpack` |
|
||||
| Astro + Vite | `astro@vite` |
|
||||
| Solid + Vite | `solid@vite` |
|
||||
| Solid + Webpack | `solid@webpack` |
|
||||
| SolidStart + Vite | `solid-start@vite` |
|
||||
| Preact + Vite | `preact@vite` |
|
||||
| Preact + Webpack | `preact@webpack` |
|
||||
| Qwik + Vite | `qwik@vite` |
|
||||
| Lit + Vite | `lit@vite` |
|
||||
| Lit + Webpack | `lit@webpack` |
|
||||
| Alpine.js + Vite | `alpine@vite` |
|
||||
| Alpine.js + Webpack | `alpine@webpack` |
|
||||
| Next.js App Router + Turbopack | `next@app/turbopack` |
|
||||
| Next.js App Router + Webpack 5 | `next@app/webpack` |
|
||||
| Next.js Pages Router + Turbopack | `next@pages/turbopack` |
|
||||
@@ -48,7 +68,7 @@ CLI принимает ровно один путь. Путь к файлу `.ts
|
||||
}
|
||||
```
|
||||
|
||||
Генерация через `npx` не добавляет package в проект. Не используй неполные `react`, `next@app`, `next@pages`, `standalone@` или удалённый `legacy`. Bare `standalone` выбирай только когда приложение само публикует SVG; для Vite/Webpack используй соответствующий полный key. Для нескольких спрайтов создай отдельную команду для каждого config-файла или каталога.
|
||||
Генерация через `npx` не добавляет package в проект. Не придумывай сокращённые или generic mode keys и не используй удалённый `legacy`: выбери один полный key из таблицы. Bare `standalone` выбирай только когда приложение само публикует SVG. Для нескольких спрайтов создай отдельную команду для каждого config-файла или каталога.
|
||||
|
||||
## Инспекция проекта
|
||||
|
||||
@@ -56,7 +76,7 @@ CLI принимает ровно один путь. Путь к файлу `.ts
|
||||
|
||||
1. Прочитай корневой `package.json`, lock-файл и workspace-конфигурацию; определи framework, bundler и существующие команды.
|
||||
2. Найди config-файлы, команды `svg-sprites` и импорты generated-компонентов. Имя конфига произвольное; ориентируйся на переданный CLI путь и поля объекта.
|
||||
3. Для React определи Vite или Webpack 5 по scripts и конфигу. Для Next.js отдельно определи App/Pages Router и сборщик реальных `dev`/`build` команд.
|
||||
3. Определи framework, router при его наличии и фактический bundler по scripts и конфигу. Для Next.js отдельно определи App/Pages Router и сборщик реальных `dev`/`build` команд.
|
||||
4. Проверь существующие `predev`, `prebuild`, `pretypecheck` и агрегирующие scripts. Не перезаписывай их.
|
||||
5. Для нового спрайта выбери целевой каталог, не навязывая конкретный слой или архитектуру приложения.
|
||||
6. Проверь TypeScript и alias-настройки. Для package subpath exports нужен TypeScript 5+ с `moduleResolution: 'bundler'`, `'node16'` или `'nodenext'`.
|
||||
@@ -88,13 +108,13 @@ CLI принимает ровно один путь. Путь к файлу `.ts
|
||||
7. Если приложение импортирует каталог sprite-модуля, создай пользовательский `index.ts` рядом с `.svg-sprite`; не помещай пользовательские файлы внутрь generated-каталога.
|
||||
8. Выполни первую генерацию до typecheck или запуска приложения, затем проверь mode-specific output и фактический импорт компонента.
|
||||
|
||||
Не добавляй Viewer автоматически. Подключай его только по запросу пользователя или когда нужна визуальная проверка набора, цветов либо сложных SVG. Способ изоляции Viewer от production бери из exact guide: Vite, Webpack, App Router и Pages Router используют разные границы.
|
||||
Не добавляй Viewer автоматически. Подключай его только по запросу пользователя или когда нужна визуальная проверка набора, цветов либо сложных SVG. Способ изоляции Viewer от production бери из exact guide: frameworks, bundlers и routers используют разные границы.
|
||||
|
||||
Не копируй snippets между exact modes даже при похожем API. Различаются asset URL, generated-файлы, CSS handling, router boundary и способ подключения debug-инструментов.
|
||||
|
||||
## Контракт generated-каталога
|
||||
|
||||
После генерации React/Next-каталог имеет следующий вид:
|
||||
Например, после генерации React/Next-каталог имеет следующий вид:
|
||||
|
||||
```text
|
||||
svg-sprite/
|
||||
@@ -126,14 +146,14 @@ export * from './.svg-sprite/index.js'
|
||||
|
||||
Генератор полностью владеет каталогом `.svg-sprite` и заменяет его при каждом запуске. Никогда не помещай туда пользовательские файлы. Генератор также владеет `.gitignore`, когда выбранный mode его создаёт. Bare `standalone` сохраняет пользовательский `.gitignore`, но удаляет управляемый `.gitignore`, оставшийся после другого mode. Generated-пути не должны содержать symlink.
|
||||
|
||||
В React/Next modes внутренний `index.js` экспортирует компонент из `react/react-component.js` и readonly-массив имён, а `index.d.ts` добавляет props/style-типы и union имени. Standalone bundler modes экспортируют Web Component helpers и типы без `react/`; bare `standalone` не создаёт facade. Manifest declarations bundler modes объявляют типы локально и не импортируют generator package. Manifest содержит mode, target, список и метаданные иконок для debug-инструментов; bundler manifest также содержит URL и не импортируется production-компонентом.
|
||||
Каждый exact-mode adapter владеет facade, framework-каталогом, runtime нативного компонента, declarations, manifest source, styles и asset URL. React/Next используют `react/`; остальные framework modes используют собственный generated-контракт из соответствующего guide. Standalone bundler modes экспортируют Web Component helpers и типы, а bare `standalone` не создаёт facade. Manifest declarations объявляют типы локально и не импортируют generator package.
|
||||
|
||||
В bundler modes спрайт остаётся отдельным asset, а SVG path-данные не встраиваются в JavaScript. Content hash зависит от настроек сборщика. Bare `standalone` создаёт файл с фиксированным именем, а приложение само определяет его публичное имя и версионирование:
|
||||
|
||||
- `react@vite` генерирует статический импорт `sprite.svg?no-inline`, запрещающий Vite inline;
|
||||
- Vite-based adapters используют mode-owned static asset import, сохраняющий sprite внешним;
|
||||
- `standalone@vite` использует тот же Vite asset-механизм и экспортирует href helper и нативный Web Component без React;
|
||||
- `standalone@webpack` использует Webpack Asset Modules и экспортирует такой же mode-local Web Component без React;
|
||||
- React Webpack 5 и все Next modes получают asset через `new URL(..., import.meta.url).href`, который должен обработать соответствующий сборщик;
|
||||
- Webpack-based adapters и все Next modes используют adapter-owned механизм внешнего asset, обычно `new URL(..., import.meta.url).href`;
|
||||
- кастомный Webpack SVG loader не должен перехватывать generated `sprite.svg`;
|
||||
- в Next mode generated-компонент не содержит `'use client'` и работает в Server Components, SSR и SSG; не добавляй клиентскую границу только ради иконки;
|
||||
- команда сборки Next и mode key должны совпадать: Turbopack с `.../turbopack`, Webpack с `.../webpack`.
|
||||
@@ -156,7 +176,7 @@ defineFileManagerIconElement()
|
||||
|
||||
Нативный элемент не имеет runtime-зависимостей, сам выбирает generated ID и `viewBox`, получает URL через bundler и рендерит `<svg><use>` в Shadow DOM. Его property `icon` типизирован точным union имён, но строковые HTML attributes проверяются только в runtime. Размер по умолчанию равен `1em × 1em`; меняй его через CSS на host. Bare `standalone` Web Component не генерирует.
|
||||
|
||||
В React/Next.js тот же `name: 'file-manager'` создаёт React-компонент `FileManagerIcon`. Для `name: 'navigation'` используй сгенерированный `NavigationIcon`.
|
||||
В component modes тот же `name: 'file-manager'` создаёт нативный компонент `FileManagerIcon`; его синтаксис и props определяет exact-mode guide. В React/Next.js значение `name: 'navigation'` создаёт `NavigationIcon`.
|
||||
|
||||
Импортируй компонент из корня соответствующего каталога спрайта. `width` и `height` не обязательны: размером можно управлять обычным CSS-классом.
|
||||
|
||||
@@ -201,7 +221,7 @@ Generated-компонент не выбирает семантику за пр
|
||||
|
||||
`SpriteViewer` необязателен. Установи `@gromlab/svg-sprites` как development dependency, только если проекту нужен Viewer. Он принимает manifests или статически обнаружимые loaders, показывает поиск, темы, цвета и примеры, но production-компоненты от него не зависят.
|
||||
|
||||
Перед подключением Viewer открой exact guide. Vite использует отдельную HTML entry, обычный Webpack — development-only entry, Next.js — debug route, а App Router дополнительно требует отдельную Client Component boundary. Не переноси способ подключения между modes.
|
||||
Перед подключением Viewer открой exact guide. Frameworks, bundlers и routers требуют разных debug entries или client boundaries. Не переноси способ подключения между modes.
|
||||
|
||||
## Проверка результата
|
||||
|
||||
@@ -211,7 +231,7 @@ Generated-компонент не выбирает семантику за пр
|
||||
2. Проверь output выбранного exact mode:
|
||||
- bare `standalone` создаёт `sprite.svg` и `svg-sprite.manifest.json`;
|
||||
- `standalone@vite` и `standalone@webpack` дополнительно создают `index.*`, `icon-data.*` и JS manifest, но не каталог `react/`;
|
||||
- React и Next.js modes также создают `react/react-component.js`, declaration и CSS Module.
|
||||
- framework modes также создают adapter-owned runtime нативного компонента, declaration и styles.
|
||||
3. Для modes с public facade проверь `.svg-sprite/index.js`, соседний `index.d.ts`, список имён и фактический импорт через пользовательский barrel.
|
||||
4. Проверь manifest: mode и target должны соответствовать выбранному adapter, а список иконок — исходным SVG. В bundler modes URL должен формироваться mode-specific способом; bare JSON manifest намеренно не содержит публичного `spriteUrl`.
|
||||
5. Запусти существующий typecheck проекта, если mode создаёт типы или изменился пользовательский TypeScript-код.
|
||||
@@ -254,7 +274,7 @@ References являются частью собранного skill. Откры
|
||||
|
||||
### Обзор
|
||||
|
||||
- [README пакета](./references/README_RU.md) — возможности, основной React/Next.js сценарий и ссылки на документацию.
|
||||
- [README пакета](./references/README_RU.md) — возможности, основной React/Next.js пример, все поддерживаемые families и ссылки на документацию.
|
||||
|
||||
### Конфигурация
|
||||
|
||||
@@ -267,6 +287,26 @@ References являются частью собранного skill. Откры
|
||||
- [`standalone@webpack`](./references/docs/ru/guides/standalone-webpack.md) — vanilla-приложение с Webpack 5 и Web Component.
|
||||
- [`react@vite`](./references/docs/ru/guides/react-vite.md) — React с Vite.
|
||||
- [`react@webpack`](./references/docs/ru/guides/react-webpack.md) — React с Webpack 5.
|
||||
- [`vue@vite`](./references/docs/ru/guides/vue-vite.md) — Vue с Vite.
|
||||
- [`vue@webpack`](./references/docs/ru/guides/vue-webpack.md) — Vue с Webpack.
|
||||
- [`nuxt@vite`](./references/docs/ru/guides/nuxt-vite.md) — Nuxt с Vite.
|
||||
- [`nuxt@webpack`](./references/docs/ru/guides/nuxt-webpack.md) — Nuxt с Webpack.
|
||||
- [`svelte@vite`](./references/docs/ru/guides/svelte-vite.md) — Svelte с Vite.
|
||||
- [`svelte@webpack`](./references/docs/ru/guides/svelte-webpack.md) — Svelte с Webpack.
|
||||
- [`sveltekit@vite`](./references/docs/ru/guides/sveltekit-vite.md) — SvelteKit с Vite.
|
||||
- [`angular@application`](./references/docs/ru/guides/angular-application.md) — Angular application builder.
|
||||
- [`angular@webpack`](./references/docs/ru/guides/angular-webpack.md) — Angular с Webpack.
|
||||
- [`astro@vite`](./references/docs/ru/guides/astro-vite.md) — Astro с Vite.
|
||||
- [`solid@vite`](./references/docs/ru/guides/solid-vite.md) — Solid с Vite.
|
||||
- [`solid@webpack`](./references/docs/ru/guides/solid-webpack.md) — Solid с Webpack.
|
||||
- [`solid-start@vite`](./references/docs/ru/guides/solid-start-vite.md) — SolidStart с Vite.
|
||||
- [`preact@vite`](./references/docs/ru/guides/preact-vite.md) — Preact с Vite.
|
||||
- [`preact@webpack`](./references/docs/ru/guides/preact-webpack.md) — Preact с Webpack.
|
||||
- [`qwik@vite`](./references/docs/ru/guides/qwik-vite.md) — Qwik с Vite.
|
||||
- [`lit@vite`](./references/docs/ru/guides/lit-vite.md) — Lit с Vite.
|
||||
- [`lit@webpack`](./references/docs/ru/guides/lit-webpack.md) — Lit с Webpack.
|
||||
- [`alpine@vite`](./references/docs/ru/guides/alpine-vite.md) — Alpine.js с Vite.
|
||||
- [`alpine@webpack`](./references/docs/ru/guides/alpine-webpack.md) — Alpine.js с Webpack.
|
||||
- [`next@app/turbopack`](./references/docs/ru/guides/next-app-turbopack.md) — Next.js App Router с Turbopack.
|
||||
- [`next@app/webpack`](./references/docs/ru/guides/next-app-webpack.md) — Next.js App Router с Webpack.
|
||||
- [`next@pages/turbopack`](./references/docs/ru/guides/next-pages-turbopack.md) — Next.js Pages Router с Turbopack.
|
||||
|
||||
Reference in New Issue
Block a user