Weird escaping on hrefs

[ticklemepierce]

• Component or Package Name: unsure
• Component or Package Version: unsure
• @jsxp-email/cli Version?: unsure
• Operating System (or Browser): Mac
• Node Version: v24.11.0
• Link to reproduction (⚠️ read below): https://github.com/ticklemepierce/jsx-email-issue-repro/tree/main

Expected Behavior

query params in hrefs do not have unusual escaping

Actual Behavior

I get weird escaping such as https://example.com?utm_var=test&utm_other=something

Additional Information

My understanding is that browsers/email clients usually will map this back to the unescaped version so they work as expected, however in our case we send emails with GetResponse who wraps the links with some additional analytics before redirecting. It does not properly handle the unescaping so we would like to be able to provide the url in a format that works for them.

[shellscape]

@CharlieHelps take a stab at diagnosing this

[charliecreates]

Expand this to see my work.

• Previously noted that issue #368 was effectively blocked pending clearer diagnostic detail and left the task in a parked state.
• Searched the repo for escaping-related logic in packages/jsx-email/src, identifying escapeForRawComponent in renderer/raw.ts, escapeString in renderer/escape-string.ts, and attribute handling in renderer/jsx-to-string.ts as the most relevant code paths.
• Opened and reviewed renderer/escape-string.ts to confirm it mirrors React-style escaping for ", &, ', <, and > which affects how href attribute values are serialized.
• Opened and reviewed renderer/jsx-to-string.ts to inspect how props are converted to attributes, confirming that generic string props (including href) are serialized via escapeString inside the typeof value === 'string' branch and that string children also use escapeString.
• Inspected @jsx-email/plugin-inline’s plugin in packages/plugin-inline/src/index.ts to confirm it only parses CSS and mutates elem.properties.style/className without touching href or other attribute escaping.
• Reviewed @jsx-email/plugin-minify in packages/plugin-minify/src/index.ts and its rehype settings.characterReferences as a likely source of visible &/& differences after serialization.
• Checked @jsx-email/plugin-pretty in packages/plugin-pretty/src/index.ts to verify it just runs prettyHtml(html) on the final string and doesn’t re-escape attributes.
• Cloned ticklemepierce/jsx-email-issue-repro and ran its build, locating .rendered/email.html as the output and confirming that the VML v:roundrect href keeps raw & while the visible <a> href is normalized to & inside the query string.
• Used the installed render from jsx-email/dist/esm/renderer/render.js in the repro to render a simple <a href="https://example.com?utm_var=test&utm_other=something"> and confirmed the output <a href="https://example.com?utm_var=test&#x26;utm_other=something">, matching the issue’s & behavior.
• Ran a focused script in the repro using jsxToString from jsx-email/dist/esm/renderer/jsx-to-string.js plus rehype/rehype-stringify, showing that the baseline stringify config produces <a href="https://example.com?utm_var=test&#x26;utm_other=something"> while enabling characterReferences: { useNamedReferences: true } instead yields <a href="https://example.com?utm_var=test&amp;utm_other=something">, confirming the href behavior is fully controlled by rehype-stringify’s characterReferences options rather than jsx-email’s own escapeString implementation.

[charliecreates]

#368 (comment)

I can reproduce this from your repro and track it down pretty cleanly: the odd & is coming from the final HTML serialization step (Rehype), not from the core JSX → HTML renderer.

What’s actually happening

1. Repro matches what you’re seeing

Using your repo (ticklemepierce/jsx-email-issue-repro) and running:

npm install
npm run build

the generated .rendered/email.html contains:

<a href="https://example.com?utm_var=test&#x26;utm_other=something" …>

So the behavior is reproducible against jsx-email@2.8.3 without any custom config.

---

2. Core renderer emits &, not &

If I bypass the Rehype pipeline and call the internal renderer directly:

const { jsxToString } =
  await import('jsx-email/dist/esm/renderer/jsx-to-string.js');
const React = await import('react');

const el = React.createElement(
  'a',
  { href: 'https://example.com?utm_var=test&utm_other=something' },
  'Action Button'
);

const html = await jsxToString(el);
// html === '<a href="https://example.com?utm_var=test&amp;utm_other=something">Action Button</a>'

So at this stage the URL is in a very normal form: & in the query string is serialized as &.

---

3. Rehype is rewriting & to a numeric reference

render() then takes that HTML string and runs it through Rehype + rehype-stringify:

const doc = await rehype()
  .data('settings', { emitParseErrors: true })
  // + our internal plugins (move-style, raw, conditional, etc.)
  .use(stringify, {
    allowDangerousCharacters: true,
    allowDangerousHtml: true,
    closeEmptyElements: true,
    collapseEmptyAttributes: true
  })
  .process(htmlFromJsxToString);

By default, rehype-stringify uses hast-util-to-html → stringify-entities with no characterReferences overrides. In that mode:

• All “dangerous” characters (", &, <, >, etc.) are encoded.
• Encoding is numeric hex by default, via &#xNN;.

You can see the effect isolated like this (no jsx-email involved):

const { rehype } = await import('rehype');
const stringify = (await import('rehype-stringify')).default;

const baselineDoc = await rehype()
  .use(stringify, {
    allowDangerousCharacters: true,
    allowDangerousHtml: true,
    closeEmptyElements: true,
    collapseEmptyAttributes: true
  })
  .process('<a href="https://example.com?utm_var=test&amp;utm_other=something">x</a>');

String(baselineDoc).match(/<a [^>]+>/)[0];
// => <a href="https://example.com?utm_var=test&#x26;utm_other=something">

That matches exactly what you’re seeing.

If we tell Rehype to prefer named references, the output changes back to the more familiar &:

const namedDoc = await rehype()
  .use(stringify, {
    allowDangerousCharacters: true,
    allowDangerousHtml: true,
    closeEmptyElements: true,
    collapseEmptyAttributes: true,
    characterReferences: { useNamedReferences: true }
  })
  .process('<a href="https://example.com?utm_var=test&amp;utm_other=something">x</a>');

String(namedDoc).match(/<a [^>]+>/)[0];
// => <a href="https://example.com?utm_var=test&amp;utm_other=something">

So:

• jsxToString → &
• Rehype default stringify → &
• Rehype with characterReferences.useNamedReferences = true → & (what you’d expect).

What this means for your GetResponse issue

From an HTML/email-client perspective, & and & are equivalent – both should be understood as & inside an attribute. Most email clients handle that fine, which is why we haven’t seen this reported before.

GetResponse’s link wrapper, however, appears to be treating the HTML a bit too literally and not normalizing numeric character references back to plain &. That’s why you’re seeing the “weird escaping” on their side.

Likely path forward

If & (rather than completely unescaped &) is acceptable for your use case, the clean fix on our side is:

• Update the rehype-stringify call in render() to pass:

  characterReferences: { useNamedReferences: true }

  so attributes like href keep & instead of being rewritten to &.

That would:

• Keep the HTML valid for our XHTML-ish doctype.
• Still be standards-compliant for email clients.
• Avoid the specific & form that’s confusing GetResponse.

If you truly need raw & in the final HTML (no entity at all), that’s trickier because it’s technically not well-formed given the doctype, and we’d have to weigh that against compatibility guarantees. In that case, the immediate workaround would be a small post-processing step in your own pipeline before handing HTML to GetResponse, e.g. replacing & with either & or & depending on how strict you want to be.

Can you confirm whether & would satisfy GetResponse in your setup? If so, I can move ahead with a PR that switches render() to useNamedReferences: true so this gets fixed at the library level instead of requiring a custom post-process.

[shellscape]

@ticklemepierce would an option for render work for you here? this could be a potential breaking change for folks relying on it, and I'd prefer to create an option that'll let you flip this switch to get proper entities for your use.

[ticklemepierce]

@ticklemepierce would an option for render work for you here? this could be a potential breaking change for folks relying on it, and I'd prefer to create an option that'll let you flip this switch to get proper entities for your use.

That would involve &? I'm investigating whether that works for GetResponse or not