Merge pull request #15 from mayank1513/optimize-ssg

Optimize-ssg
react18-tools · Dec 2, 2023 · 7d4d99b · 7d4d99b
2 parents cd71805 + 0732658
commit 7d4d99b
Show file tree

Hide file tree

Showing 71 changed files with 3,577 additions and 523 deletions.
diff --git a/.changeset/four-emus-camp.md b/.changeset/four-emus-camp.md
@@ -0,0 +1,5 @@
+---
+"nextjs-themes": minor
+---
+
+Add SSG optimization for Next.js app router
diff --git a/.github/workflows/publish-to-npm-on-new-release.yml b/.github/workflows/publish-to-npm-on-new-release.yml
@@ -29,7 +29,7 @@ jobs:
       - name: Setup Git
         run: |
           git config --global user.name "mayank1513"
-          git config --global user.email "mayank[email protected].com"
+          git config --global user.email "mayank.srmu@gmail.com"
           git fetch
           git checkout main
       - name: update version and push back to the repo

diff --git a/README.md b/README.md
@@ -1,4 +1,8 @@
-# Nextjs-Themes [![Version](https://img.shields.io/npm/v/nextjs-themes.svg?colorB=green)](https://www.npmjs.com/package/nextjs-themes) [![codecov](https://codecov.io/gh/mayank1513/nextjs-themes/branch/main/graph/badge.svg?token=SUTY0GHPHV)](https://codecov.io/gh/mayank1513/nextjs-themes) [![Downloads](https://img.jsdelivr.com/img.shields.io/npm/dt/nextjs-themes.svg)](https://www.npmjs.com/package/nextjs-themes) [![npm bundle size](https://img.shields.io/bundlephobia/minzip/nextjs-themes)](https://www.npmjs.com/package/nextjs-themes) [![Publish to npm and GitHub](https://github.com/mayank1513/nextjs-themes/actions/workflows/test.yml/badge.svg)](https://github.com/mayank1513/nextjs-themes/actions/workflows/publish-to-npm-on-new-release.yml)
+# Nextjs-Themes [![Version](https://img.shields.io/npm/v/nextjs-themes.svg?colorB=green)](https://www.npmjs.com/package/nextjs-themes) [![codecov](https://codecov.io/gh/mayank1513/nextjs-themes/branch/main/graph/badge.svg?token=SUTY0GHPHV)](https://codecov.io/gh/mayank1513/nextjs-themes) [![Downloads](https://img.jsdelivr.com/img.shields.io/npm/dt/nextjs-themes.svg)](https://www.npmjs.com/package/nextjs-themes) [![npm bundle size](https://img.shields.io/bundlephobia/minzip/nextjs-themes)](https://www.npmjs.com/package/nextjs-themes) [![Publish to npm and GitHub](https://github.com/mayank1513/nextjs-themes/actions/workflows/test.yml/badge.svg)](https://github.com/mayank1513/nextjs-themes/actions/workflows/publish-to-npm-on-new-release.yml) [![Contact me on Codementor](https://www.codementor.io/m-badges/mayank1513/get-help.svg)](https://www.codementor.io/@mayank1513?refer=badge)
+
+> This is a sister package of [react18-themes](https://github.com/react18-tools/react18-themes/). Initially we targeted only Next.js and thus this package was named `nextjs-themes`. However, we have expanded support for `Vite` and `Remix` as well. And thus published a package with more generic name, `react18-themes`.
+
+> We recommend using [react18-themes](https://github.com/react18-tools/react18-themes/) for latest updates. Though this package is also maintained with specific focus on Next.js, all the functionality of this package along with extended support for other build tools is available in [react18-themes](https://github.com/react18-tools/react18-themes/)
 
 🤟 👉 [Unleash the Power of React Server Components](https://medium.com/javascript-in-plain-english/unleash-the-power-of-react-server-components-eb3fe7201231)
 
@@ -14,12 +18,13 @@ This project is inspired by next-themes. Next-themes is an awesome package, howe
 - ✅ Perfect dark mode in 2 lines of code
 - ✅ System setting with prefers-color-scheme
 - ✅ Themed browser UI with color-scheme
-- ✅ Support for Next.js 13 `appDir`
+- ✅ Support for Next.js 13 & Next.js 14 `appDir`
 - ✅ Sync theme across tabs and windows
 - ✅ Disable flashing when changing themes
 - ✅ Force pages to specific themes
 - ✅ Class or data attribute selector
 - ✅ Manipulate theme via `useTheme` hook
+- ✅ Doccumented with [Typedoc](https://react18-tools.github.io/nextjs-themes) ([Docs](https://react18-tools.github.io/nextjs-themes))
 
 Check out the [live example](https://nextjs-themes.vercel.app/).
 
@@ -33,7 +38,7 @@ $ npm install nextjs-themes
 $ yarn add nextjs-themes
 ```
 
-## Want Lite Version? [![npm bundle size](https://img.shields.io/bundlephobia/minzip/nextjs-themes-lite)](https://www.npmjs.com/package/nextjs-themes-lite)
+## Want Lite Version? [![npm bundle size](https://img.shields.io/bundlephobia/minzip/nextjs-themes-lite)](https://www.npmjs.com/package/nextjs-themes-lite) [![Version](https://img.shields.io/npm/v/nextjs-themes-lite.svg?colorB=green)](https://www.npmjs.com/package/nextjs-themes-lite) [![Downloads](https://img.jsdelivr.com/img.shields.io/npm/dt/nextjs-themes-lite.svg)](https://www.npmjs.com/package/nextjs-themes-lite)
 
 ```bash
 $ pnpm add nextjs-themes-lite
@@ -45,24 +50,28 @@ $ yarn add nextjs-themes-lite
 
 > You need Zustand as a peer-dependency
 
-## Use
+## To do
+
+- [ ] Update examples
+
+## Usage
 
-### With pages/
+### SPA (e.g., Vite, CRA) and Next.js pages directory (No server components)
 
 The best way is to add a [Custom `App`](https://nextjs.org/docs/advanced-features/custom-app) to use by modifying `_app` as follows:
 
 Adding dark mode support takes 2 lines of code:
 
 ```js
-import { ThemeSwitcher } from "next-themes";
+import { ThemeSwitcher } from "nextjs-themes";
 
 function MyApp({ Component, pageProps }) {
-  return (
-    <>
-      <ThemeSwitcher forcedTheme={Component.theme} />
-      <Component {...pageProps} />
-    </>
-  );
+	return (
+		<>
+			<ThemeSwitcher forcedTheme={Component.theme} />
+			<Component {...pageProps} />
+		</>
+	);
 }
 
 export default MyApp;
@@ -72,44 +81,83 @@ export default MyApp;
 
 Check out examples for advanced usage.
 
-### With app/
+### With Next.js `app` router (Server Components)
 
-Update your `app/layout.jsx` to add `ThemeSwitcher` and `SSCWrapper` from `nextjs-themes`. `SSCWrapper` is required to avoid flash of un-themed content on reload.
+#### Prefer static generation over SSR - No wrapper component
 
-```js
+> If your app is mostly serving static content, you do not want the overhead of SSR. Use `NextJsSSGThemeSwitcher` in this case.
+> When using this approach, you need to use CSS general sibling Combinator (~) to make sure your themed CSS is properly applied. See (HTML & CSS)[#html--css].
+
+Update your `app/layout.jsx` to add `ThemeSwitcher` from `nextjs-themes`, and `NextJsSSGThemeSwitcher` from `nextjs-themes/server`. `NextJsSSGThemeSwitcher` is required to avoid flash of un-themed content on reload.
+
+```tsx
+// app/layout.jsx
+import { ThemeSwitcher } from "nextjs-themes";
+import { NextJsSSGThemeSwitcher } from "nextjs-themes/server/nextjs";
+
+export default function Layout({ children }) {
+	return (
+		<html lang="en">
+			<head />
+			<body>
+				/** use NextJsSSGThemeSwitcher as first element inside body */
+				<NextJsSSGThemeSwitcher />
+				<ThemeSwitcher />
+				{children}
+			</body>
+		</html>
+	);
+}
+```
+
+Woohoo! You just added multiple theme modes and you can also use Server Component! Isn't that awesome!
+
+#### Prefer SSR over SSG - Use wrapper component
+
+> If your app is serving dynamic content and you want to utilize SSR, continue using `ServerSideWrapper` component to replace `html` tag in `layout.tsx` file.
+
+Update your `app/layout.jsx` to add `ThemeSwitcher` and `ServerSideWrapper` from `nextjs-themes`. `ServerSideWrapper` is required to avoid flash of un-themed content on reload.
+
+```tsx
 // app/layout.jsx
-import { ThemeSwitcher } from "next-themes";
-import { SSCWrapper } from "next-themes/server/nextjs";
+import { ThemeSwitcher } from "nextjs-themes";
+import { ServerSideWrapper } from "nextjs-themes/server/nextjs";
 
 export default function Layout({ children }) {
-  return (
-    <SSCWrapper tag="html" lang="en">
-      <head />
-      <body>
-        <ThemeSwitcher />
-        {children}
-      </body>
-    </SSCWrapper>
-  );
+	return (
+		<ServerSideWrapper tag="html" lang="en">
+			<head />
+			<body>
+				<ThemeSwitcher />
+				{children}
+			</body>
+		</ServerSideWrapper>
+	);
 }
 ```
 
 Woohoo! You just added dark mode and you can also use Server Component! Isn't that awesome!
 
 ### HTML & CSS
 
-That's it, your Next.js app fully supports dark mode, including System preference with `prefers-color-scheme`. The theme is also immediately synced between tabs. By default, next-themes modifies the `data-theme` attribute on the `html` element, which you can easily use to style your app:
+That's it, your Next.js app fully supports dark mode, including System preference with `prefers-color-scheme`. The theme is also immediately synced between tabs. By default, nextjs-themes modifies the `data-theme` attribute on the `html` element, which you can easily use to style your app:
 
 ```css
 :root {
-  /* Your default theme */
-  --background: white;
-  --foreground: black;
+	/* Your default theme */
+	--background: white;
+	--foreground: black;
 }
 
 [data-theme="dark"] {
-  --background: black;
-  --foreground: white;
+	--background: black;
+	--foreground: white;
+}
+
+// v2 onwards when using NextJsSSGThemeSwitcher, we need to use CSS Combinators
+[data-theme="dark"] ~ * {
+	--background: black;
+	--foreground: white;
 }
 ```
 
@@ -121,18 +169,18 @@ In case your components need to know the current theme and be able to change it.
 import { useTheme } from "nextjs-themes";
 
 const ThemeChanger = () => {
-  /* you can also improve performance by using selectors
-   * const [theme, setTheme] = useTheme(state => [state.theme, state.setTheme]);
-   */
-  const { theme, setTheme } = useTheme();
-
-  return (
-    <div>
-      The current theme is: {theme}
-      <button onClick={() => setTheme("light")}>Light Mode</button>
-      <button onClick={() => setTheme("dark")}>Dark Mode</button>
-    </div>
-  );
+	/* you can also improve performance by using selectors
+	 * const [theme, setTheme] = useTheme(state => [state.theme, state.setTheme]);
+	 */
+	const { theme, setTheme } = useTheme();
+
+	return (
+		<div>
+			The current theme is: {theme}
+			<button onClick={() => setTheme("light")}>Light Mode</button>
+			<button onClick={() => setTheme("dark")}>Dark Mode</button>
+		</div>
+	);
 };
 ```
 
@@ -144,12 +192,12 @@ const ThemeChanger = () => {
 import { ForceTheme } from "nextjs-themes";
 
 function MyPage() {
-  return (
-    <>
-      <ForceTheme theme={"my-theme"} />
-      ...
-    </>
-  );
+	return (
+		<>
+			<ForceTheme theme={"my-theme"} />
+			...
+		</>
+	);
 }
 
 export default MyPage;
@@ -161,7 +209,7 @@ For pages router, you have 2 options. One is the same as the app router and the
 
 ```javascript
 function MyPage() {
-  return <>...</>;
+	return <>...</>;
 }
 
 MyPage.theme = "my-theme";
@@ -173,14 +221,34 @@ In a similar way, you can also force color scheme.
 
 Forcing color scheme will apply your defaultDark or defaultLight theme, configurable via hooks.
 
+## Migrating from v1 to v2
+
+#### Motivation:
+
+For server side syncing, we need to use cookies and headers. This means that this component and its children can not be static. They will be rendered server side for each request. Thus, we are avoiding the wrapper. Now, only the `NextJsSSGThemeSwitcher` will be rendered server side for each request and rest of your app can be server statically.
+
+Take care of the following while migrating to `v2`.
+
+- No changes required for projects not using `Next.js` app router or server components other than updating cookies policy if needed.
+- The persistent storage is realized with `cookies` in place of `localStorage`. (You might want to update cookies policy accordingly.)
+- We have provided `NextJsSSGThemeSwitcher` in addition to `ServerSideWrapper` for `Next.js`. You no longer need to use a wrapper component which broke static generation and forced SSR.
+- Visit [With Next.js `app` router (Server Components)](#with-nextjs-app-router-server-components)
+
 ## Migrating from v0 to v1
 
 - `defaultDarkTheme` is renamed to `darkTheme`
 - `setDefaultDarkTheme` is renamed to `setDarkTheme`
 - `defaultLightTheme` is renamed to `lightTheme`
 - `setDefaultLightTheme` is renamed to `setLightTheme`
 
-> Full docs coming soon!
+## Docs
+
+[Typedoc](https://react18-tools.github.io/nextjs-themes)
+
+### 🤩 Don't forger to start this repo!
+
+Want handson course for getting started with Turborepo? Check out [React and Next.js with TypeScript](https://www.udemy.com/course/react-and-next-js-with-typescript/?referralCode=7202184A1E57C3DCA8B2)
+
 
 ## License
 

diff --git a/docs/.nojekyll b/docs/.nojekyll
@@ -0,0 +1 @@
+TypeDoc added this file to prevent GitHub Pages from using Jekyll. You can turn off this behavior by setting the `githubPages` option to false.