Hyperapp

Common errors

• ReferenceError: require is not defined

  cause Attempting to use CommonJS `require()` syntax to import Hyperapp in an ES Module context (e.g., modern browser, Node.js with `"type": "module"`).
  fix Use ES Module `import` syntax: `import { app, h, text } from 'hyperapp'`. Ensure your project's `package.json` has `"type": "module"` or your build setup correctly handles ESM.

• Property 'name' does not exist on type 'VNode' or 'Property 'props' does not exist on type 'VNode'

  cause Accessing deprecated VNode property names (`name`, `props`) from Hyperapp v1.0.0 or earlier after upgrading to Hyperapp v1.1.0 or later.
  fix Update VNode property accessors in your code from `vnode.name` to `vnode.nodeName` and from `vnode.props` to `vnode.attributes`.

• TypeError: app expects a function as the first argument, not an object

  cause Attempting to initialize the `app` function with an outdated signature, specifically prior to v0.15.0 which introduced the single configuration object, or if providing arguments in the v1.x `app(state, actions, view, node)` style to v2.x.
  fix Ensure the `app` function is called with a single configuration object containing `init`, `view`, and `node` properties, as required since Hyperapp v0.15.0 and refined in v2.0.0. Example: `app({ init: {}, view: () => h('div'), node: document.body })`.

Warnings

• breaking Hyperapp v1.1.0 introduced a breaking change to the internal VNode schema, renaming `name` to `nodeName` and `props` to `attributes` to align with Preact's virtual nodes. Direct access to these properties in custom VNode processing or component libraries will break.
  Fix: Update any code directly accessing VNode properties from `vnode.name` to `vnode.nodeName` and `vnode.props` to `vnode.attributes`.
• breaking Hyperapp v0.15.0 introduced the `init(state, actions)` function, which significantly changed how applications are initialized and how global events or subscriptions are handled, replacing older patterns.
  Fix: Migrate application initialization logic to use the `init` function within the main `app` configuration object, and define subscriptions and effects within this new structure. For v2.0.0+, the `init` property is part of the main config object.
• breaking Hyperapp v0.14.0 brought substantial breaking changes, including simplified state management with 'state slices', replaced events with direct DOM event handling, and removed mixins for code clarity. Code relying on previous event systems or mixins will cease to function.
  Fix: Refactor state management to align with the state slices approach and update event handlers to use direct DOM event methods. Remove any usage of mixins.
• breaking Hyperapp v2.0.0 introduced new core features like Effects and Subscriptions, and an enhanced Dispatch mechanism. While adding capabilities, the overall architecture and how state/actions/effects interact became more structured, potentially requiring refactoring for existing v1.x applications.
  Fix: Consult the v2.0.0 tutorial and reference documentation to adapt existing state, actions, and effects to the new API and lifecycle methods. Pay attention to how state is updated and how side effects are managed.
• gotcha Modern Hyperapp (v2.0.0 and above) is primarily designed for ES Module (ESM) environments, as indicated by its documentation and examples using `import` statements. Attempting to use CommonJS `require()` syntax directly in a browser or non-transpiled Node.js environment will result in module resolution errors.
  Fix: Ensure your project is configured to use ES Modules, either by setting `"type": "module"` in your `package.json`, using a bundler (like Vite, Webpack, Rollup), or serving your scripts with `type="module"` in HTML.

Install

• npm install hyperapp npm
• yarn add hyperapp yarn
• pnpm add hyperapp pnpm

Imports

• app
  wrong:

  const { app } = require('hyperapp')

  correct:

  import { app } from 'hyperapp'

  Main entry point for initializing a Hyperapp application. ESM imports are standard since v2.0.0.
• h
  wrong:

  import h from 'hyperapp'

  correct:

  import { h } from 'hyperapp'

  The hyperscript function for creating virtual DOM nodes. It's a named export.
• text
  wrong:

  import { Text } from 'hyperapp'

  correct:

  import { text } from 'hyperapp'

  Utility function for creating text virtual DOM nodes. Case-sensitive named export.

Quickstart

This quickstart demonstrates how to set up a simple to-do list application using Hyperapp, including state management, event handling, and rendering with `h` and `text` functions.

import { h, text, app } from "hyperapp";

interface State {
  todos: string[];
  value: string;
}

const AddTodo = (state: State): State => ({
  ...state,
  value: "",
  todos: state.todos.concat(state.value),
});

const NewValue = (state: State, event: Event & { target: HTMLInputElement }): State => ({
  ...state,
  value: event.target.value,
});

// Ensure a root element exists in the DOM
const root = document.getElementById("app") || document.createElement("main");
if (!document.getElementById("app")) {
  root.id = "app";
  document.body.appendChild(root);
}

app<State>({
  init: { todos: [], value: "" },
  view: ({ todos, value }) =>
    h("main", {}, [
      h("h1", {}, text("To do list")),
      h("input", { type: "text", oninput: NewValue, value }),
      h(
        "ul",
        {},
        todos.map((todo) => h("li", {}, text(todo)))
      ),
      h("button", { onclick: AddTodo }, text("New!")),
    ]),
  node: root,
});