Update Syntax Transforms list

[SConaway]

In light of facebook/metro#681, I thought it fitting to update the list of syntax transforms so users know exactly what will work and what won't. Feel free to make any chages as you see fit, I wasn't sure where to put some things.

[netlify]

✔️ Deploy Preview for react-native ready!

🔨 Explore the source changes: d5e22cd

🔍 Inspect the deploy log: https://app.netlify.com/sites/react-native/deploys/60eff3d6e38f200007652b90

😎 Browse the preview: https://deploy-preview-2676--react-native.netlify.app

[SConaway]

After facebook/metro#681 is merged, then ES2021: Numeric Separators need to be added too

[Simek]

Hi @SConaway, thank you for updating the transformers list! One thing which needs a bit of improvement is the addition of "when not using Hermes" label. It's a bit hard to spot, so maybe we can create the special label (based on the current platform labels - example: https://reactnative.dev/docs/button) for Hermes and flip the markings? (from "when not using Hermes" to "also avaible in Hermes").

Also converting list to the table or just adding an compatibility table (with two columns "JSI" and "Hermes") might be a bit more readable for the users, I'm not sure which solution will be the best, but it will be nice to improve those markings a bit.

[SConaway]

Yes, I'll do that a bit later today! I'll try a three-column table, where the columns are:

1. Name / plugin, linked
2. included in JSI? (just a ✅ )
3. included in Hermes? (✅)

[SConaway]

Wait what should I do with the categories / groups (ES3, ES5, ES2020, ...)?

[Simek]

Wait what should I do with the categories / groups (ES3, ES5, ES2020, ...)?

You can use HTML on the Docusaurus pages, so maybe you can utilize a cell with a colspan to represent groups, what do you think?

You can also add an custom CSS `className` to further customize the group cell appearance.

Let me know if you will need any help. 🙂

[SConaway]

I was actually thinking of labeling / tagging them like so, but I'm open to that too! Let me know what you prefer.

Here's what I have so far (I've done them all, here are the first few:

I've changed the Type label to Transformation to match your example

[Huxpro]

@SConaway thanks for updating the list of transforms! There is however a small issue: the transform profile is considered an unstable feature of Metro and the Hermes profile is not turned on by default even when Hermes is used as the engine. So it may be too early to call them out.

Cc @motiz88 for a second opinion on this.

[SConaway]

Ok, that’s fine. Just let me know what to do and I can do it!

[motiz88]

Agree with @Huxpro - let's remove the Hermes mention until this is a supported workflow.

[SConaway]

Ok cool.

Do we want to stick with the version labels / tags or use groups like in @Simek’s screenshot?

[Simek]

@SConaway The short ECMAScript names are for newest versions are deprecated, so we should use the full year names (ES20XX) for ES6 onward, as listed on the wiki:

• https://en.wikipedia.org/wiki/ECMAScript#Versions

Also if we don't list the Hermes transformations currently, the table refactor is not required. I can accept the this PR if you just remove the "when not using Hermes" text and updated the ES naming. 🙂

[SConaway]

@Simek

Ok I'll do that.

Personally I think the table looks a bit better and then wouldn't need to be redone when the Hermes stuff is ready, but let me know!

[Simek]

@SConaway We can stick to the table, but it would only include Type and Code columns from your screenshot right?

Regarding to labels, website also have a quite large portion of visitors using mobile devices and it would be nice if we can spare some width (especially with yearly names in ES labels) and avoid repetition by adding group headings instead of labels (but feel free to customize the appearance of header row, if you thing it's necessary to differentiate them somehow). 🙂

[SConaway]

Yes. Sounds good. I'll have the PR updated by EOD today

[Huxpro]

The table indeed looks much better to me (notably the alignment) and it's more future-proof once the transform profile feature is going public.

@Simek I guess you were trying to mean JSC instead of JSI in your original comment, right?

[SConaway]

Converted to table, but I couldn't quite figure out the colspan cells, @Simek, so please either let me know what to change it to or feel free to do it yourself, thanks!

Here's how it looks now:

I suggest doing something with the proposals, as I'm not sure the best way to organize them—or even if the stages makes sense. Let me know how to improve it.

[SConaway]

Also, is it normal for docusaurus to take about 7 minutes for a full build (cd website && yarn build)? I am thinking of moving some personal projects to docusaurus, but it seems a bit slow!

[Simek]

@Simek I guess you were trying to mean JSC instead of JSI in your original comment, right?

Yup, my bad, hope it's not a critical issue. 😉

Also, is it normal for docusaurus to take about 7 minutes for a full build (cd website && yarn build)?

The reason behind the prod build time is the amount of versions served, in dev more and in preview most of versioned docs are stripped. Additionally adding i18n in the future will increase the build time drastically. There were also an optimizations made for the deployment process and caches settings, and currently this few minutes are not a big issue. When using V1, deploying Archive version of website (https://archive.reactnative.dev/versions) would take around 45 minutes.

According to the transformations table - as I suggested earlier to achieve table heading you need to use HTML. Unfortunately you cannot mix the Markdown and HTML table elements together. Also there are some issues in Remark when parsing table content (As seen, for example on the Button page - https://reactnative.dev/docs/button#color), so generally it's a safer approach to use HTML in case of heavily customization.

I have also utilized the CodeBlock component, to display the code examples which cannot be placed in tables when using Markdown, which should make the example more readable. There were also small tweaks and changes to the examples code and order of few transformation table entries.

Please check out the deployed preview (https://deploy-preview-2676--react-native.netlify.app/docs/next/javascript-environment#javascript-syntax-transformers), I'm curious about your feedback. 🙂

Preview

[Huxpro]

@Simek May I suggest that we should increase the font size of code blocks? I knew it's probably inherited from somewhere but I just felt like they are way too small to read.

[Simek]

@Simek May I suggest that we should increase the font size of code blocks? I knew it's probably inherited from somewhere but I just felt like they are way too small to read.

@Huxpro Do you have in mind CodeBlock font size in the tables, or the general size of CodeBlock font in on the whole page?

If you have in mind those specific CodeBlocks in the tables, after a quick check, it looks like there is some downsizing applied, because the final, computed font size differs from the font size value when CodeBlock is placed directly on the page (11.34px vs 13.77px). I will look at this issue.

[Huxpro]

@Simek In the tables! The general size over the whole website is okay.

(11.34px vs 13.77px)

Thanks for digging that out. 11.34 indeed sounds too tiny XD. I'm wondering why aren't general size 14 though.

[Simek]

@Simek In the tables! The general size over the whole website is okay.

@Huxpro The CodeBlock font size in tables has been adjusted in my last commit (4c8fad5). After all the scaling and transformations, the font size should be around 14px as expected now.

[Simek]

Thank you @SConaway for starting the work on this update and extending the list in the first place! Thank you @Huxpro & @motiz88 for the feedback! 👍

Looks like everyone is quite happy with the result right now, so let's merge it. We can always introduce the changes or fixes in the separate PRs. 🙂

[SConaway]

Yes, it does look a lot better. Glad my desire to keep the information in the docs up-to-date led to the revamp of the entire page.