Developing with Tamagui

Tamagui includes many helpful tools for debugging UI.

Tamagui has several ways of giving you more insight into what’s happening at compile-time.

Visualizer

You can set up a simple visualizer that shows a heads-up display when you hold “Option” (or any key you define) after a short delay, revealing the styled component names and even the file numbers and components they are in (if you have the compiler plugin installed) as an overlay over your app in development mode.

import { setupDev } from '@tamagui/core'

setupDev({
  // can just be true as well for defaulting to key: Alt + delay: 800
  visualizer: {
    key: 'Alt',
    delay: 800,
  },
})
Copy

Debug Pragma

To see what’s being extracted, why, and every step along the optimization pipeline, add // debug to the top of any file. Adding // debug-verbose will show even more information, including more granular timings.

If you’re developing in your design system package that is built with @tamagui/build, esbuild will strip this banner. You can try using //! debug (esbuild only preserves comments at the top that start with //!), but still occasionally esbuild will insert a helper above the comment, breaking it, so be sure to check the built file in dist/jsx.

Debug Prop

Adding debug to any Tamagui component outputs detailed information about what’s happening at runtime. Use it like so:

import { Button } from 'tamagui'

export default () => <Button debug>Hello world</Button>
Copy

You’ll see props, styles, and a variety of variables relevant to processing them.

You can do <Button debug="break" /> to have it break at the beginning of rendering, or <Button debug="verbose" /> to have it output more detailed debug information.

DEBUG Environment Variable

If you set DEBUG=tamagui before your build command, you get the full debug output of every file built. This is useful for seeing everything that’s happening across every file and is especially helpful for diagnosing production issues.

In development mode, Tamagui sets the variable Tamagui onto globalThis with a lot of helpful internals, including your entire parsed config from tamagui.config.ts.

Beyond your config, you have:

• allSelectors: All the selectors inserted by Tamagui (before runtime).

Inspecting Components

Any styled() component will have a staticConfig property attached to it:

const Circle = styled(View, {
  borderRadius: 1000,
})

console.log(Circle.staticConfig) // lots of helpful information
Copy

• componentName is taken from the name key
• variants contains the merged variants including parents.
• defaultProps is the extracted props left to use as defaults on the component.

Tamagui generates helpful CSS classes. For components created with styled() where a name is set like this:

const MyButton = styled(View, {
  name: 'MyButton',
  backgroundColor: 'red',
})
Copy

Tamagui adds the classname is_MyButton. This is a useful escape hatch for attaching CSS to any extra component. All the default Tamagui components have their name set.

For components that extend a Text-based component, a further classname is set of the format font_[fontFamily]. So if you do:

<Paragraph fontFamily="$body" />
Copy

The classnames is_Paragraph and font_body will be output to DOM.