docs: document how to override emotion's css output target

apollographql · Aug 11, 2019 · 59e42fc · 59e42fc
1 parent e8533cc
commit 59e42fc
Showing 1 changed file with 23 additions and 16 deletions.
diff --git a/README.md b/README.md
@@ -59,27 +59,34 @@ function MyComponent() {
 
 ### Emotion
 
-Some components are styled with [emotion](https://emotion.sh) under the hood; emotion appends `<style>` tags to your `<head>` element at runtime. This may cause emotions's styles to be included _after_ your project's styles, preventing you from using your own classes to override emotion's. To get around this, you need to modify how emotion adds styles to the DOM. Check out the [docs](https://emotion.sh/docs/@emotion/cache). Here's an example:
+Some components are styled with [emotion](https://emotion.sh) under the hood; emotion appends `<style>` tags to your `<head>` element at runtime. This may cause emotions's styles to be included _after_ your project's styules, preventing you from using your own classes to override emotion's. 
 
-```ts
-import React from "react";
-import { CacheProvider } from "@emotion/core";
-import createCache from "@emotion/cache";
-import { RealApp } from "./RealApp";
-
-// This expects you to have added `<style id="emotionStyleContainer"></style>` somewhere to the DOM
-const emotionCache = createCache({
-  container:
-    document.querySelector<HTMLElement>("#emotionStyleContainer") || undefined,
-});
+Ideally we'd be able to use Emotion's `<CacheProvider>` to control where Space Kit's styles would be injected, but an emotion bug ([emotion-js/emotion#1386](https://github.com/emotion-js/emotion/issues/1386)) causes `CacheProvider`s to not be recognized for bundled components.
+
+To get around this issue, we export the `emotionCacheProviderFactor` factory that you can use to create a cache provider that will work.
+
+Example:
+
+```tsx
+import { emotionCacheProviderFactory } from '@apollo/space-kit/emotionCacheProviderFactory`;
 
-export const App = (): React.FC => (
-  <CacheProvider value={emotionCache}>
-    <RealApp />
-  </CacheProvider>
+const CacheProvider = emotionCacheProviderFactor(document.queryElement('#spaceKitEmotionStyleContainer'));
+
+const App = (
+  <CacheProvider>
+    <AppCode />
+  </Cache>
 );
 ```
 
+This expects the following to exist somewhere in the DOM:
+
+```html
+<style id="spaceKitEmotionStyleContainer"></style>
+```
+
+All styles will be placed inside of that component.
+
 ### Stylesheet reset
 
 A "base" stylesheet with a few sensible rules. It uses [normalize.css](https://necolas.github.io/normalize.css/) to smooth out any inconsistencies between the ways that different browsers render elements. It also applies `box-sizing: border-box;` to everything, for [a better element sizing experience](https://www.paulirish.com/2012/box-sizing-border-box-ftw/). Lastly, the stylesheet imports and sets our two main font families: [Source Sans Pro](https://fonts.google.com/specimen/Source+Sans+Pro), and [Source Code Pro](https://fonts.google.com/specimen/Source+Code+Pro).