Falcon micro-app kit

Builds an Angular app that renders inside the Falcon shell as its own route, and switches it on for you — it registers the app in your Falcon checkout's manifests, so there is nothing to paste. No Falcon source code is touched.

Run it

From any folder, on any machine with Node 20.19+:

npx @t2falcon/create-falcon-app

That downloads the kit from npm, runs it in the current folder, and leaves nothing behind but the app it creates.

Working from the zip instead (no npm access, or someone handed you the file) — unzip it, then:

macOS / Linux:

./create-falcon-app.sh

Windows — double-click create-falcon-app.cmd, or from a terminal:

create-falcon-app.cmd

PowerShell, if the execution policy blocks the .ps1:

powershell -ExecutionPolicy Bypass -File .\create-falcon-app.ps1

Either way it asks a handful of questions, then checks your machine, writes the app, installs, builds, starts it, and prints the manifest entry to paste into Falcon. First run takes a few minutes, almost all of it npm install.

The thing you actually need: registration

Step 7 finds your Falcon checkout, shows you the path, and asks before writing. On yes it merges this app's entry into all five manifests under apps/host-shell/src/assets/, as a sibling of the existing "admin-console" key. Falcon reads those at runtime, so nothing is rebuilt — start the shell and your route is there.

Re-running is safe: an app that is already registered is updated in place, never duplicated, so changing the port and re-running just works.

It writes nothing outside that assets folder — those are uncommitted changes in your checkout, so commit or revert them like any other edit.

The step is required: an app that builds but is never registered is invisible in Falcon, with nothing on screen to say so, so the prompt repeats until it has a checkout to write to. Several clones on one machine are listed with their manifest count and last-worked-in date so you can tell them apart. --falcon-dir <path> names one outright; --no-register is the deliberate way out on a machine with no checkout at all, and prints the entry to paste instead.

⚠️ Before pasting, skim the keys already in the file. If your app's name matches one of them you will create a duplicate key: JSON allows it, the last one silently wins, and the result is confusing. Rename the app, or the key, if it collides.

You need Node 20.19 or newer (Node 22 is what Falcon's own builds use) and an internet connection — the app installs Angular and the @t2falcon/* Falcon packages from npmjs.com. A kit built with --with-vendor also carries the Falcon packages as tarballs for --offline runs.

Options

| Flag | Effect | |---|---| | --yes | Accept every default, ask nothing. | | --dir <path> | Where to generate. | | --name <name> | App name — becomes the folder, route and sidebar label. | | --route <path> | The route the app lives at in Falcon (/#/<path>). Also changes it on a re-run — the one saved answer --yes would otherwise fossilise. | | --port <n> | Dev server port. Default 4320; a busy port prompts for another. | | --no-serve | Set up and build, but do not start the server. | | --falcon-dir <path> | Your Falcon checkout, when auto-detection cannot find it. | | --install-agent | Install the Claude agent into ~/.claude/skills and exit. Then anyone can describe an app to Claude instead of running this. --agent-dir <path> overrides the location. | | --no-register | Do not write into the Falcon checkout; print the entry to paste instead. Registration is otherwise required. | | --force-register | Replace an entry already registered under this name by a different app. | | --refresh | Take the kit's current template for every generated file, discarding edits you made to them. Files of your own are never touched. | | --offline | Install the Falcon packages from the kit's bundled vendor/ tarballs instead of npm (needs a --with-vendor kit build). | | --registry <url> | Install the Falcon packages from a custom npm registry. | | --reconfigure | Re-ask the questions for a folder that already has an app in it. | | --config <file> | Replay a saved falcon.config.json. |

Re-running into the same folder upgrades: it reads falcon.config.json, skips the interview, and compares every file against the hash recorded when the kit wrote it. Untouched files are brought up to date with the current template (including deleting ones the template no longer ships); files you edited are kept and listed, with --refresh as the override. Your own new files are invisible to all of this.

What you get

An Angular 21 Module Federation remote with two working pages — a WhatsApp template list and an IVR flow list — built from Falcon components on seeded data, styled entirely with Tailwind utilities over the Falcon theme tokens, with a facade-pattern data layer (port + mock API + signal state per page) ready to swap for real endpoints.

The app's own README.md and AGENTS.md explain the pieces and, more usefully, the handful of rules that fail silently if broken.

What is in the box

create-falcon-app.sh / .cmd / .ps1   launchers — they check Node, then hand over
bin/cli.mjs                          the seven steps
lib/                                 one module per step
template/                            the app that gets written
packages.json                        which @t2falcon/* versions the app installs
vendor/                              (only in --with-vendor builds) the packages as tarballs

The packages are published to npm as @t2falcon/* — the Falcon design system under a scope T2 owns, because @falcon on npmjs.com belongs to someone else.

When something goes wrong

Every step explains its own failure — the likely cause, the exact command to fix it, and a retry / skip / abort choice. Nothing exits on the first error.

The two worth knowing in advance:

• npm install fails — usually no internet or a proxy. npm ping tells you which.
• The route shows /#/401 in Falcon — you asked for access control, and no PES rule grants that resource yet. The kit prints the seeding commands. ?visual-test=1 on the URL bypasses the guard for that browser tab if you just want to look at the page.

Rebuilding this kit

For Falcon maintainers, from a falcon-web-platform-ui checkout:

node tools/falcon-microapp-kit/build-kit.mjs

That stages the packages, assembles dist/falcon-microapp-kit/ (which is also the npm package @t2falcon/create-falcon-app), and zips it. Publishing all seven is node tools/falcon-microapp-kit/publish-packages.mjs — dry run by default.