Last week at PayPal, one of my pull requests was merged in an express codebase
which migrated us from a custom template system to using React function
components and JSX. The motivation was to reduce the maintenance overhead of
knowing and maintaining a custom template system in addition to the JSX we are
doing on the frontend.
The app is paypal.me. The way it works is we have the
home,
terms, and
supported countries pages that are 100%
rendered HTML/CSS (and just a tiny bit of vanilla JS), and then the
profile and
settings pages are rendered by the
server as “skeleton” html pages (with SEO-relevant tags and a root <div> etc.)
and then the client-side React app kicks in to load the rest of the
data/interactivity needed on the page.
You should use Remix, not just the skeleton index.html
as we’re doing on paypal.me. We have our reasons (there’s
nuance in everything and I’m not going to get into this). Of course, Remix
didn’t exist at the time we were working on this so 🤷♂️
Before my PR, we actually had two systems in place. We used
express-es6-template-engine
for the profile and settings pages (which are actually the same page), and for
the marketing pages one of our engineers came up with a tagged-template literal
solution that was react-like (with functions that accepted props and returned a
string of HTML). So engineers that work on this codebase would have to know and
maintain:
express-es6-template-enginefor the profile and settings pages- React and JSX for the client-side app
- The custom tagged-template literal solution for the marketing pages.
It was decided to simplify this down to a single solution: React and JSX for
both frontend and backend. And that’s the task I took. I want to explain a few
of the gotchas and solutions that I ran into while making this transition.
JSX compilation
This was actually as easy as npm install --save react react-dom in the
server. Because paypal.me uses
paypal-scripts, the server’s already compiled with
the built-in babel configuration which will automatically add the necessary
react plugins if the project lists react as a dep. Nice! I LOVE Toolkits!
HTML Structure
The biggest challenge I faced with this involves integration with other PayPal
modules that generate HTML that need to be inserted into the HTML that we’re
rendering. One such example of this is our polyfill service that
I wrote about a while backwhich
inserts a script tag that has some special query params and
a server nonce. We have
this as middleware and it adds a res.locals.polyfill.headHTML which is a
string of HTML that needs to appear in the <head> that you render.
With the template literal and es6-template-engine thing we had, this was pretty
simple. Just add ${polyfill.headHTML} in the right place and you’re set. In
React though, that’s kinda tricky. Let’s try it out. Let’s assume that
polyfill.headHTML is <script src="hello.js"></script>. So if we do this:
<head>{polyfill.headHTML}</head>
This will result in HTML that looks like this:
<head><script src="hello.js"></script></head>
This is because React escapes rendered interpolated values (those which appear
between { and }). This is a
cross site-scripting (XSS)
protection feature built-into React. All of our apps are safer because React
does this. However, there are situations where it causes problems (like this
one). So React gives you an escape hatch where you can opt-out of this
protection. Let’s use that:
<head>
<div dangerouslySetInnerHTML={{__html: polyfill.headHTML}} />
</head>
So this would result in:
<head>
<div>
<script src="hello.js" />
</div>
</head>
But that’s not at all semantically accurate. A div should not appear in a
head. We also have some meta tags. It technically works in Chrome, but I
don’t know what would happen in all the browsers PayPal supports and I don’t
want to bust SEO or functionality of older, less-forgiving browsers for this.
So here’s the solution I came up with that I don’t hate:
<head>
<RawText>{polyfill.headHTML}</RawText>
</head>
The implementation of that RawText component is pretty simple:
function RawText({children}) {
return <raw-text dangerouslySetInnerHTML={{__html: children}} />
}
So this will result in:
<head>
<raw-text>
<script src="hello.js" />
</raw-text>
</head>
This doesn’t solve the problem by itself. Here’s what we do when we render the
page to HTML:
const htmlOutput = ReactDOMServer.renderToStaticMarkup(<Page {...options} />)
const rendered = `
<!DOCTYPE html>
${removeRawText(htmlOutput)}
`
// ...etc...
That removeRawText function is defined right next to the RawText component
and looks like this:
function removeRawText(string) {
return string.replace(/<\/?raw-text>/g, '')
}
So, effectively what our rendered string looks like is this:
<head>
<script src="hello.js"></script>
</head>
🎉 Cool right?
So we have a simple component we can use for any raw string we want inserted
as-is into the document without having to add an extra meaningless (and
sometimes semantically harmful) DOM node in the mix. (Note, the real solution to
this problem would be for React to
support
dangerouslySetInnerHTML
on Fragments).
NOTE: The fact that this logic lives in a function right next to the
definition of the RawText component rather than just hard-coding the
replacement where it happens is IMPORTANT. Anyone coming to the codebase and
seeing RawText or removeRawText will be able to find out what’s going on
much more quickly.
Localization
In our client-side app, we use a localization module that my friend Jamund and I
worked on that relies on a singleton “store” of content strings. It works great
because there’s only one locale that’ll ever be needed through the lifetime of
the client-side application. Singletons don’t work very well on the backend
though. So I built a simple React Context consumer and provider which made it
easier to get messages using this same abstraction without the singleton. I’m
not going to share the code for it, but here’s how you can use it:
<Message msgKey="marketing_pages/new_landing.title" />
It worked out pretty well. The Message component renders the MessageConsumer
component which will get the content out of context and retrieve the message
with the given key.
Other things of note:
React.Fragmentsare everywhere.
When the structure matters so much, you find yourself using React fragments
all over the place. We’re using babel 7 and loving the new shorter syntax of
<>and</>.style/classNamechanges. Before this was straightup HTML, the biggest
changes I had to make was all theclass="had to be changed toclassName="
which wasn’t all that challenging, but I found myself forgetting the
style="attributes needing to be changed tostyle={and object syntax all
the time. Luckily React gives you a warning if you miss one 🙂${needed to be changed to{. I found a few stray$rendered several
times in the course of this refactor 😅
Conclusion
I’m pretty pleased that we now only have one templating solution for the entire
app (both frontend and backend). I think that’ll reduce the maintenance burden
of the app and that’s a real win. Trying things out and doing experiments is a
good thing, but circling back to refactor things to the winning abstraction is
an important step to making applications that are maintainable for the
long-term. I hope this is helpful to you! Good luck!
Source link
