Nuxt App Generator (@tgmc/likwidlibs:nuxt-app)
Nx workspace generator to scaffold enterprise-grade Nuxt 4 applications in the @tgmc monorepo.
Usage
npx nx g @tgmc/likwidlibs:nuxt-app <app-name> [options]
Or run interactively:
npx nx g @tgmc/likwidlibs:nuxt-app
Options
| Option | Type | Default | Description |
|---|---|---|---|
name |
string |
(prompted) | Name of the application (e.g., portal, docs, store). |
directory |
string |
core |
Target directory relative to monorepo root. |
deploymentTarget |
string |
aws-sam |
Target CD workflow: aws-sam, docker-node, or static-cloudflare. |
ui |
boolean |
true (prompted) |
Extend @tgmc/nuxt-layer-ui (the Ui* kit) instead of @tgmc/nuxt-layer-base. |
theme |
boolean |
true (prompted) |
Use the @tgmc/theme stylesheet and Sass; off uses the system-colour fallback. |
icons |
boolean |
true (prompted) |
Install @nuxt/icon with Lucide. |
primevue |
boolean |
see below | PrimeVue behind the Ui* kit. ui and theme apps only; asked in an interactive nx g when omitted, else true. |
media |
boolean |
see below | Register the media components. ui apps only; asked in an interactive nx g when omitted, else true. |
includeE2e |
boolean |
true |
Whether to scaffold a companion Cypress a11y E2E test project (core/<name>-e2e). |
Nx prompts can’t depend on an earlier answer, and a schema default would hide whether the user passed a flag, so primevue and media have neither a prompt nor a default in the schema. The generator asks for them itself, only when they apply (a base-only app gets neither; a theme-off app gets no PrimeVue) and only in an interactive terminal (NX_INTERACTIVE=true and a TTY). Non-interactive runs (--no-interactive, CI) never prompt; pass --primevue / --media explicitly, or they default to on. --primevue or --media with --no-ui, and --primevue with --no-theme, fail with an error.
What Gets Scaffolded
- Nuxt 4 Application (
core/<name>):- Extends
@tgmc/nuxt-layer-ui(or@tgmc/nuxt-layer-basewith--no-ui) and writes atgmc:block with the chosen features (theme,icon, and for ui appsprimevueandmedia; see nuxt-layers.md § 1a). The base layer addsnitro.externals.inline: ['nuxt'], which a Nuxt 4.6 app needs to render. package.jsonlists only the chosen features’ packages, with the root’s ranges:@tgmc/theme;@nuxt/iconand@iconify-json/lucide;primevueand@primevue/nuxt-module;@tgmc/media-clientand@tgmc/media-player.- Pug layout shell (
app/app.vue):<UiSkipLink />first, landmark regions,main#main-contentwithtabindex="-1", and<UiAnnouncer />, both from the base layer. ui apps also mount<UiToastHost />(PrimeVue’s toast, or the native list without PrimeVue). - Example landing page (
app/pages/index.vue, Pug) using the contrast roles (--theme-primary-fill-colorand--theme-on-primary-color),--touch-target, the themefocus-ringmixin anduseA11yAnnouncer(). - With icons,
nuxt.config.tshas an emptyicon.clientBundle.iconsfor the app’s own Lucide names; the shared ones come fromTGMC_BASE_ICONS. Without icons there is noiconblock. - In-app axe-core accessibility test (
tests/a11y.spec.ts, Vitest + jsdom, WCAG 2.0, 2.1 and 2.2 A/AA tags); the generator’s smoke spec runs it, ESLint and the E2E type-check on every generator test run. - ESM
eslint.config.json@nuxt/eslint-config/flatwitheslint-plugin-vue-pug, and boundary rules guarding against@tgmc/utilities/browserimports in SSR code. - App
.gitignore(.nuxt,.output,.data,dist,node_modules,coverage, logs,.env*except.env.example).@nuxt/eslint-configreads the nearest.gitignore, so the app’s own file keeps lint scoped to the app. - Nx targets are inferred from
package.jsonscripts and the config files (nuxt.config.ts,vitest.config.ts,eslint.config.js) — noproject.json, like every project in this repo. Tags live inpackage.json→nx.tags.
- Extends
- Companion E2E Suite (
core/<name>-e2e) (optional): an ESM package ("type": "module") whosepackage.jsondeclaresnx.implicitDependencies: ["@tgmc/<name>"]and the samee2etarget ascore/web-e2e.- Cypress 15 with axe-core injected by a
cy.runAxe()command (src/support/e2e.ts) — no extra Cypress plugins. - Landing-page WCAG 2.2 AA audit and a keyboard check with
cy.press(Cypress.Keyboard.Keys.TAB)(src/e2e/a11y-audit.cy.ts).
- Cypress 15 with axe-core injected by a
- Continuous Deployment (
.github/workflows/<name>-cd*.yml), bydeploymentTarget:aws-sam(default): mirrorscd-aws.yml/cd-aws-prod.yml(cicd.md).<name>-cd.ymlruns adeployable-gatejob (is@tgmc/<name>affected?) and thendeploy-testin thetestEnvironment (environment-scopedAWS_ROLE_ARNfor OIDC):npm run build:libs, Nitroaws_lambdabuild,sam deployof the generatedcore/<name>/infra/template.yaml(Stage=test) and a smoke GET of theHttpApiUrloutput.<name>-cd-prod.ymldeploysStage=productionon a published (non-prerelease) Release or aconfirm=deploydispatch in theproductionEnvironment. The SAM stack is Lambda + HTTP API only; assets are inlined (serveStatic: 'inline').docker-node: containerized Nitro node-server build with GitHub Container Registry publish (addcore/<name>/Dockerfileyourself).static-cloudflare: static pre-rendering vianuxt generateand Cloudflare Pages deployment.- Every job sets
HUSKY: '0'(repo CI policy).
Development
- Tests:
cd packages/likwidlibs && npx vitest run tests/generators/nuxt-app(4 files, 37 tests).features.spec.ts: feature resolution (what is asked when, flags the user passed, the combinations that can’t build) and the feature dependency lists.nuxt-app.spec.ts: the generated files for the full and the minimal app (ui,themeandiconsoff), with snapshots, plus the E2E project, workflows and SAM template.- The generator ends with Nx
formatFiles, which formats with the target workspace’s Prettier config (here the root.prettierrc: print width 120, organize-imports and Pug plugins). The test tree’s root is/virtual, so no config is found there, and since Nx 23createTreeWithEmptyWorkspace()seeds.oxfmtrc.jsoninstead of.prettierrc, which turns Prettier off. The spec therefore builds the tree with{ formatter: 'prettier' }and writes the pinnedWORKSPACE_PRETTIERoptions as the tree’s.prettierrc; a guard test fails if they drift from the root.prettierrc, and another checks the output is formatted at 120. After a deliberate Prettier change, update the constant and re-run with-u.
- The generator ends with Nx
nuxt-app.smoke.spec.ts: writes the full and the minimal app under the git-ignoredtmp/and runs each app’s a11y spec, ESLint and the E2E type-check.layer-base.spec.ts: any name the base layer auto-imports from@tgmc/utilities/universalreally exists there.