Skip to content

Commit 908df35

Browse files
Marina-L-StoyanovaMarina-L-Stoyanova
committed
feat: add ignite-ui-cli skill and command reference documentation
1 parent 64f2735 commit 908df35

2 files changed

Lines changed: 390 additions & 0 deletions

File tree

‎skills/ignite-ui-cli-skill.md‎

Lines changed: 139 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,139 @@
1+
---
2+
name: Ignite UI CLI Scaffolding & Component Architect
3+
description: Use when the user wants to scaffold an Ignite UI project, add components, serve, build, test, upgrade packages, or asks about ig CLI, igx, igr, Ignite UI, or Infragistics. Do NOT use for general Angular/React questions unrelated to Ignite UI.
4+
---
5+
6+
## Role
7+
You are the **Ignite UI Architect**. Guide developers using the `ig` CLI to build enterprise-grade UIs. Always prefer CLI commands over manual file creation. Consult `skills/reference/commands.md` for full command options and template tables.
8+
9+
---
10+
11+
## Non-Negotiable Rules
12+
13+
1. **Always run `ig list` before `ig add`** — never assume a templateId. They change between versions.
14+
2. **Never run `ig add` outside a project folder** — confirm the user is inside an `ig new`-created project first.
15+
3. **Quickstart (step-by-step) projects do NOT support `ig add`** — warn the user before attempting.
16+
4. **Never hardcode ports** — tell the user to check `ig start` output for the actual URL.
17+
5. **Always remind the user to remove `fake-backend.service.ts` before any deployment** when using `--template=side-nav-auth`.
18+
19+
---
20+
21+
## Workflow
22+
23+
Always follow this order:
24+
25+
```bash
26+
ig list # 1. verify templateId
27+
ig new "AppName" [options] # 2. scaffold project
28+
cd AppName
29+
ig add <templateId> <Name> # 3. generate component
30+
ig start # 4. build + serve
31+
```
32+
33+
---
34+
35+
## Command Cheat Sheet
36+
37+
| Command | Purpose |
38+
|---------|---------|
39+
| `ig` / `ig new` | Interactive wizard OR non-interactive scaffold |
40+
| `ig add <id> <name>` | Generate component with auto-wired routing/modules |
41+
| `ig list` | List available templates for current project |
42+
| `ig start [--port=N]` | Build + serve + open in browser |
43+
| `ig build` | Compile only |
44+
| `ig test` | Run test suite |
45+
| `ig config get/set/add` | Read/write `ignite-ui-cli.json` config |
46+
| `ig doc <term>` | Open Infragistics docs search in browser |
47+
| `ig generate` | Create a custom component template |
48+
| `ig help` | List all available commands |
49+
50+
> Full syntax, flags, and template tables → `skills/reference/commands.md`
51+
52+
---
53+
54+
## Error Recovery
55+
56+
| Symptom | Likely Cause | Fix |
57+
|---------|-------------|-----|
58+
| `ig add` does nothing | Not inside a project folder | `cd` into the project root |
59+
| Component missing from nav | `--skip-route` was used | Manually add route to `app-routing.module.ts` |
60+
| 403/404 on build | Missing Infragistics licensed account | Log in or switch to OSS packages |
61+
| Port already in use | Conflict on default port | `ig start --port=4201` |
62+
| Prompts don't render | Unsupported terminal (Inquirer.js) | Use Windows Terminal, iTerm2, or VS Code terminal |
63+
| Module not found after `ig add` | Wrong Angular module path | Use `--module=path/to/module.ts` relative to `/src/app/` |
64+
65+
---
66+
67+
## Authentication Template (Angular Only)
68+
69+
When the user wants login/signup out of the box:
70+
71+
```bash
72+
ig new "MyApp" --framework=angular --type=igx-ts --template=side-nav-auth
73+
```
74+
75+
Includes: login/signup dialogs, JWT `AuthenticationService`, `AuthGuard`, `UserService`, and optional Google/Microsoft/Facebook provider stubs.
76+
77+
**Always tell the user:**
78+
- Remove `fake-backend.service.ts` before any deployment
79+
- JWT in localStorage is XSS-vulnerable — use HttpOnly cookies in production
80+
- Uncomment the desired provider in `app.module.ts` and supply a real `<CLIENT_ID>`
81+
82+
> Full file structure and production checklist → `skills/reference/commands.md`
83+
84+
---
85+
86+
## Upgrading
87+
88+
```bash
89+
npm install -g igniteui-cli # update CLI globally
90+
ng update igniteui-angular # update Ignite UI for Angular
91+
ng g @igniteui/angular-schematics:upgrade-packages # trial → licensed migration
92+
```
93+
94+
Warn users: the upgrade schematic rewrites sources to `packages.infragistics.com`. A licensed Infragistics account is required — trial accounts get 403 errors.
95+
96+
---
97+
98+
## Prerequisites (Share on First Setup)
99+
100+
```
101+
✅ Node.js LTS (v20.x) → node --version
102+
✅ npm → npm --version
103+
✅ igniteui-cli → npm install -g igniteui-cli
104+
✅ Git (optional) → ig new auto-inits a repo; skip with --skip-git
105+
✅ Infragistics account → only needed for licensed/Grid components
106+
```
107+
108+
> macOS install failure? Run: `sudo xcode-select --install`
109+
110+
---
111+
112+
## Examples
113+
114+
**"Create a new Angular app with a hierarchical grid"**
115+
```bash
116+
ig new "Dashboard" --framework=angular --type=igx-ts --template=side-nav
117+
cd Dashboard
118+
ig list # confirm: hierarchical-grid templateId
119+
ig add hierarchical-grid MainGrid
120+
ig start
121+
```
122+
123+
**"Add a category chart to my existing React app"**
124+
```bash
125+
ig list # confirm: category-chart templateId
126+
ig add category-chart SalesChart
127+
```
128+
129+
**"Set up Angular with login out of the box"**
130+
```bash
131+
ig new "MyApp" --framework=angular --type=igx-ts --template=side-nav-auth
132+
# Remember: remove fake-backend.service.ts before deploying
133+
```
134+
135+
**"Upgrade my project from trial to licensed packages"**
136+
```bash
137+
ng g @igniteui/angular-schematics:upgrade-packages
138+
# Will prompt for Infragistics credentials
139+
```

‎skills/reference/commands.md‎

Lines changed: 251 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,251 @@
1+
# Ignite UI CLI — Command Reference
2+
3+
> **When to consult this file:** The skill (`ignite-ui-cli-skill.md`) covers rules, workflow, and quick syntax. Come here when you need the full flag list for a command, the complete template ID tables, port defaults, the auth file structure, or the production checklist. This file is reference material — not behavioral instructions.
4+
5+
---
6+
7+
## `ig new` — Full Syntax
8+
9+
Creates a new project with Ignite UI infrastructure pre-configured and dependencies installed.
10+
11+
```bash
12+
ig new "<AppName>" --framework=<f> --type=<t> --template=<tmpl> --theme=<theme>
13+
```
14+
15+
### Framework + Type Combinations
16+
17+
| Framework | Type | Notes |
18+
|-----------|------|-------|
19+
| Angular | `igx-ts` | Ignite UI for Angular — standalone components (v13.1.0+) |
20+
| Angular | `igx-ts-legacy` | Ignite UI for Angular — module-based bootstrapping |
21+
| Angular | `ig-ts` | Ignite UI Angular JS Wrappers |
22+
| React | `igr-es6` | Ignite UI for React (native components) |
23+
| React | `ig-ts` | Ignite UI jQuery React Wrappers |
24+
| jQuery | `js` | Default — `--type` not required |
25+
26+
### Templates
27+
28+
| Value | Description |
29+
|-------|-------------|
30+
| `side-nav` | Side navigation shell (default) |
31+
| `navbar` | Top navigation bar shell |
32+
| `base` | Minimal blank app |
33+
| `side-nav-auth` | Side nav + full auth module (Angular igx-ts only) |
34+
35+
### All Flags
36+
37+
| Flag | Notes |
38+
|------|-------|
39+
| `--framework` / `-f` | `angular`, `react`, `jquery` |
40+
| `--type` / `-t` | See table above |
41+
| `--template` | See table above |
42+
| `--theme` | `default`, `dark`, `fluent` |
43+
| `--skip-install` | Skip automatic npm install |
44+
| `--skip-git` | Skip Git repository initialization |
45+
46+
---
47+
48+
## `ig add` — Full Syntax
49+
50+
Generates a component and automatically integrates it into routing and module systems. Must be run inside an existing project created with `ig new` or via `ng add igniteui-angular`. Quickstart (step-by-step) projects do NOT support this command.
51+
52+
```bash
53+
ig add <templateId> <ComponentName> [options]
54+
```
55+
56+
### Flags
57+
58+
| Flag | Version | Notes |
59+
|------|---------|-------|
60+
| `--module` / `-m` | v2.0.0 | Angular only. Path to `.module.ts` relative to `/src/app/` |
61+
| `--skip-route` / `-srk` | v3.2.0 | Suppress auto-generating a navigation route |
62+
63+
### Example with flags
64+
65+
```bash
66+
ig add grid AdminGrid --module=admin/admin.module.ts --skip-route
67+
```
68+
69+
---
70+
71+
## `ig list` — Usage
72+
73+
Lists all available templates for the current project's framework and type. Always run before `ig add` — the tables below may lag behind new releases, but `ig list` is always current.
74+
75+
```bash
76+
ig list # inside a project — uses project's framework
77+
ig list --framework=angular --type=igx-ts
78+
ig list -f react
79+
ig l # alias
80+
```
81+
82+
When run inside a project folder, the project's framework takes precedence over any flags passed.
83+
84+
> ⚠️ Always run `ig list` to confirm templateIds.
85+
86+
---
87+
88+
## `ig start` — Serve & Default Ports
89+
90+
Builds the application, starts a web server, and opens it in the default browser.
91+
92+
```bash
93+
ig start
94+
ig start --port=1234
95+
ig start -p=1234
96+
```
97+
98+
| Framework | Type | Default URL |
99+
|-----------|------|-------------|
100+
| Angular | `igx-ts` | http://localhost:4200/ |
101+
| Angular | `ig-ts` (Wrappers) | http://localhost:3001/ |
102+
| React | `igr-es6` | http://localhost:3000/ |
103+
| React | `ig-ts` (Wrappers) | http://localhost:3002/ |
104+
| jQuery | `js` | http://localhost:3000/ |
105+
106+
---
107+
108+
## `ig build` — Compile Only
109+
110+
Compiles the project without launching a server. Installs npm dependencies and resolves OSS vs. licensed packages — prompts for Infragistics credentials if a licensed component (e.g. Grid) is detected. Build artifacts and CSS are output to the `output/` directory.
111+
112+
```bash
113+
ig build
114+
```
115+
116+
---
117+
118+
## `ig test` — Run Tests
119+
120+
Runs the test suite for the current project using the framework's configured test environment. Supported for Angular, React, and jQuery projects.
121+
122+
```bash
123+
ig test
124+
```
125+
126+
---
127+
128+
## `ig generate` — Custom Template
129+
130+
Creates a new custom component template scaffold. Registers the template path in the global config under `customTemplates` so it becomes available via `ig list` and `ig add`.
131+
132+
```bash
133+
ig generate
134+
```
135+
136+
Runs interactively — prompts for template name, framework, and file structure.
137+
138+
---
139+
140+
## `ig doc` — Documentation Search
141+
142+
Opens the Infragistics knowledge base in the default browser for a given search term.
143+
144+
```bash
145+
ig doc igx-grid
146+
ig doc "igx-grid paging help"
147+
ig doc # prompts for a search term interactively
148+
```
149+
150+
---
151+
152+
## `ig config` — Full Syntax
153+
154+
Reads and writes CLI configuration stored in `ignite-ui-cli.json`.
155+
156+
```bash
157+
ig config get <property> [--global]
158+
ig config set <property> <value> [--global]
159+
ig config add <property> <value> [--global]
160+
```
161+
162+
- Local config: `ignite-ui-cli.json` in project root
163+
- Global config: user home directory (`~` on Unix / `C:\Users\<user>` on Windows)
164+
- Custom templates registered under `customTemplates` via `ig generate`
165+
166+
---
167+
168+
## Authentication Template — Full Detail
169+
170+
Scaffolds a full client-side auth module on top of the side-nav shell. Angular `igx-ts` only.
171+
172+
```bash
173+
ig new "MyApp" --framework=angular --type=igx-ts --template=side-nav-auth
174+
```
175+
176+
### Files Generated under `src/app/authentication/`
177+
178+
| File | Purpose |
179+
|------|---------|
180+
| `authentication.module.ts` | Exports all auth components and services |
181+
| `authentication-routing.module.ts` | Login-related routes |
182+
| `services/user.service.ts` | Current user state |
183+
| `services/authentication.service.ts` | JWT logic wired to REST endpoints |
184+
| `services/fake-backend.service.ts` | **Dev-only mock — remove before deployment** |
185+
186+
### Enable External Providers
187+
188+
Uncomment in `app.module.ts`:
189+
190+
```typescript
191+
// this.externalAuthService.addGoogle('<CLIENT_ID>');
192+
// this.externalAuthService.addMicrosoft('<CLIENT_ID>');
193+
// this.externalAuthService.addFacebook('<CLIENT_ID>');
194+
```
195+
196+
### Production Checklist
197+
198+
- [ ] Remove `fake-backend.service.ts` and its `BackendProvider` from `app.module.ts`
199+
- [ ] Replace localStorage JWT with HttpOnly cookies (localStorage is XSS-vulnerable)
200+
- [ ] Set correct redirect URLs and allowed origins in each provider's developer console
201+
- [ ] Never commit `<CLIENT_ID>` values — use environment variables
202+
203+
---
204+
205+
## Updating & Upgrading
206+
207+
### Update CLI
208+
209+
```bash
210+
npm install -g igniteui-cli # global update
211+
ng update igniteui-cli # within Angular project
212+
ng update igniteui-angular # keep in sync with @angular/core and @angular/cli
213+
```
214+
215+
### Migrate Trial → Licensed
216+
217+
```bash
218+
ng g @igniteui/angular-schematics:upgrade-packages
219+
220+
# Yarn users — skip install, then run yarn manually
221+
ng g @igniteui/angular-schematics:upgrade-packages --skip-install
222+
yarn install
223+
```
224+
225+
Rewrites package sources to `packages.infragistics.com`. Requires a **licensed** Infragistics account — trial accounts receive 403 errors.
226+
227+
---
228+
229+
## Angular Schematics Alternative
230+
231+
For Angular CLI projects not created with `ig new`:
232+
233+
```bash
234+
npm i -g @igniteui/angular-schematics
235+
ng add igniteui-angular # wire into existing project
236+
ng g @igniteui/angular-schematics:<templateId> --name=<n> # add a component
237+
ng new --collection=@igniteui/angular-schematics # new project via schematics
238+
```
239+
240+
---
241+
242+
## Step-by-Step Interactive Mode
243+
244+
Running `ig` or `ig new` without arguments launches the Inquirer.js wizard:
245+
246+
- **Arrow keys** — navigate options
247+
- **Space** — toggle features (e.g. sorting, paging on grids)
248+
- On completion: auto-installs packages, builds, and opens the app in the browser
249+
250+
Supported terminals: Windows Terminal, iTerm2, VS Code integrated terminal.
251+
Quickstart projects created this way **do not support `ig add`**.

0 commit comments

Comments
 (0)