Hacktoberfest 2026: le issue che i maintainer hanno segnato per ottobre, aperte e adatte ai principianti. Sfoglia le issue Hacktoberfest

docs(adr): ADR-0011: TypeScript for Reference Implementation Scripts

Aperta
  • Qualcosa non va?
#19 0 commenti 0 reazioni 1 assegnatario Vedi su GitHub

@aRustyDev ci sta già lavorando.

Dal 5/1/2026.

Valutazione

Questa issue non è ancora stata valutata.

Descrizione

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

Lingua principale
Rust
Stelle
0
Fork
1
Nessuna PR unita negli ultimi 30g

Preparare l'ambiente

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di aRustyDev/mdbook-htmx

Tutte le issue di aRustyDev/mdbook-htmx

Issue simili

Altre issue su Rust

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.