Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 17 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -48,6 +48,23 @@ See [docs/cli.md](docs/cli.md) for flags, dry runs, and package-manager override
> [!TIP]
> Public CDNs such as `esm.sh` or `jsdelivr` already publish bundles that include the WASM binding, so you can import this package directly from those endpoints in `<script type="module">` blocks without any extra setup.

### CDN stability contract (browser imports)

If you load `@knighted/jsx` from a CDN, pinning only the top-level package version is
not always enough for long-term stability. CDNs resolve transitive dependencies remotely,
and semver ranges inside dependency graphs can drift over time.

For deterministic browser behavior, prefer a fully pinned CDN URL contract that also fixes
the parser, binding, and WASM runtime versions.

Example (`esm.sh`):

```ts
import { jsx } from 'https://esm.sh/@knighted/jsx@1.14.1?bundle&target=es2022&deps=oxc-parser@0.142.0,@oxc-parser/binding-wasm32-wasi@0.142.0,@napi-rs/wasm-runtime@1.2.2'
import { reactJsx } from 'https://esm.sh/@knighted/jsx@1.14.1/react?bundle&target=es2022&deps=oxc-parser@0.142.0,@oxc-parser/binding-wasm32-wasi@0.142.0,@napi-rs/wasm-runtime@1.2.2'
import { transformJsxSource } from 'https://esm.sh/@knighted/jsx@1.14.1/transform?bundle&target=es2022&deps=oxc-parser@0.142.0,oxc-transform@0.142.0,@oxc-parser/binding-wasm32-wasi@0.142.0,@oxc-transform/binding-wasm32-wasi@0.142.0,@napi-rs/wasm-runtime@1.2.2'
```

## Usage

```ts
Expand Down
18 changes: 18 additions & 0 deletions docs/runtime-helpers-overview.md
Original file line number Diff line number Diff line change
Expand Up @@ -75,6 +75,24 @@ createRoot(document.getElementById('react-root')!).render(reactJsx`<${Counter} /
- Browser builds need the WASM binding from `@oxc-parser/binding-wasm32-wasi`. Install it (or rely on CDN bundles that already include it) so the helper can parse JSX outside Node.
- When running under Node, the helper automatically loads the native binding and falls back to WASM when necessary.

### CDN determinism note

When importing `@knighted/jsx` from CDNs, pinning only `@knighted/jsx@<version>` may
still allow transitive parser/binding/runtime versions to drift over time.

For stable browser behavior, pin these as a tested set:

- `oxc-parser`
- `@oxc-parser/binding-wasm32-wasi`
- `@napi-rs/wasm-runtime`

If you use `@knighted/jsx/transform`, also pin:

- `oxc-transform`
- `@oxc-transform/binding-wasm32-wasi`

See the README CDN stability contract section for an `esm.sh` example URL shape.

## Interop tips

- You can compose the helpers anywhere: vanilla scripts, Lit components, SSR utilities, etc. They’re just functions.
Expand Down
8 changes: 4 additions & 4 deletions examples/esm-demo.html
Original file line number Diff line number Diff line change
Expand Up @@ -8,11 +8,11 @@
<link rel="dns-prefetch" href="https://cdn.jsdelivr.net" />
<link
rel="modulepreload"
href="https://cdn.jsdelivr.net/npm/@knighted/jsx@1.14.0/lite/+esm"
href="https://cdn.jsdelivr.net/npm/@knighted/jsx@1.14.1/lite/+esm"
/>
<link
rel="modulepreload"
href="https://cdn.jsdelivr.net/npm/@knighted/jsx@1.14.0/react/+esm"
href="https://cdn.jsdelivr.net/npm/@knighted/jsx@1.14.1/react/+esm"
/>
<link rel="modulepreload" href="https://cdn.jsdelivr.net/npm/react@19.2.4/+esm" />
<link
Expand Down Expand Up @@ -469,8 +469,8 @@ <h1>@knighted/jsx + CDN</h1>
</main>

<script type="module">
import { jsx } from 'https://cdn.jsdelivr.net/npm/@knighted/jsx@1.14.0/lite/+esm'
import { reactJsx } from 'https://cdn.jsdelivr.net/npm/@knighted/jsx@1.14.0/react/+esm'
import { jsx } from 'https://cdn.jsdelivr.net/npm/@knighted/jsx@1.14.1/lite/+esm'
import { reactJsx } from 'https://cdn.jsdelivr.net/npm/@knighted/jsx@1.14.1/react/+esm'
Comment on lines 471 to +473
import {
useEffect,
useRef,
Expand Down
Loading