@dx/alpine-server

⚠️ EXPERIMENTAL: This library is in early development and highly experimental. APIs may change without notice. Not recommended for production use.

A secure, experimental Hono web server optimized for serving Alpine.js applications with built-in development tools, security hardening, and automatic hot-reloading.

Supported runtimes

Runtime	Supported	Notes
Deno	✅	2.x
Node.js	✅	>= 22.18 (runs .ts files natively; older 22.x need a build step or tsx)
Bun	✅	1.x
Cloudflare Workers	❌	The server reads files from disk and watches them in dev mode.

Installation

deno add jsr:@dx/alpine-server      # Deno
npx jsr add @dx/alpine-server       # Node.js
bunx jsr add @dx/alpine-server      # Bun

On Node.js and Bun, jsr add installs the package through JSR's npm registry and adds @jsr:registry=https://npm.jsr.io to .npmrc.

Running

Put the example below into app.ts and start it with your runtime:

deno run --allow-net --allow-read app.ts   # Deno
node app.ts                                # Node.js (ESM: set "type": "module" in package.json)
bun app.ts                                 # Bun

The server listens on port 8000 by default on every runtime. Pass an AbortSignal as listenOptions.signal to shut it down; run() resolves once it has stopped.

Example

import { AlpineApp } from '@dx/alpine-server';

const app = new AlpineApp({
  app: {
    dev: true,
    staticFilesPath: './public',
  },
  server: {
    listenOptions: { port: 3000 },
  },
});

await app.run();

CLI

The scaffolding CLI runs on Deno and generates a Deno project. Create a new Alpine Server project scaffold:

deno run -A jsr:@dx/alpine-server/cli new my-app

Or with Deno 2.7+ create templates:

deno create jsr:@dx/alpine-server -- my-app

With options:

deno run -A jsr:@dx/alpine-server/cli new my-app --port 3000 --force

deno create jsr:@dx/alpine-server -- my-app --port 3000 --force

Local CLI (alp)

After creating a project, the local CLI is available as a Deno task:

deno task alp add about
deno task alp add contact --force

For global usage, install with:

deno install -gA jsr:@dx/alpine-server/cli --name alp

Then use directly:

alp new my-app
cd my-app
alp add about

Documentation

For more detailed information, please refer to the documentation in the docs folder:

• Usage
• Configuration

License

MIT

Contributing

Contributions welcome!