Hacktoberfest 2026: những issue maintainer đã đánh dấu cho tháng Mười, đang mở và phù hợp người mới. Xem issue Hacktoberfest

docs(adr): ADR-0010: Server-Side Reference Implementation Scripts

Đang mở
  • Có gì không ổn?
#18 0 bình luận 0 reaction 1 người được giao Xem trên GitHub

@aRustyDev đang làm issue này rồi.

Từ ngày 5/1/2026.

Đánh giá

Issue này chưa được đánh giá.

Mô tả

documentation

ADR-0010: Server-Side Reference Implementation Scripts

Status

Accepted

Context

mdbook-htmx generates static files (HTML, JSON manifests, search indexes) but requires server-side logic to:

  • Serve appropriate content based on HX-Request header
  • Implement search endpoints
  • Handle authentication/authorization
  • Manage scope switching

Users need guidance on implementing these server-side behaviors. The question: should the backend generate reference implementation scripts?

Decision Drivers

  1. Developer Experience - Reduce time-to-working-deployment
  2. HTMX Philosophy - Server-side code is expected and encouraged
  3. Portability - Scripts should work across runtimes (Workers, Node, Deno)
  4. Maintainability - Reference code needs ongoing updates
  5. Flexibility - Users may have different server frameworks

Decision

Generate TypeScript reference implementation scripts in book/htmx/scripts/.

These scripts are:

  • Reference implementations, not required
  • TypeScript for type safety and self-documentation
  • Runtime-agnostic (work with Workers, Node, Deno, Bun)
  • Framework-agnostic (use Web APIs, adapt to Hono/Express/etc.)

HTMX Alignment

This decision is fully aligned with HTMX philosophy:

Principle How Scripts Align
Server returns HTML Scripts render HTML responses
Minimal client-side JS Zero client-side code in scripts
Server is source of truth Scripts manage state, auth, scope
Progressive enhancement Scripts serve full pages and fragments

HTMX's "minimal JS" applies to the client. Server-side code in any language is expected.

Output Structure

book/htmx/scripts/
├── types.ts              # Shared type definitions
├── manifest-loader.ts    # Load and cache manifests
├── search.ts             # Search endpoint handler
├── authn.ts              # Authentication middleware
├── authz.ts              # Authorization middleware
├── scope.ts              # Scope switching logic
├── htmx-utils.ts         # HX-Request detection, OOB helpers
├── meili-proxy.ts        # Meilisearch proxy (if external search enabled)
└── README.md             # Usage documentation

Deployment Patterns

These scripts support multiple deployment architectures:

In-Memory Search (Simple Sites)

Worker bundles search index directly:

import searchIndex from "./search-index.json";
// Use Fuse.js/MiniSearch with bundled index
External Search via Cloudflare Tunnel (Recommended for Production)

Worker acts as policy enforcement proxy to self-hosted Meilisearch:

Worker → Cloudflare Tunnel → Private Meilisearch

Key security properties:

  • Meilisearch never internet-facing
  • Worker validates auth before searching
  • Query inputs sanitized (length limits, filter whitelists)
  • API keys server-side only (never sent to browser)
  • Results authorization-filtered at runtime

See examples/meilisearch-cf-tunnel.md for complete implementation.

Script Contents

types.ts
// Generated from manifest schema
export interface Page {
  path: string;
  title: string;
  file: string;
  fragment: string;
  auth: {
    access: 'public' | 'authenticated' | 'roles';
    roles?: string[];
    fallback?: string;
  };
  scopes: string[];
}

export interface Manifest {
  version: string;
  generated: string;
  scopes: {
    available: string[];
    default: string;
  };
  pages: Page[];
  navigation: NavigationItem[];
}

export interface User {
  id: string;
  roles: string[];
  preferences?: {
    scope?: string;
  };
}
htmx-utils.ts
export function isHtmxRequest(request: Request): boolean {
  return request.headers.get('HX-Request') === 'true';
}

export function oobSwap(id: string, content: string): string {
  return `<div id="${id}" hx-swap-oob="true">${content}</div>`;
}

export function htmxRedirect(url: string): Response {
  return new Response(null, {
    status: 200,
    headers: { 'HX-Redirect': url }
  });
}
authz.ts
import type { Page, User } from './types';

export function isAuthorized(user: User | null, page: Page): boolean {
  switch (page.auth.access) {
    case 'public':
      return true;
    case 'authenticated':
      return user !== null;
    case 'roles':
      return page.auth.roles?.some(role => user?.roles?.includes(role)) ?? false;
    default:
      return false;
  }
}

Configuration

[output.htmx.scripts]
enabled = true                    # Generate reference scripts
language = "typescript"           # typescript | javascript
runtime = "workers"               # workers | node | deno | bun
framework = "hono"                # hono | express | none

Consequences

Positive
  • Faster time-to-deployment
  • Types document the manifest schema
  • Consistent patterns across deployments
  • Testable reference implementations
Negative
  • Maintenance burden (scripts need updates)
  • May not fit all server architectures
  • Users might copy without understanding
Mitigation
  • Clear "reference implementation" labeling
  • Extensive inline documentation
  • Integration tests in mdbook-htmx repo
  • Version scripts with manifest schema

Alternatives Considered

No Scripts (Documentation Only)

Provide patterns in docs, no generated code.

Rejected because:

  • Higher barrier to entry
  • Documentation drifts from actual implementation
  • Users reinvent the wheel
Generate Full Server Application

Generate complete deployable server.

Rejected because:

  • Too opinionated
  • Hard to customize
  • Framework lock-in

References

Ngôn ngữ chính
Rust
Star
0
Fork
1
Không có pull request nào được merge trong 30 ngày

Chuẩn bị môi trường

Bắt đầu từ đâu

  1. Đọc hết issue, rồi đọc hướng dẫn đóng góp của dự án.
  2. Bình luận trên issue rằng bạn sẽ nhận — tránh hai người làm cùng một việc.
  3. Fork repository và làm thay đổi trên một nhánh.
  4. Mở pull request có tham chiếu số hiệu của issue.

Issue khác của aRustyDev/mdbook-htmx

Tất cả issue của aRustyDev/mdbook-htmx

Issue tương tự

Thêm issue về Rust

Nhận issue mới trong hộp thư của bạn

Bản tóm tắt ngắn những issue GitHub phù hợp với người mới.