Developing with Tamagui

Importing from React Native

In general either your Webpack configuration or using @tamagui/next-plugin, you will be aliasing react-native to react-native-web. This means you should import anything you need from react-native directly and never import for react-native-web. Your bundler will handle automatically changing it.

Classes generated

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

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

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 component that extends a Text-based component, a further classname is set of the format font_[fontFamily]. So if you do:

<Paragraph fontFamily="$body" />

The classnames is_Paragraph and font_body will be output to DOM.

Debugging

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

You can setup a simple visualizer that shows a quick heads-up-display when you hold "Option" (or any key you define) after a short period of time, revealing the styled components names and even the file numbers and components they are in (if you have the compiler plugin installed) as an overlay over 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
  }
})

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 helpers above the comment, breaking it, so be sure to check the built file in dist/jsx.

Adding debug to any Tamagui component will output a lot of information on what's going on at runtime. Use it like so:

import { Button } from 'tamagui'

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

And 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.

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

Runtime introspection

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).

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

• 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.