Skip to content
Henceforth Docs

Compile HFX source to a JS ES module inline.

POST
/hfx/compile
curl --request POST \
  --url https://example.com/hfx/compile \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "sidecar": "example", "source": "example" }'

Authorizations

Section titled “Authorizations”

Request Bodyrequired

Section titled “Request Bodyrequired”

Request body for POST /hfx/compile.

Media typeapplication/json

Request body for POST /hfx/compile.

object
sidecar

Optional TypeScript sidecar source. When present, compiled to JS alongside the HFX module and made available as ./sidecar import inside the iframe.

string | null
source
required

HFX source text authored by the Playground editor.

string
Examplegenerated
{
  "sidecar": "example",
  "source": "example"
}

Responses

Section titled “Responses”

200

Section titled “200”

Compiled JS module (and optional sidecar), plus content hash.

Media typeapplication/json

Success response for POST /hfx/compile.

Per SPEC-UI-0043 “Compile endpoint”, the client receives the compiled JS inline in the response body and assembles the iframe srcdoc around it. contentHash lets the client short-circuit re-POSTing identical source on repeat compiles (e.g., a no-op edit).

warnings is reserved for future non-fatal diagnostics (e.g., deprecated component usage); always empty for MVP.

object
compiledJs
required

Compiled JavaScript ES module source, ready to be embedded in a <script type="module"> tag inside an iframe srcdoc.

Bare import specifiers have been rewritten to /hfx/vendor/* URLs; the component is accessible as the module’s default export.

string
compiledSidecar

Compiled sidecar JavaScript, if a sidecar was provided.

string | null
contentHash
required

16-hex-character SHA-256 prefix of the HFX source.

Exposed so the client can detect no-op compiles across requests. The server’s internal cache key ([cache_key]) additionally carries a -pg-v{EMITTER_ABI_VERSION}-g{grammar_version} suffix: the -pg- token distinguishes this Playground-profile compile from the runtime-profile cache used by GET /hfx/modules/{file}, EMITTER_ABI_VERSION invalidates entries when the rewrite policy changes (D-G decision), and the grammar version invalidates entries when the declared HFX language version changes (R3). That suffix is NOT reflected here.

string
warnings
required

Non-fatal diagnostic messages. Empty for MVP.

Array<string>
Examplegenerated
{
  "compiledJs": "example",
  "compiledSidecar": "example",
  "contentHash": "example",
  "warnings": [
    "example"
  ]
}

default

Section titled “default”

Structured error envelope (SPEC-DATA-0006): {"errors": [{"scope", "target", "code", "message"}, ...]}.

Media typeapplication/json

The top-level response body. Wraps a non-empty list of [ErrorEntry].

object
errors
required

The error entries making up the envelope. Always non-empty.

Array<object>

One entry in the error envelope.

Carries an anchoring [ErrorScope], an optional target that disambiguates within the scope, a stable SCREAMING_SNAKE_CASE code, and a human-readable English message. See SPEC-DATA-0006 for the full envelope contract.

object
code
required

Machine-readable, stable, SCREAMING_SNAKE_CASE identifier.

string
location
Any of:

HFX source location for a [DataError::HfxCompileError] entry.

Emitted as the extra location field on the entry JSON when present, per SPEC-UI-0043. The line/column are 1-based. The frame is the offending source line extracted verbatim from the input.

object
column
required

1-based column within the line, measured in UTF-16 code units of the prefix so browser-side editors can consume it directly.

integer format: uint32
frame

The offending source line text, when available.

string | null
line
required

1-based line number within the source text.

integer format: uint32
message
required

Server-authored English message. Not part of the API contract; may change across releases without notice.

string
rule

The key of the ValidationRule that failed, when the code is RULE_FAILED. None for all other codes.

Skipped during serialization when absent so it does not appear on unrelated entries (same pattern as location).

Documented here as a plain string (#[schemars(with = "...")]) rather than a $ref to ValidationRuleKey’s own schema: that type lives in metadata-types, which does not derive JsonSchema yet (tracked by #812). ValidationRuleKey serializes transparently as its inner string (serde’s default newtype-struct behavior), so this is an accurate wire-shape description, not a placeholder.

string | null
scope
required

Anchoring category. Drives client-side rendering.

One of:

Attached to a specific request field. target is the field key.

string
Allowed value: field
target

Field key for field scope, record id for record scope, null otherwise. Always serialized, even when null.

string | null
Example
{
  "errors": [
    {
      "scope": "field"
    }
  ]
}