Native configuration and requirements matrix | Expo Supabase SaaS Kit

Native features fan configuration out across many surfaces (app env, app.json, Supabase local and hosted, provider consoles, the app stores), and one change frequently forces another — the native URL scheme dictates a Supabase redirect-URL entry, for instance. This page is the single place to look up what a feature needs configured and what a config change triggers elsewhere. It tracks operational reality, not roadmap.

1. Config surfaces (where config lives)

2. Cross-config coupling / triggers ⚠️ (the important part)

When you change the left column, you must also do the right column.

3. Per-feature config matrix

Legend: ✅ required · ➕ additive/no-behavior-change · — n/a

(Extend rows as features are added.)

Mirroring templates to a hosted project

⚠️ config push is the dangerous one, not the dashboard. The CLI reads each [auth.email.template.*].content_path off disk and uploads the file body as mailer_templates_<flow>_content — verified in the pinned CLI 2.109.1. So pushing config for an unrelated reason (a redirect URL, a provider toggle, a rate limit — all of which the rows above tell you to mirror) ships every template in the same command, while you have honoured a "don't paste into the dashboard" instruction exactly.

After any mirror, re-check by firing every template against the hosted project.

⚠️ reset-password.html is load-bearing, not cosmetic. It is the one template that never interpolates {{ .RedirectTo }} — it hard-codes {{ .SiteURL }}/auth/confirm?…&type=recovery&next={{ .SiteURL }}/update-password. Replacing it with Supabase's stock recovery template therefore drops the user at the site root with a recovery session instead of on the password form, and no client can compensate: native deliberately sends no redirectTo because this template would ignore it, and web's own redirectTo is already dead weight for the same reason. Keep the hard-coded next, or change both the template and every caller together.

Typed-code preconditions — an operator decision, not something this repo forces

Printing {{ .Token }} turns a URL-only secret into a typed 6-digit one, so review these on the hosted project:

They are deliberately left unset in config.toml: shared backend policy affecting web equally, so choosing values is the deploying operator's call. Left at hosted defaults, the code is a 6-digit secret valid for 24 hours.

⚠️ Sign-up abuse — the captcha substitute is not yet in place

Native sign-up deliberately ships no captcha (see the anti-trigger row above): the global GoTrue toggle would break every token-less native auth call, and no native Turnstile SDK exists. Rate-limiting is the intended substitute — but config.toml still carries upstream's permissive default:

No config.toml value is changed here, by the same principle as the table above: [auth.rate_limit] is shared backend policy that throttles web's transactional auth email too, so picking a number is the deploying operator's call rather than something the native app decides unilaterally. Two consequences worth stating outright:

• Tighten it before exposing native sign-up publicly. Anything in the low tens per hour is a materially different posture from 1000.
• It throttles web as well. Check web's own flows (invitations, password reset, email confirmation) still fit under whatever ceiling you pick — a value tuned for native sign-up alone can silently starve a burst of team invitations.

Local template editing — kong bind-mount caveat

The CLI bind-mounts templates into kong, which can serve a size-changed file truncated to its old length — GoTrue then fails with 500 … ends in a non-text context, which looks like a syntax error but isn't. After any template edit, restart kong and auth and confirm the served length matches on-disk:

KONG=supabase_kong_next-supabase-saas-kit-turbo; AUTH=supabase_auth_next-supabase-saas-kit-turbo
docker restart $KONG $AUTH
docker exec $AUTH sh -c "wget -qO- http://$KONG:8088/email/confirmation.html | wc -c"
wc -c apps/web/supabase/templates/confirm-email.html

Password policy — where it is (and isn't) enforced

Both apps validate client-side only — sign-up calls auth.signUp straight from the browser or device, with no server action in between — so the zod schema is the whole gate. GoTrue's own minimum_password_length / password_requirements are left at their defaults deliberately: they are shared backend policy, not native config.

⚠️ The flags only reach the screens that use a policy-derived schema. Sign-up and the recovery new-password screen do; the settings change-password screen does not — it uses PasswordUpdateSchema from @kit/accounts/shared, a flat min(8) that ignores the requirement flags entirely. Web has the same gap on the same screen, so this is upstream's shape rather than a native regression, and turning the flags on leaves that one screen accepting passwords the others reject. Setting the requirements server-side closes it for every screen at once, which is the argument for doing so if you enable them at all.

Setting them server-side is safe and needs no client change — GoTrue rejects with weak_password + reasons[] and both apps render those reasons. One caveat if you do: password_requirements is a 4-level ladder ("" → letters_digits → lower_upper_letters_digits → lower_upper_letters_digits_symbols), so the kit's three independent booleans cannot be mirrored exactly — anything without digits has no server equivalent.

4. Store / account requirements (cross-cutting)

5. Conventions

• EXPO_PUBLIC_* are public (bundled) — config flags, not secrets.
• Local config.toml ↔ hosted dashboard must stay in sync; hosted wins in prod.
• OAuth (Google + generic) is provider-generic in code — enabling a new provider is config + a logo, not code (except Apple-on-iOS, which is a native sub-flow).
• Sign in with Apple is OFF by default and build-gated. Note the Expo gotcha: expo-apple-authentication is a dependency (the dormant code imports it), and Expo autolinks its config plugin at prebuild, so the applesignin entitlement is injected just by the package being installed — not by the plugins array. So app.config.ts strips that entitlement unless EXPO_PUBLIC_AUTH_OAUTH_PROVIDERS contains apple (one flag drives both the button and the entitlement). Toggling requires a clean re-prebuild (rm -rf apps/native/ios — a merge prebuild keeps the stale entitlement); enabling needs a paid Apple Developer account or the build fails signing. The iOS app is fully usable without Apple (Google + password) — Apple is only required before public App Store submission.