Troubleshooting

Symptoms listed first, fixes below each. Most of these are first-time-integration papercuts - once you’ve hit one, you learn to spot the shape.

My package’s screens 404 in the app shell

Two common causes:

1. You haven’t linked the package. Check tinycld.packages.ts - is the full package name in the array? If not:

   npm run packages:link <slug>

2. The generator output is stale. You linked the package, but app/a/[orgSlug]/<slug>/ is empty or out of date. Regenerate:

   npm run packages:generate

   If you’re running npm run dev (or npm run start), quit and restart - the dev launcher runs the generator on startup.

TypeScript sees two copies of react (or anything else)

Symptom: hundreds of “Type X is not assignable to type X” errors, usually involving React.ReactNode, View, ScrollView, or Transaction. Shapes match but inference treats them as different types.

Cause: you ran npm install (or any other PM’s install) inside a sibling package. Any package manager materializes peer dependencies on install, creating a duplicate node_modules/ with its own react, react-native, pbtsdb, etc.

Fix:

rm -rf ../<sibling>/node_modules ../<sibling>/package-lock.json

Every sibling’s .gitignore should cover node_modules/ and package-lock.json. If they aren’t there, add them before the next commit.

Unable to resolve module @tinycld/<pkg> in a Docker build

The local dev loop uses symlinks in tinycld/packages/; Docker builds use real directories there instead (copied out of the symlinks during build). If the generator didn’t run inside the Docker context, the node_modules/@tinycld/* entries don’t exist.

Fix: ensure npm run packages:generate runs in the Docker stage where the linked packages are present. The generator detects real directories versus symlinks and creates the appropriate node_modules/@tinycld/* entries for each.

updates to go.mod needed; to update it: go mod tidy

Cause: the generator rewrote server/go.mod with new require / replace directives but can’t run the Go toolchain itself. go.sum is now out of sync.

Fix:

cd server
go mod tidy

This only matters locally - Docker builds run go mod tidy in their Go stage automatically. npm run dev starts PocketBase through a path that picks up the replace directives on the fly.

A bracket-path route file won’t resolve

Symptom: a dynamic route like screens/[id].tsx works in npm run dev but fails at bundle time with Unable to resolve "@tinycld/<pkg>/screens/[id]".

Cause: your package.json exports uses a literal bracket subpath ("./screens/[id]": "./screens/[id].tsx"). Metro cannot resolve that form, even though TypeScript and Node both can.

Fix: use a wildcard instead:

{
    "exports": {
        "./screens/*": "./screens/*.tsx"
    }
}

This matches both screens/index and screens/[id]. See Screens for the full pattern.

My migrations don’t run in dev

The generator symlinks files from each package’s pb-migrations/ into server/pb_migrations/. If your migration isn’t showing up in PocketBase’s migration list on the admin UI, the symlink is probably missing or stale.

Fix:

npm run packages:generate

Verify the symlink exists in server/pb_migrations/ and points at your package’s file. If PocketBase is already running, restart it - migrations are loaded at boot.

My settings panel is linked but doesn’t appear

Three things to check, in order:

1. Is the full package name in tinycld.packages.ts?
2. Does manifest.ts export a settings array with at least one entry?
3. Does the file at settings/<component>.tsx default-export the panel component? Named exports are not picked up.

If all three are right and it still isn’t showing, regenerate (npm run packages:generate) and reload the app.

Conflicting nav.shortcut "X" between <pkg-a> and <pkg-b>

Two packages claim the same one-letter nav shortcut. The generator refuses to proceed because the shortcut is user-facing and ambiguous.

Fix: change one of them. shortcut in the manifest can be any single lowercase letter or omitted. Common letters to avoid colliding with (currently in use across first-party packages): m (mail), o (contacts), c (calendar), d (drive).