create-quarkui-app

Official CLI scaffolder for QuarkUI applications — Angular 21, Keycloak SSO, Module Federation, and the full @quarkui component suite.

Quick Start

npx create-quarkui-app my-app

That's it. The interactive wizard handles everything else.

Prerequisites

| Tool | Minimum Version | | ------- | --------------- | | Node.js | 18.x | | npm | 10.x | | Git | 2.x |

No other global installs required. npx downloads and runs the CLI automatically.

One-Time Setup (First Run Only)

On the very first run, the CLI detects that @quarkui packages are not yet configured on your machine and guides you through it automatically:

⚠  @quarkui registry not configured on this machine.

   Get a token at: https://gitlab.bracits.com/-/user_settings/personal_access_tokens
   Required scope: read_package_registry

✔ Paste your GitLab Personal Access Token: ••••••••••••••

✅ Registry configured and saved to ~/.npmrc

How to get the token:

1. Go to GitLab → Profile → Access Tokens
2. Click "Add new token"
3. Name: quarkui-npm (or anything you like)
4. Expiry: set as needed
5. Scope: ✅ read_package_registry
6. Click "Create personal access token" → copy the token
7. Paste it when the CLI prompts you

From the second run onwards, this step is skipped entirely.

Application Types

The CLI supports 6 application types across two panel categories:

Panel Type
├── 🛡  Admin Panel
│   ├── Regular           — standalone back-office app (sidebar nav)
│   ├── MFE Host          — shell that loads remote micro-frontends
│   └── MFE Remote        — feature app exposed to a host shell
│
└── 🛍  Consumer Panel
    ├── Regular           — standalone end-user portal (top nav)
    ├── MFE Host          — shell that loads remote micro-frontends
    └── MFE Remote        — feature app exposed to a host shell

Interactive Wizard

Run the command and follow the prompts:

npx create-quarkui-app my-app

Step-by-step

 ██████╗ ██╗   ██╗ █████╗ ██████╗ ██╗  ██╗██╗   ██╗██╗
 ...
 App Scaffolder — v0.2.0

✔ Panel type:
  ❯ 🛡  Admin Panel    — back-office, management tools
    🛍  Consumer Panel — public-facing, end-user portal

✔ Application type:
  ❯ 📄  Regular          — standalone Angular app
    🔗  MFE (Micro Frontend) — module federation

✔ App display name:  › My App
✔ API base URL:      › https://api.mycompany.com
✔ Keycloak URL:      › https://auth.mycompany.com
✔ Keycloak realm:    › my-realm
✔ Keycloak client ID:› my-client

🚀 Creating my-app  [admin-regular]

  Copying template...              ✓
  Writing configuration...         ✓
  Initializing git repository...   ✓

  Installing dependencies...
  (npm install output...)

🎉 Success! Created my-app

    cd my-app
    npm start         # http://localhost:4200

MFE Host Wizard

When you select MFE → Host, you'll be asked to configure the remote apps:

npx create-quarkui-app my-shell

✔ Panel type:   Admin Panel
✔ App type:     MFE — Micro Frontend
✔ MFE role:     🏠 Host — shell app that loads remote modules

⚙  App Configuration
✔ App display name: My Shell
✔ API / Keycloak config: ...

🔗  Remote Apps Configuration

  Remote #1:
  ✔ Remote name (identifier): › hr
  ✔ Remote URL:               › http://localhost:4201
  ✔ Add another remote? › Yes

  Remote #2:
  ✔ Remote name (identifier): › finance
  ✔ Remote URL:               › http://localhost:4202
  ✔ Add another remote? › No

🎉 Success!  MFE Host — next steps:

    cd my-shell
    npm start         # serves on :4200

  Configured remotes:
    • hr      @ http://localhost:4201
    • finance  @ http://localhost:4202

  Start each remote app first, then start this host.

What gets generated:

• module-federation.config.ts — pre-configured with your remotes
• src/app/app.routes.ts — one loadChildren route per remote
• src/remotes.d.ts — TypeScript declarations for each remote module

MFE Remote Wizard

When you select MFE → Remote, you configure the remote identity:

npx create-quarkui-app my-hr-remote

✔ Panel type:   Admin Panel
✔ App type:     MFE — Micro Frontend
✔ MFE role:     📦 Remote — feature app loaded by a host

⚙  App Configuration
✔ App display name / API / Keycloak config: ...

📦  Remote Configuration
✔ Remote name (used by host to load this app): › hr
✔ Dev server port: › 4201

🎉 Success!  MFE Remote — next steps:

    cd my-hr-remote
    npm start         # serves on :4201

  Add to your host's module-federation.config.ts:
    ['hr', 'http://localhost:4201']

What gets generated:

• module-federation.config.ts — name and exposes pre-filled
• project.json — dev server port set to your chosen value
• src/app/remote-entry/entry.routes.ts — the exposed routes file

Generated Project Structures

Regular App (Admin or Consumer)

my-app/
├── environments/
│   ├── environment.base.ts        ← Keycloak + API config (your values)
│   ├── environment.development.ts
│   ├── environment.staging.ts
│   └── environment.production.ts
├── src/
│   └── app/
│       ├── core/                  ← auth guard, auth service
│       ├── features/
│       │   ├── dashboard/         ← starter feature (admin)
│       │   ├── orders/            ← starter feature (admin)
│       │   ├── home/              ← starter feature (consumer)
│       │   └── catalog/           ← starter feature (consumer)
│       ├── layouts/               ← sidebar (admin) or top-nav (consumer)
│       ├── shared/                ← interceptors, utilities
│       ├── app.config.ts          ← provideAuth, provideTheme, etc.
│       └── app.routes.ts
├── angular.json
├── tailwind.config.cjs
└── tsconfig.json

MFE Host

my-shell/
├── module-federation.config.ts    ← remote definitions (pre-configured)
├── webpack.config.ts
├── src/
│   ├── bootstrap.ts               ← actual Angular bootstrap
│   ├── main.ts                    ← async import of bootstrap
│   ├── remotes.d.ts               ← TS declarations per remote
│   └── app/
│       ├── layout/                ← admin shell layout
│       ├── app.routes.ts          ← loadChildren per remote
│       └── app.config.ts
└── project.json

MFE Remote

my-hr-remote/
├── module-federation.config.ts    ← name + exposes (pre-configured)
├── webpack.config.ts
├── src/
│   ├── bootstrap.ts
│   ├── main.ts
│   └── app/
│       ├── remote-entry/
│       │   ├── entry.routes.ts    ← exposed routes
│       │   └── entry.ts           ← entry component
│       └── app.config.ts
└── project.json

Available Scripts (in generated app)

npm start          # Dev server (http://localhost:4200 or configured port)
npm run build      # Production build
npm test           # Unit tests
npm run lint       # ESLint

Working with MFE (Full Setup Example)

1. Create the remote first:

npx create-quarkui-app my-hr-remote
# → MFE Remote, name: "hr", port: 4201
cd my-hr-remote && npm start

2. Create the host shell:

npx create-quarkui-app my-shell
# → MFE Host, add remote: name "hr" @ http://localhost:4201
cd my-shell && npm start

3. Navigate to the remote route in the host:

http://localhost:4200/hr   ← loads the hr remote module

For Workspace Maintainers (Nx)

Sync templates from submodules

When source repos (bracit-fep-admin-starter, quarkui-mfe-host, quarkui-mfe-remote) are updated:

# Pull latest submodule changes
git submodule update --remote --merge

# Re-sync templates into the CLI bundle
nx run create-quarkui-app:sync-template

# Bump version and publish
nx release --projects=create-quarkui-app

Publish to npm

# First time — make sure you're logged in to npmjs.com
npm login

# Publish
nx run create-quarkui-app:publish
# or directly:
cd quarkui/create-quarkui-app && npm publish --access public

Test locally without publishing

# Run the CLI directly from source
node quarkui/create-quarkui-app/bin/index.js my-test-app

# Or link it globally for testing
cd quarkui/create-quarkui-app && npm link
create-quarkui-app my-test-app

Troubleshooting

@quarkui packages fail to install after scaffolding

Your ~/.npmrc token may be expired. Create a new GitLab PAT and update:

# Remove the old entry manually from ~/.npmrc, then run:
npx create-quarkui-app dummy-test
# The wizard will re-prompt for your token

Template not found error

Template "admin-regular" not found. Run: nx run create-quarkui-app:sync-template

This means the templates/ directory is missing (e.g. in a fresh clone). Run:

git submodule update --init --recursive
nx run create-quarkui-app:sync-template

MFE remote module not loading in host

Ensure:

1. The remote app is running (npm start in the remote project)
2. The remote URL in module-federation.config.ts matches the remote's actual port
3. Both apps are using compatible Angular and @nx/module-federation versions

License

ISC © BracIT