diff --git a/README (1).md b/README (1).md new file mode 100644 index 0000000..5a1a4fc --- /dev/null +++ b/README (1).md @@ -0,0 +1,46 @@ +--- +description: How to integrate emotion cache with TSS +--- + +# 💽 Cache + +By default, `tss-react` uses an emotion cache that you can access with + +```tsx +import { getTssDefaultEmotionCache } from "tss-react" +``` + +If you want `tss-react` to use a specific [emotion cache](https://emotion.sh/docs/@emotion/cache) you can provide it using + +```typescript +import { TssCacheProvider } from "tss-react" +``` + +If you are using `tss-react` with mui, be aware that mui and TSS can't share the same cache. + +Also the caches used by mui should have be instantiated with `"prepend": true`. + +```tsx +import createCache from "@emotion/cache"; +import { TssCacheProvider } from "tss-react; +import { CacheProvider } from "@emotion/react"; + +const muiCache = createMuiCache({ + "key": "my-custom-prefix-for-mui", + "prepend": true +}); + +const tssCache = createMuiCache({ + "key": "my-custom-prefix-for-tss" +}); + + + + {/* ... */} + +; +``` + +{% hint style="info" %} +Using custom emotion caches impact how you [setup SSR](ssr/). +{% endhint %} diff --git a/README.md b/README.md index caeba85..4aac1ae 100644 --- a/README.md +++ b/README.md @@ -1,46 +1,67 @@ ---- -description: How to integrate emotion cache with TSS ---- +# 🔩 MUI Integration -# Cache +{% hint style="info" %} +If you are migrating from `@material-ui/core` (v4) to `@mui/material` (v5) checkout the migration guide from MUI's documentation website [here](https://mui.com/guides/migration-v4/#2-use-tss-react). +{% endhint %} -By default, `tss-react` uses an emotion cache that you can access with +{% hint style="info" %} +If you are still using material-ui v4 [here is a reference setup](https://github.com/garronej/tss-react/tree/main/src/test/apps/muiV4ssr). +{% endhint %} ```tsx -import { getTssDefaultEmotionCache } from "tss-react" +import { render } from "react-dom"; +import { CacheProvider } from "@emotion/react"; +import createCache from "@emotion/cache"; +import { ThemeProvider } from "@mui/material/styles"; + +export const muiCache = createCache({ + "key": "mui", + "prepend": true, +}); + +//NOTE: Don't use +render( + + + + + , + document.getElementById("root") +); ``` -If you want `tss-react` to use a specific [emotion cache](https://emotion.sh/docs/@emotion/cache) you can provide it using +As a MUI user (if you are using TypeScript >= v4.4), you can simply: ```typescript -import { TssCacheProvider } from "tss-react" +import { makeStyles, withStyles } from "tss-react/mui"; ``` -If you are using `tss-react` with mui, be aware that mui and TSS can't share the same cache. +The theme object that will be passed to your callbacks functions will be the one you get with `import { useTheme } from "@mui/material/styles"`. -Also the caches used by mui should have be instantiated with `"prepend": true`. +If you want to take controls over what the `theme` object should be, you can re-export `makeStyles` and `withStyles` from a file called, for example, `makesStyles.ts`: -```tsx -import createCache from "@emotion/cache"; -import { TssCacheProvider } from "tss-react; -import { CacheProvider } from "@emotion/react"; +```typescript +import { useTheme } from "@mui/material/styles"; +//WARNING: tss-react require TypeScript v4.4 or newer. If you can't update use: +//import { createMakeAndWithStyles } from "tss-react/compat"; +import { createMakeAndWithStyles } from "tss-react"; -const muiCache = createMuiCache({ - "key": "my-custom-prefix-for-mui", - "prepend": true +export const { makeStyles, withStyles } = createMakeAndWithStyles({ + useTheme, + // OR, if you have extended the default mui theme adding your own custom properties: + // Let's assume the myTheme object that you provide to the is of + // type MyTheme then you'll write: + //"useTheme": useTheme as (()=> MyTheme) }); +``` -const tssCache = createMuiCache({ - "key": "my-custom-prefix-for-tss" -}); +{% hint style="warning" %} +**Keep `@emotion/styled` as a dependency of your project**. - - - {/* ... */} - -; -``` +Even if you never use it explicitly, it's a peer dependency of `@mui/material`. +{% endhint %} -{% hint style="info" %} -Using custom emotion caches impact how you [setup SSR](ssr/). +{% hint style="warning" %} +[Storybook](https://storybook.js.org): As of writing this lines storybook still uses by default emotion 10.\ +Material-ui and TSS runs emotion 11 so there is [some changes](https://github.com/garronej/onyxia-ui/blob/324de62248074582b227e584c53fb2e123f5325f/.storybook/main.js#L31-L32) to be made to your `.storybook/main.js` to make it uses emotion 11. {% endhint %} diff --git a/SUMMARY.md b/SUMMARY.md index d453846..3ac1b89 100644 --- a/SUMMARY.md +++ b/SUMMARY.md @@ -1,7 +1,8 @@ # Table of contents -* [🤓 Cache](README.md) +* [🔩 MUI Integration](README.md) +* [💽 Cache]() * [💲 Nested selectors (ex $ syntax)](nested-selectors-ex-usd-syntax.md) -* [SSR](ssr/README.md) +* [⚡ SSR](ssr/README.md) * [Next.js](ssr/next.js.md) * [Other backend](ssr/other-backend.md) diff --git a/nested-selectors-ex-usd-syntax.md b/nested-selectors-ex-usd-syntax.md index fe4cf88..426a514 100644 --- a/nested-selectors-ex-usd-syntax.md +++ b/nested-selectors-ex-usd-syntax.md @@ -1,4 +1,4 @@ -# Nested selectors (ex $ syntax) +# 💲 Nested selectors (ex $ syntax) `tss-react` unlike `jss-react` doesn't support the `$` syntax but a better alternative. diff --git a/ssr/README.md b/ssr/README.md index bff4d14..163bd47 100644 --- a/ssr/README.md +++ b/ssr/README.md @@ -2,6 +2,6 @@ description: How to configure Server Side Sendering --- -# SSR +# ⚡ SSR There are some minimal configuration required to make `tss-react` work with SSR.