Skip to content
Skills Library
Programming · Building & coding

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.

Repository
ng-prism ↗
Licence
MIT
Last repository change
20.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
2
Deprecation

No signals detected. Repository changed on 20.10.2026, without references to retired models or APIs.

Licence

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

  1. The installed version decides
  2. Install
  3. ng-prism.config.ts
  4. Official plugins
  5. Theming
  6. Publishing the library
  7. Upgrading
  8. Guides
Original SKILL.md headings · 150 lines, 1,197 words
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

RepositoryScoreLicence
This page · ng-prism/ng-prism100MIT
HwangSlater/harness-fit100MIT
nesquikm/dev-process-toolkit100MIT
userKael/rastro100MIT
als-apg/osprey100BSD-3-Clause
dedujeong/gemba100Apache-2.0
eigenwise/eigenwise-toolshed100MIT
awrshift/agent-memory-kit100MIT
lifecycle-innovations-limited/claude-ops100MIT

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.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.