create-vite-hyperapp 1.2.0 → 2.0.0

package/README.md

@@ -1,34 +1,126 @@
 # create-vite-hyperapp
 
-Quickly scaffold new web-frontend projects using the [Hyperapp](https://hyperapp.dev) microframework, using the [Vite](https://vitejs.dev) bundler.
+Create a project using [Hyperapp](https://github.com/jorgebucaran/hyperapp) and [Vite](https://vite.dev/). The generated projects use [vite-plugin-hyperapp](https://github.com/zaceno/vite-plugin-hyperapp#readme) for development, builds, and optional server-side rendering; see its README for more about the plugin.
 
 ## Usage
 
-With your shell in the folder _under which_ you would like to create your new project folder, run `npm create vite-hyperapp` and answer the questions. 
+```text
+Usage: npm create vite-hyperapp -- [name] [options]
 
-To skip questions and do the entire setup directly in the command line, use the options:
+Create a Vite + Hyperapp project in an empty directory.
+Run without arguments to choose options interactively.
 
-```
-Usage: npm create vite-hyperapp -- [TARGET_DIR] [OPTIONS]
+Arguments:
+  name                            Project name and directory (default: hyperapp-app)
+                                  Use . or ./ for the current empty directory.
 
 Options:
-    -t, --typescript      Use typescript
-    -s, --ssr             Use server-side rendering
-    -n, --no-prompt       Just do it, no questions asked
-    -h, --help            Show this message 
-
-If no target dir is specified, the project name will be used.
-If --no-prompt option is used, project name will be target dir
-Default project-name/target-dir is 'hyperapp-project'
+  --types=none|jsdoc|typescript   Type checking (default: typescript)
+  --views=plain|html|jsx          View style (default: jsx)
+  --ssr=no|yes                    Server-side rendering (default: no)
+  -h, --help                      Show this message and exit
+
+Examples:
+  npm create vite-hyperapp -- my-app --types=jsdoc --views=html --ssr=yes
+  npm create vite-hyperapp -- .
+```
+
+## Writing views
+
+Choose how you want to write Hyperapp's view functions. These examples show the same counter component in plain JavaScript; your choice of view style is independent of your choice of typing system.
+
+### Plain Hyperapp (`--views=plain`)
+
+Use Hyperapp's built-in `h` and `text` functions:
+
+```js
+import { h, text } from "hyperapp"
+
+const Counter = ({ clicks, onclick }) =>
+  h("div", { class: "card" }, [
+    h("button", { onclick }, text("Clicks: " + clicks)),
+  ])
+```
+
+### HTML functions (`--views=html`)
+
+Use tags from `@hyperapp/html` as functions:
+
+```js
+import { div, button, text } from "@hyperapp/html"
+
+const Counter = ({ clicks, onclick }) =>
+  div({ class: "card" }, button({ onclick }, text("Clicks: " + clicks)))
+```
+
+### JSX (`--views=jsx`)
+
+Write markup-like components in `.jsx` files:
+
+```jsx
+const Counter = ({ clicks, onclick }) => (
+  <div class="card">
+    <button onclick={onclick}>Clicks: {clicks}</button>
+  </div>
+)
 ```
 
-## About the scaffolds
+## Typing
+
+Choose separately whether—and how—to type-check your project. The following examples all use the HTML-function view style so you can compare the same component.
+
+### JavaScript without type-checking (`--types=none`)
+
+Write JavaScript without type annotations. `npm run build` does not run a type checker:
+
+```js
+import { div, button, text } from "@hyperapp/html"
+
+const Counter = ({ clicks, onclick }) =>
+  div({ class: "card" }, button({ onclick }, text("Clicks: " + clicks)))
+```
+
+### JavaScript with JSDoc type-checking (`--types=jsdoc`)
+
+Keep `.js`/`.jsx` files and add types in [JSDoc comments](https://www.typescriptlang.org/docs/handbook/jsdoc-supported-types.html). The build runs TypeScript's checker on your JavaScript:
 
-There are four basic templates that can be scaffolded up, depending on wether you want to use Typescript or not, and if you want to scaffold your project for SSR or not. 
+```js
+import { div, button, text } from "@hyperapp/html"
 
-The vite-hyperapp connection is provided by [vite-plugin-hyperapp](https://github.com/zaceno/vite-plugin-hyperapp).
+/**
+ * @template S
+ * @typedef CounterProps
+ * @property {number} clicks
+ * @property {Action<S>} onclick
+ */
 
-The SSR scaffolds are based directly on Vite's SSR docs for setting up a server with SSR support.
+/**
+ * @template S
+ * @param {CounterProps<S>} props
+ */
+const Counter = ({ clicks, onclick }) =>
+  div({ class: "card" }, button({ onclick }, text("Clicks: " + clicks)))
+```
+
+Here `Action<S>` is available from the generated project's `src/types/global.d.ts`.
+
+### TypeScript (`--types=typescript`)
+
+Use [TypeScript syntax](https://www.typescriptlang.org/docs/handbook/2/everyday-types.html) in `.ts`/`.tsx` files. The build type-checks the project before bundling:
+
+```ts
+import { div, button, text } from "@hyperapp/html"
+import type { Action } from "hyperapp"
+
+type CounterProps<S> = {
+  clicks: number
+  onclick: Action<S>
+}
+
+const Counter = <S>({ clicks, onclick }: CounterProps<S>) =>
+  div({ class: "card" }, button({ onclick }, text("Clicks: " + clicks)))
+```
 
-All templates have their views written in JSX (or TSX, for the TS-templates), but you can just as easily install a view-system of your preference (or use hyperapp's builtin `h` and `text`). Just name your files with `.js` or `.ts` extensions instead of `.jsx`.
+## Server-side rendering
 
+With `--ssr=yes`, the server sends the initial view as HTML, so visitors can see it before the client app finishes loading. This can improve perceived loading speed. When the client starts, Hyperapp recycles the server-provided DOM rather than replacing it. The generated project includes separate client and server entries and a server for development and production. See the [vite-plugin-hyperapp SSR documentation](https://github.com/zaceno/vite-plugin-hyperapp#server-side-rendering) for more detail.

package/create-vite-hyperapp.mjs

@@ -0,0 +1,193 @@
+#!/usr/bin/env node
+import { cpSync, existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, renameSync, writeFileSync } from "node:fs"
+import { basename, dirname, join, resolve } from "node:path"
+import { fileURLToPath } from "node:url"
+import { confirm, input, select } from "@inquirer/prompts"
+import { bold, cyan, isColorSupported, red, white, yellow } from "colorette"
+
+const templates = join(dirname(fileURLToPath(import.meta.url)), "templates")
+const usage = `Usage: npm create vite-hyperapp -- [name] [options]
+
+Create a Vite + Hyperapp project in an empty directory.
+Run without arguments to choose options interactively.
+
+Arguments:
+  name                            Project name and directory (default: hyperapp-app)
+                                  Use . or ./ for the current empty directory.
+
+Options:
+  --types=none|jsdoc|typescript   Type checking (default: typescript)
+  --views=plain|html|jsx          View style (default: jsx)
+  --ssr=no|yes                    Server-side rendering (default: no)
+  -h, --help                      Show this message and exit
+
+Examples:
+  npm create vite-hyperapp -- my-app --types=jsdoc --views=html --ssr=yes
+  npm create vite-hyperapp -- .
+`
+
+function parseOptions(args) {
+  const options = { name: "hyperapp-app", types: "typescript", views: "jsx", ssr: "no" }
+  const choices = {
+    types: ["none", "jsdoc", "typescript"],
+    views: ["plain", "html", "jsx"],
+    ssr: ["no", "yes"],
+  }
+  const seen = new Set()
+  let hasName = false
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i]
+    if (!arg.startsWith("-")) {
+      if (hasName) throw new Error("Provide only one project name. See --help.")
+      options.name = arg
+      hasName = true
+      continue
+    }
+    if (!arg.startsWith("--")) throw new Error(`Unknown argument: ${arg}. See --help.`)
+    const equal = arg.indexOf("=")
+    const key = arg.slice(2, equal === -1 ? undefined : equal)
+    if (!(key in choices)) throw new Error(`Unknown option: --${key}. See --help.`)
+    if (seen.has(key)) throw new Error(`--${key} was provided more than once.`)
+    seen.add(key)
+
+    const value = equal === -1 ? args[++i] : arg.slice(equal + 1)
+    if (!value || value.startsWith("--")) throw new Error(`--${key} requires a value. See --help.`)
+    if (!choices[key].includes(value)) {
+      throw new Error(`Invalid --${key} value: ${value}. Choose ${choices[key].join(", ")}.`)
+    }
+    options[key] = value
+  }
+  return options
+}
+
+function getTarget(options) {
+  const here = options.name === "." || options.name === "./"
+  const name = here ? basename(process.cwd()) : options.name
+  if (!/^[a-z0-9][a-z0-9._-]*$/.test(name)) {
+    throw new Error(`Invalid project name: ${name}. Use lowercase letters, digits, dots, hyphens, or underscores (starting with a letter or digit).`)
+  }
+
+  const destination = here ? process.cwd() : resolve(process.cwd(), name)
+  if (existsSync(destination)) {
+    if (!lstatSync(destination).isDirectory()) throw new Error(`Target is not a directory: ${destination}`)
+    if (readdirSync(destination).length) throw new Error(`Target directory is not empty: ${destination}`)
+  }
+  return { here, name, destination }
+}
+
+function createProject(options) {
+  const { here, name, destination } = getTarget(options)
+  const variant = `${{ none: "js", jsdoc: "tj", typescript: "ts" }[options.types]}-${options.views}-${options.ssr === "yes" ? "ssr" : "cli"}`
+
+  if (!existsSync(destination)) {
+    try {
+      mkdirSync(destination)
+    } catch (error) {
+      throw new Error(`Could not create target directory ${destination}: ${error.message}`)
+    }
+  }
+
+  cpSync(join(templates, "common"), destination, { recursive: true, force: false, errorOnExist: true })
+  cpSync(join(templates, variant), destination, { recursive: true, force: false, errorOnExist: true })
+  renameSync(join(destination, "_gitignore"), join(destination, ".gitignore"))
+
+  for (const filename of ["package.json", "index.html"]) {
+    const path = join(destination, filename)
+    writeFileSync(path, readFileSync(path, "utf8").replaceAll("__PROJECTNAME__", name))
+  }
+
+  console.log(`Created ${name} in ${destination}.\n\nNext steps:`)
+  if (!here) console.log(`  cd ${name}`)
+  console.log("  npm install\n  npm run dev")
+}
+
+async function wizard() {
+  if (!process.stdin.isTTY || !process.stdout.isTTY) {
+    throw new Error("The wizard needs an interactive terminal. Pass a name or options to run without it.")
+  }
+
+  // Colorette handles bold and white; truecolor supplies the requested RGB accent.
+  const logo = isColorSupported
+    ? `\x1b[48;2;107;154;238m ${bold(white("+\\"))} \x1b[49m`
+    : "+\\"
+  const heading = isColorSupported
+    ? `\x1b[38;2;107;154;238m${bold("Create a project with Vite & Hyperapp")}\x1b[39m`
+    : "Create a project with Vite & Hyperapp"
+  console.log(`\n${heading} ${logo}\n`)
+
+  try {
+    const name = (await input({
+      message: "Project name (. or ./ for current directory)",
+      default: "hyperapp-app",
+      validate(value) {
+        try {
+          getTarget({ name: value.trim() || "hyperapp-app" })
+          return true
+        } catch (error) {
+          return error.message
+        }
+      },
+    })).trim() || "hyperapp-app"
+
+    const views = await select({
+      message: "Views",
+      choices: [
+        { name: "Plain Hyperapp (h/text)", value: "plain" },
+        { name: "@hyperapp/html", value: "html" },
+        { name: "JSX", value: "jsx" },
+      ],
+      default: "jsx",
+    })
+    const types = await select({
+      message: "Types",
+      choices: [
+        { name: "JavaScript (no type-checking)", value: "none" },
+        { name: "JavaScript with JSDoc type-checking", value: "jsdoc" },
+        { name: "TypeScript", value: "typescript" },
+      ],
+      default: "typescript",
+    })
+    const ssr = await select({
+      message: "Server-side rendering",
+      choices: [
+        { name: "No (client-only)", value: "no" },
+        { name: "Yes (SSR)", value: "yes" },
+      ],
+      default: "no",
+    })
+
+    console.log(`\n${bold("Your project")}`)
+    console.log(`  Name:  ${cyan(name)}`)
+    console.log(`  Views: ${cyan(views)}`)
+    console.log(`  Types: ${cyan(types)}`)
+    console.log(`  SSR:   ${cyan(ssr)}`)
+
+    if (!await confirm({ message: "Create this project?", default: false })) {
+      console.log(yellow("Cancelled. No project was created."))
+      return
+    }
+    createProject({ name, views, types, ssr })
+  } catch (error) {
+    if (error.name !== "ExitPromptError") throw error
+    console.log(yellow("\nCancelled. No project was created."))
+  }
+}
+
+async function main() {
+  const args = process.argv.slice(2)
+  if (args.some(arg => arg === "--help" || arg === "-h")) {
+    console.log(usage)
+  } else if (args.length === 0) {
+    await wizard()
+  } else {
+    createProject(parseOptions(args))
+  }
+}
+
+try {
+  await main()
+} catch (error) {
+  console.error(red(`Error: ${error.message}`))
+  process.exitCode = 1
+}

package/package.json

@@ -1,19 +1,26 @@
 {
   "name": "create-vite-hyperapp",
-  "type": "module",
-  "version": "1.2.0",
-  "description": "\"Scaffold a project quickly with Hyperapp and Vite\"",
-  "main": "index.js",
-  "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
+  "version": "2.0.0",
+  "description": "Create a Vite + Hyperapp project",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/zaceno/create-vite-hyperapp.git"
   },
   "author": "Zacharias Enochsson",
   "license": "MIT",
-  "dependencies": {
-    "minimist": "^1.2.8",
-    "prompts": "^2.4.2"
-  },
+  "type": "module",
   "bin": {
-    "create-vite-hyperapp": "index.js"
+    "create-vite-hyperapp": "./create-vite-hyperapp.mjs"
+  },
+  "files": [
+    "create-vite-hyperapp.mjs",
+    "templates"
+  ],
+  "engines": {
+    "node": ">=22.18.0"
+  },
+  "dependencies": {
+    "@inquirer/prompts": "^8.7.3",
+    "colorette": "^2.0.20"
   }
 }

package/templates/{template → common}/_gitignore

@@ -21,4 +21,4 @@ dist-ssr
 *.ntvs*
 *.njsproj
 *.sln
-*.sw?
+*.sw?

package/templates/{template-ts/src → common/src/app}/style.css

@@ -52,10 +52,6 @@ h1 {
 .logo:hover {
   filter: drop-shadow(0 0 2em #646cffaa);
 }
-.logo.vanilla:hover {
-  filter: drop-shadow(0 0 2em #3178c6aa);
-}
-
 .card {
   padding: 2em;
 }

package/templates/{template → js-html-cli}/index.html

@@ -2,12 +2,12 @@
 <html lang="en">
   <head>
     <meta charset="UTF-8" />
-    <link rel="icon" type="image/svg+xml" href="/vite.svg" />
+    <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-    <title>Vite + Hyperapp</title>
+    <title>__PROJECTNAME__</title>
   </head>
   <body>
-    <div id="app"></div>
+    <main id="app"></main>
     <script type="module" src="/src/run.js"></script>
   </body>
 </html>

package/templates/js-html-cli/jsconfig.json

@@ -0,0 +1,13 @@
+{
+  "compilerOptions": {
+    "baseUrl": ".",
+    "paths": {
+      "@/*": [
+        "src/*"
+      ]
+    }
+  },
+  "include": [
+    "src"
+  ]
+}

package/templates/js-html-cli/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "__PROJECTNAME__",
+  "private": true,
+  "version": "0.0.0",
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build",
+    "preview": "vite preview"
+  },
+  "dependencies": {
+    "@hyperapp/html": "^2.0.0",
+    "@hyperapp/svg": "^2.0.0",
+    "hyperapp": "^2.0.22"
+  },
+  "devDependencies": {
+    "vite": "^8.3.4",
+    "vite-plugin-hyperapp": "^2.0.1"
+  }
+}

package/templates/js-html-cli/src/app/counter.js

@@ -0,0 +1,5 @@
+import { div, button, text } from "@hyperapp/html"
+const Counter = ({ clicks, onclick }) =>
+  div({ class: "card" }, button({ onclick }, text("Clicks: " + clicks)))
+
+export default Counter

package/templates/js-html-cli/src/app/logos.js

@@ -0,0 +1,24 @@
+import { a, img } from "@hyperapp/html"
+import viteLogo from "@/assets/vite.svg"
+import hyperappLogo from "@/assets/hyperapp.svg"
+
+const Logos = () => [
+  a(
+    { href: "https://vitejs.dev" },
+    img({
+      src: viteLogo,
+      class: "logo",
+      alt: "Vite logo",
+    }),
+  ),
+  a(
+    { href: "https://github.com/jorgebucaran/hyperapp" },
+    img({
+      src: hyperappLogo,
+      class: "logo",
+      alt: "Hyperapp logo",
+    }),
+  ),
+]
+
+export default Logos

package/templates/js-html-cli/src/app/main.js

@@ -0,0 +1,24 @@
+import "./style.css"
+import { main, h1, p, text } from "@hyperapp/html"
+import Counter from "./counter"
+import Logos from "./logos"
+
+export const init = () => ({
+  counter: 0,
+})
+
+const HandleClick = state => ({
+  ...state,
+  counter: state.counter + 1,
+})
+
+export const view = state =>
+  main({ id: "app" }, [
+    h1(text("Vite + Hyperapp")),
+    ...Logos(),
+    Counter({ clicks: state.counter, onclick: HandleClick }),
+    p(
+      { class: "read-the-docs" },
+      text("Click on the Vite & Hyperapp logos to learn more"),
+    ),
+  ])

package/templates/{template → js-html-cli}/src/run.js

@@ -1,5 +1,5 @@
 import { app } from "hyperapp"
-import { init, view } from "./main"
+import { init, view } from "./app/main"
 const node = document.querySelector("#app")
 if (!node) throw new Error("mountpoint not found")
-export const dispatch = app({ init, view, node })
+app({ init, view, node })

package/templates/js-html-cli/vite.config.js

@@ -0,0 +1,12 @@
+import { defineConfig } from "vite"
+import hyperapp from "vite-plugin-hyperapp"
+import { fileURLToPath } from "node:url"
+
+export default defineConfig({
+  plugins: [hyperapp()],
+  resolve: {
+    alias: {
+      "@": fileURLToPath(new URL("./src", import.meta.url)),
+    },
+  },
+})

package/templates/{template-ssr → js-html-ssr}/index.html

@@ -2,9 +2,9 @@
 <html lang="en">
   <head>
     <meta charset="UTF-8" />
-    <link rel="icon" type="image/svg+xml" href="/vite.svg" />
+    <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-    <title>Vite (SSR) + Hyperapp</title>
+    <title>__PROJECTNAME__</title>
   </head>
   <body>
     <!--ssr-outlet-->

package/templates/js-html-ssr/jsconfig.json

@@ -0,0 +1,13 @@
+{
+  "compilerOptions": {
+    "baseUrl": ".",
+    "paths": {
+      "@/*": [
+        "src/*"
+      ]
+    }
+  },
+  "include": [
+    "src"
+  ]
+}

package/templates/js-html-ssr/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "__PROJECTNAME__",
+  "private": true,
+  "version": "0.0.0",
+  "type": "module",
+  "scripts": {
+    "dev": "node server.js",
+    "build:client": "vite build --outDir dist/client",
+    "build:server": "vite build --outDir dist/server --ssr src/entry-server.js",
+    "build": "npm run build:client && npm run build:server",
+    "preview": "NODE_ENV=production node server.js"
+  },
+  "devDependencies": {
+    "vite": "^8.3.4"
+  },
+  "dependencies": {
+    "@hyperapp/html": "^2.0.0",
+    "@hyperapp/svg": "^2.0.0",
+    "compression": "^1.7.4",
+    "express": "^4.19.2",
+    "hyperapp": "^2.0.22",
+    "sirv": "^2.0.4",
+    "vite-plugin-hyperapp": "^2.0.1"
+  }
+}

package/templates/{template-ssr → js-html-ssr}/server.js

@@ -19,7 +19,6 @@ async function createServer() {
     vite = await createServer({
       server: { middlewareMode: true },
       appType: "custom",
-      base,
     })
     app.use(vite.middlewares)
   } else {
@@ -29,26 +28,29 @@ async function createServer() {
     app.use(base, sirv("./dist/client", { extensions: [] }))
   }
 
-  app.use("*", async (req, res) => {
-    const url = req.originalUrl.replace(base, "")
+  app.use("*", async (req, res, next) => {
+    const url = req.originalUrl
+    if (!url.startsWith(base)) return next()
     try {
       let template
       let render
       if (!isProduction) {
+        if (!vite) throw new Error("Vite dev server is not initialized")
         // Always read fresh template in development
         template = await fs.readFile("./index.html", "utf-8")
         template = await vite.transformIndexHtml(url, template)
         render = (await vite.ssrLoadModule("/src/entry-server.js")).render
       } else {
         template = await fs.readFile("./dist/client/index.html", "utf-8")
-        render = (await import("./dist/server/entry-server.js")).render
+        const serverEntry = "./dist/server/entry-server.js"
+        render = (await import(serverEntry)).render
       }
-      const html = template.replace(`<!--ssr-outlet-->`, await render())
+      const html = template.replace(`<!--ssr-outlet-->`, () => render())
       res.status(200).set({ "Content-Type": "text/html" }).end(html)
     } catch (e) {
-      vite?.ssrFixStacktrace(e)
-      console.log(e.stack)
-      res.status(500).end(e.stack)
+      if (e instanceof Error) vite?.ssrFixStacktrace(e)
+      console.error(e)
+      res.status(500).end()
     }
   })
 

package/templates/js-html-ssr/src/app/counter.js

@@ -0,0 +1,5 @@
+import { div, button, text } from "@hyperapp/html"
+const Counter = ({ clicks, onclick }) =>
+  div({ class: "card" }, button({ onclick }, text("Clicks: " + clicks)))
+
+export default Counter

package/templates/js-html-ssr/src/app/logos.js

@@ -0,0 +1,24 @@
+import { a, img } from "@hyperapp/html"
+import viteLogo from "@/assets/vite.svg"
+import hyperappLogo from "@/assets/hyperapp.svg"
+
+const Logos = () => [
+  a(
+    { href: "https://vitejs.dev" },
+    img({
+      src: viteLogo,
+      class: "logo",
+      alt: "Vite logo",
+    }),
+  ),
+  a(
+    { href: "https://github.com/jorgebucaran/hyperapp" },
+    img({
+      src: hyperappLogo,
+      class: "logo",
+      alt: "Hyperapp logo",
+    }),
+  ),
+]
+
+export default Logos