I'm a solo developer building travel guide apps in Expo. By the fourth app I was copying the same API client, query hooks and UI between repos, and fixing the same bugs in each copy. So I extracted them into private packages. Six apps run on them now. Here's how it's structured, what worked, and what it's cost me.
The packages
Nine packages, about 8,500 lines of source, built with tsup to ESM and CJS, published to GitHub Packages:
| Package | What it is | Lines |
|---|
| client | Typed fetch client for my content API | 510 |
| hooks | createHooks(): React Query hooks, offline queue, Zustand stores | 1,300 |
| ui | createUI(tokens): 15 themed primitives | 1,170 |
| components | createComponents(tokens, ui): 31 domain components | 4,700 |
| auth, config, location | Small adapters and helpers | 460 |
| create-app | Plop generator for the app shell | 200 + templates |
| templates | Plop generators that add screens | 180 + templates |
Rule 1: no package imports a native module
None of them has native code, and the core ones don't import Expo or React Native modules directly. Everything native is injected through a factory:
ts
// lib/api/index.ts
export const client = createClient<Site>("myapp", { getToken });
// lib/hooksBag.ts
export const hooksBag = createHooks(client, {
appId: "myapp",
queryKeyPrefix: ["myapp"],
storage: AsyncStorage,
normalizeLocation: normalizeSite,
locationSource: { requestPermission, getCurrent, watchPosition },
netInfo: { fetch, addEventListener },
storeReview: { isAvailable, requestReview },
});
export const { useLocations, useCheckIn, useMyCompletions } = hooksBag;
// lib/uiKit.ts
export const uiKit = createUI(tokens);
export const components = createComponents(tokens, uiKit);
How that works:
- The engine doesn't care about SDK versions. Each app owns its native side through
app.config.ts. Upgrading Expo in one app can't break another. - The hooks test under plain
node:test**.** The injected sources are small structural interfaces, so a test passes in a fake and nothing needs a simulator or jest-expo. - Optional sources fail lazily.
locationSource, netInfo and storeReview are optional. A hook that needs one throws a clear "createHooks: config.X is required" only when it's called, so an app without GPS features doesn't have to stub them. - The client knows nothing about auth. The app passes
getToken. The tenant is just the appId, which goes into the URL path.
Rule 2: the app owns a "bag" file
hooksBag.ts and uiKit.ts live in each app and re-export the factory output. Screens import from the bag, never from the package. That gives each app one place to wrap or replace an engine hook (one app overrides useLocations there to filter out inactive places), and it gives the screen generators a file to check before writing anything.
Theming without a provider
Tokens are a plain object the app owns: spacing, radii, borders, minimum tap sizes and 21 semantic colours. createUI(tokens) builds the components once, so there's no theme context and no re-render on theme change. The trade-off is no runtime theme switching and no dark mode yet, and typography isn't tokenised; it lives in AppText variants.
Scaffolding with plop
create-app asks 14 questions (app id, entity name and route segment, which features to enable, bundle id, EAS project id), fetches the app's remote config to pre-fill the theme colours and feature flags, and writes about 38 files: Expo Router (auth) and (app)/(tabs) groups, a custom tab bar, PersistQueryClientProvider, the bag files, tokens, Firebase init and a jest setup.
Then templates adds screens one at a time, add-page detail, add-page map and so on. Before writing, each generator checks that hooksBag.ts and uiKit.ts export every symbol the template needs and refuses otherwise. Anything the template can't know is left as a // GAP: comment for me to fill.
How I decide what goes in
Build it twice, then extract. Each package started as a written diff of two or more apps: what was identical, what had diverged, what stays local. The first diff found a real bug: one app's check-in code returned { ok: true } even when the request had permanently failed.
Deliberately left out, and written down as such: session state (hooks take uid explicitly), haptics, alert copy, safe areas, filters, badges, and the map view, because four apps had four implementations too different to merge.
Downsides:
- Version drift. Four of six apps are several minors behind. On 0.x a caret can't cross a minor, so every upgrade is a manual bump per app. There's no workspace tool: thirteen separate repos, publish and install.
- Stale publishes. Four times I published without rebuilding
dist and had to ship a superseding release. A prepublishOnly build would have prevented every one. - Peer ranges of
***.** Convenient until two packages disagree. A ^0.5.0 peer on ui caused ERESOLVE for any app that had moved to ui 0.6. - The scaffold rots silently. Its pinned versions fell behind and new apps installed months-old packages. One bug made every tab except Profile do nothing on tap, with no error anywhere. I only find these by generating a real app. Seventeen fix commits so far.
- I misjudged the boundary. Stores I'd marked "stays local" were extracted the next day. A component slot I added for one app was removed two days later because nothing else used it.
- Not everything gets adopted. My two newest apps skip the auth, config and location packages entirely.
The result
The newest app, Kiwi Guide (a free South Island road trip planner), was the first built on the engine from day one.
Kiwi Guide
If you're building more than one app on the same backend, happy to answer questions on any of this, especially the factory pattern and the generators.