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-0011: TypeScript for Reference Implementation Scripts

Đang mở
  • Có gì không ổn?
#19 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-0011: TypeScript for Reference Implementation Scripts

Status

Accepted

Context

ADR-0010 establishes that mdbook-htmx generates server-side reference scripts. This ADR addresses the language choice: TypeScript vs JavaScript.

Decision Drivers

  1. Self-Documentation - Types describe manifest schema without separate docs
  2. Error Prevention - Catch type mismatches at compile time
  3. IDE Support - Autocomplete, refactoring, go-to-definition
  4. Runtime Compatibility - Must work in Workers, Node, Deno, Bun
  5. User Accessibility - Not all users know TypeScript

Options Considered

Option A: JavaScript Only

Plain JavaScript with JSDoc comments for types.

/**
 * @param {import('./types').User | null} user
 * @param {import('./types').Page} page
 * @returns {boolean}
 */
function isAuthorized(user, page) {
  return page.auth.access === 'public' || user !== null;
}

Pros:

  • No build step
  • Universally understood
  • Runs directly in Node

Cons:

  • Types are comments, not enforced
  • Verbose JSDoc for complex types
  • Less IDE support than native TS
Option B: TypeScript (Recommended)

TypeScript with explicit types.

import type { User, Page } from './types';

function isAuthorized(user: User | null, page: Page): boolean {
  return page.auth.access === 'public' || user !== null;
}

Pros:

  • Types are enforced
  • Self-documenting
  • Excellent IDE support
  • Catches errors before runtime
  • Industry standard for server-side code

Cons:

  • Requires build step
  • Learning curve for some users
Option C: Both (Generate TS, Transpile to JS)

Generate TypeScript, also include transpiled JavaScript.

book/htmx/scripts/
├── src/                 # TypeScript source
│   └── *.ts
├── dist/                # Transpiled JavaScript
│   └── *.js
└── types/               # Declaration files
    └── *.d.ts

Pros:

  • TypeScript users get native TS
  • JavaScript users get working code
  • Type definitions available for both

Cons:

  • Larger output
  • Two versions to maintain conceptually

Decision

TypeScript as default, with JavaScript output option.

Default configuration:

[output.htmx.scripts]
language = "typescript"
emit-js = false           # Also emit transpiled JS
emit-declarations = true  # Emit .d.ts files

Users can set language = "javascript" for plain JS output with JSDoc.

Rationale

  1. Types Document the Manifest

    // Types ARE the documentation
interface Page {
  auth: {
    access: 'public' | 'authenticated' | 'roles';
    roles?: string[];
  };
}

    Users reading the code understand the manifest structure without separate docs.

  2. Cloudflare Workers Natively Supports TypeScript

    # wrangler handles TypeScript automatically
wrangler deploy

    No separate build step for the primary deployment target.

  3. Error Prevention

    // Caught at compile time
if (page.auth.access === 'admin') {  // Error: 'admin' not in union type

  4. Modern Standard

    TypeScript is the de facto standard for:

    • Cloudflare Workers
    • Deno (native support)
    • Node.js server applications
    • Most modern web frameworks

Bundle Size Considerations

TypeScript transpiles to JavaScript with zero runtime overhead:

Metric TypeScript Transpiled JS
Bundle size N/A (source) Same as hand-written JS
Runtime perf N/A Identical
Types at runtime Erased None

The type imports are completely removed:

// Source
import type { Page } from './types';

// Transpiled - import disappears

Configuration

[output.htmx.scripts]
enabled = true
language = "typescript"           # typescript | javascript

# TypeScript options
target = "es2022"                 # ECMAScript target
module = "esm"                    # esm | commonjs
strict = true                     # Strict type checking
emit-js = false                   # Also generate .js files
emit-declarations = true          # Generate .d.ts files

Consequences

Positive
  • Types serve as schema documentation
  • Compile-time error catching
  • Better IDE experience
  • Industry-standard choice
  • Native Workers/Deno support
Negative
  • Some users unfamiliar with TypeScript
  • Build step required for Node.js (unless using ts-node)
Mitigation
  • Include transpiled JS as option (emit-js = true)
  • Provide tsconfig.json with recommended settings
  • Document common TypeScript patterns

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.