Conflicting Docs: Optimizing Tamagui CSS in Next.js App Router #3517

24dlong · 2025-06-22T15:18:59Z

24dlong
Jun 22, 2025

I'm trying to figure out the optimal way to load tamagui generated css into my next.js application. The configuration guide suggests either injecting css inline using config.getCSS() or using outputCss to create and import a tamagui.css generated at build time.

However, tamagui's (next.js App Router guide)[https://tamagui.dev/docs/guides/next-js#applayouttsx] does both. This approach seems to contradict the configuration guide's suggestion to only do 1 of the options.

Which is the proper approach?
Also, any idea why disableInjectCSS is not set in the next.js TamaguiProvider? It seems to me like this should definitely be set based on the information from the Configuration doc. Furthermore, it seems to be set in the Pages Router's TamaguiProvider, so I'm wondering if this was intentionally left out in the App Router guide, or just an oversight (I suspect the latter, but figured I'd confirm)

Relevant Documentation Snippets

From the tamagui configuration guide:

By default, Tamagui injects the CSS for your configuration on the client-side into document.head, but you probably will want something better for production. To do this, pass true to disableInjectCSS on TamaguProvider, and then do one of the following three options:

If your framework has server-side layouts, you can just render it inline:

// app/_layout.tsx
import { config } from './tamagui.config'

export default () => (
  <html>
    <head>
      <style
        dangerouslySetInnerHTML={{
          __html: config.getCSS(),
        }}
      />
    </head>
    <body>
      <Slot />
    </body>
  </html>
)

To optimize a bit more so you share a single CSS file between all pages, you can use one of our bundler plugins' outputCSS setting, like so:

// vite.config.ts
import { tamaguiPlugin } from '@tamagui/vite-plugin'

export default {
  plugins: [
    tamaguiPlugin({
      config: './src/tamagui.config.ts',
      outputCSS: './src/tamagui.css'
    }),
  ]
}

And then you'll want to import the resulting tamagui.css into your app.

And from the (next.js guide)[https://tamagui.dev/docs/guides/next-js#applayouttsx]:

Create a new component to add TamaguiProvider:

'use client'

import '@tamagui/core/reset.css'
import '@tamagui/polyfill-dev'

import { ReactNode } from 'react'
import { StyleSheet } from 'react-native'
import { useServerInsertedHTML } from 'next/navigation'
import { NextThemeProvider } from '@tamagui/next-theme'
import { TamaguiProvider } from 'tamagui'
import tamaguiConfig from '../tamagui.config'

export const NextTamaguiProvider = ({ children }: { children: ReactNode }) => {

  useServerInsertedHTML(() => {
    // @ts-ignore
    const rnwStyle = StyleSheet.getSheet()
    return (
      <>
        <style
          dangerouslySetInnerHTML={{ __html: rnwStyle.textContent }}
          id={rnwStyle.id}
        />
        <style
          dangerouslySetInnerHTML={{
            // the first time this runs you'll get the full CSS including all themes
            // after that, it will only return CSS generated since the last call
            __html: tamaguiConfig.getNewCSS(),
          }}
        />
      </>
    )
  })

  return (
    <NextThemeProvider skipNextHead>
      <TamaguiProvider config={tamaguiConfig} disableRootThemeClass>
        {children}
      </TamaguiProvider>
    </NextThemeProvider>
  )
}

Then add it to your app/layout.tsx:

import { Metadata } from 'next'
import { NextTamaguiProvider } from './NextTamaguiProvider'

export const metadata: Metadata = {
  title: 'Your page title',
  description: 'Your page description',
  icons: '/favicon.ico',
}

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        <NextTamaguiProvider>{children}</NextTamaguiProvider>
      </body>
    </html>
  )
}

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

Conflicting Docs: Optimizing Tamagui CSS in Next.js App Router #3517

Uh oh!

{{title}}

Uh oh!

Replies: 0 comments

Select a reply

Uh oh!

Uh oh!

Conflicting Docs: Optimizing Tamagui CSS in Next.js App Router #3517

Uh oh!

24dlong Jun 22, 2025

Replies: 0 comments

24dlong
Jun 22, 2025