vite-plugin-hyperapp 1.1.1 → 1.2.0

package/README.md

@@ -1,4 +1,5 @@
-# vite-plugin-hyperapp
+
+# Vite Hyperapp Plugin & Starter
 
 Use vite as a dev-server and bundler for your hyperapp projects. Supports:
 
@@ -6,7 +7,7 @@ Use vite as a dev-server and bundler for your hyperapp projects. Supports:
 - Hot module reloading (HMR)
 - Server-side rendering (SSR)
 
-## Quickstart
+## Get Started
 
 To get up and running with Hyperapp and Vite in a few seconds, use [create-vite-hyperapp](https://github.com/zaceno/create-vite-hyperapp):
 
@@ -14,19 +15,21 @@ To get up and running with Hyperapp and Vite in a few seconds, use [create-vite-
 > npm create vite-hyperapp
 ```
 
-This will set you up with all the necessary configuration described below.
+> Use `npm create vite-hyperapp -- --help` for some command line options.
+
+The starter will ask you for a folder in which to scaffold the project, and it will also ask if you would like to use typescript and/or SSR.
 
-## Config
 
-To manually set up your vite-project for use with Hyperapp, install this plugin:
+### Manual setup
+
+In case you want to install manually, you need a project folder with `vite` installed, and a `vite.config.js` ready to go. Then you can install the vite-plugin for hyperapp, and enable it in the config:
 
 ```sh
 > npm install vite-plugin-hyperapp
 ```
 
-And add it to the plugins in your `vite.config.js`:
-
-```
+```js
+// vite.config.js
 import { defineConfig } from "vite"
 import hyperapp from "vite-plugin-hyperapp"
 
@@ -34,49 +37,90 @@ export default defineConfig({
   plugins: [hyperapp()],
 })
 ```
+> Options are passed as an object to `hyperapp({...})`. Available options described below.
 
-You can pass an options object to the plugin, e.g:
+In order to enable build TSX files to build, please add the following options to `compilerOptions` in your `tsconfig.json`:
 
+```json
+/* Necessary for tsx to work with vite-plugin-hyperapp */
+"jsx": "preserve",
+"jsxFactory": "jsx",
+"jsxFragmentFactory": "jsxFragment"
 ```
-  plugins: [hyperapp({
-    optionA: 'foo',
-    optionB: 'bar',
-  })]
+
+and to make sure your editor's TS language server picks up the right types for JSX/TSX,
+add this line in your `src/vite-env.d.ts`:
+
+```
+/// <reference types="vite-plugin-hyperapp/jsx" />
 ```
 
-...but most of the time you won't need it. See "Hot-module-reloading" below for some options that might be relevant.
+## JSX/TSX 
 
-## Typescript
+Our JSX/TSX works the same as React/Preact, however, note that when you pass children to a component, like:
 
-To make sure you get proper typing support in your `.tsx` files, make sure to add these compiler options to your `tsconfig.json`:
+```jsx
+<MyComponent>
+  <p>foo</p>
+  <p>bar</p>
+</MyComponent>
+```
 
+they will arrive as an array of virtual nodes in the _second_ argument to the component.
+
+```jsx
+const MyComponent = (props, children) => {
+  //children will be: [<p>foo</p>, <p>bar</p>]
+}
 ```
-/* Necessary for tsx to work with vite-plugin-hyperapp*/
-"jsx": "preserve",
-"jsxImportSource": "vite-plugin-hyperapp"
+
+It's ok to put this array of children among other children, because the jsx transform will flatten the child-list:
+
+```jsx
+const MyComponent = (props, children) => (
+  <div>
+    <h1>Header</h1>
+    {children} {/* <--- this is fine */}
+  </div>
+)
 ```
 
 ## Hot-module-reloading (HMR)
 
-For hot-module-reloading to work, the plugin injects some code in the module where you initiate the app. It only works if the module follows these two rules:
+> The following is taken care of already, when you scaffold your app with `npm create vite-hyperapp`, but it is useful to be aware of
+
+For hot-module-reloading to work, the plugin injects some code in the module where you initiate the app. In order for this to work, the app-initiation module must follow these two rules:
+
+1. It must import `app` from `"hyperapp"` using named imports (i.e. with `{..app...}`, not `*`
+2. The dispatch function returned from the app-call must be exported as a _named_ (not default) export.
 
-- It must contain:
+By default, HMR expects the exported dispatch function to be named `dispatch`. If you choose to name it something else, let the plugin know by providing it to the plugin options: 
 
 ```js
-import {..., app [as something],...} from 'hyperapp'
+//vite.config.js
+export default defineConfig({
+  plugins: [hyperapp({
+    dispatchExport: "myDispatchAlias"
+  })],
+})
 ```
 
-- It must _export_ a _named_ (not default) constant/variable `dispatch`, which should be the function retuned from calling `app({...})`.
+And if you'd rather use Vite's HMR api directly, or forego HMR entirely, you can use set that as an option in the plugin as well:
 
-If you'd rather name the `dispatch` export something else, you can tell the plugin the name you're using as a plugin option: `dispatchExport: "myPreferredName"`
-
-And if you'd rather use Vite's HMR api directly, or forego HMR entirely, you can use the plugin option: `hmr: false`
+```js
+//vite.config.js
+export default defineConfig({
+  plugins: [hyperapp({
+    hmr: false
+  })],
+})
+```
 
 ## Server-side Rendering (SSR)
 
-Generally, in order to set up SSR in your project you can follow Vite's instructions here: [https://vitejs.dev/guide/ssr.html#server-side-rendering](https://vitejs.dev/guide/ssr.html#server-side-rendering)
+Server side rendering with Vite in general is described here: https://vitejs.dev/guide/ssr.html#server-side-rendering Below are some important details specific to Hyperapp and this plugin.
 
-Here are some specifics you'll need to know when using hyperapp and this plugin:
+> When you use `npm create vite-hyperapp` to scaffold a project with SSR, these details are set up for you. But they're useful to be aware of as you build out your app.
 
 ### Redering your initial app to raw html
 
@@ -94,7 +138,7 @@ export async function render() {
 
 `renderApp` is an async function that takes the same options object as `hyperapp.app` - except the `node` option - and returns a promise which resolves to the html-string.
 
-Note: it is important that the server-entry module has `import ... from 'vite-plugin-hyperapp/ssr'` somewhere in it, in order for HMR to continue working on SSR enabled apps.
+> It is important that the server-entry module has `import ... from 'vite-plugin-hyperapp/ssr'` somewhere in it, in order for HMR to continue working on SSR enabled apps.
 
 ### Mountpoint defined by the view
 
@@ -136,3 +180,4 @@ Then you _DON'T_ add your ssr outlet like this:
 ```
 
 And you make sure that the root-node of your view has `id="app"`.
+

package/index.d.ts

@@ -0,0 +1,10 @@
+import { type PluginOption } from "vite"
+
+export interface HyperappPluginOptions {
+  hmr?: boolean
+  dispatchExport?: string
+}
+
+export default function hyperapp(
+  options?: HyperappIntegrationOptions,
+): PluginOption

package/jsx.d.ts

@@ -0,0 +1,59 @@
+import type { Props, MaybeVNode, ElementVNode } from "hyperapp"
+
+type Component<S, P> = (
+  props: P,
+  children: MaybeVNode<S>[],
+) => MaybeVNode<S> | MaybeVNode<S>[]
+
+type _JSXChild<S> = string | number | MaybeVNode<S>
+type JSXChild<S> = _JSXChild<S> | _JSXChild<S>[]
+
+export declare function jsx<S>(
+  type: string,
+  props?: Props<S>,
+  ...children: JSXChild<S>[]
+): ElementVNode<S>
+
+export declare function jsx<S, P>(
+  type: Component<S, P>,
+  props?: P | null,
+  ...children: JSXChild<S>[]
+): ReturnType<Component<S, P>>
+
+export declare function jsxFragment<S>(
+  _: any,
+  children: JSXChild<S>[],
+): MaybeVNode<S>[]
+
+declare global {
+  namespace JSX {
+    /** Result of a JSX expression. Components may return arrays. */
+    type Element = MaybeVNode<any> | MaybeVNode<any>[]
+
+    /** What you can put in the `<X />` position */
+    type ElementType = string | Component<any, any>
+
+    /** Allow `<>...</>` fragments; returns an array */
+    type Fragment = MaybeVNode<any>[]
+
+    /** Intrinsic (HTML/SVG) elements. */
+    interface IntrinsicElements {
+      [elem: string]: Props<any>
+    }
+
+    /** prevents errors about children missing from props in components */
+    type LibraryManagedAttributes<P> = P & { children?: JSXChild<any>[] }
+  }
+}
+
+// make jsx and jsxFragment ambient globals because
+// ts server doesn't know I'll add them later in transform
+type JsxFn = typeof jsx
+type JsxFragmentFn = typeof jsxFragment
+
+declare global {
+  const jsx: JsxFn
+  const jsxFragment: JsxFragmentFn
+}
+
+export {}

package/jsx.js

@@ -1,13 +1,13 @@
 import { h, text } from "hyperapp"
 
-const nodeify = x =>
-  (typeof x === "string") | (typeof x === "number") ? text(x) : x
+const cproc = children =>
+  children
+    .flat()
+    .map(x => ((typeof x === "string") | (typeof x === "number") ? text(x) : x))
 
-export const jsxNode = (tag, props, ...children) =>
+export const jsx = (tag, props, ...children) =>
   typeof tag === "function"
-    ? tag(props, children)
-    : h(tag, props || {}, children.flat(2).map(nodeify))
+    ? tag(props, cproc(children))
+    : h(tag, props || {}, cproc(children))
 
-export const jsxFragment = (_, children) => {
-  return children.flat(2).map(nodeify)
-}
+export const jsxFragment = (_, children) => cproc(children)

package/package.json

@@ -1,16 +1,51 @@
 {
   "name": "vite-plugin-hyperapp",
-  "version": "1.1.1",
+  "version": "1.2.0",
   "type": "module",
   "description": "Plugin and helpers for using Hyperapp with Vite",
-  "main": "index.js",
+  "main": "./index.js",
   "scripts": {
     "test": "echo \"Error: no test specified\" && exit 1"
   },
   "author": "Zacharias Enochsson",
   "license": "MIT",
+  "files": [
+    "*.js",
+    "*.d.ts"
+  ],
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "import": "./index.js",
+      "default": "./index.js"
+    },
+    "./jsx": {
+      "types": "./jsx.d.ts",
+      "import": "./jsx.js",
+      "default": "./jsx.js"
+    },
+    "./jsx.js": {
+      "types": "./jsx.d.ts",
+      "import": "./jsx.js",
+      "default": "./jsx.js"
+    },
+    "./ssr": {
+      "types": "./ssr.d.ts",
+      "import": "./ssr.js",
+      "default": "./ssr.js"
+    },
+    "./ssr.js": {
+      "types": "./ssr.d.ts",
+      "import": "./ssr.js",
+      "default": "./ssr.js"
+    },
+    "./package.json": "./package.json"
+  },
   "dependencies": {
     "jsdom": "^24.1.0",
     "hyperapp": "^2.0.22"
+  },
+  "peerDependencies": {
+    "vite": "^4.5.14"
   }
 }

package/ssr.d.ts

@@ -2,7 +2,7 @@ import { Subscription } from "hyperapp"
 
 type Defs<S = any> = {
   init?: Dispatchable<S>
-  view?: (state: S) => ElementVNode<S>
+  view?: (state: S) => VNode<S>
   subscriptions?: (state: S) => Subscription<S>[]
   dispatch?: (d: Dispatch<S>) => Dispatch<S>
 }

package/jsx-runtime.d.ts

@@ -1,11 +0,0 @@
-/*
-  This type declaration is named 'jsx-runtime.d.tx' even though
-  jsx is compiled in the classic way. It's only named this to make
-  it easier for tsconfig.json to be ok with jsx in .tsx-files.
-*/
-import { Props } from "hyperapp"
-declare global {
-  module JSX {
-    type IntrinsicElements = Record<string, Props<any>>
-  }
-}