Common Issues

This document collects tips and tricks for debugging common issues. If you'd like to see a workaround documented here, please submit it to our GitHub issues.

If you see an error while rendering from the server, it can often be hard to diagnose. There's a few ways to debug it.

First, we've found turning off Vite external dependencies entirely will often help, what it does is make Vite use esbuild and apply CommonJS transforms for compatibility, transforming all of them into your .vite directory. You can enable it like so:

{
  ssr: {
    noExternal: true
  }
}

The reason we don't turn this on by default it is can cause other issues, namely if a node module relies on, say, __dirname, or __filename, then when they are transformed into the .vite folder these paths will change. Another reason we don't turn it on by default is that it can slow things down.

If you do find the individual module that is causing an issue, you can also configure it quickly using the deps option in the One Vite plugin configuration.

In general you want to add any dependency like this to optimizeDeps.exclude. But One has some default optimizeDeps options we add that may prevent that.

You can use fixDependencies in your vite.config.ts:

import { one } from 'one/vite'

export default {
  plugins: [
    one({
      fixDependencies: {
        'erroring-dep': 'exclude'
      }
    })
  ]
}

The first thing you'll want to try is optimizing this dependency using the Vite interop transforms:

import one from 'one/vite'

{
  plugins: [
    one({
      deps: {
        '@bad/dependency': 'interop',
      }
    })
  ]
}

You can also try using one of the commonjs plugins, either vite-require or vite-plugin-commonjs.

When using bundlers like Vite, Rollup, or esbuild, developers often encounter issues with React Native and Expo packages originally designed to work only for Metro. Metro’s tolerant nature allows certain practices that other bundlers may not support, such as:

• Including Flow types in distributed .js files.
• Including JSX syntax in .js files instead of .jsx.
• Releasing packages as ESM-only without proper declarations in package.json (e.g., missing "type": "module") or appropriate .mjs extensions.
• Omitting import path extensions in distributed ESM, which can prevent Node.js from running those modules correctly, and break SSR.

These issues can break builds and require specific handling to make the packages compatible with non-Metro bundlers. Related error messages you might encounter includes:

• The JSX syntax extension is not currently enabled.
• The esbuild loader for this file is currently set to "js" but it must be set to "jsx" to be able to parse JSX syntax.
• SWC failed to transform file following with a syntax error parsing something like import type.

To workaround these issues, you can use the package patching feature of One to fix the packages that are causing problems. Here's an example:

export default {
  plugins: [
    one({
      // ...
      deps: {
        'react-native-vector-icons': {
          '**/*.js': [
            'jsx', // Transpile JSX in .js files
            'flow', // Remove flow types
          ],
        },
      },
    }),
  ],
}

For more details, see the deps section in Configuration.

One calls AppRegistry.registerComponent for you to set up your React Native entry component.

If you React Native app is erroring on startup, you need to make sure your One Vite plugin is configured to register the component:

import { one } from 'one/vite'

export default {
  plugins: [
    one({
      native: {
        // make sure this matches the key you use to build your native app
        key: 'my-app'
      }
    })
  ]
}