@inovus-medical/create-app

Provision a new Inovus app from the GitHub template: clone at a pinned git ref, stamp identity, write .env, and optionally install allowlisted add-ons. Analogous to create-vite — this package is the CLI, not the app.

It does not generate routes, menus, or SQL migrations, and it does not delete example pages when you skip a questionnaire group. Skipped groups simply omit those env keys.

Requirements · Usage · Flags · How it works · Publishing · Contributing

npx @inovus-medical/create-app my-app
npm create @inovus-medical/app my-app

Requirements

| Tool | Why | |---|---| | Node.js ^20.19.0 \|\| >=22.12.0 | Same engines as the app template | | GitHub CLI (gh auth login) | Copies the (usually private) template with your session | | git | Initialises the new app when using --no-repo | | npm access to org.inovus.* | npm install after clone |

The CLI never bakes in a token. Private templates are fine: this package can be public; GitHub auth of the developer unlocks the template.

Template source

Default: inovus-ltd/app-template (https://github.com/inovus-ltd/app-template.git)

That is only a fallback. Override it without changing this package:

| Override | Example | |---|---| | --template owner/repo | --template acme/app-template | | --template <git-url> | --template https://github.com/inovus-ltd/app-template.git | | --template <local path> | --template ./path/to/template (requires --no-repo) | | --branch / --tag | --branch next or --tag v1.2.0 | | CREATE_APP_TEMPLATE | Same values as --template | | CREATE_APP_REF | Same values as --branch / --tag |

Flags win over environment variables. This package never vendors the app source.

New apps are created under a GitHub org or user you choose. The first question is Where should the new GitHub repo be created? Company org inovus-ltd is listed first (and is the --yes / CREATE_APP_OWNER default). Your personal account is an option, not the default. --owner login skips the prompt.

--branch / --tag clones that git ref and writes it to TEMPLATE_VERSION. Without a ref, the installer uses the latest semver tag on the template (or the default branch if no tags exist). GitHub’s --template API is never used, so installs can be pinned to a tag. The clone is pushed to a new private repo (unless --no-repo).

Manual equivalent for default-branch template copy (does not pin a tag):

gh repo create inovus-ltd/my-app --template inovus-ltd/app-template --private --clone

The CLI does not use that path; it always clones an explicit ref.

Usage

npx @inovus-medical/create-app my-app
npx @inovus-medical/create-app my-app --yes
npx @inovus-medical/create-app my-app --tag v1.2.0
npx @inovus-medical/create-app my-app --owner inovus-ltd
npx @inovus-medical/create-app ./apps/theatre-log --name theatre-log --no-repo

--yes derives the HTML title from the slug (my-app → My App) and skips confirm groups so it cannot invent Supabase URLs.

Flags

| Flag | Meaning | |---|---| | --template source | GitHub owner/repo, git URL, or local path | | --owner login | GitHub org or user for the new repo (prompted; default inovus-ltd) | | --branch / --tag ref | Git ref to clone (default: latest semver tag, or default branch) | | --yes | Non-interactive identity; skip optional confirm groups and add-ons | | --no-repo | Local folder only; do not gh repo create | | --name slug | Override package name / NAVIGATION_SOURCE | | --skip-group id | Skip that questionnaire group (repeatable) | | --manifest path | Extra groups JSON concatenated after the template’s | | -h, --help | Show help |

--no-repo clones (or copies a local / file:// path) then runs git init so origin does not point at the template.

The slug must be a legal npm name: lowercase, start with a letter, then [a-z0-9-]*.

How it works

1. Parse <dir> and flags.
2. Ask which GitHub org or user should own the new repo (unless --owner, --yes, or --no-repo). Clone inovus-ltd/app-template at the chosen git ref and write TEMPLATE_VERSION.
3. Create an empty private GitHub repo and push the clone (unless --no-repo).
4. Read <dir>/create-app.manifest.json. If it is missing, stamp identity only and write no .env.
5. Prompt for display name and description (or derive them with --yes).
6. Walk env groups in order. Confirm no skips nested env keys.
7. Stamp identity files and write .env from answered keys only.
8. Read <dir>/addons.manifest.json. If present, show grouped checkboxes and npm install only allowlisted packages. Copy each package’s instructions to .inovus/addons/<id>/AGENTS.md and write .inovus/TELL_YOUR_AGENT.md. Missing file → skip silently (old templates).
9. Root npm install if no add-on install already ran.
10. Print next steps: cd into the app, checklist, npm run dev, npm run verify, and paste .inovus/TELL_YOUR_AGENT.md when add-ons were selected.

The installer never edits App.tsx, routes, menus, or other application source.

What it stamps

Driven by identity in the template manifest:

| Field | File | |---|---| | Package name / version | package.json | | <title> and <meta name="description"> | index.html | | NAVIGATION_SOURCE | src/utils/baseUrl.ts |

It does not rewrite README.md, favicon, MENU_ITEMS, or example pages.

Questionnaire

Questions live in the template repo’s create-app.manifest.json (the CLI reads the copy it just cloned). The file at the root of this repository is the example/fixture tests honour — keep the template in sync so npx users see the same wording.

Nothing in groups is required. No (or skip) only omits those env keys; the example app code still ships.

| Group | What it is for | Typical answer | |---|---|---| | supabase | This app’s own Supabase project (URL + anon key). | Skip until you have a project. | | apiProxy | Optional override for local /api. Default No = production https://totum.surgery (no URL to type). Yes = only if you already know a staging Totum https://… URL. Does not change production deploys. | No, unless you have a staging host. | | analytics | This app’s own Google Analytics property. | Skip unless you have a dedicated G- ID. | | seats | Only people with a paid seat (Stripe product + Cognito group) can use the app. | Skip for tools anyone in the org may open. | | feedback | Custom URL for the in-app feedback widget. | Skip to keep the template default. | | notifications | Inovus Notifications V2 inbox (NOTIFICATIONS_* keys, not VITE_*). | Skip unless you want the header bell. |

v1 group types: confirm, select, text. New product setup is a new group in that manifest, not a new function here.

.env is gitignored. Never commit it. Env names must be VITE_* or NOTIFICATIONS_* (never rewrite NOTIFICATIONS_API_KEY into a VITE_ key). Names containing SERVICE_ROLE or SECRET are rejected.

After it finishes

1. cd into the new app directory
2. docs/NEW_APP_CHECKLIST.md — pages, menus, and migrations stay manual
3. npm run dev
4. npm run verify

npm install errors

| Symptom | What to do | |---|---| | 404 on org.inovus.unified-auth | npm login to the registry that hosts org.inovus.* packages | | Missing inovusmedical-org-switcher-*.tgz | The tarball must be committed in the template repo |

Development

npm install
npm test
npm run test:coverage
npm run build

Coverage thresholds are enforced in CI (see .github/workflows/ci.yml). Publishing is documented in docs/PUBLISHING.md.

License

Copyright © 2026 Inovus Ltd. All rights reserved. Proprietary / closed source.