Prerequisites
- Node.js (version 20.19.0 || >=22.12.0).
- npm for dependency management.
- Docker installed and running (for uploading the container to Supernova).
- Access to your company's component library and design system.
Framework
Clone the container template that matches your framework into a repository of choice, typically where your design system lives.
Once container is cloned into desired repository, you can:
- Update the container’s name in package.json to reflect a design system, or a product. → This name will be visible in Supernova UI after upload.
- Change the version for better recognition of the state of container. The version will be visible in Supernova UI after upload.
"name": "supernova-container-template", // rename your container to your design system
"private": true,
"version": "1.1.0", // use it for versioning your container
"type": "module",
"scripts": {
"dev": "vite",
"vite": "vite",
"build": "tsc -b && vite build",
"lint": "eslint .",
"preview": "vite preview"
},
Container’s file directory
Here is a quick summary of the most important files in the container templates and what they are used for:
├── src/ # Empty Project sandbox where AI will create code in Supernova Create
├── supernova/
│ ├── usage.md # The first file where the Supernova AI goes for instructions
│ ├── components.md # Information about your component library
│ ├── icons.md # Information about your icon library if you upload it
└── package.json # Where you'll add your dependencies + manage container version
Importing your libraries
- Install project’s dependencies
npm i
2. Add your dependencies:
- Install your company's packages (e.g., components, design systems) through npm
- If your packages are private dependencies: Each npm dependency that is coming from a private registry needs to be declared in the package.json file under supernova.privateDependencies:
"supernova": { // where you declare your private dependencies
"privateDependencies": ["@example/package"]
},
"dependencies": { // where you add your dependencies
"react": "^18.3.1",
"react-dom": "^18.3.1"
}
If you declared private dependencies:
- Supernova CLI uses docker secrets to inject NPM token. To make sure you are passing NPM token via Docker secrets, make sure to pass in NPM token via command’s --npmToken argument and then consume it in the .npmrc file like this:
//registry.npmjs.org/:_authToken={NPM_TOKEN}.
- This way the NPM token doesn’t get baked into the image and is never transmitted to Supernova (we only upload private dependencies that the user choses to install in the template).
Provide AI instructions
In order to get the best results on te get go, add basic instructions for the AI to know a bit more about your design system library in the supernova/usage.md folder. Here is a sample prompt you can run to set it up with you IDE’s coding agent of choice:
Create a `supernova/usage.md` file for this project that will be used as agent rules when generating or editing code. The file should instruct the AI to follow our stack and conventions so generated code is consistent and correct.
**Project context (fill in):**
- Framework: [e.g. Vue 3, React, Angular 17+]
- UI library: [e.g. PrimeVue 4, Angular Material, MUI, none]
- Theme or design system: [e.g. Aura from @primeuix/themes, Material theme in styles.scss, custom tokens]
- Entry file where AI-generated UI should go: [e.g. App.vue, app.component.ts, app.tsx]
- Any other critical libraries: [e.g. Vue Router, Pinia, React Query, RxJS]
**Required structure for usage.md:**
1. **Title and intro**
- Start with: "# Supernova Agent Rules" and "When using the codebase, follow these rules:"
2. **[Framework] basics**
- How to write components (e.g. SFCs with `<script setup>`, standalone components, function components with hooks).
- Preferred template/JSX syntax (e.g. v-if/v-for, @if/@for, conditional rendering patterns).
- Data binding and state (e.g. ref/reactive, signals, useState).
- Where to put shared logic (composables, hooks, services, inject()).
- Include 1–2 short code examples for the main patterns.
3. **UI library (if used)**
- How to import components (per-component imports vs barrel imports).
- List the most used components with minimal usage snippets: buttons, cards, form inputs, feedback (messages/toast), icons.
- How icons work (e.g. PrimeIcons class names, mat-icon, icon component).
- Where theme is configured and that it should not be changed unless required.
- Reference `supernova/icons.md` if that file exists.
4. **Code style**
- Naming: components, files, services/hooks/composables, selectors if relevant.
- TypeScript: strict typing, interfaces, avoid `any`, prefer const.
- Styling: scoped styles, layout (flex/grid), spacing (e.g. gap), theming (e.g. CSS variables).
5. **File structure**
- A short tree of `src/` showing: entry component, main config, global styles, components/, services/, lib/ (or equivalent), and a one-line comment for the file where AI should generate code.
6. **Important notes**
- Numbered list of 5–7 critical reminders, including:
- Where AI-generated code should be placed (the entry file above).
- One or two framework-specific must-dos (e.g. "Use Composition API only", "Use standalone components only", "Use hooks only").
- One or two UI library must-dos (e.g. how to import components, how to use toast/icons).
- Any app-level setup that must exist (e.g. Toast in App.vue, provideAnimations(), Zone.js).
Write the content in Markdown with clear headings and short code blocks. Match the tone and level of detail of a “Supernova Agent Rules” usage doc: concise, rule-oriented, with copy-pasteable examples for the stack we actually use in this repo.
How to use this prompt:
- Fill in the bracketed bits (framework, UI library, entry file, theme, critical libs)
- Run the prompt in the project (so the AI can read package.json, main.ts/main.tsx, and key components)
- Review and tweak the generated supernova/usage.md (add project-specific rules or remove unused UI components)
- Keep supernova/icons.md in sync if they reference it from usage.md.
Learn more about how to make the instructions for AI work best:
Upload to Supernova
- Verify the template runs correctly using npm run dev
- Make sure Docker is installed and running locally in the background
- Install Supernova CLI
npm i -g @supernovaio/cli
4. Login to Supernova through the CLI
supernova login
5. Run this command from your template directory to upload your container, using your workspaceId and designSystemId:
supernova template-upload -w [WORKSPACE_ID] -d [DESIGN_SYSTEM_ID]
Options
|
Flag |
Alias |
Description |
Required |
|---|---|---|---|
|
--workspaceId |
-w |
ID of the workspace to upload to. |
Yes |
|
--designSystemId |
-d |
ID of the design system to attach the template to. |
Yes |
|
--force |
-f |
Force upload to the same version, overwriting existing template. |
No |
Example
supernova template-upload -w 332 -d 34142
Obtaining IDs
Get both IDs from your browser URL when viewing your design system:
https://app.supernova.io/[WORKSPACE_ID]-[WORKSPACE_NAME]/ds/[DESIGN_SYSTEM_ID]-[DESIGN_SYSTEM_NAME]/...
After uploading
- In Supernova, go to Workspace Settings, and then open Prototyping contexts.
- Create new Shared context.
- Select your container and version from the dropdown.
- Publish the Shared context to your workspace.
Projects using this Shared context will now generate features with your custom components.
Learn more about uploading container to Supernova:
Prototyping with your components
Now you can go to Portal Create, select shared context you’ve created that uses your code container and generate prototypes using with your custom components.
Read more about it in our Learn documentation:
