{"id":"l-rn-4-2","courseId":"react-native-apps","lang":"en","kind":"lesson","summary":"Choose between AsyncStorage, expo-sqlite and expo-secure-store for each kind of data in Trailhead, and use each one correctly, from preferences to a migrated hike database to the sign-in token.","html":"

A hiking app that forgets your log when you lose signal, or asks you to sign in every morning, gets deleted. Trailhead has three kinds of data to keep on the device, and each fits a different tool:

\n
\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
DataExampleTool
Small preferencesunits (km or mi), last-used tabAsyncStorage
Structured records you querythe hike log, sorted and filteredexpo-sqlite
Secretsthe sign-in refresh tokenexpo-secure-store

Picking the wrong one rarely fails loudly. It fails as slow screens, lost data after an update, or a security review you don’t pass.

\n
\n Trailhead stores preferences in AsyncStorage as unencrypted strings, hikes in an SQLite database it can query, and the refresh token in SecureStore, encrypted by the Keychain or Keystore. Photos are files on disk whose paths are stored in SQLite.\n \n Trailhead\n \n AsyncStorage\n strings, unencrypted\n units = \"km\"\n \n expo-sqlite\n tables, queries\n hikes, photo paths\n \n SecureStore\n Keychain / Keystore\n refresh token\n \n \n \n
Three stores, three jobs
\n

AsyncStorage for preferences

\n

AsyncStorage is a persistent key-value store of strings. Every call is async, and nothing is encrypted:

\n
src/lib/prefs.ts
import AsyncStorage from '@react-native-async-storage/async-storage';\n\nexport type Prefs = { units: 'km' | 'mi'; remindersOn: boolean };\nconst KEY = 'trailhead.prefs.v1';\nconst defaults: Prefs = { units: 'km', remindersOn: false };\n\nexport async function loadPrefs(): Promise<Prefs> {\n  const raw = await AsyncStorage.getItem(KEY);\n  if (!raw) return defaults;\n  try {\n    return { ...defaults, ...JSON.parse(raw) };\n  } catch {\n    return defaults;\n  }\n}\n\nexport function savePrefs(prefs: Prefs) {\n  return AsyncStorage.setItem(KEY, JSON.stringify(prefs));\n}
\n

Store one JSON blob under a versioned key rather than many tiny keys, merge with defaults when reading (so a new preference added in v2 gets a sensible value for old users), and survive corrupt data with a try. Install it with npx expo install @react-native-async-storage/async-storage. If your app already uses expo-sqlite, expo-sqlite/kv-store offers the same API backed by SQLite, so you can skip the extra dependency.

\n

Read preferences once at startup, keep them in a context like the hikes, and write them back when they change. Calling getItem inside components on every render turns a fast screen into one that flickers through default values first.

\n

AsyncStorage gets slow and awkward when you start storing lists of records in it: every read parses the whole blob, and there’s no way to ask for “hikes over 10 km in 2026” without loading everything.

\n

expo-sqlite for the hike log

\n

The hike log is structured data you sort, filter and total, which is what a database is for. expo-sqlite gives you a real SQLite database file on the device. SQLiteProvider opens it and runs your setup before any child renders:

\n
src/app/_layout.tsx
import { Stack } from 'expo-router';\nimport { SQLiteProvider, type SQLiteDatabase } from 'expo-sqlite';\n\nasync function migrate(db: SQLiteDatabase) {\n  const row = await db.getFirstAsync<{ user_version: number }>('PRAGMA user_version');\n  let version = row?.user_version ?? 0;\n\n  if (version === 0) {\n    await db.execAsync(`\n      PRAGMA journal_mode = WAL;\n      CREATE TABLE hikes (\n        id TEXT PRIMARY KEY NOT NULL,\n        name TEXT NOT NULL,\n        date TEXT NOT NULL,\n        distanceKm REAL NOT NULL,\n        favorite INTEGER NOT NULL DEFAULT 0\n      );\n    `);\n    version = 1;\n  }\n  if (version === 1) {\n    await db.execAsync('ALTER TABLE hikes ADD COLUMN photoUri TEXT');\n    version = 2;\n  }\n  await db.execAsync(`PRAGMA user_version = ${version}`);\n}\n\nexport default function RootLayout() {\n  return (\n    <SQLiteProvider databaseName=\"trailhead.db\" onInit={migrate}>\n      <Stack />\n    </SQLiteProvider>\n  );\n}
\n

PRAGMA user_version is a number SQLite stores in the file for you. Each if block upgrades one step, so a user on version 0 runs both, and a user on version 1 runs only the second. Never edit an old step once it has shipped; add a new one.

\n

Any screen can then use the database:

\n
TSX
import { useSQLiteContext } from 'expo-sqlite';\n\nconst db = useSQLiteContext(); // in a component or custom hook\n\n// …later, inside an async function such as an effect or a save handler:\nconst hikes = await db.getAllAsync<Hike>('SELECT * FROM hikes ORDER BY date DESC');\nawait db.runAsync(\n  'INSERT INTO hikes (id, name, date, distanceKm) VALUES (?, ?, ?, ?)',\n  hike.id, hike.name, hike.date, hike.distanceKm,\n);
\n

In practice you’d call these from your reducer’s provider: load the hikes once into state, and write to SQLite whenever an action changes them.

\n\n

SecureStore for secrets

\n

The refresh token lets Trailhead sign in silently. Anyone who reads it can act as the user, so it goes in expo-secure-store, which encrypts values using the iOS Keychain and the Android Keystore:

\n
src/lib/session.ts
import * as SecureStore from 'expo-secure-store';\n\nconst TOKEN_KEY = 'trailhead.refreshToken';\n\nexport const saveToken = (token: string) => SecureStore.setItemAsync(TOKEN_KEY, token);\nexport const readToken = () => SecureStore.getItemAsync(TOKEN_KEY);\nexport const clearToken = () => SecureStore.deleteItemAsync(TOKEN_KEY);
\n

This is what the isLoading state in the previous section’s useSession was waiting for: at startup, readToken() decides whether the user lands on the tabs or on the sign-in screen. SecureStore is meant for small values; some platform versions have rejected values over about 2 KB. Keep tokens and keys there, never whole objects or files. It doesn’t run on the web, so a web build needs a different approach.

\n

Files belong on disk

\n

A trail photo is several megabytes. Don’t put it in SQLite or AsyncStorage. Keep the file on disk (expo-file-system manages your app’s document directory) and store only its URI in the photoUri column. Your database stays small and fast, and the image component loads the file directly.

\n

All of this data survives app updates, including over-the-air ones, and is deleted when the user uninstalls the app, with one quirk: on iOS, Keychain values from SecureStore can survive a reinstall, so don’t treat a missing database as proof that no token exists. If losing it would hurt, sync it to your server, which is exactly why Trailhead has accounts.

\n

Next, the most delicate part of talking to the device: asking for permission to use its location and camera.

\n","toc":[{"id":"sec-1","text":"AsyncStorage for preferences","level":2},{"id":"sec-2","text":"expo-sqlite for the hike log","level":2},{"id":"sec-3","text":"SecureStore for secrets","level":2},{"id":"sec-4","text":"Files belong on disk","level":2}],"takeaways":["AsyncStorage is an unencrypted, asynchronous string key-value store, right for small preferences and wrong for secrets.","expo-sqlite stores structured data you query, sort and filter; run schema migrations in onInit using PRAGMA user_version.","Always pass SQL values as parameters (?), never by building the SQL string yourself.","expo-secure-store encrypts small values with the platform’s Keychain or Keystore; tokens and keys belong there.","Store files such as photos on the file system and keep only their paths in the database."],"further":[{"title":"Store data","url":"https://docs.expo.dev/develop/user-interface/store-data/"},{"title":"SQLite","url":"https://docs.expo.dev/versions/latest/sdk/sqlite/"},{"title":"SecureStore","url":"https://docs.expo.dev/versions/latest/sdk/securestore/"}],"quiz":[{"q":"

Where should Trailhead keep the refresh token it receives after sign-in?

","options":[{"text":"AsyncStorage, under a key like auth.refreshToken.","why":"AsyncStorage is unencrypted. On a compromised or backed-up device, the token can be read as plain text."},{"text":"An EXPO_PUBLIC_ environment variable.","why":"Those are baked into the app bundle at build time; they can’t hold per-user values and are readable by anyone."},{"text":"expo-secure-store, which encrypts it with the Keychain on iOS and the Keystore on Android.","why":"Correct. Small secrets like tokens are exactly what it’s for."},{"text":"A tokens table in the SQLite database.","why":"The database file isn’t encrypted by default, so the token would sit in plain text next to the hikes."}],"answer":2},{"q":"

Which line is safe for saving a hike’s name typed by the user?

","options":[{"text":"db.runAsync(`INSERT INTO hikes (name) VALUES ('${name}')`)","why":"A name containing a quote, like O’Brien Ridge, breaks the statement, and crafted input can change the SQL itself."},{"text":"db.runAsync('INSERT INTO hikes (name) VALUES (?)', name)","why":"Correct. The value is bound as a parameter, so it’s always treated as data, never as SQL."},{"text":"db.execAsync('INSERT INTO hikes (name) VALUES (' + JSON.stringify(name) + ')')","why":"JSON quoting isn’t SQL quoting, and execAsync doesn’t bind parameters. It’s string-building with extra steps."}],"answer":1},{"q":"

Trailhead v2 adds an elevationM column to the hikes table. Existing users already have v1’s table. What’s the reliable approach?

","options":[{"text":"In the onInit migration, read PRAGMA user_version; if it’s 1, run ALTER TABLE hikes ADD COLUMN elevationM INTEGER and set the version to 2.","why":"Correct. Versioned migrations upgrade each user’s database exactly once, in order, whatever version they start from."},{"text":"Delete the database at startup and recreate it with the new schema.","why":"That wipes every user’s hike log on update. Data on the device is the user’s; you can’t reload it from anywhere."},{"text":"Change the CREATE TABLE statement; SQLite updates existing tables to match.","why":"CREATE TABLE IF NOT EXISTS skips existing tables entirely, so old users never get the new column."}],"answer":0}],"exercise":{"kind":"choice","multiple":true,"options":["units-async","log-sqlite","token-async","photo-secure","token-secure","log-async"],"correct":["units-async","log-sqlite","token-secure"],"title":"Put each piece of data in the right store","prompt":"

A teammate drafted Trailhead’s storage plan. Select every line of the plan that you would approve in code review.

\n","hints":["Ask two questions about each piece of data: is it secret, and will you need to query or filter it?","SecureStore is for small secrets; photos are megabytes.","Three lines are right."],"explanation":"

Preferences are small and harmless, so AsyncStorage (one JSON blob under a versioned key) fits. The hike log is structured data you sort and filter, so it belongs in expo-sqlite with versioned migrations. The refresh token is a secret, so it belongs in expo-secure-store, encrypted by the Keychain or Keystore. Tokens in AsyncStorage sit in plain text; photos in SecureStore exceed the size it’s designed for; and a 600-hike log in AsyncStorage means parsing everything for every query.

\n","checkLabels":{},"optionText":{"units-async":{"text":"Store the user’s units preference (km or mi) and reminder setting as one JSON value in AsyncStorage under trailhead.prefs.v1.","why":"Approve. Small, non-secret preferences are what AsyncStorage is for, and the versioned key makes future changes easy."},"log-sqlite":{"text":"Store the hike log in an expo-sqlite table, with schema changes handled by migrations keyed on PRAGMA user_version.","why":"Approve. Structured records you query belong in a database, and versioned migrations keep old users’ data intact."},"token-async":{"text":"Store the refresh token in AsyncStorage so it loads fast at startup.","why":"Reject. AsyncStorage is unencrypted. Startup speed doesn’t justify keeping a credential in plain text."},"photo-secure":{"text":"Store each trail photo as a base64 string in expo-secure-store so photos are private.","why":"Reject. SecureStore is designed for small values; multi-megabyte photos belong on the file system, with only their paths in SQLite."},"token-secure":{"text":"Store the refresh token in expo-secure-store and delete it on sign-out.","why":"Approve. SecureStore encrypts it with the platform keystore, and deleting it on sign-out leaves nothing behind."},"log-async":{"text":"Keep all 600 hikes as one JSON array in AsyncStorage and filter it in JavaScript.","why":"Reject. Every read parses the whole log, every write rewrites it, and there’s no way to query without loading everything."}}},"words":676,"readMinutes":3}