Troubleshooting

Verify your versions

Make sure your environment meets or exceeds these minimum versions.

Components look transparent or unstyled

Surfaces, borders and text colors come from the Docyrus design tokens (bg-background, border-field-border, bg-sheet-surface, …). If they render transparent, your Uniwind CSS entry is missing the tokens import — add it after Tailwind and Uniwind, with a path relative to that file:

@import "tailwindcss";
@import "uniwind";
@import "./docyrus-native/index.css";

The file is installed by the CLI with any rn-* component (docyrus add rn-styles installs it alone). Restart Metro with npx expo start --clear after changing the CSS entry. Theme X is missing variable … means a token you override is declared in one @variant but not the other; Cannot use @variant with unknown variant means color-schemes.css is imported without its themes in Metro extraThemes (or through a package path instead of a relative one) — see Theming.

Theme not applying

Make sure your app is wrapped with DocyThemeProvider at the root level. Without this provider, components will fall back to default styles. If using Expo Router, wrap it in your root _layout.tsx.

import { DocyThemeProvider } from '@/lib/docyrus/theme';

export default function RootLayout() {
  return (
    <DocyThemeProvider>
      {/* Your app content */}
    </DocyThemeProvider>
  );
}

Expo Go compatibility

Some native components require a development build and won't work in Expo Go. Check the component's documentation for Expo Go compatibility. Components that use native modules require npx expo prebuild and a custom dev client:

npx expo prebuild
npx expo run:ios

Missing peer dependencies

Native components declare peer dependencies for packages like react-native-svg, expo-document-picker, and expo-localization. If you see module resolution errors, install the required dependency:

npx expo install react-native-svg
npx expo install expo-document-picker
npx expo install expo-localization

Font Awesome icons not loading

If DocyrusIcon is not rendering icons, make sure you've configured the icon CDN path correctly. Native icons are loaded from the Docyrus CDN — verify your network connectivity and that the icon name matches the registry.

React Native Reanimated errors

If you see errors related to Reanimated, make sure you've added the Babel plugin:

module.exports = function(api) {
  api.cache(true);
  return {
    presets: ['babel-preset-expo'],
    plugins: ['react-native-reanimated/plugin'],
  };
};

Metro bundler cache issues

If you're seeing stale code or unexpected errors after installing new components, clear the Metro cache:

npx expo start --clear

Still having issues?

If none of the above solutions resolve your problem, please open an issue on GitHub with a description of what you're experiencing and your environment details.