html.js
htmx.js is the server-side js framework for HTMX. Build modern hyper-speed web apps and web sites with minimal fuss.
A html.js app is server side js that returns html to the browser. It's a back-to-the-future web stack. There are several things that make the html.js approach unique:
The foundations of html.js are built using the following excellent libraries. Get familiar with them, they're your new best friends:
I'df you're planning to deploy to Cloudflare Workers, get familiar with the Workers docs.
This tutorial covers the basics of html.js. If you want to see a more feature complete app checkout the htmljs-todo-example repo.
The simplest html.js is single js file which contains your routing, layout and views. To get started, we use Hono's create command. You can choose any deploy target you like. We like cloudflare-workers or nodejs for simplicity:
npm create hono@latest my-app
Now open up src/index.js and let's create a simple app:
import { Hono } from 'hono';
import { html } from 'hono/html';
import { rootLayout, view } from 'htmxjs';
const db = {
posts: {
1: { title: 'Hello World', body: 'This is my first post' },
},
};
const app = new Hono();
app.use('*', rootLayout(AppLayout));
app.get('/post/:id', view(GetBlogPost));
const GetBlogPost = async ({ context }) => {
const { id } = context.req.param();
const post = db.posts[id]; // Replace with your own db call
return (
<article>
<h1>{post.title}</h1>
<p>{post.body}</p>
</article>
);
};
const AppLayout = ({ context, children }) => html`
<html>
<head>
<meta charset="UTF-8" />
<title>html.js</title>
</head>
<body>
${props.children}
</body>
</html>
`;
export default app;
Take note of a few interesting things here:
Let's improve the code by separating out the jsx GetBlogPost returns into a new jsx function called BlogPost:
const BlogPost = async ({ post, linked }) => (
<article>
<h1>{linked ? <a href={`/post/{post.id}`}>{post.title}</a> : post.tit;e}</h1>
<p>{post.body}</p>
</article>
)
const GetBlogPost = async ({ context }) => {
const { id } = context.req.param()
const post = db.posts[id]; // Replace with your own db call
return <BlogPost post={post} />
}
Now we can reuse BlogPost in another function if we like. Remember, jsx is a function, so return <BlogPost post={post} /> can also be written as return BlogPost({ post }).
As you app grows, we recommend moving realted jsx functions into their own files in a folder (we like to use routes/). For example, you could create a file called routes/blog.js and move BlogPost and GetBlogPost into it. If you wanted to follow an MVC pattern, you could move GetBlogPost into a controllers/ folder and BlogPost into a views/ folder. You can even split your routes into multiple files using Hono's grouping feature.
Now, let's add a list of blog posts to the homepage:
app.get('/', view(ListBlogPosts));
const ListBlogPosts = async ({ context }) => {
const posts = db.posts; // Replace with your own db call
return (
<div id="main">
{posts.map((post) => (
<BlogPost post={post} linked={true} />
))}
</div>
);
};
Currently our app will work great as a regular website with a full page load when clicking links. Let's upgrade this to a fast ajax driven experience using the htmx library. Add the htmx script tag to your AppLayout <head>: <script src="https://unpkg.com/htmx.org@^1"></script>
htmx lets you turn regular links and form submissions into js driven ajax requests. The server responds with HTML, and htmx lets you specify where in the page this updated HTML should be inserted. You do this by adding hx- attributes to your HTML.
The simplest htmx feature is hx-boost="true". This turns a link or form into an ajax request, and htmx replaces the whole page body with the response. E.g. <a href="/"hx-boost="true">Home</a>. We recommend using hx-boost="true" as the default link behaviour in html.js. It's especially helpful to use hx-boost when a form updates data that appears in multiple places on the page, as the whole page will be updated.
htmx really shines when you make use of hx-target alongside the hx-get, hx-post, hx-put and hx-delete attributes. hx-target lets you specify a CSS selector to insert the response into. E.g. <a href="/post/1" hx-target="#main">Post 1</a>. This will insert the response into the element with the id main. This is great for updating a only the part of the page which needs to change. You can also use hx-swap="outerHTML" to replace the element itself. hx-get etc. are used to specify the HTTP method and URL to request.
Let's change our blog post links to replace the #main div with the response:
const BlogPost = async ({ post, linked }) => (
<article>
<h1>
{linked ? (
<a hx-get={`/post/{post.id}`} hx-target="#main">
{post.title}
</a>
) : (
post.title
)}
</h1>
<p>{post.body}</p>
</article>
);
But how does the server know when to return the full page including the AppLayout, or just the BlogPost view? That's where our rootLayout(), layout() and view() html.js functions come in. They check for HX-Request, HX-Boosted and HX-Target headers, and appropriately return the full page or just the view.
We can make our links cleaner by writing a Link jsx function. html.js includes two helpful functions: Link and Form.
export const Link = ({
to,
'hx-target': hxTarget,
class: className,
children,
}) => {
if (hxTarget) {
return html`<a
href="${to}"
class="${className}"
hx-get="${to}"
hx-target="${hxTarget}"
hx-push-url="true"
>${children}</a
>`;
} else {
return html`<a href="${to}" class="${className}" hx-boost="true"
>${children}</a
>`;
}
};
Now you can simply write <Link to="/post/1" hx-target="#main">Post 1</Link> and the correct htmx attributes will be added when hxTarget is passed. We also add hx-push-url="true" to make the browser history update. You may also want to add hx-swap which specifies a merge strategy for updating the HTML. We recommend Idiomorph lib which requires the hx-swap="morph" attribute.
Now you've seen the basics of a html.js app, you probably want to learn see what a more feature complete app looks like. Checkout the htmljs-todo-example repo which uses html.js deployed to Cloudflare Workers with Cloudflare D1 SQLite database and tailwindcss.
Hono and htmx have many powerful features which we haven't covered here. We recommend reading the Hono docs and htmx docs.
html.js is currently the small single js file src/htmljs.js you see in this repo. Simply copy it into your app (alongside hono and htmx). We'll be releasing as an npm package once we have stabilized the design decicions. We're also working on a CLI tool to help you get started with a new html.js app.
html.js is in its infancy. If you think it's exciting, please contribute!
FAQs
htmxjs is the server-side js framework for HTMX
The npm package htmxjs receives a total of 2 weekly downloads. As such, htmxjs popularity was classified as not popular.
We found that htmxjs demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
PyPI confirms no security flaws were exploited in the Ultralytics supply chain attack and highlights improvements for safer package publishing.
Security News
Research
The Socket Research Team breaks down a malicious wrapper package that uses obfuscation to harvest credentials and exfiltrate sensitive data.
Research
Security News
Attackers used a malicious npm package typosquatting a popular ESLint plugin to steal sensitive data, execute commands, and exploit developer systems.