Hyperapp Integration for Astro
Allows you to add client-side-interactive islands in your astro apps using hyperapp, with jsx if you want it.
Does not yet support HMR and TS/TSX
Demo: https://stackblitz.com/github/zaceno/astrojs-hyperapp-demo
Installation:
In your astro project:
> npm install @zxlabs/astrojs-hyperappIn your astro.config.mjs:
import { defineConfig } from "astro/config"
import hyperapp from "@zxlabs/astrojs-hyperapp"
export default defineConfig({
integrations: [hyperapp()],
})Note on mixing with other ui frameworks
If you're using jsx for your components, and also use other frameworks that use jsx, you need to explicitly tell the integrations which files it should include or exclude using picomatch patterns.
This might require you to use some naming convention or folder structure to make it possible to separate components from different frameworks
import { defineConfig } from "astro/config"
import hyperapp from "@zxlabs/astrojs-hyperapp"
import preact from "@astrojs/preact"
export default defineConfig({
integrations: [
hyperapp({ include: ["**/hyperapp/*"] }), //exclude option also possible
preact({ include: ["**/preact/*"] }), //exclude option also possible
],
})Authoring islands
In astrojs, an 'island' is a part of a page that is hooked up to a client-side framework
for interactivity. Each of our islands will be activated (or "hydrated") with a call to
Hyperapp's app(...) function.
An island module needs to default-export a function that optionally takes some server-side
props, and returns an object we could pass to Hyperapp's app() – except the node prop,
which will be provided by this integration.
/src/components/counter.jsx
export default const serverProps => ({
init: serverProps.startCount || 0,
view: value => (
<div class="counter">
<h1>{value}</h1>
<button onclick={x => x - 1}>-</button>
<button onclick={x => x + 1}>+</button>
</div>
),
// could also define these props:
// subscriptions: ...
// dispatch: ...
})Using islands on a page:
With a island thus defined, the we can use hyperapp to render the component (both server side and hydrate client side), in our astro-components like this:
/src/pages/index.astro
---
import Counter from '../components/counter.jsx'
---
<!doctype html>
<html>
<head></head>
<body>
<p> Here is the counter, starting at 5</p>
<Counter client:load startCount={5} />
</body>
</html>Note how the props passed in to the island in the astro-component,
are available in the serverProps we defined in the counter.
Passing static content to islands
You can pass static content from astro components in to your islands, for example to control hiding/showing the content.
index.astro
---
import ContentToggle from '../components/ContentToggle.jsx'
---
<p> Click to reveal contents:</p>
<ContentToggle client:load>
<p class="red">
This text his hidden by default. And red.
</p>
</ContentToggle>
<style>
.red {
color: red;
}
</style>ContentToggle.jsx
export default (props, content) => ({
init: false,
view: showing => (
<div style={{border: '1px black solid'}}>
<button onclick={showing => !showing}>
{showing ? 'Hide' : 'Show'}
</button>
<div>
{showing && content}
</div>
)
})This is the default behavior for all content not specifically slotted. You can also
set a html node to appear in a specific slot with the slot attribute. Such content
is passed to the island in a property named as the slot:
index.astro
---
import ContentToggle from '../components/ContentToggle.jsx'
---
<p> Click to reveal contents:</p>
<ContentToggle client:load>
<p class="red">
This text his hidden by default. And red.
</p>
<p slot="footer">This footer text is always visible</div>
</ContentToggle>
<style>
.red {
color: red;
}
</style>ContentToggle.jsx
export default (props, content) => ({
init: false,
view: showing => (
<div style={{border: '1px black solid'}}>
<button onclick={showing => !showing}>
{showing ? 'Hide' : 'Show'}
</button>
<div>
{showing && content}
{props.footer}
</div>
)
})Slot-names need to be given as snake/kebab case (e.g slot="kebab-case" or slot="snake_case") but
in .astro files (in order to be html-compliant). But for your convenience, such names are transformed to
camelCase (e.g. props.kebabCase or props.snakeCase) in the props passed to the island.
Sharing state between islands
Since each island will be it's own instance of a hyperapp-app they will not share state. Astro recommends using nanostores for sharing states, and that is a perfectly good option. You will just have to write your own effects/subscriptions.
Another option is to use state synchronization utility shipped with this integration.
With this, you define a headless "master-app" by providing an
init prop and optionally subscriptions and dispatch (for middleware). It will return
a function which islands can use to simply provide their view-funcitons. Although they will
be rendered as separate islands (and technically individual app-instances), their state
will be shared.
island1.jsx
import syncedIslands from '@zxlabs/astrojs-hyperapp/synced-islands'
//define a syncer for islands 1 and 2
export const sync = syncedIslands({
init: ... // initial states and effects
subscriptions: ... // optional
dispatch: ... // optional
})
// This is the same as defining a regular island,
// but init and dispatch props are provided by
// the island-function, to sync the state
// with the headless master.
export default props => sync(state => (
<section class="info">
...
</section>
))island2.jsx
import {sync} from './island1.jsx'
const DoSomething = state => ... // state will be as defined by master
export default props => sync(state => (
<button onclick={DoSomething}>...</button>
))