feat(oxfmt): Support gql-in-js substitution

[leaysgur]

Part of #15180

gql-in-js is the simplest among other xxx-in-js cases.

It works by:

• splitting the template with ${}, converting each part into an IR using:
  • prettier({ parser:"graphql" }) and oxc_formatter respectively
• and then interleaving them

However, for this to work, two things are essential:

• Obtaining a formatted Doc from Prettier, rather than just a formatted string.
• Converting the Doc JSON into oxc_formatter's IR.

The diffs primarily arise from the implementation of these two.

TODOs

• Implement by Claude
• Self review and fix up
• Check bench, ecosystem

[leaysgur]

• fix(formatter): Trim trailing whitespace before breaking line #19740
• test(oxfmt): Add xxx-in-js-conformance #19739
• feat(oxfmt): Support graphql() variant for gql-in-js #19703
• feat(oxfmt): Support gql-in-js substitution #19670 👈 (View in Graphite)
• refactor(oxfmt): Apply rethrow error for all pool.run() calls #19700
• refactor(formatter): Split print/embed file #19699
• main

---

How to use the Graphite Merge Queue

Add either label to this PR to merge it via the merge queue:

• 0-merge - adds this PR to the back of the merge queue
• hotfix - for urgent hot fixes, skip the queue and merge this PR next

You must have a Graphite account in order to use the merge queue. Sign up using this link.

An organization admin has enabled the Graphite Merge Queue in this repository.

Please do not merge from GitHub as this will restart CI on PRs being processed by the merge queue.

This stack of pull requests is managed by Graphite. Learn more about stacking.

[codspeed-hq]

Merging this PR will not alter performance

✅ 48 untouched benchmarks
⏩ 7 skipped benchmarks¹

---

_{Comparing 02-24-feat_oxfmt_support_gql-in-js_substitution (204128f) with main (06983a4)²}

Footnotes

1. 7 benchmarks were skipped, so the baseline results were used instead. If they were deleted from the codebase, click here and archive them to remove them from the performance reports. ↩

2. No successful run was found on main (a447840) during the generation of this report, so 06983a4 was used instead as the comparison base. There might be some changes unrelated to this pull request in this report. ↩

[leaysgur]

Oxfmt Ecosystem CI

suite	oxfmt@latest	188eba2 branch
actualbudget/actual	❌	✅
huggingface/huggingface.js	✅	✅
vercel/turborepo	✅	✅
eggjs/egg	✅	✅
AmanVarshney01/create-better-t-stack	❌	✅
formatjs/formatjs	❌	✅
vuejs/pinia	❌	✅
vuejs/core	✅	✅
cloudflare/agents	✅	✅
fuma-nama/fumadocs	✅	✅
monkeytypegame/monkeytype	✅	✅
cnpm/cnpmcore	✅	✅
mastodon/mastodon	✅	✅
npmx-dev/npmx.dev	✅	✅
fastify/fastify-vite	✅	✅
rolldown/rolldown	✅	✅
lichess-org/lila	✅	✅
tale/headplane	❌	✅
Comfy-Org/ComfyUI_frontend	✅	✅
aidenybai/react-grab	❌	✅
getsentry/sentry-javascript	✅	✅
openclaw/openclaw	✅	✅
dyad-sh/dyad	✅	✅

[leaysgur]

In the oxfmt-ecosystem-ci, it seemed only sentry-javascript was using gql (and it only had about 5 files...).

However, the fact that no differences were detected there means there's at least no issue there.

---

Benched with https://github.com/redwoodjs/graphql shows:

Benchmark 1: dist-main
  Time (mean ± σ):      1.978 s ±  0.050 s    [User: 13.350 s, System: 0.871 s]
  Range (min … max):    1.892 s …  2.038 s    10 runs

Benchmark 2: dist
  Time (mean ± σ):      2.085 s ±  0.034 s    [User: 14.097 s, System: 0.922 s]
  Range (min … max):    2.034 s …  2.143 s    10 runs

Summary
  dist-main ran
    1.05 ± 0.03 times faster than dist

Since it performs more operations than the previous code path, a performance decrease is expected.

The result doesn't seem to be too bad.

[Copilot]

Pull request overview

This PR implements GraphQL-in-JS template literal formatting as part of the broader xxx-in-js support effort (#15180). It introduces a new Doc→IR conversion path that allows oxc_formatter to properly respect printWidth for embedded languages, addressing a key limitation of the previous string-based approach.

Changes:

• Adds GraphQL template literal formatting via a new Doc→IR path that handles both no-substitution templates and templates with expressions
• Implements bidirectional conversion between Prettier's Doc format and oxc_formatter's IR format
• Refactors the embedded language formatting architecture with new format_embedded_doc callback and write_embedded_ir helper
• Updates all NAPI bindings and JavaScript integration code to support the new callback

Reviewed changes

Copilot reviewed 17 out of 18 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
crates/oxc_formatter/src/print/template/embed/graphql.rs	New module implementing GraphQL template formatting with quasi analysis, comment handling, and expression interpolation
crates/oxc_formatter/src/print/template/embed/mod.rs	Refactored embed module with new IR writing infrastructure and template character escaping
apps/oxfmt/src/prettier_compat/from_prettier_doc.rs	New module converting Prettier Doc JSON to EmbeddedIR with comprehensive test coverage
apps/oxfmt/src/core/external_formatter.rs	Extended with new format_embedded_doc callback supporting batch Doc formatting
apps/oxfmt/src-js/libs/apis.ts	Added formatEmbeddedDoc function using Prettier's internal printToDoc API
apps/oxfmt/src-js/index.ts, cli.ts, cli-worker.ts, worker-proxy.ts	Integration updates for new callback across all entry points
apps/oxfmt/src/main_napi.rs, api/*.rs	NAPI binding updates for new callback signature
apps/oxfmt/cmp.js	Comparison script for testing against Prettier's GraphQL formatting
crates/oxc_formatter/src/lib.rs, external_formatter.rs	Public API updates exposing new EmbeddedIR types

[Dunqing]

Nice! You also solved the printWidth issue!

[Dunqing]

One thing I don't know is why we need EmbeddedIR rather than using FormatElement directly.

[graphite-app]

Merge activity

• Feb 26, 3:23 PM UTC: Dunqing added this pull request to the Graphite merge queue.
• Feb 26, 3:30 PM UTC: Merged by the Graphite merge queue.

[leaysgur]

One thing I don't know is why we need EmbeddedIR rather than using FormatElement directly.

I believe it was because the lifetimes FormatElement<'a> and GroupId allocation were confined to oxc_formatter, and I couldn't figure out how to simply bring them over to the oxfmt side.

However, I feel like I can do it now, so I'll try it as a refactoring. 👌🏻