Testing op-sqlite with Turso on an Expo/React Native project

Table of Contents

1. Description
2. Supported Platforms
3. Prerequisites
4. Steps to make this project work
   • Clone, download or fork the project
   • Install dependencies
   • Create a new turso database and populate it
   • Create a project build and run it
   • Start the project
5. Troubleshooting
6. Extra info

Description

This projects is a test ground for connecting a Turso database to an Expo/React Native project using op-sqlite (set up to use libsql as the database source) leveraging Turso's embedded replicas.

Turso's embedded replicas allow database reads and/or writes to always happen from a local SQLite database first, providing very fast reads and/or writes which are then synced to a remote database.

The project is currently set up to leverage Turso's main features of interest such as:

• Embedded replicas
• Offline writes with sync
• Local database encryption at rest
• Periodic sync
• Read your writes

Project Structure

The main src/app/index.tsx file allows for displaying, adding, deleting and refreshing a list of items from the database. New items are automatically generated for demonstration purposes.

The src/db folder is where most of the op-sqlite code is located.

• The src/db/index.ts creates and exports the database client as well as a sync function.
• The src/db/schema.ts file currenly mainly contains TypeScript types
• The src/db/queries.ts file contains query functions to retrieve data from the database
• The src/db/mutations.ts file contains insert and delete functions
• The src/db/seedData.ts file mainly contains a function to create data on the fly using faker.js

Suported Platforms

This project was created on a Mac with an M1 chip running MacOS Sequoia 15.5.

• For Android builds it should work on most computers that have the correct development environment set up.
• For iOS builds you will likelly need a work on MacOS computer.

Prerequisites

This project assumes you have an Expo/React Native development environment already. If you don't, you can follow the relevant steps below:

• Install Node.js LTS version
• Install Expo command line tools
• For Android builds follow this guide to install and configure OpenJDK, Android Studio, and an Android Emulator
• For iOS buids (Mac users only), follow this guide to install and configure Xcode, an iOS simulator and watchman
  • You will likely need Homebrew to manage packages in your Mac.

Steps to make this project work:

You can use your favorite package manager. I'm using pnpm in this example. But you can replace any pnpm in the scripts section of the project's package.json to calls for npm or yarn. If you do, also make sure to replace any pnpm dlx with npx (if using npm) or yarn dlx (if using yarn).

1. Clone, download or fork this repository

git clone https://github.com/theorib/op-sqlite-turso-expo-react-native.git

2. install dependencies

pnpm install

3. Create a new turso database and populate it:

1. If you don't have it already, begin by installing the Turso CLI:

brew install tursodatabase/tap/turso

2. Authenticate or create a new account with Turso

turso auth signup

3. Create a new database (replace db-name with the name you want to give to your database)

turso db create db-name

4. Seed the database with the included sql dump file

turso db shell db-name < dbDump/dump.sql

5. Get your new database URL

turso db show db-name

6. Get an authentication token for the database

turso db tokens create db-name

7. Rename the .env.sample file in the root of this project folder to .env and replace the value of the environment variables with the URL and authentication token you got from the previous two steps

4. Create a project build and run it in your iOS or Android simulators

pnpm ios
pnpm android

5. Start the project at any time

pnpm start

Troubleshooting

If you are running into problems with your iOS build try running a pod install first with

pnpm pod

Extra info

This projects uses a nearly "vanilla" installation of Expo with very few changes. Most notably:

• TanStack Query to make data fetching and syncing with Turso more straightforward while handling pending and loading states properly
• op-sqlite is installed as a dependency since this is what we are testing
• faker-js is installed to provide mock data
• expo-dev-client to allow for Expo custom builds (necessary when using op-sqlite)