Standalone mobile starter

What you'll have afterwards:

• A web app on http://localhost:3000 with sign-up, sign-in, account pages and an admin area, signed in with the admin role.
• A mobile app on http://localhost:3001, and on iOS and Android, that signs in at that web app.
• An API route, /api/me, that the mobile app calls with its access token.

Use this starter when your app needs its own users and API, with nothing else to run. It is the workspace starter plus the app of the mobile starter, wired together:

• apps/web has sign-up and sign-in, /account pages and an admin area with user management. With OAuth Server it is also the issuer and the API of the mobile app.
• apps/mobile is a Capacitor app on Mobile. It signs in at apps/web with Auth in client mode, and picks its guards with Authorization. It calls /api/me with its access token.

Prerequisites

The tools in Requirements, plus:

1. Create the project

Copy .starters/mobile-standalone 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 web,mobile
cd my-app
git init

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

pnpm prepare:env creates apps/web/.env and apps/mobile/.env from their examples, and generates the secrets. It never overwrites a value, so it is safe to run again.

2. Run both apps

pnpm dev

This starts apps/web on http://localhost:3000 and apps/mobile on http://localhost:3001. On the first start, NuxtHub creates a local SQLite database in apps/web/.data/. It applies the committed migrations, including the tables of OAuth Server.

3. Sign in

1. Open http://localhost:3000, choose Create account and sign up with the email you put in NUXT_ACL_ADMINS. Signing up sends a verification email (verifyEmail is on), printed in the terminal that runs pnpm dev: open its link and press Continue to sign in. The list only counts for a verified address.
2. /admin is the admin dashboard. /admin/oauth lists the OAuth applications. The mobile app's mobile application is marked Managed in nuxt.config. On Security (/account/security) you can add a passkey, which the mobile app's sign-in then offers too.
3. Open http://localhost:3001, the mobile app in a browser. Its '/**': { authenticated: true } route rule sends you to its /login page.
4. Sign in sends you to apps/web, which asks you to approve the app. It then returns to http://localhost:3001/auth/callback.
5. On Account, Sign out revokes the refresh token and returns to /. The route rule sends you on to the sign-in page.

Both apps use the same app API: useUserSession(), useAuth() and $api / useApi().

• apps/web runs Auth in server mode: a cookie session.
• apps/mobile runs it in client mode: tokens on the device.

Emails such as password resets are printed in the terminal that runs pnpm dev, by the log driver of Notify. They stay there until you configure a real driver.

4. Run it on the iOS simulator

Keep the web app running (pnpm dev, or pnpm dev:web). Then, in a second terminal:

pnpm mobile:ios

The script creates the native projects the first time: cap add ios and cap add android, plus the URL scheme com.example.mobile in Info.plist and AndroidManifest.xml. It builds the SPA, syncs it into ios/ and asks which simulator to run.

The simulator shares your Mac's network, so the app reaches http://localhost:3000. Sign in opens the in-app browser at apps/web. It has its own cookies, so you sign in there once. After you approve, the redirect to com.example.mobile:/auth/callback returns to the app, signed in.

5. Run it on an iPhone

A phone cannot reach localhost on your Mac. Start the web app on every interface, and build the app against your Mac's local network (LAN) address:

pnpm dev:lan             # apps/web on 0.0.0.0:3000
pnpm mobile:ios:device   # MOBILE_LAN=1 build, then opens Xcode

MOBILE_LAN=1 rewrites localhost in the issuer and API base to this Mac's LAN address. MOBILE_LAN=192.168.1.20 picks the address. OAuth Server takes its issuer from the request, so it matches.

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.

What is in the starter

apps/mobile is the mobile starter's app, file for file. apps/web is the workspace starter's app, except for the files below. The workspace starter and the mobile starter list those files. This starter adds:

How the two apps fit together

apps/mobile/identity.ts is exported as @workspace/mobile/identity. apps/web depends on @workspace/mobile to read it:

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

export default defineNuxtConfig({
  modules: [
    // ... the workspace starter's modules
    '@frigear-nu/oauth-server',
  ],
  oauthServer: {
    cors: {
      // The webviews of the native app: iOS (capacitor://localhost) and Android (https://localhost).
      origins: ['capacitor://localhost', 'https://localhost'],
      // Your API: the same origins may call it with `Authorization: Bearer`.
      paths: ['/api/'],
    },
    clients: [{
      id: clientId, // 'mobile'
      name: appName,
      redirectUris: [nativeRedirectUri], // 'com.example.mobile:/auth/callback'
      devRedirectUris: [devRedirectUri], // 'http://localhost:3001/auth/callback', under `nuxt dev` only
    }],
    settings: { pages: { admin: true } },
  },
})

oauthServer.clients. The configured client uses PKCE (Proof Key for Code Exchange) and has no secret. It is created in the database on the first OAuth request. The dev redirect URI, and its origin for CORS (cross-origin resource sharing), only exist under nuxt dev, so production never accepts them. NUXT_OAUTH_SERVER_CLIENTS (JSON) replaces the list per environment. Create it in nuxt.config has the details.

server/api/me.get.ts. requireUser(event) accepts the session cookie and the access token. Write your API routes the same way.

Who may do what. OAuth Server registers its permissions (oauth:read, oauth:manage), and the starter's admin role holds them through grant: ['*'], so admins manage the applications at /admin/oauth. An application's allowedRoles is checked against the user's roles from authorization.roles, the NUXT_ACL_ADMINS admins included, so no plugin is needed. The mobile application has no allowedRoles, so every signed-in user may use it. An access token holds the permissions of its scopes that the user has, frozen when it is issued, and every request is still checked against the user's current permissions.

NUXT_OAUTH_SERVER_PRIVATE_KEY. Without it, nuxt dev keeps a dev key in apps/web/.data/oauth-server/dev-key.pem.

To register more OAuth applications, such as another app or a confidential web app, or to change this one, see Create an OAuth application.

Rename the app

Change apps/mobile/identity.ts (app id, name, client id, scopes). The mobile starter guide lists the fields. Then:

1. Restart pnpm dev. apps/web reads the new client id and redirect URIs from the same file. The old OAuth application stays in the database as an ordinary application, so its users stay signed in. Delete it in /admin/oauth when you no longer need it.
2. Delete apps/mobile/ios and apps/mobile/android. Then run pnpm mobile:native (or pnpm mobile:ios) to create them with the new id and URL scheme.

Commands

Run everything from the project root:

Production checklist

Do everything in Deployment for apps/web: the database and its migrations, NUXT_APP_SECRET, NUXT_ACL_ADMINS and a real Notify driver. Then add the items below.

The server:

• Set oauthServer.issuer to the public https origin, so tokens do not depend on the request host behind a proxy.
• Set NUXT_OAUTH_SERVER_PRIVATE_KEY in your hosting platform's environment, as above.
• Serve apps/web on its final https domain. A passkey belongs to the domain it was created on, so moving means users add theirs again.

The app:

• Set your own appId, appName and clientId in identity.ts, and recreate ios/ and android/.
• Point NUXT_PUBLIC_AUTHENTICATION_CLIENT_ISSUER and NUXT_PUBLIC_AUTHENTICATION_CLIENT_API_BASE at the production server in the environment of the release build. Build with MOBILE_RELEASE=1.
• Keep @aparajita/capacitor-secure-storage installed, and run pnpm mobile:doctor.
• Replace the icon and splash screen, set the version and build number, and set up signing for the App Store and Google Play.

The Mobile release checklist and the OAuth Server page have the details.

Next steps

• Add a module – add a feature to apps/web, with the same steps as any app.
• OAuth Server – scopes, claims, roles and the admin pages for OAuth applications.
• Auth in client mode – the app's sign-in, tokens and options.
• UX patterns – follow the shared patterns when you add screens.