setup
/setup
Use when setting up or configuring ng-prism (@ng-prism/core) in an Angular CLI or Nx workspace - ng add, ng-prism.config.ts, the prism and prism-build targets and their options, adding an official plugin (jsdoc, box-model, figma, perf, coverage, visual-regression), theming the styleguide, publishing a library without its @Showcase decorators, or upgrading ng-prism. Not for writing showcases (skill showcase) or plugins (skill write-plugin), and not for developing ng-prism itself.
- Author
- ng-prism ↗
- Repository
- ng-prism ↗
- Licence
- MIT
- Last repository change
- 20.10.2026
Assessment and security
- Files in this package
- 1
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 2
No signals detected. Repository changed on 20.10.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
What it does and when to use it
Use when setting up or configuring ng-prism (@ng-prism/core) in an Angular CLI or Nx workspace - ng add, ng-prism.config.ts, the prism and prism-build targets and their options, adding an official plugin (jsdoc, box-model, figma, perf, coverage, visual-regression), theming the styleguide, publishing a library without its @Showcase decorators, or upgrading ng-prism. Not for writing showcases (skill showcase) or plugins (skill write-plugin), and not for developing ng-prism itself.
Original author description
Use when setting up or configuring ng-prism (@ng-prism/core) in an Angular CLI or Nx workspace - ng add, ng-prism.config.ts, the prism and prism-build targets and their options, adding an official plugin (jsdoc, box-model, figma, perf, coverage, visual-regression), theming the styleguide, publishing a library without its @Showcase decorators, or upgrading ng-prism. Not for writing showcases (skill showcase) or plugins (skill write-plugin), and not for developing ng-prism itself.
How it works
- The installed version decides
- Install
- ng-prism.config.ts
- Official plugins
- Theming
- Publishing the library
- Upgrading
- Guides
SKILL.md preview
---
name: setup
description: Use when setting up or configuring ng-prism (@ng-prism/core) in an Angular CLI or Nx workspace - ng add, ng-prism.config.ts, the prism and prism-build targets and their options, adding an official plugin (jsdoc, box-model, figma, perf, coverage, visual-regression), theming the styleguide, publishing a library without its @Showcase decorators, or upgrading ng-prism. Not for writing showcases (skill showcase) or plugins (skill write-plugin), and not for developing ng-prism itself.
---
# Setting up and configuring ng-prism
ng-prism adds a styleguide app to an Angular library. Its builder scans the library's `@Showcase` decorators and serves
or builds the app around them.
## 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:
- `NgPrismConfig`, the authoritative field list (only some fields carry JSDoc, the guides cover the rest):
`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/guide/installation.md`. The pages for this skill are listed at the end.
## Install
Angular CLI, from the workspace root:
```bash
ng add @ng-prism/core --project <lib>
```
Nx: `npm i -D @ng-prism/core`, then `npx nx g @ng-prism/core:ng-add --project=<lib>`. Plain `ng add` needs an
`angular.json` and stops with this hint otherwise. If Nx reports `Cannot find target 'prism'` right afterwards, run
`npx nx reset`. Further options: `--port` (default 4400), `--zoneless`.
What it adds, without overwriting existing files or path mappings:
- an app `<lib>-prism` next to the library (Nx: under `apps/` or `workspaceLayout.appsDir`) with `src/main.ts`,
`src/index.html` and `tsconfig.app.json`
- on the library: the targets `prism` (`@ng-prism/core:serve`, port 4400) and `prism-build` (`@ng-prism/core:build`,
output `dist/<lib>-prism`), both with `entryPoint` set to the library directory
- `ng-prism.config.ts` at the workspace root
- path mappings in `tsconfig.base.json` (or `tsconfig.json`): `ng-prism.config`, `prism-manifest/*` and `<lib>` for the
library's barrel
- `ng-prism-cache/` in `.gitignore`: the generated manifest lives there, is rebuilt on every run and never edited
- the script `strip-showcase` and the devDependencies `highlight.js` and `ngx-highlightjs`
**Up to 22.5.0, check `entryPoint` right after `ng add`.** There a library without secondary entry points (no
`ng-package.json` without `dest` below its root) needs `entryPoint` to name its barrel file, the `lib.entryFile` of its
`ng-package.json` (e.g. `projects/<lib>/src/public-api.ts`), on both targets. With the directory, those versions find
no component and don't warn: the log says `Generated manifest with 0 component(s)`. Later versions read the barrel
from the directory's `ng-package.json`.
Run it with `ng run <lib>:prism` (dev server, rescans on change) or `ng run <lib>:prism-build` (static build); in Nx
with `npx nx run <lib>:prism`. Target options: `entryPoint` (library directory or its barrel, required), `prismProject`
(required), `libraryProject`, `libraryImportPath`, `configFile` (default `ng-prism.config.ts`, must be inside the
workspace), `cacheDir`, `port` (serve) and `outputPath` (build). Unknown options fail validation.
## ng-prism.config.ts
```ts
import { provideHttpClient } from '@angular/common/http';
import { defineConfig } from '@ng-prism/core/config';
import { jsDocPlugin } from '@ng-prism/plugin-jsdoc';
export default defineConfig({
plugins: [jsDocPlugin()],
appProviders: [provideHttpClient()],
theme: { '--prism-primary': '#0f766e' },
strictShowcase: true
});
```
The file is loaded twice: the builder imports it in Node, and the styleguide app imports it in the browser through
`main.ts`. Whatever it imports must load on both sides. In Node, only this file is transpiled and its imports resolve
the Node way, without tsconfig `paths`.
- `plugins`: official or your own (skill write-plugin).
- `appProviders`: providers for the whole styleguide app, where `@Showcase({ providers })` moved to.
- `pages`: custom pages declared in the config.
- `theme`, `darkTheme`, `lightTheme`: CSS custom property overrides (see Theming).
- `title`, `subtitle`, `logo: { light, dark }`, `buildInfo: { version, gitHash }`: the header.
- `urlState` (default `true`) keeps the selection in the URL; `persistState` (default `true`) keeps state in
sessionStorage across reloads.
- `a11y`: thresholds and report path for the accessibility audit (`api/ng-prism-config.md`).
- `strictShowcase` (default `false`): a dropped `@Showcase` value fails the build instead of warning.
`ui`, `appComponent`, `themeStylesheet` and `headless` are in the typings, but nothing has ever read them; they are
deprecated (removed in 23.0.0) and the build prints a notice while one is set. Don't use them, and suggest removing
them where a config has them.
## Official plugins
Each one installs with `ng add @ng-prism/plugin-<name>`, which adds the import and the call to `ng-prism.config.ts`
and skips a plugin that is already there. In Nx: `npm i -D @ng-prism/plugin-<name>`, then
`npx nx g @ng-prism/plugin-<name>:ng-add`. Import from the package name; the Angular build picks the browser half
itself. Keep the core and every plugin on the same version: plugins require `@ng-prism/core` `^<their version>-0`.
| Package | Call | Adds |
| ------------------------------------ | --------------------------------------------------------------------- | ---------------------------------------------------------- |
| `@ng-prism/plugin-jsdoc` | `jsDocPlugin()` | an API tab built from the JSDoc of inputs and outputs |
| `@ng-prism/plugin-box-model` | `boxModelPlugin()` | a Box Model panel with a canvas overlay |
| `@ng-prism/plugin-figma` | `figmaPlugin({ designDiff?, accessToken? })` | a Figma embed; with `designDiff: true` a Design Diff panel |
| `@ng-prism/plugin-perf` | `perfPlugin({ bundle?: { maxTreeDepth? } })` | a Performance panel |
| `@ng-prism/plugin-coverage` | `coveragePlugin({ coveragePath?, thresholds? })` | coverage panel, header badge, sidebar marker |
| `@ng-prism/plugin-visual-regression` | `visualRegressionPlugin({ reportPath?, assetBaseUrl?, thresholds? })` | VRT report panel, header badge, sidebar marker |
- **Figma:** the embed shows when the component sets `meta: { figma: '<Figma URL with node-id>' }` as a string on
`@Showcase` itself. The Design Diff panel appears once a variant sets `meta.figma`: a URL with `node-id`, or
`{ url, nodeId }`; a variant without its own value falls back to the component's `meta.figma`. It calls the Figma
API from the browser, so `accessToken` becomes part of the styleguide app: never deploy a styleguide built with a
personal token where others can open it. `process.env` doesn't work in the config, which also runs in the browser:
keep the token in a gitignored `figma-token.local.ts` next to it, import it with the `.ts` extension and set
`"rewriteRelativeImportExtensions": true` in the styleguide app's `tsconfig.app.json` (as for a plugin inside the
repo, skill write-plugin).
- **Coverage** reads `coverage/coverage-summary.json` (Istanbul's `json-summary` reporter) at build time.
- **Visual regression** reads `vrt-report.json`, written by your own screenshot runner (`guide/visual-regression.md`).
## Theming
Theme values are CSS custom properties, set inline on `<html>`. The order: built-in tokens, the built-in dark or light
theme, `darkTheme` / `lightTheme`, then `theme`, which wins in both modes. Dark is the default; the user's choice is
stored in localStorage (`ng-prism-theme`). The main tokens: `--prism-primary`, `--prism-primary-from`,
`--prism-primary-to`, `--prism-accent`, `--prism-bg`, `--prism-bg-surface`, `--prism-bg-elevated`, `--prism-text`,
`--prism-text-muted`, `--prism-border`, `--prism-success`, `--prism-warn`, `--prism-danger`, `--prism-font-sans`,
`--prism-font-mono`.
## Publishing the library
`@Showcase` does nothing at runtime, but the built library still imports `@ng-prism/core`, which its consumers don't
have. Strip the decorators after the build:
```bash
ng build <lib> && npm run strip-showcase # runs ng-prism-strip dist/<lib>
```
In Nx, a target with `"command": "npx ng-prism-strip dist/<path>"` and `"dependsOn": ["build"]`. It rewrites `.js` and
`.mjs` files in place and can run twice. `@ng-prism/core` then stays a devDependency of the library. In code:
`createShowcaseStripTransformer()` or `stripShowcaseDecorators(source)` from `@ng-prism/core/transformer`.
## Upgrading
- ng-prism's major version follows Angular's. A breaking change within one Angular major ships as a minor release, with
a deprecation first and the removal in the next major. 22.x supports Angular 20 to 22.
- Update the core and all plugins in one call: `ng update @ng-prism/core @ng-prism/plugin-jsdoc …`.
- The migrations to v22 (manifest moved to `ng-prism-cache/`, `.ng-prism/` renamed) read `angular.json` only; in an Nx
workspace apply them by hand following `guide/migration-v22.md`. They need Angular CLI 22 and a Node version it
supports.
## Guides
- `guide/installation.md`, `guide/configuration.md`, `api/ng-prism-config.md`
- `plugins/overview.md` and one page per plugin (`plugins/jsdoc.md`, `plugins/figma.md`, …)
- `guide/theming.md`, `guide/library-publishing.md`, `guide/migration-v22.md`
Versions
| Repository | Score | Licence |
|---|---|---|
| This page · ng-prism/ng-prism | 100 | MIT |
| HwangSlater/harness-fit | 100 | MIT |
| nesquikm/dev-process-toolkit | 100 | MIT |
| userKael/rastro | 100 | MIT |
| als-apg/osprey | 100 | BSD-3-Clause |
| dedujeong/gemba | 100 | Apache-2.0 |
| eigenwise/eigenwise-toolshed | 100 | MIT |
| awrshift/agent-memory-kit | 100 | MIT |
| lifecycle-innovations-limited/claude-ops | 100 | MIT |
Database snapshot: 13.11.2026 · package version 607f219c5825 (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100prism-showcase-component
Annotates an Angular component with the @Showcase decorator for ng-prism discovery. Triggers on "add showcase", "showcase this", "make showcaseable", "annotate component". - 100showcase
Use when writing or changing an @Showcase decorator in an Angular library that uses @ng-prism/core (variants, inputs, content projection, directive hosts, states and pseudo states, canvas background and layout, status, component pages), when a build prints a "⚠ ng-prism:"… - 95prism
Use when the user wants to solve or evolve the Prism GPU model-placement benchmark. - 84prism-analyze
Analyze Claude Code session health using PRISM. Use when asked to check token usage, audit CLAUDE.md, understand why sessions are failing, or list projects. - 100prism-ui
Implement a complete UI screen or feature from a Form visual spec. Use when asked to "build a page", "implement this screen", "build the frontend for this feature", or "create this UI". - 84prism-advise
Get CLAUDE.md recommendations from PRISM. Use when asked to audit, fix, improve, or check what is wrong with a CLAUDE.md file.