Mobile starter

What you'll have afterwards:

• An iOS and Android app, also runnable in a browser on http://localhost:3001, that signs you in at an issuer you already have.
• A Home tab that shows who signed in and calls /api/me on your API with the access token.
• An Account tab that shows your profile and signs you out.

Use this starter when your users and API already live on a server: frigear.nu, your own OAuth Server, or any issuer on the checklist. It is a pnpm workspace with one app in apps/mobile. The app is a static Nuxt 4 single-page app (SPA) that Capacitor wraps for iOS and Android.

• Mobile is the app shell.
• Auth in client mode signs the user in and keeps the tokens.
• Authorization provides the guards.

Prerequisites

The tools in Requirements, plus:

1. Create the project

Copy .starters/mobile with pnpm create frigear-app (CLI) or with giget. pnpm create frigear-app also runs pnpm install and pnpm prepare:env:

pnpm create frigear-app my-app --platform mobile
cd my-app
git init

pnpx giget@latest gh:Frigear-nu/frigear-nu/.starters/mobile my-app
cd my-app
git init
corepack enable
pnpm install
pnpm prepare:env

pnpm prepare:env copies apps/mobile/.env.example to apps/mobile/.env. It never overwrites a value.

2. Choose the issuer

Set the issuer and your API in apps/mobile/.env:

Then register a public OAuth application at the issuer: one that uses PKCE (Proof Key for Code Exchange) and has no secret. Use the values from apps/mobile/identity.ts:

The app needs a refresh token to stay signed in:

• OAuth Server always issues one. It does not support the offline_access scope and drops it.
• Most other issuers only issue one for offline_access. For Keycloak, Auth0, Zitadel and the like, add it to scopes in identity.ts, or to NUXT_PUBLIC_AUTHENTICATION_CLIENT_SCOPE.

How that looks for each kind of issuer:

3. Run it in a browser

pnpm dev

Open http://localhost:3001. Every page needs a signed-in user (the '/**' route rule), so you land on /login:

1. Sign in sends you to the issuer, where you sign in and approve the app. Passkeys work when the issuer offers them, as the workspace and mobile-standalone starters do.
2. The issuer redirects to http://localhost:3001/auth/callback. The app exchanges the code for tokens and opens Home.
3. Account shows your name and email. Sign out revokes the refresh token at the issuer and returns to /. The route rule sends you on to /login.

Tokens live in localStorage in a browser. On a device they live in the Keychain or Keystore, through @aparajita/capacitor-secure-storage. The access token is refreshed when it expires.

4. Run it on the iOS simulator

pnpm mobile:ios

The script does four things:

1. The first time, it creates the native projects (frigear-mobile native --if-missing). That runs cap add ios and cap add android, and adds the URL scheme of the redirect URI to Info.plist and AndroidManifest.xml.
2. It builds the SPA (nuxt generate).
3. It copies the SPA into ios/ (cap sync ios).
4. It asks which simulator to run (cap run ios).

Sign in opens the in-app browser at the issuer. After you approve, the issuer redirects to com.example.mobile:/auth/callback. iOS hands that URL to the app, and you are signed in. The simulator shares your Mac's network, so an issuer on http://localhost:3000 works as is.

pnpm mobile:doctor lists missing plugins and URL schemes.

5. Run it on an iPhone

With an issuer on the internet, open the project in Xcode and run it on the phone:

pnpm mobile:ios:device

The script builds with MOBILE_LAN=1. That rewrites localhost in the issuer and API base to this Mac's local network (LAN) address. MOBILE_LAN=192.168.1.20 picks the address. So a phone on the same Wi-Fi reaches an issuer running on your Mac. Start that server on every interface; for a Nuxt server, run nuxt dev --host 0.0.0.0.

Then, in Xcode:

1. Select the App target, then Signing & Capabilities, and pick your team. A free Apple ID works, but the install then expires after 7 days. Do not commit the team id.
2. Connect the phone and turn on Developer Mode on it (Settings, Privacy & Security). Choose it as the run destination and press Run.
3. The first time, trust the developer profile on the phone (Settings, General, VPN & Device Management). Allow local network access when asked.

6. Run it on Android

pnpm mobile:android

The steps are the same as for iOS: native project, build, cap sync android, cap run android.

• Android shows the web tab bar and header. The native chrome is iOS only by default.
• The back button closes an overlay, then goes back, then returns to the first tab.

How the guards work

Mobile protects nothing by default. The app picks its guards with Authorization, in apps/mobile/nuxt.config.ts:

routeRules: {
  '/**': { authenticated: true },
},
authorization: { redirectTo: '/login' },

• /login and the callback stay public without a rule.
• Both tabs have requiresAuth: true, so they are hidden while signed out. The sign-in page shows no tab bar.
• For a public home screen, remove the '/**' rule and remove requiresAuth from the Home tab. Guard single pages instead, for example '/account': { authenticated: true }.

Rename the app

Everything that names the app is in apps/mobile/identity.ts:

export const appId = 'com.example.mobile' // bundle id, application id, and (lowercase) the redirect URI scheme
export const appName = 'Example' // home screen name and fallback page title
export const clientId = 'mobile' // the OAuth client_id
export const callbackPath = '/auth/callback'
export const devPort = 3001 // keep the `dev` script of apps/mobile/package.json in step
export const scopes = ['openid', 'profile', 'email'] // add 'offline_access' for issuers that need it
export const nativeRedirectUri = `${appId.toLowerCase().replaceAll('_', '-')}:${callbackPath}`
export const devRedirectUri = `http://localhost:${devPort}${callbackPath}`

After changing appId:

1. Register the new redirect URI (<new app id>:/auth/callback) at the issuer. An OAuth Server in the same workspace picks it up from @workspace/mobile/identity instead.
2. Delete apps/mobile/ios and apps/mobile/android. Then run pnpm mobile:native, or any mobile:ios / mobile:android script, to create them with the new id and URL scheme.

The tabs are mobile.tabs in apps/mobile/nuxt.config.ts. The sign-in page's title and icon are in apps/mobile/app/app.config.ts (authentication.login).

What is in the starter

ios/ and android/ are not in the starter: pnpm mobile:native creates them. Commit them once you change native settings, such as the signing team, icons or entitlements.

The app's package.json lists:

• the Capacitor plugins the shell uses: @capacitor/app, browser, haptics, action-sheet, dialog, share, status-bar, keyboard, preferences and @capgo/capacitor-native-navigation,
• @aparajita/capacitor-secure-storage for the tokens,
• @frigear-nu/mobile, @frigear-nu/auth and @frigear-nu/authorization.

Add apps/mobile to an existing workspace

To add the app to a project made from the workspace starter, or any pnpm workspace with apps/*, copy just the app:

pnpx @frigear-nu/cli app:create mobile --template mobile
pnpm prepare:env

pnpx giget@latest gh:Frigear-nu/frigear-nu/.starters/mobile/apps/mobile apps/mobile
pnpm install
pnpm prepare:env

pnpm prepare:env creates apps/mobile/.env too: scripts/prepare-env.mjs handles every app with an .env.example. If your project predates it, copy the script from a current starter. Add the root scripts you want from the standalone starter, such as dev:mobile, mobile:native and mobile:ios.

To make apps/web the issuer and API of the app, apply the difference between the two starters. It is all in apps/web:

pnpm --filter ./apps/web add @frigear-nu/oauth-server @workspace/mobile@workspace:*

import { appName, clientId, devRedirectUri, nativeRedirectUri } from '@workspace/mobile/identity'

export default defineNuxtConfig({
  modules: [
    // ...
    '@frigear-nu/oauth-server',
  ],
  oauthServer: {
    cors: {
      origins: ['capacitor://localhost', 'https://localhost'],
      paths: ['/api/'],
    },
    clients: [{
      id: clientId,
      name: appName,
      redirectUris: [nativeRedirectUri],
      devRedirectUris: [devRedirectUri],
    }],
    settings: { pages: { admin: true } },
  },
})

The standalone starter guide explains each piece.

Production checklist

• Set your own appId, appName and clientId in identity.ts, and recreate ios/ and android/.
• Register the production redirect URI <app id>:/auth/callback at the issuer.
• Point NUXT_PUBLIC_AUTHENTICATION_CLIENT_ISSUER and NUXT_PUBLIC_AUTHENTICATION_CLIENT_API_BASE at https production URLs, in the environment of the release build.
• Allow capacitor://localhost and https://localhost for CORS at the issuer and on your API.
• Build releases with MOBILE_RELEASE=1, for example MOBILE_RELEASE=1 pnpm mobile:sync, so MOBILE_LAN cannot slip in.
• Keep @aparajita/capacitor-secure-storage installed. Without it a production build fails, because tokens would be stored unencrypted.
• Check the route rules. Nothing is protected without them, and your API checks every protected request.
• Run pnpm mobile:doctor and fix what it reports. For CI, frigear-mobile doctor --strict exits with 1 on errors.
• Replace the app icon and splash screen in the native projects, set the version and build number, and set up signing for the App Store and Google Play.

The Mobile release checklist has the details.

Next steps

• Mobile – tabs, page meta, native chrome, useNative(), deep links and the CLI.
• Auth in client mode – useUserSession(), useAuth(), $api, token storage and the options.
• Authorization – route rules and permissions for the app's guards.
• Use your own OAuth server – point the app at another issuer.