Add `insertionPoint` option in `EmotionCache` #2521

mnajdova · 2021-10-20T12:35:27Z

What:

Fixes #2037 (it is closed, but the feature request haven't been implemented before).

It adds an option to the EmotionCache for specifying an insertion point - dom node after which the style rules will be inserted.

Why:

It is necessary feature for applications that have third-party styles coming from one place, which should be injected first, then the app's styles coming from emotion, for example, coming from a UI library (as @mui/material) that needs to be injected next, and then any other overrides for the default styles.

How:

It's pretty much self explanatory, the style rules are being injected after the specified node. This option wins over prepend, if both are being specified, as I would say is more specific.

Checklist:

Documentation
Tests
Code complete
Changeset

changeset-bot · 2021-10-20T12:35:30Z

🦋 Changeset detected

Latest commit: 61fcc7f

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 2 packages

Name	Type
@emotion/cache	Minor
@emotion/sheet	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

codesandbox-ci · 2021-10-20T12:38:26Z

This pull request is automatically built and testable in CodeSandbox.

To see build info of the built libraries, click here or the icon next to each commit SHA.

Latest deployment of this branch, based on commit 61fcc7f:

Sandbox	Source
Emotion	Configuration

codecov · 2021-10-20T12:38:29Z

Codecov Report

Merging #2521 (ef3412f) into main (4be3391) will increase coverage by 0.00%.
The diff coverage is 100.00%.

❗ Current head ef3412f differs from pull request most recent head 61fcc7f. Consider uploading reports for the commit 61fcc7f to get more accurate results
| Impacted Files | Coverage Δ | |
|---|---|---|
| packages/cache/src/index.js | 97.80% <ø> (ø) | |
| packages/sheet/src/index.js | 100.00% <100.00%> (ø) | |

.changeset/sixty-balloons-build.md

Andarist · 2021-10-20T14:55:44Z

packages/cache/types/index.d.ts

@@ -37,6 +37,7 @@ export interface Options {
  container?: HTMLElement
  speedy?: boolean
  prepend?: boolean


Suggested change

prepend?: boolean

/** @deprecate use `insertionPoint` instead */

prepend?: boolean

a note about this deprecation should both go into the docs and into the changeset

I would keep the prepend option, it is much simplified version for that use-case (adding the style rules first in the head). Otherwise you would need to create a node and add it first in the head, just so that you can say, add the style rules after this element.

Btw I am adding the style rules after the node specified in the insertionPoint

I would keep the prepend option, it is much simplified version for that use-case (adding the style rules first in the head). Otherwise you would need to create a node and add it first in the head, just so that you can say, add the style rules after this element.

I was thinking about this in the last few days and I think I would still prefer to deprecate the prepend. This would align more with Emotion's overall philosophy (minimal API surface, only a few options, not using conflicting options etc). While achieving prepend with insertionPoint is a little bit more involved it can still be done. I expect that not that many people need any of those options anyway (both didn't exist in Emotion 10) and this has to be usually only done once in the application.

Removing this option would simplify the code (the cost ain't high here though), but importantly it would simplify the docs, teachability and would allow us to drop conflicting options in the future (insertionPoint used together with prepend doesn't make any sense).

packages/sheet/__tests__/index.js

packages/cache/src/index.js

packages/sheet/src/index.js

packages/cache/__tests__/index.js

packages/sheet/__tests__/index.js

Andarist · 2021-10-26T21:11:32Z

packages/sheet/README.md

@@ -51,6 +51,10 @@ This defines how rules are inserted. If it is true, rules will be inserted with

 This defines where rules are inserted into the `container`. By default they are appended but this can be changed by using `prepend: true` option.

+#### insertionPoint
+
+This defines specific dom node after which the rules are inserted into the `container`.


It might not always be obvious which element one should choose as their insertionPoint. Even if a correct element gets chosen the relation between this element and it being insertion point might not be obvious.

To make things easier for people and to alleviate the indirect relationship problem we could suggest here using smth like this as the insertion point:

<meta name="emotion-insertion-point" content="" />

This technique (using custom <meta/>) is used by next/head.

Updated with a codesnippet

Co-authored-by: Mateusz Burzyński <mateuszburzynski@gmail.com>

Andarist · 2021-11-03T07:43:06Z

.changeset/sixty-balloons-build.md

+// <meta name="emotion-insertion-point" content="">
+const emotionInsertionPoint = document.createElement('meta')
+emotionInsertionPoint.setAttribute('name', 'emotion-insertion-point')
+emotionInsertionPoint.setAttribute('content', '')


FYI: I've checked the spec and it seems that content attribute is required in this case:

If either name, http-equiv, or itemprop is specified, then the content attribute must also be specified. Otherwise, it must be omitted.

Kindly, does this work with SSR, 'cause document seems to be undefined in my case? What do you suggest I do?
Thanks.

You need to create such a tag (or similar) in your SSR response and then select it on the client's side and pass it as the insertionPoint to createCache

Hi, @Andarist. Thanks for your response. I saw and did as you suggested and it worked. Thank you.

But then, there's another issue which I'm noticing. I'm using Framer Motion's page transition feature--AnimatePresence--with MUI, and it happens that on route change start, the styles of the unmounting page/component (seem) to get removed from the DOM causing a FOUC of the unmounting page (before it transitions out).

Is there a way to preserve the styles of the pages as they get mounted, so they don't have to get removed and re-added everytime they get mounted/unmounted. I hope you understand what I mean?

Cc: @oliverturner

What styles are removed on the route change? By default Emotion doesn't unmount any styles - except global ones when used through <Global/>. Framer Motion also works in a way that it temporarily preserve components that are unmounted in the tree (they just render exiting children for longer than you are rendering them - they can do that cause they just cache previously received children). So even if some styles would get unmounted during the process they should be unmounted after the component goes completely out of the page so there should be no FOUC.

So while I understand what you are observing there, I don't understand how this can happen. Do you have a repro case (even a complex one, like a full deployed page) that I could take a look at?

...versus what it currently looks like in prod:

prod-480x.mov

@Andarist , so you'll notice the FOUC in the production (build) video.

Hi, @Andarist . Seen these yet?

Could you perhaps record this with https://www.replay.io/ ? I'd like to debug this and can't do that with just a standard recording of the problem.

Alright, I will. Thanks for your support. 🤲🏼

Andarist · 2021-11-03T07:43:24Z

Thank you! ❤️

mnajdova added 2 commits October 20, 2021 14:22

Add insertionPoint option in EmotionCache

84cf0a4

yarn changeset

a8a38cc

yarn lint

5e801e0

Andarist reviewed Oct 20, 2021

View reviewed changes

.changeset/sixty-balloons-build.md Show resolved Hide resolved

Andarist reviewed Oct 20, 2021

View reviewed changes

packages/sheet/__tests__/index.js Outdated Show resolved Hide resolved

Andarist reviewed Oct 20, 2021

View reviewed changes

packages/cache/src/index.js Show resolved Hide resolved

mnajdova added 2 commits October 21, 2021 12:09

Add tests as per view

221c298

Updated changeset, improved tests

60bf5bd

mnajdova requested a review from Andarist October 21, 2021 10:48

mnajdova commented Oct 25, 2021

View reviewed changes

packages/sheet/src/index.js Outdated Show resolved Hide resolved

Update packages/sheet/src/index.js

b13a72c

Andarist reviewed Oct 26, 2021

View reviewed changes

packages/cache/__tests__/index.js Outdated Show resolved Hide resolved

Andarist reviewed Oct 26, 2021

View reviewed changes

packages/cache/__tests__/index.js Outdated Show resolved Hide resolved

Andarist reviewed Oct 26, 2021

View reviewed changes

packages/sheet/__tests__/index.js Outdated Show resolved Hide resolved

Andarist reviewed Oct 26, 2021

View reviewed changes

mnajdova and others added 6 commits October 27, 2021 14:28

Update packages/cache/__tests__/index.js

3fc9c88

Co-authored-by: Mateusz Burzyński <mateuszburzynski@gmail.com>

Improve tests

c8fa22d

Use @testing-library

1c94b62

Address comments from review

74ab823

Fix some flow issues

218ea87

fix selectors

ef3412f

mnajdova requested a review from Andarist October 28, 2021 12:18

Andarist approved these changes Nov 2, 2021

View reviewed changes

small tweaks

61fcc7f

Andarist merged commit 516fe45 into emotion-js:main Nov 3, 2021

Andarist reviewed Nov 3, 2021

View reviewed changes

This was referenced Nov 3, 2021

Version Packages #2539

Merged

Version Packages eps1lon/emotion#1

Open

Andarist added a commit that referenced this pull request Nov 14, 2021

Tweak changesets created in #2521

9e82a99

Andarist mentioned this pull request Dec 2, 2021

Ability to insert styles at a specific position in <head> #2037

Closed

mnajdova mentioned this pull request Dec 22, 2021

[example] Avoid double rendering in the Remix example mui/material-ui#30366

Merged

ANTARES-KOR mentioned this pull request Mar 31, 2022

[examples] Change Next.js example's createEmotionCache from using 'prepend' to using 'insertionPoint' mui/material-ui#32068

Closed

2 tasks

sgarcia-dev mentioned this pull request Jul 27, 2022

Add configuration option to <ChakraProvider> to prepend, not append, Emotion's <style> tags to the <head> chakra-ui/chakra-ui#6381

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add `insertionPoint` option in `EmotionCache` #2521

Add `insertionPoint` option in `EmotionCache` #2521

mnajdova commented Oct 20, 2021 •

edited

changeset-bot bot commented Oct 20, 2021 •

edited

codesandbox-ci bot commented Oct 20, 2021 •

edited

codecov bot commented Oct 20, 2021 •

edited

Andarist Oct 20, 2021

mnajdova Oct 20, 2021

mnajdova Oct 20, 2021

Andarist Oct 26, 2021

mnajdova Oct 27, 2021

Andarist Oct 26, 2021

mnajdova Oct 27, 2021

Andarist Nov 3, 2021

power-f-GOD Feb 1, 2022

Andarist Feb 1, 2022

power-f-GOD Feb 5, 2022 •

edited

Andarist Feb 5, 2022

power-f-GOD Feb 6, 2022 •

edited

power-f-GOD Feb 6, 2022

power-f-GOD Feb 9, 2022 •

edited

Andarist Feb 9, 2022

power-f-GOD Feb 9, 2022

Andarist commented Nov 3, 2021

	prepend?: boolean
	/** @deprecate use `insertionPoint` instead */
	prepend?: boolean

Add insertionPoint option in EmotionCache #2521

Add insertionPoint option in EmotionCache #2521

Conversation

mnajdova commented Oct 20, 2021 • edited

changeset-bot bot commented Oct 20, 2021 • edited

🦋 Changeset detected

codesandbox-ci bot commented Oct 20, 2021 • edited

codecov bot commented Oct 20, 2021 • edited

Codecov Report

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

power-f-GOD Feb 5, 2022 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

power-f-GOD Feb 6, 2022 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

power-f-GOD Feb 9, 2022 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Andarist commented Nov 3, 2021

Add `insertionPoint` option in `EmotionCache` #2521

Add `insertionPoint` option in `EmotionCache` #2521

mnajdova commented Oct 20, 2021 •

edited

changeset-bot bot commented Oct 20, 2021 •

edited

codesandbox-ci bot commented Oct 20, 2021 •

edited

codecov bot commented Oct 20, 2021 •

edited

power-f-GOD Feb 5, 2022 •

edited

power-f-GOD Feb 6, 2022 •

edited

power-f-GOD Feb 9, 2022 •

edited