Alchemy Logo

Getting started with Smart Wallets on Expo

We would go through the steps to get your environment setup for using Smart Wallets within a React Native application on Expo.

  • React Native version 0.76 or later
  • iOS Minumum Deployment Target: 17.0
  • Hermes and Fabric must be enabled (if using expo these are on by default)
  • The Signer package requires you to be on React Native's new architecture. For information on how to enable it in your Expo project, check their documentation.
  • The Signer package is incompatible with Expo Go and as a result, you'd need to use a Development Build. Check the Expo Development Builds documentation for more information.

If you don't have an Expo project setup, you can create one using the following command:

npx create-expo-app@latest

The first thing we need to do is make sure we're on the latest version of Expo (SDK 52 or later). The reason for this is that we need React Native version 0.76 or higher because it has TextEncoder natively supported.

For more information on upgrading an Expo project, check out the Expo documentation.

npx expo install expo@latest

You can also use our quickstart template to get started quickly. Simply run

npx create-expo-app@latest --template https://github.com/alchemyplatform/account-kit-expo-quickstart

Then you want to upgrade all dependencies to match the new Expo SDK version.

npx expo install --fix

Once we've got our Expo project setup and running, we need to setup a few shims so we can use crypto libraries in React Native.

npm install --save node-libs-react-native crypto-browserify stream-browserify react-native-get-random-values

Create or edit your metro.config.js file in the root of your project so that it includes the following:

// Learn more https://docs.expo.io/guides/customizing-metro
const { getDefaultConfig } = require("expo/metro-config");
const path = require("path");
const fs = require("fs");
const projectRoot = __dirname; // <-- Adjust this as fits your project setup
 
// Add aliases for file-system import based modules
const ALIASES = {
  "@noble/hashes/crypto": path.resolve(
    projectRoot,
    "node_modules/@noble/hashes/crypto.js",
  ),
  "@sinclair/typebox": path.resolve(
    projectRoot,
    "node_modules/@sinclair/typebox/build/cjs/index.js",
  ),
};
 
/** @type {import('expo/metro-config').MetroConfig} */
const config = getDefaultConfig(projectRoot);
// [!code focus:9]
// The following code ensures we have the necessary
// shims for crypto built into our project
config.resolver.extraNodeModules = {
  ...config.resolver.extraNodeModules,
  ...require("node-libs-react-native"),
  crypto: require.resolve("crypto-browserify"),
  stream: require.resolve("stream-browserify"),
};
 
config.resolver.resolveRequest = (context, moduleName, platform) => {
  if (ALIASES[moduleName]) {
    return {
      filePath: ALIASES[moduleName],
      type: "sourceFile",
    };
  }
 
  // Handle .js/.jsx extensions on TypeScript files
  if (
    (moduleName.startsWith(".") || moduleName.startsWith("/")) &&
    (moduleName.endsWith(".js") || moduleName.endsWith(".jsx"))
  ) {
    const moduleFilePath = path.resolve(
      context.originModulePath,
      "..",
      moduleName,
    );
 
    // if the file exists, we won't remove extension, and we'll fall back to normal resolution.
    if (!fs.existsSync(moduleFilePath)) {
      return context.resolveRequest(
        context,
        moduleName.replace(/\.[^/.]+$/, ""),
        platform,
      );
    }
  }
 
  return context.resolveRequest(context, moduleName, platform);
};
 
// The `account-kit/react-native` and it's supoorting packages leverages package.json `exports` which is not (yet) suported by default in Metro.
// we can enable this support using:
config.resolver.unstable_enablePackageExports = true;
config.resolver.unstable_conditionNames = [
  "browser",
  "require",
  "react-native",
];
 
module.exports = config;

Import the following packages at the topmost entry point of your app so that libraries that depend on globals like crypto have access to them.

If you are using expo-router, add the imports in your topmost _layout.tsx file in the app directory. However if you are using a different navigation library (e.g. react-navigation), add the imports in your topmost App.tsx file.

import "node-libs-react-native/globals.js";
import "react-native-get-random-values";
 
// rest of App.tsx

That's it! Now you can install the packages you want from Smart Wallets and start building your React Native Account Abstraction app.

If you get an error about mismatched peer dependencies for React, you can use --legacy-peer-deps in your install commands to avoid this error.

The @account-kit/react-native package is an ESM module. As such, have to add the following to your tsconfig.json's compilerOptions:

"module": "NodeNext",
"moduleResolution": "nodenext",
npm install --save @account-kit/react-native @account-kit/smart-contracts @account-kit/infra @account-kit/react-native-signer

To ensure the Signer package works correctly, you'll need to add the following dependencies to your project:

npm install --save react-native-mmkv zustand abitype react-native-inappbrowser-reborn viem wagmi @tanstack/react-query

The zustand library uses import.meta which is not supported in the latest version of Expo. To fix this, create a babel.config.js file with the following content:

module.exports = function (api) {
  api.cache(true);
  return {
    presets: [["babel-preset-expo", { unstable_transformImportMeta: true }]],
  };
};

Since we require a minimum deployment target of iOS 17, you will need to instruct Expo to set this during pre-build. First, install expo-build-properties via:

npx expo install expo-build-properties

Then add the plugin to your app.json:

// app.json
{
  "expo": {
    "plugins": [
      [
        "expo-build-properties",
        {
          "ios": {
            "deploymentTarget": "17.0"
          }
        }
      ]
    ]
  }
}

Now that we've got everything setup, we can run a prebuild to ensure the native modules are properly built and added to your project.

npx expo prebuild --platform android

Because the app is using native modules, you cannot run it with expo go and instead need to use development builds. You can do this with the android and ios commands:

npm run android

If you get this error, you can add the following to you app.json within the expo config:

"extra": {
  "router": {
    "origin": false
  }
}

If you get this error when running the Android app, you can fix this by updating the android/build.gradle to include the following override:

allprojects {
  configurations.all {
      resolutionStrategy {
          // Force a specific version of androidx.browser
          force 'androidx.browser:browser:1.8.0'
      }
  }
}

Related issue: https://github.com/alchemyplatform/aa-sdk/issues/1534

Our packages list a minimum version of React as 18.2.0, but the latest version of expo is on >=19. If you are using npm install it's likely you'll get errors about peer dependencies. To force a consistent version of react, you can add the following to your package.json:

"overrides": {
  "react": "19.0.0",
  "react-dom": "19.0.0"
}

Move on to app integration!

Was this page helpful?