Use Code analyze to create snapshots of your design system and usage code to help determine adoption of your design system components in code.
The output becomes a shared, LLM-optimized knowledge layer used by both:
- Portal Create (prototyping agent)
- MCP/CLI workflows (engineering)
This keeps prototyping and implementation aligned with the same source of truth.
What analyze does
Code analyze processes:
- TypeScript definitions
- JSDoc
- Markdown documentation
- Storybook stories
- real usage/adoption signals in consumer code
It creates snapshot artifacts and uploads them for backend processing.
Analysis modes
Full pipeline
supernova code analyze
Running supernova code analyze with no flags and no saved config launches an interactive wizard. Use --wizard to force it even when flags or a saved config are present.
Runs both analyzers:
- Components: what exists and how to use it
- Adoption: how it is used in real code
supernova code analyze --package @design-system-package
If packages are already configured in supernova.config.json:
supernova code analyze
For multiple packages:
supernova code analyze --package @design-system-package --package @icons-package
To skip specific packages (either a package name or a relative path):
supernova code analyze --package @design-system-package --exclude @acme/utils
supernova code analyze --package @design-system-package --exclude packages/utils
Wizard-selected exclusions and --exclude values are persisted to analyze.excludedPackages in supernova.config.json, so later runs don't need the flag.
Integration topologies
Unified monorepo (single root scan)
Use this when design system packages and consumer apps live in one monorepo.
How to run:
- Execute from monorepo root
- Run wizard without any flag or provide all DS packages as --package (or persist in config)
- Run full pipeline for complete context
# one-off run
supernova code analyze \\
--package @company/design-system \\
--package @company/icons \\
--package @company/primitives
# after packages are saved in supernova.config
supernova code analyze
When to use:
- centralized platform ownership
- easiest operational model
- best end-to-end visibility in a single run
Distributed multi-repo
Use this when teams run separate CI pipelines in separate repositories.
How to run:
- Run Analyze wizard first in your design system repository to select your design system packages
# design system repo
supernova code analyze
- Run Analyze independently in each repo you want to scan for usage providing all DS packages as --package (you can add multiple --package flags if needed)
- Target the same --designSystemId as with design system repo
- Use async mode in CI and monitor centrally
# repo A / B / C pipeline
supernova code analyze --package @company/design-system --designSystemId <id> --noWait
# monitor processing
supernova code analyze status --designSystemId <id>
When to use:
- federated orgs
- autonomous team pipelines
- repo-level rollout control with shared DS identity
Typical flows
Full data refresh
supernova code analyze --package @design-system-package
CI async run
supernova code analyze --package @design-system-package --noWait
Preflight without upload
supernova code analyze --package @design-system-package --dryRun
Monitor processing
supernova code analyze status --designSystemId <id>
Flags
|
Flag |
Short |
Required |
Description |
|---|---|---|---|
|
--package <value> |
-p |
Conditionally |
Repeatable. Required only when analyze.packages is not configured. |
|
--designSystemId <id> |
-d |
No |
Uses provided design system ID; otherwise from config/prompt. |
|
--exclude <value> |
|
No |
Repeatable path or package exclusion for usage analyzer. |
|
--wizard |
|
No |
Force the interactive wizard even when flags or a saved config are present. |
|
--dryRun |
|
No |
Write local snapshots only; skip upload. |
|
--noWait |
|
No |
Upload and start processing, do not wait for completion. Useful for CI. |
Configuration
Analyze reads/writes supernova.config.json in the current directory.
Example:
{
"designSystemId": "123",
"analyze": {
"repoId": "7c8e9b6b-4c0a-4dbd-8f78-2d5c3d6a9f10",
"packages": ["@design-system-package", "@icons-package"],
"excludedPackages": ["excluded-package"]
}
}
Stored fields:
- designSystemId
- analyze.repoId
- analyze.packages
- analyze.excludedPackages
Output artifacts
Snapshots are written under:
<package>/.supernova/snapshots/<snapshotId>/
Primary files:
- raw/*.json analyzer outputs
Upload and processing lifecycle
- CLI uploads snapshot archives
- CLI finalizes snapshots
- CLI starts processing runs
- CLI waits for completion (default)
Use --noWait to skip step 4 in CI.
Best practices
- Run full pipeline regularly (for example after releases).
- Use targeted modes for faster incremental updates.
- Keep analyze.packages explicit and versioned.
- Use -dryRun before widening analysis scope.
- Use -exclude to reduce noise.
- In CI, use -noWait plus supernova code analyze status.
Github actions configuration
Prerequisites
- SUPERNOVA_TOKEN stored as a repository secret (Settings → Secrets and variables → Actions)
- Node.js available in your runner (the workflow below handles this)
- Either supernova.config.json committed to the repo, or --package and --designSystemId passed explicitly
Minimal production-ready workflow
name: Analyze Components with Supernova
on:
push:
branches: [main]
workflow_dispatch:
jobs:
analyze:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- name: Setup Node.js
uses: actions/setup-node@v3
with:
node-version: "22"
- name: Install dependencies
run: npm i
- name: Install Supernova CLI
run: npm install -g @supernovaio/cli
- name: Analyze components
env:
SUPERNOVA_TOKEN: ${{ secrets.SUPERNOVA_TOKEN }}
run: supernova code analyze --package {packageName} --designSystemId {dsId} --noWait
Replace {packageName} and {dsId} with your values, or drop both flags if they are defined in supernova.config.json.
When to trigger
- push to main — keeps snapshots in sync with every merge
- workflow_dispatch — manual trigger for on-demand runs or debugging
- Add schedule (cron) if you want periodic refreshes independent of commits, for example after release branches land
Multi-repo setup
If your design system and consumer apps live in separate repos, run this workflow independently in each. Keep --designSystemId and package names identical across repos so snapshots are correlated correctly on the backend.