{"id":47952645,"url":"https://github.com/bookedsolidtech/create-helix-app","last_synced_at":"2026-05-12T06:00:39.935Z","repository":{"id":346933970,"uuid":"1192198622","full_name":"bookedsolidtech/create-helix-app","owner":"bookedsolidtech","description":"Scaffold a new project with HELiX web components — npx create-helix","archived":false,"fork":false,"pushed_at":"2026-05-11T12:04:13.000Z","size":4354,"stargazers_count":1,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-11T13:32:35.902Z","etag":null,"topics":["booked-solid","cli","create-helix","design-system","drupal","helix","lit","scaffold","starter-kit","web-components"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/create-helix","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bookedsolidtech.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-26T01:35:26.000Z","updated_at":"2026-05-11T12:03:39.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/bookedsolidtech/create-helix-app","commit_stats":null,"previous_names":["bookedsolidtech/create-helix-app"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/bookedsolidtech/create-helix-app","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bookedsolidtech%2Fcreate-helix-app","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bookedsolidtech%2Fcreate-helix-app/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bookedsolidtech%2Fcreate-helix-app/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bookedsolidtech%2Fcreate-helix-app/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bookedsolidtech","download_url":"https://codeload.github.com/bookedsolidtech/create-helix-app/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bookedsolidtech%2Fcreate-helix-app/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32926039,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-11T17:09:15.040Z","status":"online","status_checked_at":"2026-05-12T02:00:06.338Z","response_time":102,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["booked-solid","cli","create-helix","design-system","drupal","helix","lit","scaffold","starter-kit","web-components"],"created_at":"2026-04-04T09:13:04.658Z","updated_at":"2026-05-12T06:00:39.929Z","avatar_url":"https://github.com/bookedsolidtech.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n\u003cimg src=\"assets/social-card.png\" alt=\"create-helix — Scaffold HELiX projects in seconds\" width=\"600\"\u003e\n\n# create-helix\n\n[![npm version](https://img.shields.io/npm/v/create-helix)](https://www.npmjs.com/package/create-helix)\n[![CI](https://img.shields.io/github/actions/workflow/status/bookedsolidtech/create-helix-app/ci.yml?branch=main\u0026label=CI\u0026logo=github)](https://github.com/bookedsolidtech/create-helix-app/actions)\n[![Coverage](https://img.shields.io/badge/coverage-70%25-brightgreen)](https://github.com/bookedsolidtech/create-helix-app/actions)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n[![Node 20+](https://img.shields.io/badge/node-%3E%3D20-brightgreen)](https://nodejs.org)\n[![TypeScript](https://img.shields.io/badge/TypeScript-strict-blue?logo=typescript)](tsconfig.json)\n\n\u003c/div\u003e\n\nScaffold a HELiX design system project in seconds. TUI-powered CLI with a **two-step starter-kit picker** — first you tell it what the project builds (`wc-storybook` design system, `react-next` app, `react-vite` app, or `drupal-theme`), then it offers to bundle a shared `design-system` package alongside. 13 additional experimental frameworks are available behind `--show-experimental`.\n\n**New in v0.8.0 — Astro joins the production-tier starter kits.** The Q1 picker now offers four production-tier targets: `wc-storybook`, `react-next`, `react-vite`, and **`astro`**. The Astro starter ships a real Astro 5 landing page (hero, features, view transitions, theme toggle, two routed pages) and consumes the design system as `\u003chx-*\u003e` web components natively — no React-wrapper indirection. The flat Astro path stays reachable via `--no-design-system` for back-compat, but the monorepo is the supported shipping target going forward. First Playwright visual baselines in the project ship under [`tests/e2e/screenshots/astro/`](./tests/e2e/screenshots/astro/).\n\n**v0.7.0 introduced monorepo by default for app frameworks.** When you pick `react-next`, `react-vite`, or now `astro` and keep the design system (the default Y at Q2), `create-helix` emits a **turbo + pnpm-workspaces monorepo** with `apps/web/` + `packages/{design-system,types,utils}/` — modeled on the shadcn `apps/web` + `packages/ui` precedent. Pass `--no-design-system` (or answer \"n\" at Q2) to keep the v0.6.x flat single-app shape. See [Monorepo by default](#monorepo-by-default-v070) and [`MIGRATING.md`](./MIGRATING.md).\n\nThe flagship `wc-storybook` template remains the default interactive selection and ships a brand-storytelling Storybook experience out of the box — Cover narrative, foundations IA (including a v0.6.0 Iconography page wired to `@helixui/icons`), per-component AAA conformance pages with auto-injected accessibility status cards, and a token-driven manager chrome that follows your brand. See [WC-Storybook brand-storytelling experience](#wc-storybook-brand-storytelling-experience) below.\n\n## Quick Start\n\n```bash\nnpx create-helix\n# or\nnpm create helix\n```\n\nFollow the interactive prompts to choose your framework, component bundles, and features.\n\n### Drupal Theme Scaffolding\n\n```bash\nnpx create-helix --drupal\n```\n\nOr pass a preset directly:\n\n```bash\nnpx create-helix --drupal --preset healthcare\n```\n\n## Supported Frameworks\n\nThe interactive prompt shows a curated slim list by default — the flagship `wc-storybook` factory plus the three production-tier app starters that have shipped beyond stub quality. The remaining 12 framework templates exist but are gated behind `--show-experimental` until they reach the same bar.\n\n| Framework                  | Command Hint                     | Features                                                                                                  |\n| -------------------------- | -------------------------------- | --------------------------------------------------------------------------------------------------------- |\n| **WC Storybook (factory)** | default — design system factory  | Lit 3, Storybook 10, brand-storytelling docs, AAA cards, Iconography page, auto-catalog ~99 hx-\\* entries |\n| **React + Next.js 16**     | recommended for new app projects | SSR, App Router, React wrappers                                                                           |\n| **React + Vite**           | best DX for SPAs                 | Hot reload, React wrappers, production landing page                                                       |\n| **Astro 5** _(new v0.8.0)_ | islands + native web components  | Landing page, view transitions, theme toggle, native `\u003chx-*\u003e` consumption, Playwright visual baseline     |\n\n### Experimental templates\n\nRun `npx create-helix --show-experimental` (or set `HELIX_SHOW_EXPERIMENTAL=1`) to surface these in the prompt, the `list` subcommand, and as valid `--template \u003cname\u003e` values:\n\n`remix`, `vue-nuxt`, `vue-vite`, `sveltekit`, `angular`, `lit-vite`, `solid-vite`, `qwik-vite`, `preact-vite`, `stencil`, `ember`, `vanilla`\n\nThese templates compile and emit a project skeleton, but their docs / examples / DX polish lag behind the curated four. They'll graduate out of `--show-experimental` as they reach the same bar.\n\n## Monorepo by default (v0.7.0+)\n\nWhen you pick an app framework (`react-next`, `react-vite`, or **`astro`** as of v0.8.0) and keep the design system at the second prompt — the **default Y** — `create-helix` emits a turbo + pnpm-workspaces monorepo:\n\n```\nmy-project/\n├── apps/\n│   └── web/                # Next.js, Vite, or Astro app\n├── packages/\n│   ├── design-system/      # Lit web components + Storybook\n│   ├── types/              # Shared TS types + brand utilities\n│   └── utils/              # Shared helpers (cn, isPresent, …)\n├── pnpm-workspace.yaml\n├── turbo.json\n├── tsconfig.base.json\n└── package.json\n```\n\n`apps/web` declares the workspace packages via `workspace:*` deps. The framework-specific wiring per starter kit:\n\n- **Next.js** carries `transpilePackages` + `experimental.externalDir`; the design system is consumed via generated React wrappers from `packages/design-system/src/react.ts`.\n- **Vite** carries `optimizeDeps.exclude` + `server.fs.allow: ['..', '../..']`; React wrappers as with Next.\n- **Astro (v0.8.0)** consumes the design system as **`\u003chx-*\u003e` web components natively** — no React wrappers, no `createComponent` indirection — because Astro's island architecture is web-component-first.\n\nRunning `pnpm dev` at the root runs `turbo run dev`, which boots both `apps/web` and `packages/design-system` Storybook (port 6006) concurrently. Default app ports: **Next.js 3000**, **Vite 5173**, **Astro 4321**.\n\nThe shape mirrors the [shadcn `apps/web` + `packages/ui` monorepo precedent](https://github.com/shadcn-ui/ui/tree/main/apps/www) — proven at scale, familiar to consumers.\n\n### Available starter-kit combinations\n\nAfter Q1 (what does this project build?) and Q2 (include design system?), the supported combinations are:\n\n- **Design system** (`wc-storybook`, flat — always flat, it _is_ the design system)\n- **Next.js + design system** (monorepo, default for Next pick)\n- **Vite + design system** (monorepo, default for Vite pick)\n- **Astro + design system** _(new v0.8.0)_ — monorepo, default for Astro pick\n\n### Opting out\n\nThree escape valves keep the v0.6.x flat single-app shape available:\n\n- **Interactive** — answer \"n\" at the \"Include design-system package?\" prompt.\n- **CLI flag** — pass `--no-design-system` (or `--monorepo=false`).\n- **API** — `scaffold({ framework: 'react-next' | 'react-vite' | 'astro', monorepoMode: false })`.\n\n`wc-storybook` always scaffolds flat — it is itself the design system, so wrapping it in a monorepo would duplicate the layer.\n\n**The flat Astro path is deprecated as of v0.8.0** — still reachable via the API + `--no-design-system` for back-compat, but the monorepo is now the supported shipping target. New Astro investment lands in the monorepo emit. See [`MIGRATING.md`](./MIGRATING.md) v0.7 → v0.8 section.\n\n**Existing v0.5.x / v0.6.x / v0.7.x scaffolds are not broken.** Their shape on disk is unchanged. A `create-helix migrate-to-monorepo` subcommand is deferred; see [`MIGRATING.md`](./MIGRATING.md) for the manual recipe (which covers Next/Vite/Astro alike — they share the same workspace shape).\n\n## WC-Storybook brand-storytelling experience\n\n`npx create-helix` → choose **WC Storybook (factory)** to scaffold a Lit 3 design system with a fully-staged Storybook out of the box. Three brand prompts shape the experience:\n\n- **Design system codename** (`--ds-name`) — drives element prefix (`{ds}-button`) and CSS token namespace (`{prefix}-*`).\n- **Brand tagline** (`--brand-tagline`) — surfaces in `Cover.mdx` and `Brand.mdx`. Falls back to a neutral default.\n- **Brand verticals** (`--brand-verticals \"fintech,wellness\"`) — populates the brand toolbar dropdown. Empty = single-brand mode.\n\nThe scaffolded Storybook ships:\n\n- **Cover.mdx** with brand tagline + vertical chips + quick-start commands.\n- **Overview.mdx** explaining the three-tier token cascade (primitive → semantic → component).\n- **Foundations** — 8 MDX pages: Tokens, Color, Typography, Spacing, Layout, Brand, Accessibility, **Iconography** (new in v0.6.0 — renders the full `@helixui/icons` catalog plus a curated showcase, wired to `setBasePath('/icons')` and the `@helixui/icons/dist` static dir). All live-bound to the consumer's `var({prefix}-*)` tokens.\n- **Token deep-dives** — dedicated `Foundations/Tokens/Borders` and `Foundations/Tokens/Shadows` pages with live swatches, plus a `Foundations/Tokens/Playground` story for interactive token inspection.\n- **Per-component AAA conformance pages** — 8 hand-authored MDXes (button, card, checkbox, dialog, form, select, tabs, text-input) parameterized by `{dsName}` so `\u003caurora-card\u003e`, `\u003caurora-form\u003e` etc. render the consumer's tags. Each ships hero scenarios + auto-injected `A11yStatusCard` reading from CEM `helixMeta.aaa.*` + APG pattern card + consumer obligations.\n- **Accessibility narrative** — top-level `Accessibility/*` namespace with 8 pages: Dashboard, AAA Story Template, Keyboard Contracts, Success Criteria, Consumer Obligations, Focus Management, Contrast Deep-Dive, Forced Colors. Editorial content modeled on HELiX's own Storybook depth.\n- **Scene stories** — 3 cross-domain-neutral pattern playgrounds (`Account Setup`, `Team Dashboard`, `Settings`) demonstrating composition of multiple components in real flows.\n- **React helper components** — `TokenSwatchGrid`, `ContrastMatrix`, `RatioCard`, `CodeBlock`, `CodeTabs`, plus `useResolvedToken` hook and APCA `contrast` util. Available under `src/stories/_components/` for consumers to compose their own MDXes.\n- **`InlineAuditPanel` opt-in pattern** — ships as a no-op stub by default. Consumers wire their own `markdown` prop to surface per-component AAA-AUDIT content (the audit source lives inside the HELiX monorepo and isn't published; see `docs/FOLLOW-UP-shared-storybook-kit.md` for the trigger conditions that would make this live).\n- **Token-driven manager chrome** — light / dark / high-contrast modes via `@helixui/tokens`. FOUC-prevention sync scripts so dark/HC pages don't flash white on reload.\n- **Brand toolbar** + persistence via `localStorage[\"helix:storybook:globals\"]`.\n- **8 Storybook addons** — a11y, docs, themes, vitest, designs, links, pseudo-states, chromatic-com.\n- **`helix.storybook.config.ts`** at the consumer root — opt out of components / docs pages / brand verticals / AAA / narrative pages without diving into `.storybook/`.\n- **Auto-catalog on install** (v0.6.0) — when scaffolding with `--install-deps` (default), `pnpm cem:catalog` runs immediately after `pnpm install` so the ~99-entry hx-\\* catalog sidebar (atoms / molecules / organisms) is populated on first `pnpm storybook` boot. If you used `--no-install`, the Next-steps banner explicitly lists `pnpm install \u0026\u0026 pnpm cem:catalog` so the catalog populates before first boot.\n\n## Drupal Presets\n\n| Preset       | Description                                         | SDC Count |\n| ------------ | --------------------------------------------------- | --------- |\n| `standard`   | Core Drupal SDCs for general-purpose themes         | 7         |\n| `blog`       | Standard + blog-specific content components         | 12        |\n| `healthcare` | Blog + healthcare-specific components (HIPAA-aware) | 16        |\n| `intranet`   | Standard + employee portal components               | 11        |\n\nEach preset generates a complete Drupal theme directory with:\n\n- Theme info and libraries YAML files\n- Single Directory Components (SDCs) with Twig templates\n- HELiX component CDN integration via `helixui.libraries.yml`\n- Drupal behaviors using the `once()` pattern\n- `composer.json` and `package.json`\n\nSee [docs/drupal-presets.md](./docs/drupal-presets.md) for full details.\n\n## Component Bundles\n\nWhen scaffolding a framework project, you can select which component bundles to include:\n\n| Bundle                  | Components | Description                                                  |\n| ----------------------- | ---------- | ------------------------------------------------------------ |\n| **All Components**      | 98         | The full HELiX library                                       |\n| **Core UI**             | 14         | button, card, badge, text, icon, avatar, divider, chip       |\n| **Form Components**     | 16         | text-input, select, checkbox, radio, switch, textarea, field |\n| **Navigation**          | 12         | nav, sidebar, tabs, breadcrumb, pagination, menu             |\n| **Data Display**        | 10         | data-table, stat, progress, meter, counter, structured-list  |\n| **Feedback \u0026 Overlays** | 8          | alert, toast, dialog, drawer, banner, skeleton               |\n| **Layout**              | 11         | grid, stack, split-panel, accordion, carousel                |\n\n## Additional Features\n\n- **TypeScript** -- strict mode configuration\n- **ESLint + Prettier** -- code quality and formatting\n- **HELiX Design Tokens** -- CSS custom properties for theming\n- **Dark Mode Support** -- automatic dark mode via `prefers-color-scheme`\n- **Example Pages** -- forms, dashboard, and settings page examples\n\n## Roadmap \u0026 Migration\n\n- **Migrating from v0.6.x → v0.7.0** — see [MIGRATING.md](./MIGRATING.md). Existing flat scaffolds keep working; the new monorepo shape is opt-in via the second prompt (or `--monorepo`). A manual flat → monorepo recipe is included for early adopters who want to convert.\n- **`create-helix migrate-to-monorepo` subcommand** — deferred to **v0.7.1**. Will automate the manual recipe in MIGRATING.md.\n- **Publishable design-system package** — deferred. v0.7.0 emits `packages/design-system` as a workspace-internal package only; publishing it standalone to npm needs additional wiring (build pipeline, narrowed peer deps).\n- **npm / yarn workspace support** — not on the v0.7.x roadmap. v0.7.0 is pnpm-only (`pnpm-workspace.yaml` + `workspace:*`).\n- **`@helixui/storybook-kit` shared package extraction** — deferred. See [docs/FOLLOW-UP-shared-storybook-kit.md](./docs/FOLLOW-UP-shared-storybook-kit.md) for trigger conditions and scope sketch. Today's wc-storybook factory ports helix's Storybook depth at scaffold time; a future iteration may consume a shared kit instead.\n\n## Requirements\n\n- Node.js \u003e= 20.0.0\n\n## Development\n\n```bash\ngit clone https://github.com/bookedsolidtech/create-helix-app.git\ncd create-helix-app\nnpm install\nnpm run build\n```\n\n### Scripts\n\n| Script                 | Description                      |\n| ---------------------- | -------------------------------- |\n| `npm run build`        | Compile TypeScript               |\n| `npm run dev`          | Watch mode                       |\n| `npm start`            | Run the CLI                      |\n| `npm run type-check`   | TypeScript strict check          |\n| `npm run lint`         | ESLint                           |\n| `npm run format`       | Prettier auto-fix                |\n| `npm run format:check` | Prettier check                   |\n| `npm test`             | Run tests                        |\n| `npm run verify`       | lint + format:check + type-check |\n| `npm run preflight`    | verify + test                    |\n\n## Contributing\n\n1. Fork the repo and create a feature branch\n2. Make your changes\n3. Run `npm run verify` before pushing (enforced by pre-push hook)\n4. Run `npm test` to ensure all tests pass\n5. Open a pull request against `dev`\n\n### Secret Scanning\n\nThis repo uses [gitleaks](https://github.com/gitleaks/gitleaks) to prevent secrets from being committed. Install it locally to enable pre-commit scanning:\n\n```bash\n# macOS\nbrew install gitleaks\n\n# Linux\nGITLEAKS_VERSION=\"8.21.2\"\ncurl -sSfL \\\n  \"https://github.com/gitleaks/gitleaks/releases/download/v${GITLEAKS_VERSION}/gitleaks_${GITLEAKS_VERSION}_linux_x64.tar.gz\" \\\n  | tar -xz -C ~/.local/bin gitleaks\n\n# Windows (via scoop)\nscoop install gitleaks\n```\n\nIf gitleaks is not installed, the pre-commit hook will warn but will not block your commit. CI always runs the full scan. Configuration is in `.gitleaks.toml`.\n\n## License\n\n[MIT](./LICENSE) -- Copyright 2026 BookedSolid Tech\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbookedsolidtech%2Fcreate-helix-app","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbookedsolidtech%2Fcreate-helix-app","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbookedsolidtech%2Fcreate-helix-app/lists"}