Troubleshooting

Verify your versions

Make sure your environment meets or exceeds these minimum versions to ensure Docyrus UI components work correctly.

Web

React Native

Web

Registry not found

If you see a "registry not found" error when installing components, make sure you've added the Docyrus registry to your components.json file. The registry URL should point to https://ui.docy.app/r. Without this entry, neither the shadcn CLI nor the Docyrus CLI will know where to fetch components from.

Components not resolving after installation

After installing a component, your imports should point to the local file path where the component was placed — not to an NPM package. If your IDE shows unresolved imports, check that the component files were actually written to disk and that your TypeScript path aliases match the install location.

Tailwind CSS v4 classes not applying

Tailwind CSS v4 uses a CSS-based configuration system. If component styles aren't applying, make sure your CSS entry file includes a @source directive that covers the directory where Docyrus UI components are installed. Without this, Tailwind's compiler won't scan those files for utility classes.

Dark mode not working

Docyrus UI components use CSS custom properties (CSS variables) for theming. Dark mode relies on these variables being defined in your global stylesheet. If dark mode isn't working, verify that your theme variables are set up correctly for both light and dark color schemes.

Motion library version conflicts

Some Docyrus UI components use the Motion library for animations. If you see runtime errors related to motion or framer-motion, make sure you're using a compatible version. Docyrus UI targets Motion v12 and above.

React Native

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.

Expo Go compatibility

Some native components require a development build and won't work in Expo Go. Check the component's expoGoCompatible flag in the documentation. Components that use native modules (e.g., expo-document-picker, expo-localization) require npx expo prebuild and a custom dev client.

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 peer dependency:

npx expo install react-native-svg

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.

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.