Przejdź do treści
Biblioteka skilli
Programowanie · Budowanie i kod

write-plugin

/write-plugin

Pisze własną wtyczkę ng-prism na bazie NgPrismPlugin: hooki budowania, panele, nakładki i akcje w nawigacji, także do pakowania na npm.

Repozytorium
ng-prism ↗
Licencja
MIT
Ostatnia zmiana repozytorium
20.10.2026

Ocena i bezpieczeństwo

100/ 100Klasa: dobry
Format25 / 25
Frontmatter z nazwą i opisem, poprawna nazwa, opis do 1024 znaków, nazwa zgodna z folderem.
Odkrywalność25 / 25
Opis mówi, kiedy użyć skilla, ma sensowną długość i jest w 3. osobie.
Treść35 / 35
Co najmniej 150 słów i do 500 linii, nagłówki, listy kroków, przykłady albo kod.
Higiena15 / 15
Bez zaślepek typu TODO, bez ścieżek Windows, z licencją.
Ryzykobrak sygnałów w skanie
Pliki w paczce
1
Skrypty
0
Komentarze HTML
0
Adresy URL w SKILL.md
2
Przestarzałość

Brak sygnałów. Repozytorium zmienione 20.10.2026, bez odwołań do wycofanych modeli i API.

Licencja

MIT, otwarta: można używać i zmieniać, z zachowaniem informacji o autorze.

Co robi i kiedy

Pisze własną wtyczkę ng-prism na bazie NgPrismPlugin: hooki budowania, panele, nakładki i akcje w nawigacji, także do pakowania na npm.

Oryginalny opis (EN)

Use when writing your own ng-prism plugin (NgPrismPlugin from @ng-prism/core/plugin) - build-time hooks (onComponentScanned, onPageScanned, onManifestReady), panels and canvas overlays, custom input controls, header widgets, sidebar navigation decorations - or packaging one for npm. Not for adding an official plugin (skill setup) and not for developing ng-prism itself.

Jak działa

  1. The installed version decides
  2. Build-time hooks
  3. Runtime contributions
  4. Packaging for npm
  5. A plugin inside your repo
  6. Testing
  7. Guides
Sekcje z nagłówków SKILL.md, w oryginale · 132 linii, 1 048 słów
Podgląd SKILL.md
---
name: write-plugin
description: Use when writing your own ng-prism plugin (NgPrismPlugin from @ng-prism/core/plugin) - build-time hooks (onComponentScanned, onPageScanned, onManifestReady), panels and canvas overlays, custom input controls, header widgets, sidebar navigation decorations - or packaging one for npm. Not for adding an official plugin (skill setup) and not for developing ng-prism itself.
---

# Writing an ng-prism plugin

A plugin is a factory function that returns an `NgPrismPlugin`, registered in `ng-prism.config.ts`
(`plugins: [notesPlugin()]`). That file runs twice: in Node inside the builder, where the hooks run, and in the
browser, where the styleguide picks up panels, controls, widgets and decorations. Whatever a plugin imports at the top
level has to load on both sides.

## The installed version decides

Read `version` in `node_modules/@ng-prism/core/package.json`. Where this skill and the installed package disagree, the
package is right:

- Every type below, with JSDoc: `node_modules/@ng-prism/core/dist/plugin/plugin.types.d.ts`.
- A field this skill names that those typings don't have is newer than the installed version: don't use it, suggest an
  update at most.
- Guides: `https://ng-prism.github.io/ng-prism/`, served as raw Markdown you can fetch directly, e.g.
  `https://ng-prism.github.io/ng-prism/plugins/writing-plugins.md`. The pages for this skill are listed at the end.

## Build-time hooks

```ts
import type { NgPrismPlugin } from '@ng-prism/core/plugin';

export function notesPlugin(): NgPrismPlugin {
    return {
        name: 'notes',
        onComponentScanned(component) {
            const variants = component.showcaseConfig.variants ?? [];
            component.showcaseConfig.meta = { ...component.showcaseConfig.meta, notes: { variants: variants.length } };
            return component;
        }
    };
}
```

- `onComponentScanned(component)` runs once per component, `onPageScanned(page)` once per page from the config's
  `pages` (not the component pages registered in `main.ts`), `onManifestReady(manifest)` once at the end.
- Plugins run in registration order, one after the other, and each gets the previous one's result. Return the changed
  object, a new one, or nothing to keep it as it is; `async` is fine.
- What a user wrote in `@Showcase({ meta })` arrives as `component.showcaseConfig.meta`, a variant's as
  `component.showcaseConfig.variants[i].meta`.
- Store per-component results in `component.showcaseConfig.meta[<your key>]`, as the official plugins do. Data for the
  whole library goes into `manifest.meta`, read in the browser with `inject(PRISM_MANIFEST).meta`.
- The manifest that carries these results to the browser is generated source code: only JSON-like data survives. In
  a component's showcase meta a function becomes `undefined`, and a `Date`, `Map`, `Set` or class instance becomes a
  plain object of its own enumerable fields (`{}` for the built-ins). `manifest.meta` is written with `JSON.stringify`:
  functions are dropped, a `Date` becomes an ISO string.
- Import Node-only modules inside the hook (`const { readFile } = await import('node:fs/promises')`), never at the top
  of the file: the same file is bundled for the browser.
- A hook that throws stops the build with `ng-prism: plugin "<name>" failed in <hook> for …`; during `serve`, a failed
  rescan keeps the previous manifest.

## Runtime contributions

| Field                   | Definition                                                                                                                              | The component receives                            |
| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------- |
| `panels`                | `{ id, label, loadComponent, icon?, placement?: 'addon' \| 'view', isVisible?, badge?, keepAlive?, providers?, loadOverlayComponent? }` | input `activeComponent: RuntimeComponent \| null` |
| overlay                 | `loadOverlayComponent` on a panel, drawn over the canvas while that panel is active                                                     | input `rendererService: PrismRendererService`     |
| `controls`              | `{ matchType: (input: InputMeta) => boolean, component }`                                                                               | inputs `inputMeta` and `rendererService`          |
| `headerWidgets`         | `{ id, loadComponent, placement?: 'start' \| 'end', order? }`                                                                           | nothing                                           |
| `navigationDecorations` | `{ id, icon, order?, badge: (c) => { variant: 'warn' \| 'danger', label } \| null }`                                                    | (no component)                                    |

- Components are standalone. Load panels, overlays and header widgets lazily:
  `loadComponent: () => import('./notes-panel.component').then((m) => m.NotesPanelComponent)`. An eager `component`
  pulls its imports into the file that also runs in Node. Controls only have `component`.
- `RuntimeComponent.meta` is the whole scanned component, so the user's showcase meta is
  `activeComponent()?.meta.showcaseConfig.meta`.
- The selected variant and its inputs: inject `PrismRendererService` from `@ng-prism/core` (`activeVariantIndex()`,
  `inputValues()`, `renderedElement()`, `selectVariant()`, `updateInput()`). `PrismNavigationService.activeComponent`
  is the selection. `PRISM_MANIFEST`, `PRISM_CONFIG` and `ICON_NAMES` (the valid `icon` values) come from
  `@ng-prism/core/plugin`.
- `isVisible`, `badge` and a decoration's `badge` run during change detection: keep them pure and cheap, and decide
  verdicts in `onComponentScanned`.
- Panel ids are not deduplicated: prefix yours and avoid the built-in `overview`, `controls`, `events` and `a11y`.
- Decoration ids are deduplicated: built-ins first (only `a11y`), then plugins in registration order. The first
  definition of an id wins, later ones are dropped silently. The orders 10, 20 and 30 belong to a11y, visual regression
  and coverage.
- The first control whose `matchType` matches wins, in registration order.
- `wrapComponent` and a panel's `position` are in the typings, but nothing has ever read them; they are deprecated
  (removed in 23.0.0). Don't use them. Where a panel appears is `placement`.

## Packaging for npm

The official plugins with build-time hooks split into a Node entry with everything and a browser entry with the
runtime contributions only:

```json
{
    "type": "module",
    "exports": {
        "./package.json": "./package.json",
        ".": {
            "types": "./dist/index.d.ts",
            "browser": "./dist/index.browser.js",
            "import": "./dist/index.js",
            "default": "./dist/index.js"
        }
    },
    "peerDependencies": { "@angular/core": ">=20.0.0", "@ng-prism/core": "^22.5.0-0" }
}
```

- `index.ts` exports the factory with hooks and contributions; `index.browser.ts` exports a factory of the same name
  without the hooks. Both export the same names, since they share one `index.d.ts`.
- Angular and `@ng-prism/core` are `peerDependencies`, never bundled.
- Optional `ng add`: a schematic that calls `addPluginToConfig(tree, path, { importName, importFrom, call })` from
  `@ng-prism/core/schematics/utils`, with `path` pointing at `ng-prism.config.ts`.

## A plugin inside your repo

A plugin doesn't have to be a package. Import its file from `ng-prism.config.ts` with the `.ts` extension
(`import { notesPlugin } from './prism/notes-plugin.ts';`) and add `"rewriteRelativeImportExtensions": true` to the
`compilerOptions` of the styleguide app's `tsconfig.app.json`, so the browser build accepts that path. In the builder,
Node loads the file as it is, which needs Node 22.18 or newer; without `"type": "module"` in the root `package.json` it
prints a harmless `MODULE_TYPELESS_PACKAGE_JSON` warning. That file and whatever it imports statically may only
use TypeScript Node can strip: `import type` for types, no `enum`, no decorators, no constructor parameter properties.
Write its own relative imports with `.ts` as well; Node adds no extension. Keep components behind `loadComponent`,
which only the browser runs. That rules out `controls`: a control's `component` is eager, so its decorator would have
to run in Node. Restart `ng run <lib>:prism` after changing a hook: Node caches the imported plugin module, so a rescan
doesn't reload it.

## Testing

- Hooks are plain functions: unit-test them with a hand-built `ScannedComponent`.
- Then run the styleguide (`ng run <lib>:prism`), check the hook's effect in the log and open the panel; the showcase
  skill's screenshot script with `--shell` shows the UI.

## Guides

- `plugins/writing-plugins.md`, `architecture/plugin-hooks.md`, `api/ng-prism-plugin.md`, `api/services.md`

Wersje

W bazie nie ma innych skilli o nazwie write-plugin.

Migawka bazy z 13.11.2026 · wersja paczki e67dcd15312e (skrót SHA-256 całej paczki)

Pobrania w ostatnich 30 dniach: 0 · ranking

Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.

Podobne skille

  • 100prism-plugin
    Tworzy wtyczki dla biblioteki ng-prism zgodne z interfejsem NgPrismPlugin, gdy potrzebny jest nowy dodatek.
  • 100setup
    Konfiguruje ng-prism w Angularze lub Nx: ng add, plik konfiguracji, cele prism i prism-build, wtyczki oraz motyw katalogu komponentów.
  • 95prism
    Rozwiązuje lub rozwija benchmark rozmieszczania modeli na GPU w projekcie Prism.
  • 85prism
    Działa jako inżynier frontendu: komponenty UI, dashboardy, wdrożenie design systemu i audyty frontendu.
  • 84prism-advise
    Pobiera od PRISM rekomendacje dotyczące pliku CLAUDE.md i wskazuje, co w nim wymaga poprawy.
  • 100prism-ui
    Implementuje kompletny ekran lub funkcję interfejsu na podstawie wizualnej specyfikacji Form, przy budowie strony, ekranu lub frontendu funkcji.

Uwagi i zgłoszenia

Wiadomość trafi do Bartosza Sokolińskiego. Adres e-mail jest potrzebny tylko do odpowiedzi. Szczegóły w polityce prywatności.