@fusion.dev/helix-templates 0.0.9

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Fusion Development Group
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,43 @@
+# @fusion.dev/helix-templates
+
+The Helix starter templates, as data. Read by `helix new` and by
+`npm create helix-app`, which are one capability behind two doors.
+
+```sh
+npm create helix-app@latest my-app
+```
+
+You are unlikely to install this package yourself. It exists so that the thing
+that would drift between those two doors — the templates — is one artifact rather
+than two copies, and so that a template is versioned with the components it was
+written against.
+
+| Template | What it is |
+|---|---|
+| `react-vite` | React and TypeScript on Vite. The shortest path to a running component. |
+| `react-nextjs` | React and TypeScript on the Next.js App Router, elements registered once. |
+
+**There is no build-free HTML template**, and that is a fact about the packages
+rather than an omission. `@fusion.dev/helix`'s published entry re-exports bare
+specifiers — `@fusion.dev/helix-core`, ninety-odd `@fusion.dev/helix-headless/*`
+subpaths, `lit` and its own graph — none of which a browser resolves without an
+import map covering all of it, and an import map that large is a build artifact
+wearing a template's clothes. The honest build-free story is a CDN that rewrites
+the graph, which wants the packages public first.
+
+## Reading it yourself
+
+```js
+import { findTemplate, PROJECT_NAME, templates } from '@fusion.dev/helix-templates'
+```
+
+`templates` is the register, in the order a chooser should offer them. Each entry
+names the files whose contents carry `PROJECT_NAME`, which a scaffolder replaces
+with the project's own. The payloads sit under `templates/<id>/` in this package.
+
+**The named files are named rather than discovered.** Scanning every file for the
+placeholder would rewrite a template that merely mentions it in prose, and a
+rename that missed a file would ship rather than fail. The register is held to the
+directories by this package's own spec, in both directions.
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,55 @@
+/**
+ * The starter templates, as data.
+ *
+ * **Templates are a package rather than a directory inside a scaffolder**, which
+ * is the whole reason this exists. `helix new` and `npm create helix-app` are one
+ * capability behind two doors, and the thing that would drift between them is the
+ * templates rather than the twenty lines of copy-and-substitute around them. Both
+ * doors read this.
+ *
+ * **Versioned with Helix**, so a template scaffolds against the components it was
+ * written for. A template pinned to nothing is a template that stops compiling on
+ * somebody else's release.
+ *
+ * The payloads sit in `templates/<id>/` and travel in the published package. This
+ * module is the register: what exists, what each one is for, and which file a
+ * consumer's project name has to be written into.
+ */
+/** One template, and everything a scaffolder needs to lay it down. */
+export interface Template {
+    /** What a reader chooses it for, in one line. */
+    readonly description: string;
+    /**
+     * Files whose contents carry `__PROJECT_NAME__`.
+     *
+     * Named rather than discovered by scanning every file, so a template that
+     * mentions the placeholder in prose does not get it silently rewritten, and so
+     * a rename that misses a file fails a test rather than shipping.
+     */
+    readonly named: readonly string[];
+    /** The directory under `templates/`, and the id a caller passes. */
+    readonly id: string;
+    /** What it is called in a chooser. */
+    readonly title: string;
+}
+/**
+ * **In the order a chooser should offer them**, which is not alphabetical.
+ *
+ * `react-vite` is first because it is the shortest path from nothing to a
+ * component on screen, and a first release is judged on that.
+ *
+ * **There is no build-free HTML template, and that is a fact about the packages
+ * rather than an omission.** `@fusion.dev/helix`'s published entry re-exports
+ * bare specifiers — `@fusion.dev/helix-core`, ninety-odd
+ * `@fusion.dev/helix-headless/*` subpaths, `lit` and its own graph — which a
+ * browser cannot resolve without an import map covering all of it. An import map
+ * that large is a build artifact wearing a template's clothes. The honest
+ * build-free story is a CDN that rewrites the graph, which wants the packages
+ * public first.
+ */
+export declare const templates: readonly Template[];
+/** The placeholder a scaffolder replaces with the project's name. */
+export declare const PROJECT_NAME = "__PROJECT_NAME__";
+/** The one template with this id, or `undefined` where there is none. */
+export declare const findTemplate: (id: string) => Template | undefined;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,sEAAsE;AACtE,MAAM,WAAW,QAAQ;IACvB,iDAAiD;IACjD,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B;;;;;;OAMG;IACH,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAA;IACjC,oEAAoE;IACpE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,sCAAsC;IACtC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CACvB;AAED;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,SAAS,EAAE,SAAS,QAAQ,EAcxC,CAAA;AAED,qEAAqE;AACrE,eAAO,MAAM,YAAY,qBAAqB,CAAA;AAE9C,yEAAyE;AACzE,eAAO,MAAM,YAAY,OAAQ,MAAM,KAAG,QAAQ,GAAG,SACb,CAAA"}

package/dist/index.js

@@ -0,0 +1,17 @@
+export const templates = [
+    {
+        description: 'React and TypeScript on Vite. The shortest path to a running component.',
+        id: 'react-vite',
+        named: ['index.html', 'package.json', 'src/App.tsx'],
+        title: 'React (Vite)',
+    },
+    {
+        description: 'React and TypeScript on the Next.js App Router, with the elements registered once.',
+        id: 'react-nextjs',
+        named: ['app/layout.tsx', 'app/page.tsx', 'package.json'],
+        title: 'React (Next.js)',
+    },
+];
+export const PROJECT_NAME = '__PROJECT_NAME__';
+export const findTemplate = (id) => templates.find((one) => one.id === id);
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAmDA,MAAM,CAAC,MAAM,SAAS,GAAwB;IAC5C;QACE,WAAW,EAAE,yEAAyE;QACtF,EAAE,EAAE,YAAY;QAChB,KAAK,EAAE,CAAC,YAAY,EAAE,cAAc,EAAE,aAAa,CAAC;QACpD,KAAK,EAAE,cAAc;KACtB;IACD;QACE,WAAW,EACT,oFAAoF;QACtF,EAAE,EAAE,cAAc;QAClB,KAAK,EAAE,CAAC,gBAAgB,EAAE,cAAc,EAAE,cAAc,CAAC;QACzD,KAAK,EAAE,iBAAiB;KACzB;CACF,CAAA;AAGD,MAAM,CAAC,MAAM,YAAY,GAAG,kBAAkB,CAAA;AAG9C,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,EAAU,EAAwB,EAAE,CAC/D,SAAS,CAAC,IAAI,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,EAAE,KAAK,EAAE,CAAC,CAAA"}

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@fusion.dev/helix-templates",
+  "description": "Starter templates for Helix, as data. Read by `helix new` and by `npm create helix-app`.",
+  "version": "0.0.9",
+  "license": "MIT",
+  "author": "Ross Sheppard <ross.sheppard@fusion.dev>",
+  "repository": {
+    "directory": "helix/templates",
+    "type": "git",
+    "url": "git+https://github.com/project-fusion/fusion.git"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./templates.json": "./templates.json"
+  },
+  "files": [
+    "dist",
+    "templates",
+    "templates.json"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "bun run register && tsc -p tsconfig.json && tsc -p tsconfig.types.json",
+    "register": "bun scripts/build-register.mjs",
+    "typecheck": "bun run register && tsc -p tsconfig.json --noEmit"
+  },
+  "bugs": "https://github.com/project-fusion/fusion/issues",
+  "homepage": "https://fusion.dev",
+  "keywords": [
+    "helix",
+    "templates",
+    "scaffold",
+    "design-system"
+  ],
+  "publishConfig": {
+    "access": "restricted"
+  }
+}

package/templates/react-nextjs/app/helix-elements.tsx

@@ -0,0 +1,10 @@
+'use client'
+
+/* Import the whole library while you are finding your feet. When you would rather
+   pay for only what you use, `@fusion.dev/helix/button` and its siblings are
+   subpath exports and this file becomes the list of what the app actually uses. */
+import '@fusion.dev/helix'
+
+export function HelixElements(): null {
+  return null
+}

package/templates/react-nextjs/app/layout.tsx

@@ -0,0 +1,33 @@
+import type { Metadata, Viewport } from 'next'
+import type { ReactNode } from 'react'
+
+/* Every layer in one import: the tokens, the reset, the utility layer, and the
+   `:not(:defined)` rules that keep a tag from arriving unstyled. */
+import '@fusion.dev/helix/helix.css'
+
+import { HelixElements } from './helix-elements.js'
+
+export const metadata: Metadata = { title: '__PROJECT_NAME__' }
+export const viewport: Viewport = { initialScale: 1, width: 'device-width' }
+
+/**
+ * `HelixElements` is rendered once, here, and returns `null`.
+ *
+ * A custom element registers as a side effect of importing its module, and that
+ * import has to be in the *client* graph to ever run: a server component's
+ * imports do not ship to the browser. One client component holds them all.
+ *
+ * Pages stay server components. An unregistered tag is only an unknown element in
+ * the HTML, which upgrades the moment the definition lands, so nothing here asks
+ * you to mark a page `'use client'` to use a button.
+ */
+export default function RootLayout({ children }: { children: ReactNode }) {
+  return (
+    <html lang="en">
+      <body>
+        <HelixElements />
+        {children}
+      </body>
+    </html>
+  )
+}

package/templates/react-nextjs/app/page.tsx

@@ -0,0 +1,18 @@
+/**
+ * A server component, rendering custom elements directly.
+ *
+ * Helix events are props: `onhelix-before-change` reaches `helix-before-change`.
+ * Anything needing a handler is a client component, the same as any other React
+ * app — this page needs none.
+ */
+export default function Page() {
+  return (
+    <helix-flex align="center" direction="column" gap="lg">
+      <helix-text as="h1">__PROJECT_NAME__</helix-text>
+      <helix-text>Edit `app/page.tsx` and save.</helix-text>
+      <helix-button emphasis="solid" tone="primary">
+        Get started
+      </helix-button>
+    </helix-flex>
+  )
+}

package/templates/react-nextjs/helix-jsx.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Types for the Helix custom elements written directly in JSX.
+ *
+ * Emitted by `@wc-toolkit/jsx-types` from the same manifest the API pages read,
+ * so a wrong attribute or a wrong event detail is a compile error rather than a
+ * silent no-op.
+ *
+ * **A side-effect import in a `.d.ts`, rather than an entry in `types`.** The
+ * typings are the subpath export `@fusion.dev/helix/jsx`, and entries in the
+ * `types` compiler array resolve as ambient type packages rather than through a
+ * package's exports map, so naming the subpath there resolves to nothing and
+ * every Helix tag comes out untyped.
+ */
+import '@fusion.dev/helix/jsx'

package/templates/react-nextjs/next.config.ts

@@ -0,0 +1,5 @@
+import type { NextConfig } from 'next'
+
+const config: NextConfig = {}
+
+export default config

package/templates/react-nextjs/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "__PROJECT_NAME__",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "build": "next build",
+    "dev": "next dev",
+    "start": "next start"
+  },
+  "dependencies": {
+    "@fusion.dev/helix": "^0.0.9",
+    "next": "^16.0.0",
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.0"
+  }
+}

package/templates/react-nextjs/tsconfig.json

@@ -0,0 +1,34 @@
+{
+  "compilerOptions": {
+    "jsx": "preserve",
+    "lib": [
+      "DOM",
+      "DOM.Iterable",
+      "ES2023"
+    ],
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "skipLibCheck": true,
+    "strict": true,
+    "target": "ES2023",
+    "verbatimModuleSyntax": true,
+    "noEmit": true,
+    "incremental": true,
+    "plugins": [
+      {
+        "name": "next"
+      }
+    ]
+  },
+  "include": [
+    "app",
+    "next-env.d.ts",
+    "**/*.ts",
+    "**/*.tsx",
+    ".next/types/**/*.ts",
+    "helix-jsx.d.ts"
+  ],
+  "exclude": [
+    "node_modules"
+  ]
+}

package/templates/react-vite/helix-jsx.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Types for the Helix custom elements written directly in JSX.
+ *
+ * Emitted by `@wc-toolkit/jsx-types` from the same manifest the API pages read,
+ * so a wrong attribute or a wrong event detail is a compile error rather than a
+ * silent no-op.
+ *
+ * **A side-effect import in a `.d.ts`, rather than an entry in `types`.** The
+ * typings are the subpath export `@fusion.dev/helix/jsx`, and entries in the
+ * `types` compiler array resolve as ambient type packages rather than through a
+ * package's exports map, so naming the subpath there resolves to nothing and
+ * every Helix tag comes out untyped.
+ */
+import '@fusion.dev/helix/jsx'

package/templates/react-vite/index.html

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>__PROJECT_NAME__</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>

package/templates/react-vite/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "__PROJECT_NAME__",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "build": "tsc && vite build",
+    "dev": "vite",
+    "preview": "vite preview"
+  },
+  "dependencies": {
+    "@fusion.dev/helix": "^0.0.9",
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0"
+  },
+  "devDependencies": {
+    "@vitejs/plugin-react": "^5.0.0",
+    "typescript": "^5.9.0",
+    "vite": "^7.0.0"
+  }
+}

package/templates/react-vite/src/App.tsx

@@ -0,0 +1,24 @@
+/**
+ * Helix components are custom elements, so you write the tags directly. There is
+ * no wrapper package and nothing to import per component.
+ *
+ * Events are props: `onhelix-before-change` reaches `helix-before-change`. React's
+ * own bubbling events work as they always do, so `onClick` is fine here.
+ */
+export function App() {
+  return (
+    <helix-flex align="center" direction="column" gap="lg">
+      <helix-text as="h1">__PROJECT_NAME__</helix-text>
+      <helix-text>Edit `src/App.tsx` and save.</helix-text>
+      <helix-button
+        emphasis="solid"
+        onClick={() => {
+          console.log('clicked')
+        }}
+        tone="primary"
+      >
+        Get started
+      </helix-button>
+    </helix-flex>
+  )
+}

package/templates/react-vite/src/main.tsx

@@ -0,0 +1,20 @@
+import { StrictMode } from 'react'
+import { createRoot } from 'react-dom/client'
+
+/* Every layer in one import: the tokens, the reset, the utility layer, and the
+   `:not(:defined)` rules that keep a tag from arriving unstyled. It reaches its
+   pieces by bare specifier, so a bundler resolves it and a `<link>` cannot. */
+import '@fusion.dev/helix/helix.css'
+/* A custom element registers as a side effect of being imported, so this line is
+   what makes every Helix tag in the app real. Import the whole library while you
+   are finding your feet; `@fusion.dev/helix/button` and its siblings are subpath
+   exports when you would rather pay for only what you use. */
+import '@fusion.dev/helix'
+
+import { App } from './App.js'
+
+createRoot(document.querySelector('#root') as HTMLElement).render(
+  <StrictMode>
+    <App />
+  </StrictMode>,
+)

package/templates/react-vite/tsconfig.json

@@ -0,0 +1,21 @@
+{
+  "compilerOptions": {
+    "jsx": "react-jsx",
+    "lib": [
+      "DOM",
+      "DOM.Iterable",
+      "ES2023"
+    ],
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "skipLibCheck": true,
+    "strict": true,
+    "target": "ES2023",
+    "verbatimModuleSyntax": true,
+    "noEmit": true
+  },
+  "include": [
+    "src",
+    "helix-jsx.d.ts"
+  ]
+}

package/templates/react-vite/vite.config.ts

@@ -0,0 +1,4 @@
+import react from '@vitejs/plugin-react'
+import { defineConfig } from 'vite'
+
+export default defineConfig({ plugins: [react()] })

package/templates.json

@@ -0,0 +1,25 @@
+{
+  "placeholder": "__PROJECT_NAME__",
+  "templates": [
+    {
+      "description": "React and TypeScript on Vite. The shortest path to a running component.",
+      "id": "react-vite",
+      "named": [
+        "index.html",
+        "package.json",
+        "src/App.tsx"
+      ],
+      "title": "React (Vite)"
+    },
+    {
+      "description": "React and TypeScript on the Next.js App Router, with the elements registered once.",
+      "id": "react-nextjs",
+      "named": [
+        "app/layout.tsx",
+        "app/page.tsx",
+        "package.json"
+      ],
+      "title": "React (Next.js)"
+    }
+  ]
+}