Prevent Cloudflare Rocket Loader deferring script (#156)

* Prevent Cloudflare Rocket Loader deferring script

* Add scriptAttribute prop to ThemeProvider

* Wording

* fix types, add test

---------

Co-authored-by: Paco <34928425+pacocoursey@users.noreply.github.com>

next-themes/README.md

@@ -157,6 +157,7 @@ All your theme configuration is passed to ThemeProvider.
 - `value`: Optional mapping of theme name to attribute value
   - value is an `object` where key is the theme name and value is the attribute value ([example](#differing-dom-attribute-and-theme-name))
 - `nonce`: Optional nonce passed to the injected `script` tag, used to allow-list the next-themes script in your CSP
+- `scriptProps`: Optional props to pass to the injected `script` tag ([example](#using-with-cloudflare-rocket-loader))
 
 ### useTheme
 
@@ -267,6 +268,14 @@ document.documentElement.getAttribute('data-theme')
 // => "my-pink-theme"
 ```
 
+### Using with Cloudflare Rocket Loader
+
+[Rocket Loader](https://developers.cloudflare.com/fundamentals/speed/rocket-loader/) is a Cloudflare optimization that defers the loading of inline and external scripts to prioritize the website content. Since next-themes relies on a script injection to avoid screen flashing on page load, Rocket Loader breaks this functionality. Individual scripts [can be ignored](https://developers.cloudflare.com/fundamentals/speed/rocket-loader/ignore-javascripts/) by adding the `data-cfasync="false"` attribute to the script tag:
+
+```jsx
+<ThemeProvider scriptProps={{ 'data-cfasync': 'false' }}>
+```
+
 ### More than light and dark mode
 
 next-themes is designed to support any number of themes! Simply pass a list of themes:

next-themes/__tests__/index.test.tsx

@@ -460,3 +460,17 @@ describe('setTheme', () => {
     expect(result.current.resolvedTheme).toBe('light')
   })
 })
+
+describe('inline script', () => {
+  test('should pass props to script', () => {
+    act(() => {
+      render(
+        <ThemeProvider defaultTheme="light" scriptProps={{ 'data-test': '1234' }}>
+          <HelperComponent />
+        </ThemeProvider>
+      )
+    })
+
+    expect(document.querySelector('script[data-test="1234"]')).toBeTruthy()
+  })
+})

next-themes/src/index.tsx

@@ -33,7 +33,8 @@ const Theme = ({
   attribute = 'data-theme',
   value,
   children,
-  nonce
+  nonce,
+  scriptProps
 }: ThemeProviderProps) => {
   const [theme, setThemeState] = React.useState(() => getTheme(storageKey, defaultTheme))
   const [resolvedTheme, setResolvedTheme] = React.useState(() => getTheme(storageKey))
@@ -161,7 +162,8 @@ const Theme = ({
           defaultTheme,
           value,
           themes,
-          nonce
+          nonce,
+          scriptProps
         }}
       />
 
@@ -180,7 +182,8 @@ const ThemeScript = React.memo(
     defaultTheme,
     value,
     themes,
-    nonce
+    nonce,
+    scriptProps
   }: Omit<ThemeProviderProps, 'children'> & { defaultTheme: string }) => {
     const scriptArgs = JSON.stringify([
       attribute,
@@ -195,6 +198,7 @@ const ThemeScript = React.memo(
 
     return (
       <script
+        {...scriptProps}
         suppressHydrationWarning
         nonce={typeof window === 'undefined' ? nonce : ''}
         dangerouslySetInnerHTML={{ __html: `(${script.toString()})(${scriptArgs})` }}

next-themes/src/types.ts

@@ -4,6 +4,16 @@ interface ValueObject {
   [themeName: string]: string
 }
 
+type DataAttribute = `data-${string}`
+
+interface ScriptProps
+  extends React.DetailedHTMLProps<
+    React.ScriptHTMLAttributes<HTMLScriptElement>,
+    HTMLScriptElement
+  > {
+  [dataAttribute: DataAttribute]: any
+}
+
 export interface UseThemeProps {
   /** List of all available theme names */
   themes: string[]
@@ -19,7 +29,7 @@ export interface UseThemeProps {
   systemTheme?: 'dark' | 'light' | undefined
 }
 
-export type Attribute = `data-${string}` | 'class'
+export type Attribute = DataAttribute | 'class'
 
 export interface ThemeProviderProps extends React.PropsWithChildren {
   /** List of all available theme names */
@@ -41,5 +51,7 @@ export interface ThemeProviderProps extends React.PropsWithChildren {
   /** Mapping of theme name to HTML attribute value. Object where key is the theme name and value is the attribute value */
   value?: ValueObject | undefined
   /** Nonce string to pass to the inline script for CSP headers */
-  nonce?: string | undefined
+  nonce?: string
+  /** Props to pass the inline script */
+  scriptProps?: ScriptProps
 }