Product Decisions This Supports
- Feature scoping for code display surfaces. Any roadmap item that renders code to users — docs pages, API references, a changelog/blog with snippets, admin log or query viewers, customer-facing "example request" blocks — needs a highlighting layer. This package is a candidate for that one component; the decision it unblocks is "what do we ship for syntax display," not "what's our frontend stack."
- Build vs. buy vs. borrow. Highlighting is a solved commodity problem with zero product differentiation for us. Borrowing a small, dependency-free, single-file highlighter keeps the sprint cost at roughly a day (asset drop-in, Blade component wrapper, language metadata convention) instead of a multi-day custom tokenizer or a vendor trial. This is a "keep the team on the differentiated work" decision.
- Frontend vs. backend rendering. Adopting a browser-side highlighter is a deliberate vote for zero server cost and static caching over render accuracy and first-paint quality. That trade-off should be made explicitly and recorded, because reversing it later touches every page that renders code.
- Long-tail language coverage. If our audience pastes SQL, shell, config, or PHP/JS/CSS mixed together, coverage breadth matters more than perfect fidelity on TypeScript. jush's differentiator is breadth in a small footprint, which supports "serve a heterogeneous developer audience" without a per-language integration project.
- Risk acceptance on a low-signal dependency. 28 GitHub stars and a single maintainer is a maintenance-risk decision a PM signs off on, not an engineer. The mitigating fact to weigh is real-world deployment on high-traffic developer documentation — but that must be verified, not assumed, before it goes in the risk register as "low."
- Vendor-neutral content modeling. The decision to store language as a
data-language attribute on <code> rather than baking highlighter-specific class names into authored content preserves the option to swap highlighters later at near-zero content-migration cost. This should be a standing convention regardless of which package we pick.
When to Consider This Package
Consider it when all of the following hold:
- The requirement is client-side, static-page code display with no need for server-rendered HTML (SEO of code blocks is not a factor; content is behind auth or already crawlable as plain text).
- We need many languages, shallowly — breadth over depth — and we do not need TypeScript/JSX accuracy, diff highlighting, line numbers, copy buttons, or theme ecosystems out of the box.
- We want no build step, no npm graph, no transitive dependencies — for example, a legacy Blade-admin surface or an air-gapped/internal tool where adding a bundler pipeline is disproportionate.
- The team accepts manual asset management: this is a raw JS + CSS drop-in, not a Composer package. There is no service provider, no Blade directive, no config publish, no Laravel version constraint to reason about — which is a benefit (nothing to break on framework upgrades) and a cost (we own the wiring and the Blade wrapper ourselves).
- Legal confirms a permissive license and the asset is pinned/vendored into the repo rather than CDN-loaded, so an upstream disappearance is not an outage.
Look elsewhere when:
- Render accuracy or fenced-language ergonomics matter — a docs product with TSX, diff blocks, and copy-to-clipboard affordances belongs on Shiki (server-side, VS Code grammars, zero client JS) or Torchlight (paid, API-backed), not a generalist highlighter.
- The ecosystem is the requirement — themes, plugins, line-highlighting, autolinking, and a large contributor base point to Prism.js or highlight.js. Choosing jush means building those affordances ourselves.
- First-paint quality is a product requirement. Client-side highlighting means a flash of unstyled code and layout shift on long pages. If code blocks are above the fold on marketing or SEO-critical docs, go server-side.
- Any of the integration facts are unverifiable — if we cannot confirm the license, a tagged release cadence, and that upstream is not effectively abandoned, the correct answer is a one-day spike on Prism or highlight.js instead. At 28 stars, unverifiability is disqualifying, not a caveat.
- We need a supported, upgradeable dependency with an owner. If nobody on the team will own the vendored asset, pick the option with the larger community so the maintenance burden is externalized.
How to Pitch It (Stakeholders)
To executives: We need code to render legibly in several places on the roadmap. That is a commodity capability, not a differentiator, so the goal is to spend as little as possible on it. This option is a small, dependency-free browser script we vendor into the repo — roughly a day of engineering, no new build pipeline, no server cost, no recurring license, and no framework-version maintenance. The honest trade-off is that it is a low-visibility open-source project with a single maintainer; we mitigate that by pinning the asset to the repo, wrapping it in one internal Blade component, and keeping our content markup vendor-neutral so swapping highlighters later is a one-file change. Recommendation: approve as a scoped, reversible frontend choice for non-critical code display, and explicitly exclude it from SEO-sensitive or TypeScript-heavy docs surfaces, where we should evaluate a server-side renderer instead.
To engineering: Treat this as a vendored frontend asset, not a dependency. Pin the file, add a thin Blade component that emits <pre><code data-language="…">, initialize once on load, and keep the highlighter's class names out of authored content. Confirm the license and the last-release date before merge; if either is unclear, fall back to Prism.js — the integration cost is comparable and the ecosystem risk is lower. Own it in the repo, not on a CDN.