VIP-39: .vibex, VibeLang with JSX

Status: accepted by Will, 2026-10-31. Merged from four independent panel submissions (Codex Astra, Codex Sol, Claude Opus, Claude Fable); disputed points were decided by probes with a .vibex-enabled build of the compiler, TypeScript 5.9.3 on .tsx controls, and opencode's pinned babel-preset-solid 1.9.15.

Decision

.vibex is to .vibe what .tsx is to .ts:

A .vibex file is a .vibe file read with TypeScript's JSX language variant. Every JSX production, and its scanning, checking and emit, is exactly .tsx's. Every VibeLang production is exactly .vibe's. Where they compete for the same tokens, < in expression position takes its .tsx reading. JSX adds no other rule.

// compiler-gap: VIP-39 TS6054; file-kind support waits for the Preconditions below
// Profile.vibex   tsconfig: "jsx": "preserve", "jsxImportSource": "solid-js"
error ProfileMissing { id: string }

export const loadProfile = effect (id: string) => {
  const users = try Users
  return try users.find(id)
}

export function ProfileCard(props: { name: string; role: "admin" | "member" }) {
  return (
    <section class="card">
      <h2>{props.name |> titleCase(%)}</h2>
      {match (props.role) { when "admin": <Badge/>; default: null; }}
    </section>
  )
}

// Profile.tsx, the same module in Effect TypeScript
import { Data, Effect } from "effect"
 
class ProfileMissing extends Data.TaggedError("ProfileMissing")<{ readonly id: string }> {}
 
export const loadProfile = (id: string) =>
  Effect.gen(function* () {
    const users = yield* Users
    return yield* users.find(id)
  })
 
export function ProfileCard(props: { name: string; role: "admin" | "member" }) {
  return (
    <section class="card">
      <h2>{titleCase(props.name)}</h2>
      {props.role === "admin" ? <Badge/> : null}
    </section>
  )
}

The file kind

• .vibex = ScriptKindTSX plus VibeLang. The compiler gives .vibex TypeScript's ScriptKindTSX (so LanguageVariantJSX) and treats it as a VibeLang source exactly as it treats .vibe. No new ScriptKind, LanguageVariant, scanner mode or JSX parser. .vibe stays non-JSX; .ts and .tsx are unchanged. A .vibex with no JSX is legal.
• Renaming parses the same both ways. Renaming x.vibe to x.vibex changes how the file parses only where it has < in expression position or </ (rows 1–5 and 39). The project still needs .tsx's settings: without jsx, an import of x.vibex is TS6142, and under preserve the output is x.jsx (Options, output and declarations). Renaming x.tsx to x.vibex changes nothing in its JSX; the rest of the file follows .vibe's rules, as it would in x.vibe.
• Every .vibe rule applies. VIP-30 (every source file is a module), VIP-33 (platform code), VIP-14 and VIP-6 (Effect names in scope), VIP-38 (built-in Effect lint) and every other accepted VIP apply to .vibex as to .vibe. A file extension waives nothing.
• No stricter mode. .vibex implies no option, check or lint that .tsx and .vibe don't already imply.

< in expression position reads as in .tsx

• <T>x is JSX, never a type assertion. Write x as T.
• A generic arrow writes <T,>, <T extends U> or <T = D>. <T>(x: T) => x is JSX. This includes effect <T,>(x: T) => x, async <T,>(…) and a generic catch handler catch <E,>(e: E) => ….
• An operand that starts with < is JSX: try <A/>, fork <A/>, join <A/>, throw <A/>, as await <A/> is in .tsx.

// compiler-gap: VIP-39 TS6054; file-kind support waits for the Preconditions below
const id = <T,>(x: T) => x
const lift = effect <T,>(x: T) => x
const n = input as number

const id = <T,>(x: T) => x
const lift = <T,>(x: T) => Effect.gen(function* () { return x })
const n = input as number

The cost is the one every .tsx author already pays. effect <T>(x: T) => x, legal in .vibe, is a syntax error in .vibex, with TypeScript's own diagnostics (TS1005), as async <T>(x: T) => x is in .tsx.

Inside JSX: names and text are JSX's, {…} is VibeLang's

• Tag names, attribute names, attribute strings and JSX text are JSX's alone. match, try, effect, service, data, fork, join, provide, is and when there are names; !, % and |> there are characters. % in text is never the pipe topic. <try.all/> is a member tag on an identifier try, never VIP-18's form.
• {…} holds a VibeLang expression. Child containers, attribute containers and {...spread} take any VibeLang expression: try, match, |> and %, do {}, effect {}, effect functions and arrows, catch, is. A declaration or statement (provide, service, data, schema, error) is not an expression; it goes inside a block (do {}, effect {}, a function body), as everywhere.
• A container is transparent. It creates no function, scope or Effect context. {try load()} is legal exactly where try load() is legal. return, break and continue inside a do {} in a container leave the enclosing function or loop (VIP-2). An is binding binds in the enclosing lexical home (VIP-7). A written arrow or function keeps its ordinary boundary.
• The pipe topic crosses JSX. VIP-23's ContainsOuterTopic recurses through JSX containers and through arrows, as the pinned TC39 spec's default rule says; only a nested pipe body hides its own topic. JSX text, attribute strings and names never contain a topic.
• An attribute value is a string, a container or an element, as in .tsx. task=effect { … } is a syntax error; write task={effect { … }}.

// compiler-gap: VIP-39 TS6054; file-kind support waits for the Preconditions below
export effect function Row(id: string) {
  const item = try loadItem(id)
  return (
    <li title="50% off!" onClick={() => select(id)}>
      {item.price |> formatCents(%)}
      {match (item.stock) { when 0: <SoldOut/>; default: <Buy id={id}/>; }}
      <Timer task={effect { return try countdown(item) }} />
    </li>
  )
}

export function Row(id: string) {
  return Effect.gen(function* () {
    const item = yield* loadItem(id)
    return (
      <li title="50% off!" onClick={() => select(id)}>
        {formatCents(item.price)}
        {item.stock === 0 ? <SoldOut/> : <Buy id={id}/>}
        <Timer task={Effect.gen(function* () { return yield* countdown(item) })} />
      </li>
    )
  })
}

Types and patterns stay VibeLang's

• Every type is a VibeLang type, JSX type arguments included. <Task<User!NotFound> run={load} /> passes Effect.Effect<User, NotFound>; .tsx reads that ! as JSDoc's non-null type and fails. VIP-3's optional-slot rule ends a type before >, }, / and a line break.
• Pattern position is not expression position. After when, is, and, or and not, < is TC39's relational pattern, as in .vibe, except that </ is one token in every .vibex context (row 39): write when < /re/:. A JSX value goes after the arm's :.

// compiler-gap: VIP-39 TS6054; file-kind support waits for the Preconditions below
const view = <Task<User!NotFound> run={load} />
const size = match (n) { when < 5: <Small/>; default: <Big/>; }

const view = <Task<Effect.Effect<User, NotFound>> run={load} />
const size = n < 5 ? <Small/> : <Big/>

Effects and throws

• JSX never runs an Effect. An element doesn't run its props; a component is a plain function (VIP-1), not an Effect; an Effect-returning event handler returns an unrun Effect unless something runs it. TypeScript's void callback assignability means that mistake is not always a type error, as in .tsx.
• An element is not a throw-tracked call (VIP-4), as a getter isn't. The expressions inside it are tracked as usual. A .vibe component's declaration carries @throws {never} (VIP-27). (React's jsx() only builds a description; Solid's createComponent calls the component at once. What a component throws there is the framework's error-boundary business, as in .tsx.)
• try inside JSX is legal and lowers in place. Under react, react-jsx and react-jsxdev, TypeScript transforms the element and try runs where it stands, in source order. Under preserve and react-native, which keep the element in the output, the framework's compiler decides (Metro's Babel transform under react-native); Solid's compiler wraps an intrinsic element in an arrow, so <div>{try x}</div> fails Solid's build with "Unexpected reserved word 'yield'", exactly as <div>{yield* x}</div> and <div>{await x}</div> do in .tsx. Bind it first; that reads the same in every framework.
• An attribute is an object member under VIP-4. TypeScript checks the attributes against the props type member by member, so a function value in an attribute must fit the prop's call signature, as in f({ onClick: … }) (Assignability). A handler imported from a .ts file with /** @throws {Error} */ is EK0402 against an untagged onClick, in onClick={handler} and in a spread {...{ onClick: handler }} alike. The check of a tag against JSX.ElementType or JSX.ElementClass is not an assignability site: an element is not a tracked call (Rejected: "JSX elements as throw-tracked calls"), so an imported component is never rejected for what it may throw.

// compiler-gap: VIP-39 TS6054; file-kind support waits for the Preconditions below
export effect function Greeting() {
  const name = try currentUser()
  return <p>Hello, {name}</p>
}
export function SaveButton() {
  return <button onClick={() => runFork(save())}>Save</button>
}

export function Greeting() {
  return Effect.gen(function* () {
    const name = yield* currentUser()
    return <p>Hello, {name}</p>
  })
}
export function SaveButton() {
  return <button onClick={() => Effect.runFork(save())}>Save</button>
}

SaveButton's declaration carries /** @throws {never} */ (VIP-27); the element <button> contributes nothing to it.

Options, output and declarations

• Options. jsx, jsxFactory, jsxFragmentFactory, jsxImportSource, reactNamespace and the @jsx, @jsxFrag, @jsxImportSource and @jsxRuntime pragmas mean what they mean for .tsx, read through VIP-30's vibe.config.json → tsconfig.json → jsconfig.json discovery. A project without jsx gets .tsx's errors (TS17004 at the element, TS6142 at the import). No VibeLang option touches JSX.
• Output names. x.vibex emits x.jsx under "jsx": "preserve" and x.js otherwise (react-native keeps JSX in x.js), as x.tsx does. This extends VIP-34's .vibe → .js rule. With rewriteRelativeImportExtensions, as VIP-34's amended emit-name rule requires for ./x.vibe, a relative ./x.vibex specifier in emitted JavaScript rewrites to ./x.jsx under preserve and ./x.js otherwise, as TypeScript rewrites ./x.tsx, decided by the target file's actual output.
• Declarations. x.vibex writes the public x.d.ts to outDir and the sidecar x.d.vibex.ts beside the source (VIP-27), which plain tsc resolves under allowArbitraryExtensions. Neither contains JSX or VibeLang syntax. The public x.d.ts is API-identical (VIP-27) to the one the fork writes for the .tsx twin that carries the same @throws tags. VIP-27 is unchanged: a converted component gains @throws, exactly as a .ts file converted to .vibe does.
• Source maps. x.js.map/x.jsx.map and x.d.ts.map name x.vibex with its sourcesContent; JSX nodes keep TypeScript's positions, VibeLang's lowered nodes stand on their keyword as in .vibe.
• Diagnostics. JSX errors keep their TypeScript codes; VibeLang errors keep their EK codes (VIP-34). VIP-39 adds no diagnostic. EK39xx stays reserved for it.

// tsconfig.json, identical for the .tsx project
{ "compilerOptions": { "jsx": "preserve", "jsxImportSource": "solid-js", "declaration": true, "outDir": "dist" } }

src/Profile.vibex  ->  dist/Profile.jsx, dist/Profile.d.ts, src/Profile.d.vibex.ts
src/Profile.tsx    ->  dist/Profile.jsx, dist/Profile.d.ts

Imports and resolution

.vibe, .vibex, .ts and .tsx import and re-export each other freely. Resolution treats .vibex as .vibe's .tsx:

These orders apply after TypeScript's exports, imports, paths, moduleSuffixes and resolution-mode rules select a lookup; NodeNext still requires extensions where .tsx does. A live source beats its sidecar. App.vibe beside App.vibex, or App.tsx beside App.vibex, get TypeScript's TS5055/TS5056 only where the selected inputs write the same output path, as App.ts beside App.tsx does: under "jsx": "preserve" with declarations off, App.vibe and App.vibex write App.js and App.jsx and are both admitted; with declarations on both write App.d.ts, and under "jsx": "react" both write App.js, so those collide. Their compatibility sidecars stay distinct, App.d.vibe.ts and App.d.vibex.ts.

Corrected 2026-11-02: the collision follows the selected native output paths, not a shared source stem (decided detail 265; found by the round-6 review).

// compiler-gap: VIP-39 TS6054; file-kind support waits for the Preconditions below
// main.vibex
import { ProfileCard } from "./Profile"      // Profile.vibex
import { format } from "./format.js"         // format.vibe

// main.tsx
import { ProfileCard } from "./Profile"      // Profile.tsx
import { format } from "./format.js"         // format.ts

Preconditions

The .vibex examples explicitly name the current unsupported-file diagnostic, TS6054, with a // compiler-gap: marker while these prerequisites and file-kind support are pending. This records the planned feature, not successful compilation. The check rejects a stale marker once that code disappears; remaining diagnostics then retain their own checks.

.vibex ships after these, each fixed in VibeLang with a test (see Clashes, rows marked gap):

1. VIP-1's plain functions. Main still lowers every plain function to an Effect: export function Label(…) { return <b/> } is declared Effect.Effect<JSX.Element>, and <Label/> fails with TS2786 "'Label' cannot be used as a JSX component" (probe q17). No component works until VIP-1's lowering ships.
2. Four parser gaps that change how .vibex reads: a bodyless error eats a < on the next line; fork/join reject a < operand; a generic catch handler doesn't parse; the denied trailing-block parser (VIP-11) still runs.

Clashes

Every place any panelist found where the same tokens could read two ways, or where JSX meets a VibeLang rule. Deduplicated to 39 rows. Parser functions are in typescript/tsc/internal/parser/parser.go unless a file is named. "Agrees" means both readings give the same result. Gap means main's compiler is wrong today, independent of JSX, and must be fixed in VibeLang first. Rows 1–5 and 39 are the only places where .vibe text changes meaning in .vibex.

<: angle brackets

!: Effect types and bangs

Names

Text, strings, comments

Containers: VibeLang forms inside JSX

Meaning

Two semantic meetings are rules in the Decision rather than token clashes: an element is not a throw-tracked call (Opus), and a plain component must stay plain (VIP-1 precondition; Opus, Fable).

Alternatives

Did similar features cause problems elsewhere?

Yes, and each shaped a rule here:

• TypeScript's own .tsx removed <T>x and made <T>(x) => JSX (handbook, "JSX"). Users write as and <T,>. .vibex inherits the same cost and the same errors, including after effect.
• Babel and Flow parse <T>(x) => x in .js by trying JSX and backtracking. A parse that depends on backtracking is hard for other tools to match; a file kind avoids it.
• Reason's JSX had its own children and props semantics; ReScript's JSX v4 (2022) moved back to React's model. Lesson: JSX means what the host's JSX means.
• Swift result builders (SE-0289) document "unable to type-check this expression in reasonable time" on large views, and one-way constraints added to contain it. .vibex adds no inference.
• Rust UI macros: rustfmt can't format inside them, so Leptos ships leptosfmt; rust-analyzer support lags. A file kind keeps every tool in the loop.
• Svelte and Vue needed svelte2tsx and Volar's virtual files, and a generics attribute for type parameters.
• MDX 2 made JSX parsing strict and broke content written for MDX 1. Lesson: take one JSX grammar and never fork it.
• E4X (ECMA-357) gave XML literals their own runtime; it was withdrawn and removed from SpiderMonkey.
• Solid wraps containers in closures, so await (and yield*) inside an intrinsic element breaks its build. Row 38 inherits this unchanged.
• Babel's React transform rejects namespaced tags by default (throwIfNamespace) even though JSX parses them. Parse success is not framework support.

Recommendation

Accept. .vibex is one extension that selects .tsx's language variant plus VibeLang's forms, with no grammar of its own and no new diagnostic. Its only source-visible cost is .tsx's (as, <T,>, a space in < /re/). Every real witness from opencode, t3code and foldkit (15 files across the panel) compiles as .vibex with zero JSX errors; their remaining errors are VibeLang rules (VIP-33 platform code, the VIP-1 gap) and missing dependencies. Ship it after VIP-1's plain functions and the four parser gaps, then land it on t3code's web modules (React, Vite) and opencode's app (Solid, Vite) first; t3code's 78 mobile modules wait for a Metro adapter, which .vibe lacks too.

Credits

Rejected

Will's words

"Great question! New vip. We should support vibex. Have a panel of Astra opus fable and sol all research and write a vip and an implementation plan followed by an opus agent combining them into a single plan that uses the best ideas from all of them. Be careful to look for any ways the Jsx syntax might clash with vibe syntax if there are any." (2026-10-31)

"we should support Jsx ideally mostly from typescript itself already supporting it and us forking ts." (2026-10-31)

"Looks pretty simple I approve." (2026-10-31, accepting this VIP)

Context

The proposals page lists "JSX source files" as not in VibeLang: components live in .tsx files that call .vibe functions. The earlier design left .vibex as a candidate that must not imply a stricter mode (research note D21). 45 opencode (Solid, class=, jsxImportSource from tsconfig), 218 t3code (React, react-jsx, @effect/atom-react) and 4 foldkit Effect modules are .tsx and can't become VibeLang today.

• Amended 2026-11-03: declaration specifiers follow the .tsx twin. Ordinary package declarations use the native twin’s relative specifiers: ./user.vibe is declared as ./user.ts and ./App.vibex as ./App.tsx; written ./user.js, ./App.jsx, ./user and native ./plain.ts keep their spelling. Synthesized import types use TypeScript’s spelling for the twin under the same imports and tsconfig. Compatibility sidecars instead keep VibeLang source references such as ./user.vibe and ./App.vibex, relocated to the selected compatibility declaration when necessary, to preserve source identity. Neither allowImportingTsExtensions nor rewriteRelativeImportExtensions rewrites declaration specifiers; JavaScript output rewriting is separate. The jsx options keep their native meanings. There are no nondefault VibeLang declaration styles (VIP-27, VIP-30).
• Amended 2026-11-03: a written source extension keeps the .ts/.tsx substitution. ./App.vibe tries App.vibe, App.vibex, then App.d.ts, and ./App.vibex tries App.vibex, App.vibe, then App.d.ts, as TypeScript 5.9.3 resolves ./App.ts to App.tsx and ./App.tsx to App.ts when only the other exists. This corrects the table above to its own rule, "Resolution treats .vibex as .vibe's .tsx", and to the 2026-11-02 resolution amendment that each rule follows TypeScript on the .ts twin. Output-path collisions still follow TypeScript.