Forem: Aaron K Saunders

A Complete Guide to Building a Payment System with Payload CMS and Lemon Squeezy

Aaron K Saunders — Wed, 22 Oct 2025 18:30:21 +0000

Learn how to build a full payment system using the modern stack of Payload CMS, Next.js API Routes, and Lemon Squeezy, including a deep dive into debugging common API errors.

Integrating payments into an application can be a complex task, especially when you're working with a modern headless stack. How do you handle server-side logic securely when your CMS is embedded in a Next.js app?

In this guide (and the embedded video), we'll build a complete, production-ready payment system from start to finish using Payload CMS, Lemon Squeezy, and the power of Next.js API Routes.

The Architectural Shift: Why Next.js API Routes?

If you've used older versions of Payload, you might be familiar with creating custom endpoints directly within the CMS config. The game has changed. With Payload's deep integration into Next.js, the modern, recommended approach is to handle all custom server-side logic using Next.js API Routes.

This gives you:

Seamless Integration: Your backend logic lives alongside your frontend code in a familiar structure (/pages/api or /app/api).
Serverless-Ready: Perfectly aligns with deploying on serverless platforms like Vercel.
Unified Tooling: No need to context-switch. You're in a Next.js environment from top to bottom.

The Full Video Tutorial

This video is a comprehensive walkthrough of the entire process. I cover everything from the initial setup to handling the final webhook confirmation.

What We'll Cover in the Video

I've structured the tutorial to be a step-by-step guide, covering every critical stage:

✅ Initial Setup: Configuring products in Lemon Squeezy and collections in Payload CMS.
👨‍💻 Building the Client: Creating a reusable client to communicate with the Lemon Squeezy API.
🚀 Coding the API Routes: We'll build two key serverless functions in Next.js:
1. A Checkout API Route to generate payment links.
2. A Webhook Handler API Route to process order confirmations from Lemon Squeezy.
🌐 Testing Locally: Using ngrok to expose our local API routes to the internet so Lemon Squeezy can send webhooks to our machine.
🐛 Real-World Debugging: I hit real errors during the recording, and I'll show you exactly how to fix them.

Don't Skip the Debugging Chapter!

Things rarely work perfectly the first time. Instead of editing it out, I dedicated a full chapter to troubleshooting the integration. We'll fix frustrating, real-world errors related to:

Missing Store ID parameters.
Incorrect custom data types (the classic string vs. number issue).
Other common API request errors that can leave you stuck for hours.

Wrapping Up

By the end of this tutorial, you'll not only have a functional payment system but also a solid understanding of the modern architecture for building server-side logic with Payload CMS and Next.js.

I hope this helps you out! If you have any questions, drop a comment below or on the video. Happy coding!

📚 USEFUL RESOURCES

GitHub Repository: https://github.com/aaronksaunders/payload-lemon-1
Payload CMS Documentation: https://payloadcms.com/docs
Lemon Squeezy API Docs: https://docs.lemonsqueezy.com
ngrok Setup Guide: https://ngrok.com/docs

Source Code

aaronksaunders / payload-lemon-1

Payload CMS + LemonSqueezy Integration Example

Payload Lemon - E-commerce with Payload CMS & Lemon Squeezy

A modern e-commerce solution built with Payload CMS 3.x and Lemon Squeezy payment processing, featuring custom checkout creation and webhook handling.

🚀 Features

Payload CMS 3.x - Headless CMS with Next.js integration
Lemon Squeezy Integration - Payment processing and checkout creation
Custom API Routes - Next.js API routes for checkout and webhook handling
TypeScript - Full type safety throughout the application
SQLite Database - Local development with easy deployment options
Webhook Support - Handle Lemon Squeezy order events

📋 Prerequisites

Node.js 18.20.2 or higher
pnpm 9 or higher
Lemon Squeezy account
ngrok account (for webhook testing)

🛠️ Installation

1. Clone and Install Dependencies

git clone <your-repo-url>
cd payload-lemon
pnpm install

2. Environment Setup

Create a .env.local file in the project root:

# Payload CMS Configuration
PAYLOAD_SECRET=your-super-secret-payload-key-here
DATABASE_URI=file:./payload-lemon.db
# Lemon Squeezy Configuration
LEMON_SQUEEZY_API_KEY=your-lemon-squeezy-api-key
LEMON_SQUEEZY_STORE_ID=your-store-id
LEMON_SQUEEZY_WEBHOOK_SECRET=your-webhook-secret

# Next.js Configuration
NEXT_PUBLIC_SERVER_URL=http://localhost:3000

…

View on GitHub

Simplifying Auth and Role-Based Routing with Stack.Protected in Expo Router

Aaron K Saunders — Wed, 15 Oct 2025 15:01:01 +0000

Expo Router’s latest release introduces Stack.Protected, a powerful, declarative way to handle route protection and role-based access in your Expo and React Native apps. This feature, combined with a thoughtful directory structure, makes authentication and authorization flows much simpler, more maintainable, and scalable.

Why `Stack.Protected` Is a Game Changer

Before Stack.Protected, developers often relied on manual redirects, conditional rendering, or navigation hacks to protect routes. This approach has several drawbacks:

Scattered Logic: Authentication checks and redirects are spread across multiple files and components, making the codebase harder to maintain and reason about.
Fragile Navigation: Manual redirects can be bypassed by deep links, browser navigation, or race conditions, allowing unauthenticated users to access protected screens.
Boilerplate: You end up writing repetitive code to check authentication and handle navigation in every screen or layout.
Poor Scalability: As your app grows, managing access control for many routes becomes complex and error-prone.

Example of a flawed approach:

// In every protected screen
if (!user) {
  return <Redirect href="/auth" />;
}

This pattern is easy to break and hard to scale. If you forget to add the check to a new screen, it becomes a security risk.

The Power of Declarative Protection

With Stack.Protected, you centralize access control in your navigation tree, making your app more robust, maintainable, and secure.

import { Stack } from "expo-router";

function useAuth() {
  // Replace with your real auth logic
  const [user] = React.useState(null); // null means not signed in
  return { user };
}

export default function AppLayout() {
  const { user } = useAuth();

  return (
    <Stack>
      <Stack.Protected guard={!!user}>
        <Stack.Screen name="(app)/index" options={{ title: "Home" }} />
      </Stack.Protected>
      <Stack.Protected guard={!user}>
        <Stack.Screen name="(auth)/index" options={{ headerShown: false }} />
      </Stack.Protected>
    </Stack>
  );
}

Example Directory Structure

A clean directory structure helps Expo Router automatically map routes and segments. Here’s a typical setup for protected and public routes:

app/
├── _layout.tsx
├── (app)/
│   └── index.tsx      # Home screen (protected)
├── (auth)/
│   └── index.tsx      # Login screen (public)

app/_layout.tsx: Navigation and protection logic.
app/(app)/index.tsx: Main app screen, only for authenticated users.
app/(auth)/index.tsx: Login screen, for unauthenticated users.

Why Name Files `index.tsx` in Segments?

Naming your files index.tsx inside segments (like (app) and (auth)) makes them the default route for that segment. For example:

Navigating to /app automatically loads app/(app)/index.tsx.
Navigating to /auth loads app/(auth)/index.tsx.

This means you don’t need to manually redirect or specify a screen name—Expo Router will always show the segment’s index file as the default. It also ensures that your guards in Stack.Protected work as expected, because the router can always find a valid route to render.

Why Segment Layout Redirects Are Still Flawed

Some developers place authentication checks and redirects in the layout file for each segment (e.g., (app)/_layout.tsx). While this centralizes logic for that segment, it still has flaws compared to Stack.Protected:

Manual Redirects: You must remember to add redirect logic in every segment’s layout, which can be error-prone.
Duplication: If you have multiple protected segments, you end up duplicating similar logic across layouts.
Less Declarative: The navigation tree doesn’t clearly show which routes are protected; protection is hidden in layout code.
Edge Cases: Deep links or navigation actions can still bypass segment-level redirects if not handled perfectly.

With Stack.Protected:

Protection is part of your navigation tree, not hidden in layout files.
You avoid duplication and make access control obvious and maintainable.
The router handles fallback to allowed routes automatically.

Role-Based Route Protection with `Stack.Protected`

Stack.Protected isn’t just for authentication—it’s also perfect for role-based access control. You can conditionally expose routes based on user roles, permissions, or any custom logic.

Example:

import { Stack } from "expo-router";

function useAuth() {
  // Example user object with a role
  const [user] = React.useState({ role: "admin" }); // or null if not signed in
  return { user };
}

export default function AppLayout() {
  const { user } = useAuth();

  return (
    <Stack>
      {/* Public route */}
      <Stack.Protected guard={!user}>
        <Stack.Screen name="(auth)/index" options={{ headerShown: false }} />
      </Stack.Protected>

      {/* User route */}
      <Stack.Protected guard={user?.role === "user"}>
        <Stack.Screen name="(app)/user-dashboard" options={{ title: "User Dashboard" }} />
      </Stack.Protected>

      {/* Admin route */}
      <Stack.Protected guard={user?.role === "admin"}>
        <Stack.Screen name="(app)/admin-dashboard" options={{ title: "Admin Dashboard" }} />
      </Stack.Protected>
    </Stack>
  );
}

How it works:

Only users with the correct role see the corresponding routes.
You can easily add more roles or permissions by updating the guard logic.
Your navigation tree clearly shows which routes are exposed to which users.

Final Thoughts

With Stack.Protected and a well-structured directory using index.tsx files, Expo Router makes authentication and route protection clean, declarative, and scalable. You can easily extend this pattern for role-based access, making your app secure and maintainable as it grows.

Ready to try it?

Check out the Expo Router docs and start simplifying your navigation today!
Using Stack.Protected docs
Sample project Git Repository

I Asked an AI to Build a Mobile App. It Chose Ionic Capacitor and Surprised Me

Aaron K Saunders — Mon, 06 Oct 2025 15:35:46 +0000

I've been hearing a lot about AI's potential to build software, so I decided to run an experiment. I gave Loveable, an AI app builder, a detailed prompt to create a to-do app. I expected it to generate a standard React web app, and maybe suggest React Native for mobile.

I was not expecting it to choose Ionic Capacitor.

As the generation process unfolded, I saw the logs reference Capacitor and was genuinely surprised. It was an interesting, opinionated choice by the AI. This is the story of what happened next—the impressive AI debugging, the manual "last mile" to get it on a device, and what this surprising choice tells us about the future of AI in development.

Phase 1: The Initial Prompt and Impressive Scaffolding

I started with a clear set of requirements: a to-do app with role-based access (admin vs. user), image uploads, and comments, all powered by a Supabase backend.

In just a few minutes, Loveable built a complete React application. It didn't just create the UI; it configured the entire Supabase project:

Database tables for todos, comments, and profiles.
Row-Level Security (RLS) policies to keep user data separate.
Storage buckets for the image uploads.

The result was a fully functional web application, built faster than I could have done it myself.

Where the AI Became a True Co-Pilot: Conversational Debugging

The first version wasn't perfect. It had bugs, just like any real-world project. But instead of cracking open VS Code, I just kept talking to the AI.

Problem 1: Broken Images. My prompt: "The images are uploaded but are not rendered in the application." The AI correctly identified that the Supabase storage bucket was private and needed signed URLs. It then generated the necessary logic and updated the frontend to fix it.
Problem 2: The Admin View Crashed. My prompt: "When logged in as a super admin, I should see all users' to-dos, but the page crashes." The AI diagnosed the issue, added the correct RLS policies for the admin role, and patched the data-fetching code.

This iterative, conversational style of debugging felt like the future.

The Surprise Twist: The AI's Job Was Done, But Mine Wasn't

Loveable's choice of Capacitor was clever—it allows a single web codebase to run natively on iOS and Android. But it also meant the AI's automated work had reached its limit. It could generate the web code, but it couldn't perform the native builds or deployment for me.

The README file simply said, "Follow the Capacitor setup instructions." The "magic" had ended, and it was time for me to step in as a developer.

My Manual "Last Mile" with Capacitor

As someone who's used Capacitor before, I knew the drill. But I was curious to see if the AI-generated code was truly ready for the transition. Here's what that process looked like:

Sync to GitHub: I pushed the entire codebase to a new repository.
Clone Locally: I brought the project onto my local machine and ran npm install.
Add Native Platforms: I ran npx cap add ios and npx cap add android.
Build & Sync: I created a production build (npm run build) and synced the web assets into the native projects with npx cap sync.
Run on Device: Finally, I used npx cap run ios to open Xcode and launch the app on a simulator.

Once it was running, I hit the classic mobile UI problems: content was hiding under the iOS notch and status bar. Once again, I turned to the AI with a prompt: "We need to account for the safe area and status bar in the mobile view." It successfully installed the Capacitor status bar plugin and added the necessary viewport meta tags. Problem solved.

Final Thoughts: An Accelerator, Not an Automator

Loveable's decision to use Capacitor was an unexpected and insightful one. It shows that these AI tools are being trained on modern, efficient web development practices.

The experience proved that AI is an incredible accelerator. It handled the boilerplate, the backend setup, and even complex debugging, saving hours of work. But it's not an automator. The final, crucial steps of mobile deployment still require a developer's knowledge.

The AI can build the car, but you still need to know how to drive it off the lot.

For the full, unfiltered journey—from the first prompt to the final app running on both iOS and Android—check out the video linked at the top of this article.

Tags
#ai #javascript #react #ionic #capacitor #mobile #webdev #supabase

Can AI Really Build a Full-Stack Mobile App? A Brutally Honest Test of Bolt.new V2

Aaron K Saunders — Fri, 03 Oct 2025 16:28:20 +0000

I just tested the new Bolt.new V2 AI app builder. Here's the verdict in 10 seconds:

The Good: The Supabase integration is unbelievably fast and saved me a ton of time.
The Bad: It's tough for non-coders, and the AI generated code it knew was faulty.
The Verdict: A solid thumbs-up, but with some major caveats.

Want to see how I got to that conclusion?
I documented my entire 34-minute journey building a full-stack React Native (Expo) and Supabase app.

Instead of a polished demo, you get the real, unfiltered experience—including 8+ minutes of live debugging that you won't see in most tutorials. It's in the struggle that you really learn something.

In the full video below, I walk through:

Authentication and database setup.
The impressive speed of AI-assisted prototyping.
The inevitable troubleshooting that comes with a real-world project.
My final grade and whether this tool is ready for production.

Click play to see the full deep-dive!

TanStack Start to Mobile: Building Robust Apps with Capacitor

Aaron K Saunders — Mon, 29 Sep 2025 14:35:58 +0000

Discover how TanStack Start takes your full-stack web-to-mobile development to the next level with the power of the entire TanStack ecosystem – building amazing mobile apps, and a great developer experience.**

This is a companion document to this Video Tutorial

Full Source code available Here on Github

Introduction: Why TanStack Start for Your Next Mobile Adventure?

While other frameworks are fantastic, TanStack Start, built upon the mature and widely-adopted TanStack libraries (Router, Query), brings unique advantages:

Deep Type Safety: Imagine your API endpoints, data fetching, and UI components all benefiting from end-to-end type safety. TanStack Start pushes this further than many alternatives, reducing runtime errors and improving code maintainability.
Intuitive Server Functions (createServerFn): (Not Supported On Mobile) This is a game-changer. Instead of manually defining REST endpoints and separate API clients, you write plain TypeScript functions that feel local but execute securely on your remote backend. It's an RPC-like paradigm that drastically simplifies full-stack development.
Unified Ecosystem: With TanStack Router handling sophisticated client-side and server-side routing, and TanStack Query providing advanced data management, caching, and mutations, you're working with a cohesive and highly optimized toolkit.

In this guide, we'll walk through creating a simple TanStack Start application, specifically designed to run its backend API on a remote server, while packaging its client-side frontend into a native iOS and Android app using Ionic Capacitor. We'll cover the crucial configuration for development and production, demystifying how these decoupled pieces work together.

The Core Idea: One Start App + Mobile Client Using API Routes

For packaged mobile apps, the reliable approach is:

Single TanStack Start App (Web + API): Deploy your Start app as usual. Expose API endpoints using file-based API routes (e.g., src/routes/api.*).
Capacitor Mobile Client (SPA): Package the client-side build into the native app. From the mobile app, call your deployed API endpoints via a fully-qualified base URL.

Notes:

createServerFn works great when the client and Start server share an origin (web/SSR). In a packaged mobile app (capacitor://localhost/file://), there is no co-located server at /__server, so use explicit API routes instead. See why server functions don't work in the mobile app.
Configure CORS on your deployed app to allow capacitor://localhost and local dev origins.

What We're Building

Modifying the TanstackStart project to support building fullstack mobile applications with Ionic Capacitor

For details on why we avoid calling createServerFn directly from the mobile UI, see Troubleshooting: Why server functions don't work in the mobile app.

Step 1: Project Setup - Initialize TanStack Start

Let's begin by creating a new TanStack Start project.

# 1. Create a new TanStack Start project
npm create @tanstack/start@latest

# When prompted, choose:
# - framework: react
# - language: typescript
# - ssr mode: spa (Single Page Application mode for Capacitor)
# - css: tailwind (or your preference)

# 2. Navigate into your new project directory
cd your-app-name

# 3. Install project dependencies
npm install

After running these commands, you'll have a fully functional TanStack Start application with the following structure:

src/routes/ - File-based routing directory
src/routes/__root.tsx - Root route component
src/routes/index.tsx - Main index page
src/router.tsx - Router configuration
vite.config.ts - Vite configuration
package.json - Dependencies and scripts

Initial `package.json` Notes

After running npm install, your package.json will contain essential scripts and dependencies. Here's what you'll find in the actual implementation:

// package.json (excerpt - actual dependencies)
{
  "name": "tanstack-mobile-1",
  "private": true,
  "type": "module",
  "scripts": {
    "dev": "vite dev --port 3000",        // Starts the Vite development server
    "start": "node .output/server/index.mjs", // Starts the production server
    "build": "vite build",                // Builds the client-side SPA for production
    "serve": "vite preview --host",       // Serves the production build locally
    "serve:backend": "vite dev --host",   // Serves the backend for development
    "test": "vitest run"                  // Runs tests
  },
  "dependencies": {
    "@capacitor/cli": "^7.4.3",           // Capacitor CLI for mobile development
    "@capacitor/core": "^7.4.3",          // Core Capacitor runtime
    "@capacitor/ios": "^7.4.3",           // iOS platform support
    "@capacitor/status-bar": "^7.0.3",    // Status bar plugin
    "@tanstack/react-router": "^1.132.0", // Type-safe, file-based routing
    "@tanstack/react-start": "^1.132.0",  // The core TanStack Start framework
    "@tanstack/router-plugin": "^1.132.0", // Router plugin for TanStack Start
    "react": "^19.0.0",                   // React framework
    "react-dom": "^19.0.0",               // React DOM for web
    "tailwindcss": "^4.0.6"               // CSS framework
  },
  "devDependencies": {
    "@vitejs/plugin-react": "^4.3.4",     // Vite plugin for React
    "typescript": "^5.7.2",
    "vite": "^6.3.5",
    "vitest": "^3.0.5",
    // ... other dev dependencies
  }
}

Key Dependencies:

TanStack Start: Full-stack React framework with file-based routing
Capacitor: Mobile app development platform
React 19: Latest React version with improved features
Tailwind CSS: Utility-first CSS framework

Step 2: Editing Existing Route Files

The create-tanstack-app command already created several demo route files for us. We'll edit these existing files to add our API routes and server functions.

Edit src/routes/api.demo-names.ts
This file already exists. No Changes aer needed
Edit src/routes/demo.start.server-funcs.tsx
This file already exists. No changes are needed

Edit src/routes/demo.start.api-request.tsx
Replace its contents with the following code.

// src/routes/demo.start.api-request.tsx
import { createFileRoute } from "@tanstack/react-router";
import { Capacitor } from "@capacitor/core";

/**
 * Demo route that shows how to make API requests in a mobile context.
 * Uses Capacitor to detect if running in a native app and adjusts the URL accordingly.
 */
export const Route = createFileRoute("/demo/start/api-request")({
  component: Home,
  loader: async () => {
    // We need to use the full URL here because in a mobile app context,
    // so we check for mobile with capacitor and use the full URL to access the server
    let url = "";
    if (Capacitor.isNativePlatform()) {
      url = `${import.meta.env.VITE_SERVER_BASE_URL}/api/demo-names`;
    } else {
      url = `/api/demo-names`;
    }
    return await fetch(url).then((res) => res.json());
  },
});

function Home() {
  const names = Route.useLoaderData();
  console.log("names", names);

  return (
    <div
      className="flex items-center justify-center min-h-screen p-4 text-white"
      style={{
        backgroundColor: "#000",
        backgroundImage:
          "radial-gradient(ellipse 60% 60% at 0% 100%, #444 0%, #222 60%, #000 100%)",
      }}
    >
      <div className="w-full max-w-2xl p-8 rounded-xl backdrop-blur-md bg-black/50 shadow-xl border-8 border-black/10">
        <h1 className="text-2xl mb-4">Start API Request Demo - Names List</h1>
        <ul className="mb-4 space-y-2">
          {names.map((name: any) => (
            <li
              key={name}
              className="bg-white/10 border border-white/20 rounded-lg p-3 backdrop-blur-sm shadow-md"
            >
              <span className="text-lg text-white">{name}</span>
            </li>
          ))}
        </ul>
      </div>
    </div>
  );
}

Note: These route files already exist in your project created by create-tanstack-app. We're simply editing their contents to add our custom functionality.

Key Changes:

Add import for Capacitor
Update the loader to set the root url based on evnironment using the Capacitor plugin

Step 3: Updating the Root Route for Mobile Support

Now we need to update the existing src/routes/__root.tsx file to add Capacitor support for mobile development.

Update src/routes/__root.tsx
Edit the existing root route file to add Capacitor status bar support:

// src/routes/__root.tsx
import { HeadContent, Scripts, createRootRoute } from "@tanstack/react-router";
import { TanStackRouterDevtoolsPanel } from "@tanstack/react-router-devtools";
import { TanstackDevtools } from "@tanstack/react-devtools";

import Header from "../components/Header";
import appCss from "../styles.css?url";
import { useEffect } from "react";
import { StatusBar } from "@capacitor/status-bar"; // Add this import

export const Route = createRootRoute({
  head: () => ({
    meta: [
      {
        charSet: "utf-8",
      },
      {
        name: "viewport",
        content: "width=device-width, initial-scale=1",
      },
      {
        title: "TanStack Start Starter",
      },
    ],
    links: [
      {
        rel: "stylesheet",
        href: appCss,
      },
    ],
  }),

  shellComponent: RootDocument,
});

function RootDocument({ children }: { children: React.ReactNode }) {
  useEffect(() => {
    // Add Capacitor status bar configuration for mobile apps
    StatusBar.setOverlaysWebView({ overlay: false });
  }, []);

  return (
    <html lang="en">
      <head>
        <HeadContent />
      </head>
      <body>
        <Header />
        {children}
        <TanstackDevtools
          config={{
            position: "bottom-left",
          }}
          plugins={[
            {
              name: "Tanstack Router",
              render: <TanStackRouterDevtoolsPanel />,
            },
          ]}
        />
        <Scripts />
      </body>
    </html>
  );
}

Key Changes:

Added import { StatusBar } from "@capacitor/status-bar"
Added StatusBar.setOverlaysWebView({ overlay: false }) in the useEffect

Step 4: Configure Vite for Mobile Development

The existing vite.config.ts already has most of what we need, but we should verify it has the correct CORS configuration for mobile development.

Check vite.config.ts
Your existing Vite config should look like this (it's already configured correctly):

// vite.config.ts
import { defineConfig } from "vite";
import { tanstackStart } from "@tanstack/react-start/plugin/vite";
import viteReact from "@vitejs/plugin-react";
import viteTsConfigPaths from "vite-tsconfig-paths";
import tailwindcss from "@tailwindcss/vite";

const config = defineConfig({
  server: {
    cors: {
      origin: "*",
      credentials: true,
      methods: ["GET", "POST", "PUT", "DELETE", "PATCH", "OPTIONS"],
      allowedHeaders: ["Content-Type"],
    },
  },
  plugins: [
    // This is the plugin that enables path aliases
    viteTsConfigPaths({
      projects: ["./tsconfig.json"],
    }),
    tailwindcss(),
    tanstackStart({
      spa: {
        enabled: true,
        prerender: {
          crawlLinks: true,
          outputPath: "index.html",
        },
      },
    }),
    viteReact(),
  ],
  build: {
    outDir: "dist",
  },
});

export default config;

Key Configuration Notes:

CORS Configuration: Created to support API calls from the mobile device, without it you will get CORS errors
SPA Mode: Add the whole spa object in tanstackStart plugin configuration
Path Aliases: outputPath required by Capacitor and build.outDir also required by Capacitor
Tailwind CSS: Already integrated for styling

If your config looks different, make sure it includes the CORS configuration in the server section.

Step 5: Adding Capacitor for Mobile Development

Now we'll add Capacitor to your existing TanStack Start project to enable mobile app development.

Install Capacitor Dependencies:
Add Capacitor to your existing project:

npm install @capacitor/cli @capacitor/core @capacitor/ios @capacitor/android @capacitor/status-bar

Initialize Capacitor:
This command creates the capacitor.config.ts file and prompts you for basic app info.

npx cap init "tanstack-mobile" "com.example.tanstack.mobile"
# Follow the prompts:
# - App name: tanstack-mobile
# - App ID: com.example.tanstack.mobile (use a unique reverse-domain identifier)

Add Native Platforms:
This generates the actual ios/ and android/ native project folders.

npx cap add android  # Add Android platform
npx cap add ios      # Add iOS platform (requires macOS)

Verify capacitor.config.ts
The generated config file should look like this after the edits are made
```
// capacitor.config.ts
import type { CapacitorConfig } from "@capacitor/cli";

const config: CapacitorConfig = {
  appId: "com.example.tanstack.mobile",
  appName: "tanstack-mobile",
  webDir: "dist/client",
};

export default config;
```
Configuration Notes:
- webDir: Points to dist/client where TanStackStart builds the SPA
- appId: Use a reverse-domain identifier (e.g., com.yourcompany.appname)
- appName: Display name for your app in app stores
- No server config: For production builds, Capacitor uses the bundled files

Step 6: Adding Mobile Development Scripts

Your existing package.json already has the essential scripts. Let's add some convenient scripts for mobile development.

Current Scripts (Already Present)
Your package.json already includes these essential scripts:

"scripts": {
  "dev": "vite dev --port 3000",        // Starts the Vite dev server
  "start": "node .output/server/index.mjs", // Starts the production server
  "build": "vite build",                // Builds the client-side SPA
  "serve": "vite preview --host",       // Serves the built client locally
  "serve:backend": "vite dev --host",   // Serves the backend for development
  "test": "vitest run"                  // Runs tests
}

Add Mobile Development Scripts
Add these additional scripts to your package.json for easier mobile development:

// Add these scripts to your existing package.json
"scripts": {
  // ... your existing scripts ...

  // Capacitor-specific commands
  "cap:sync": "npx cap sync",               // Copy web assets to native projects
  "cap:open:ios": "npx cap open ios",       // Open iOS project in Xcode
  "cap:open:android": "npx cap open android",// Open Android project in Android Studio

  // Development with live reload
  "cap:dev:ios": "npm run dev & npx cap run ios --external",
  "cap:dev:android": "npm run dev & npx cap run android --external",

  // Production build for mobile
  "cap:build": "npm run build && npm run cap:sync"
}

Key Script Notes:

dev: Already configured to run on port 3000
build: Already creates both client and server builds
cap:sync: Copies your built web assets to native projects
cap:open:*: Opens native IDEs for platform-specific development
cap:dev:*: Runs development server with live reload on mobile

Development Workflow: Testing Your Mobile App

Now that you've set up your TanStack Start project with Capacitor, here's how to test it:

Start the Development Server:
Open your terminal and run:
```
npm run dev
```
This single command:
- Starts the Vite development server on http://localhost:3000
- Enables both frontend and backend functionality
- Handles API routes and server functions automatically
- Provides hot module replacement for fast development
Test in Browser:
Open http://localhost:3000 in your browser to test:
- The main application at /
- API request demo at /demo/start/api-request
- Server functions demo at /demo/start/server-funcs

Test on Mobile Device/Emulator:
For mobile testing, you have two options:

Option A: Build and test with native IDEs

# Build and sync to native projects
npm run build
npm run cap:sync

# Open in native IDE
npm run cap:open:ios     # For iOS (macOS only)
npm run cap:open:android # For Android

Option B: Live reload development (recommended)

# Start dev server in one terminal
npm run dev

# In another terminal, run with live reload
npm run cap:dev:ios     # For iOS
npm run cap:dev:android # For Android

Key Advantages:

Single Command: No need to manage multiple processes
Automatic CORS: Built-in CORS handling for mobile development
Hot Reload: Changes reflect immediately in both browser and mobile
Full-Stack: Both API routes and server functions work out of the box

Key Benefits:

Single Deployment: One TanStack Start app serves both web and mobile
Automatic Detection: Mobile context is handled automatically
Type Safety: Full end-to-end type safety maintained
Easy Updates: Update the web app and mobile users get the latest backend functionality

Troubleshooting: Why server functions don't work in the mobile app

When the app runs inside a Capacitor WebView, calling createServerFn directly from the packaged SPA fails. Here's why and how to fix it:

Root cause 1: createServerFn targets the current origin (e.g., capacitor://localhost or file://) and expects a co-located Start server at /__server. In a packaged mobile app, there is no server at that origin, so requests are unreachable.

What you’ll see in the mobile network panel (Web Inspector):

This is when the mobile app is trying to connect to the server, using a serverFunction, but the url is off.

You can see here where we are just making an API call all is well

Recommended approach for mobile:

Use explicit API routes for mobile calls (like src/routes/api.demo-names.ts) and fetch them with a fully-qualified base URL.
Configure VITE_SERVER_BASE_URL to your deployed Start app, and in routes like src/routes/demo.start.api-request.tsx, switch between relative and absolute URLs using Capacitor.isNativePlatform().
Ensure your deployed backend allows CORS from capacitor://localhost, http://localhost, and your device IPs used during development.
Reserve createServerFn for environments where the Start server is co-located with the client (web/SSR). For packaged mobile apps, prefer REST-like API routes or RPC endpoints hosted remotely.

This is why in this guide we demonstrate mobile-friendly API calls in demo.start.api-request.tsx instead of invoking server functions directly from the mobile UI.

Key Takeaways

Unified Development: TanStack Start provides a single codebase that works for both web and mobile, with automatic mobile detection.
File-Based Routing: API routes and server functions are defined using TanStack Start's file-based routing system.
Automatic Mobile Detection: Use Capacitor.isNativePlatform() to detect mobile context and adjust URLs accordingly.
Environment Variables: Use VITE_SERVER_BASE_URL to configure the backend URL for mobile builds.
Simplified Workflow: Single npm run dev command handles both frontend and backend development.
Built-in CORS: TanStack Start handles CORS configuration automatically for mobile development.
Type Safety: Full end-to-end type safety maintained from API routes to React components.

Conclusion

By leveraging TanStack Start's powerful full-stack capabilities, especially its createServerFn, and combining it with Capacitor, you gain an incredibly efficient and type-safe workflow to build native-feeling mobile applications from your web codebase. You can now confidently extend your web development skills to the mobile realm, building robust, modern applications with a truly unified and delightful developer experience.

Happy coding, and go build some amazing mobile apps!

🎥 YouTube Channel
🐦 Twitter
💼 LinkedIn
🌐 GitHub

aaronksaunders / tanstack-capacitor-mobile-1

tanstackStart with Ionic Capacitor for Fullstack Mobile Development, basic template

Understanding the TanStack Start + Capacitor Mobile App Project

There is a video tutorial available here - https://youtu.be/H84he9ijMfc
There is a full blog post explaining step by step how to recreate the project available here -

TANSTACK + Capacitor FINALLY Working Together, Fullstack Mobile Apps

Wanting to get TanStack Start running on mobile with Capacitor? This quick guide shows you the few quick config changes that makes it work—plus a live demo of what fails and what succeeds."

🎥 YouTube Channel
🐦 Twitter
💼 LinkedIn
🌐 GitHub

Getting Started with the TasnstackStart Project

To run this application:

npm install
npm run start

Building For Production

To build this application for production:

npm run build

Testing

This project uses Vitest for testing. You can run the tests with:

npm run test

Styling

This project uses Tailwind CSS for styling.

Routing

This project uses TanStack Router. The initial setup is a…

View on GitHub

How to Instantly Unblock Your AI Dev Tool: The GitHub Issues Prompt

Aaron K Saunders — Thu, 25 Sep 2025 18:15:56 +0000

I recently hit a wall, with cursor struggling to resolve a bug in a particular library. It kept offering basic fixes that just weren't right and we kept looping through the same fixes burning throught tokens

Thats when i remember what I did back in the days when we all coded first and googled second

The Problem:

Modern AI models are powerful, but their training data has a knowledge cutoff. This means they do not have real-time information on the absolute latest bugs, edge cases, or workarounds being discussed and solved right now in the open-source community.

The Solution: tell your AI to search GitHub issues.

Instead of asking "How do I fix X?", you prompt it to leverage GitHub issues. This shifts the AI from trying to recall (potentially outdated) information to actively searching a live, community-maintained database of real issues from real developers

The Prompt I Used:

this bug in [Library/Framework Name, e.g., 'React Query', 'TensorFlow', 'MyProjectName'] can you check recent GitHub issues for related solutions or workarounds? Specifically, look for issues matching [specific error message, function name, or keyword].

Augmenting the intelligence of the AI tool with the intelligence of the community taps you into the collective intelligence of thousands of developers who have likely encountered (and solved) similar issues.

Have you tried anything similar? Share your AI prompting hacks in the comments!

🎥 YouTube Channel

🐦 Twitter
💼 LinkedIn
🌐 GitHub

ChatGPT Mobile App Tutorial: Vue, Convex & Capacitor (Step-by-Step)

Aaron K Saunders — Wed, 24 Sep 2025 16:56:41 +0000

Built with: Ionic Vue, Convex (real-time DB + functions), OpenAI streaming
Runs on: Web + Mobile (same codebase)
What you’ll learn in the full video: Convex Vue plugin, schema + indexes, actions vs mutations, streaming → DB → UI, iOS deploy

In this comprehensive, step-by-step tutorial, you'll learn how to build a full-stack, real-time ChatGPT Style OpenAI chatbot from scratch. We'll integrate the power of OpenAI's API for intelligent conversations, use Convex for a real-time database and serverless backend, and build the front end with Vue.js and the Ionic Framework.

Finally, you'll see how to easily package the entire web application into a native mobile app for iOS and Android using Capacitor. This project covers everything from setting up your environment to deploying a fully functional AI chat application with conversation history.

Tools & Resources Mentioned:

Convex: For a real-time database, serverless functions, and backend logic. https://www.convex.dev/
OpenAI API: To power the AI chat functionality. https://openai.com/api/
Vue.js: For building the reactive user interface. https://vuejs.org/
Ionic Framework: For UI components and project structure. https://ionicframework.com/
Capacitor: To package the Vue.js web app into a native mobile application. https://capacitorjs.com/

Whether you're a beginner or an experienced developer, this video will guide you through every line of code needed to bring this project to life.

🎥 YouTube Channel
🐦 Twitter
💼 LinkedIn
🌐 GitHub

40 years in tech… and I feel like I’m just getting started. 😉

Aaron K Saunders — Wed, 24 Sep 2025 16:52:56 +0000

After four decades in software development, I've seen frameworks come and go. The one thing that remains constant? The power of fundamental principles.

In this video, I share my perspective on how senior developers can stay relevant and ensure their voice is heard. It’s not about chasing the latest trend; it’s about leveraging a career's worth of wisdom to guide, mentor, and build things that last.

Experience isn’t about being the oldest person in the room; it’s about being the one who can provide a strategic view that no one else can.

What's your top strategy for staying relevant in our ever-changing industry?

Share your thoughts in the comments below.

Run Payload Jobs on Vercel (Serverless) — Step‑by‑Step Migration

Aaron K Saunders — Wed, 17 Sep 2025 17:03:03 +0000

I recently did a video tutorial on using jobs and queues in PayloadCMS and the solution I provide will not work in a Vercel deployment, runs locally and will probably also run on Railway because those are actual servers.

This blog post explains why and walks you through how to update the project to run on Vercel.

Get the source code here

The "Why": Serverless vs. Long-Running Processes

The code in the video uses Payload's built-in jobs queue, which relies on a long-running Node.js server process. The autoRun: true setting starts a persistent "clock" (setInterval) inside your server that checks every minute if a job needs to run.

With Vercel, however, since it is a serverless platform, your code doesn't run on a server that is "always on." Instead, it's packaged into serverless functions that spin up to handle an incoming request and then shut down shortly after the response is sent.

Because the functions shut down, there is no persistent process to keep the scheduler's "clock" ticking in the background. Your job would never be triggered after the initial deployment.

A Vercel functions have execution timeouts (e.g., 10-60 seconds on hobby/pro plans). Since the payload job queue designed to run indefinitely would be terminated.

The Solution: How to Run Scheduled Jobs on Vercel

You can run scheduled tasks with your Payload CMS app on Vercel, but you need to change the trigger mechanism. Instead of having the app schedule itself, you use an external service to call your app on a schedule.

Vercel has Vercel Cron Jobs which can be utilized to solve our problem

Here is how you would updat the project to work on Vercel:

Step 1: Disable `autoRun` in Payload Config

First, prevent Payload from trying to start its own internal scheduler.

In payload.config.ts, Disable auto scheduling by default on serverless. Opt‑in locally or on traditional servers with ENABLE_PAYLOAD_AUTORUN=true.

// payload.config.ts

  jobs: {
    tasks: [processTrackersTask],
    /**
     * Conditionally enable autoRun based on environment
     * @description Serverless environments (e.g., Vercel) should disable in-process schedulers.
     * Set ENABLE_PAYLOAD_AUTORUN="true" locally or on traditional servers to turn this on.
     */
    autoRun:
      process.env.ENABLE_PAYLOAD_AUTORUN === 'true'
        ? [
            {
              cron: '* * * * *', // Process jobs every minute
              queue: 'tracker-queue',
            },
          ]
        : [],
    jobsCollectionOverrides: ({ defaultJobsCollection }) => {
      // keep jobs visible in Admin
      if (!defaultJobsCollection.admin) {
        defaultJobsCollection.admin = {}
      }
      defaultJobsCollection.admin.hidden = false
      return defaultJobsCollection
    },
  },

Step 2: Create a Secure API Endpoint to Trigger the Job

Make the task’s internal schedule conditional and export a runProcessTrackers function you can call from an API route which is what the vercel cron job will call.

export const processTrackersTask: TaskConfig<'process-trackers'> = {
  slug: 'process-trackers',
  /**
   * Conditionally attach schedule when ENABLE_PAYLOAD_TASK_SCHEDULE === 'true'
   * @description On serverless, keep this empty and rely on Vercel Cron hitting an API route.
   */
  schedule:
    process.env.ENABLE_PAYLOAD_TASK_SCHEDULE === 'true'
      ? [
          {
            cron: '* * * * *', // Run every minute
            queue: 'tracker-queue',
          },
        ]
      : [],
  handler: async (): Promise<TaskHandlerResult<'process-trackers'>> => {
    return runProcessTrackers()
  },
}

/**
 * Reusable runner for process-trackers
 * @description Extracted so we can call from API route or the Task handler.
 */
export const runProcessTrackers = async (): Promise<TaskHandlerResult<'process-trackers'>> => {
  console.log(`[TASK] Processing all active price trackers...`)
  // ... rest of implementation unchanged
}

Step 3: Create a Secure API Endpoint to Trigger the Job

You need to create a route in your application that an external service can call. When this route is hit, it will manually trigger the job.

It's critical to protect this endpoint, the standard way is to use a CRON_SECRET stored in an environment variable. If you don't implement a way to secure the endpoint then anyone can spam the endpoint and disrupt your site

Create a new file, for example, at src/app/api/payload-cron/route.ts:

import { NextResponse } from 'next/server'
import { runProcessTrackers } from '@/tasks/process-trackers'

/**
 * Validates cron job requests using CRON_SECRET authentication
 * @description Implements Vercel's official cron job security pattern:
 * - Primary: Checks Authorization header for "Bearer {CRON_SECRET}" (production)
 * - Fallback: Checks query parameter "secret" for manual testing
 */
const isAuthorized = (req: Request): boolean => {
  const configured = process.env.CRON_SECRET || ''
  if (!configured) {
    console.log('[CRON] No CRON_SECRET configured')
    return false
  }

  const authHeader = req.headers.get('authorization') || ''

  // Check if Authorization header matches CRON_SECRET (as per Vercel docs)
  if (authHeader === `Bearer ${configured}`) {
    return true
  }

  // Fallback to query param for manual testing
  try {
    const url = new URL(req.url)
    const qsSecret = url.searchParams.get('secret') || ''
    if (qsSecret === configured) {
      return true
    }
  } catch (e) {
    console.log('[CRON] Error parsing URL:', e)
  }

  console.log('[CRON] Authorization failed')
  return false
}

export const dynamic = 'force-dynamic'

export async function GET(req: Request) {
  console.log('[CRON] Processing cron job request')

  if (!isAuthorized(req)) {
    return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
  }

  console.log('[CRON] Authorization successful, running task...')
  const result = await runProcessTrackers()
  console.log('[CRON] Task completed:', result)
  return NextResponse.json(result)
}

export async function POST(req: Request) {
  if (!isAuthorized(req)) {
    return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
  }
  const result = await runProcessTrackers()
  return NextResponse.json(result)
}

Step 4: Configure environment variables

Add the new environment variables

ENABLE_PAYLOAD_AUTORUN=false
ENABLE_PAYLOAD_TASK_SCHEDULE=false
CRON_SECRET=replace-with-long-random-string

Step 5: Configure Vercel Cron Jobs

Finally, you tell Vercel to call this new endpoint on a schedule. You do this by adding a crons section to a vercel.json file in the root of your project.

Vercel will automatically send the CRON_SECRET environment variable as an Authorization: Bearer {CRON_SECRET} header when invoking your endpoint. This follows Vercel's official documentation for cron job security.

// vercel.json

{
  "crons": [
    {
      "path": "/api/payload-cron",
      "schedule": "* * * * *"
    }
  ]
}

path: This is the API route you created in Step 2.
schedule: This is the standard cron syntax. * * * * * means "run every minute," just like in the video.

Notes:

This sets a once-per-minute schedule. Adjust the cron as needed.
Vercel automatically sends CRON_SECRET as Authorization header - no manual header configuration needed.
For manual testing, you can pass the secret via query string: /api/payload-cron?secret=$CRON_SECRET. The route supports both header and ?secret= for convenience.

Test Locally

Vercel Cron only runs in Vercel’s cloud environment. The vercel dev command does not simulate cron triggers.

Run dev server and trigger the route manually:

pnpm run dev
curl -i -H "x-cron-secret: $CRON_SECRET" http://localhost:3000/api/payload-cron
curl -i "http://localhost:3000/api/payload-cron?secret=$CRON_SECRET" # query param alternative

You should see logs:

[TASK] Processing all active price trackers...
[TASK] Found N active trackers to process.
[TASK] Fetching prices for coins: ...
[TASK] Finished processing trackers.

Expected responses:

Success (200): { "output": { "success": true } }
Unauthorized (401): { "error": "Unauthorized" } (check your header/query secret)

Tips:

Ensure ENABLE_PAYLOAD_AUTORUN=false and ENABLE_PAYLOAD_TASK_SCHEDULE=false locally to avoid double execution while testing the route.
If you prefer in-process scheduling in local dev, set ENABLE_PAYLOAD_AUTORUN=true and skip calling the route.

So, while the core logic of the process-tracker.ts file remains the same, the method of triggering that logic must be adapted for Vercel's serverless architecture.

Vercel deployment checklist

Configure env vars (Project → Settings → Environment Variables)
- DATABASE_URI, PAYLOAD_SECRET
- ENABLE_PAYLOAD_AUTORUN=false, ENABLE_PAYLOAD_TASK_SCHEDULE=false, CRON_SECRET=<long-random>
Deploy the app (Git push or Vercel CLI)
vercel.json is included and automatically configures cron jobs
Verify
- Call: https://<your-app>.vercel.app/api/payload-cron?secret=<CRON_SECRET>
- Expect 200 and { "output": { "success": true } }
- Check Vercel logs and Payload Admin for updates

When everything is properly deployed you can go to Project Setting / Jobs and you should see something similar to this.

Summary

This blog post shows how to update Payload CMS's built-in Jobs Queue system for serverless deployment on Vercel. By replacing in-process schedulers with Vercel Cron, we achieve:

Reliable Scheduling: Cron jobs run consistently in serverless environments
Proper Authentication: Uses Vercel's official CRON_SECRET Authorization header pattern
Environment Flexibility: Same codebase works locally (with in-process scheduling) and on Vercel (with HTTP scheduling)
Production Ready: Follows Vercel's documented best practices for cron job security

The key insight is that serverless functions are short lived, so persistent timers don't work. The solution is to trigger work via scheduled HTTP requests that execute tasks on-demand, maintaining the same functionality while adapting to the serverless model.

Reference Links

Official Documentation

Vercel Cron Jobs Documentation - Official guide for setting up cron jobs
Vercel Cron Jobs Management - Managing and securing cron jobs
Payload CMS Jobs Queue - Payload's built-in job system
Next.js API Routes - Creating API endpoints

Related Resources

Vercel Functions Documentation - Understanding Vercel's serverless functions
Payload CMS Configuration - General Payload configuration
Vercel Cron Examples - Vercel templates with cron jobs

Building a Mobile App with Ionic, Vue, and Clerk

Aaron K Saunders — Fri, 12 Sep 2025 18:42:08 +0000

Building a Headless Authentication App with Ionic, Vue, and Clerk

This is an AI generated post of the video transcript with the code snippets integrated into the flow of the original video

Welcome back to the channel! This tutorial will guide you step-by-step on how to integrate Clerk, a full-stack authentication and user management system, into an Ionic Vue application. Clerk handles complex tasks like password management, login, logout, and email verification, freeing you from building these features from scratch. While Clerk is very popular in the React/Next.js world, we'll explore how to get it working seamlessly with Vue.js and Capacitor for packing solution on mobile device.

Our primary goal is to use Clerk as your authentication provider on a mobile app wrapped with Capacitor, specifically using Vue.

Demo of the Final Application

Let's start with a quick demo of the final application we're aiming to build. We're using Clerk in a "headless" manner, meaning we're not relying on Clerk's pre-built UI components. Instead, we've created a custom UI for our sign-in and sign-up screens. This approach gives you full control over the user experience.

Create Account Flow

When you navigate to the "Create Account" screen and enter your email, first name, last name, and password, Clerk handles the process. You'll see a CAPTCHA verification step, which Clerk manages automatically. After successful CAPTCHA, Clerk sends an email with a verification code. You'll then enter this code into the app to complete the sign-up process.

Once verified, you'll be logged in and redirected to the profile page.

Profile Page Features

The profile page displays user information like your email and user ID. We've also integrated calls to the Clerk Vue library to demonstrate how you can access additional user and session information, and even refresh the session.

Session Persistence

A crucial aspect of mobile applications is maintaining user state. If you close the app after logging in and then reopen it, the app should automatically re-authenticate you and take you back to the profile page. This demonstrates that Clerk successfully persists the session.

Sign Out and Re-Login

Finally, the app allows you to sign out and then log back in, confirming that the authentication flow works as expected.

This application serves as a template to help you understand how to integrate Clerk into your existing app or use it as a starting point for a new project.

Starting Point: The `clerk-tutorial-start` Project

To make this project easier to follow, we're starting with a pre-built project called clerk-tutorial-start. This is a basic Vue app with mock authentication, designed to save time on setting up basic screens and the Vue application structure.

Project Source Code - the starting point is on the main branch and the finished project is on the finished-code branch

This application is built with Ionic, utilizing Ionic components for the UI. However, you could easily swap these out for other UI frameworks like Tailwind or DaisyUI. Importantly, it already has iOS and Android integrated, allowing you to run it as a Capacitor app and deploy directly to your device.

For those who want to follow along with the code, I suggest you pause the video, check out the repo, and download the clerk-tutorial-start project.

Setting Up Clerk

The next step is to get Clerk set up. Go to Clerk.com and log in. You'll need to set up a new project or application. Here are a few key configurations you'll need to make:

Configure User Model: Since our application collects first name and last name during sign-up, you need to enable these fields in your Clerk application's user model. Go to "Configure User Model" and ensure "First Name" and "Last Name" are checked.
Sign-Up Settings:
- Ensure "Sign up with email" is turned on.
- Enable "Verify at sign up."
- Select "Email code" for verification.
- You can also enable "Sign in with verification email code" if you plan to implement that flow.
- Important Note on Email Verification Links: While Clerk offers email verification links, it's generally recommended to use email codes for mobile devices. Verification links can be challenging to implement correctly on mobile due to external browser dependencies and a more complex flow. Clerk itself warns about poor conversion rates with links on mobile.
API Keys: You'll need to retrieve your Publishable Key from the Clerk dashboard. This key will be used in your application's environment variables.

Once you've made these changes in your Clerk dashboard, you're ready to start modifying the project.

Modifying the Project: Adding Clerk Functionality

Step 1: Install Clerk and Set Environment Variable

First, ensure you have the Clerk Vue SDK installed:

npm install @clerk/vue

Next, create a .env file in the root of your project (if you don't have one already) and set your Clerk Publishable Key:

VITE_CLERK_PUBLISHABLE_KEY=pk_test_your_publishable_key_here

Replace pk_test_your_publishable_key_here with the actual key from your Clerk dashboard.

Step 2: Integrate Clerk Plugin in `main.ts`

The main.ts file is the entry point of our Vue application. Here, we'll import and initialize the Clerk plugin. This step is crucial as it makes Clerk's functionalities, like useClerk and useUser hooks, available throughout our application.

File: src/main.ts

import { createApp } from "vue";
import App from "./App.vue";
import router from "./router/auth";

import { IonicVue } from "@ionic/vue";

// ... (Ionicons imports) ...

/* Theme variables */
import "./theme/variables.css";
// NEW: Import clerkPlugin
import { clerkPlugin } from "@clerk/vue";

const PUBLISHABLE_KEY = import.meta.env.VITE_CLERK_PUBLISHABLE_KEY;

if (!PUBLISHABLE_KEY) {
  throw new Error("Missing VITE_CLERK_PUBLISHABLE_KEY");
}

const app = createApp(App)
  .use(IonicVue, {
    mode: "ios",
  })
  .use(router)
  // NEW: Initialize clerkPlugin
  .use(clerkPlugin, {
    publishableKey: PUBLISHABLE_KEY,
  });

router.isReady().then(() => {
  app.mount("#app");
});

Step 3: Implement Login/Logout with `useAuth.ts` Composable

We'll create a useAuth composable to centralize all our authentication logic. This is a powerful pattern in Vue that allows us to reuse this logic across our application.

Create a new file: src/composables/useAuth.ts.

Understanding Clerk's Hooks

Inside useAuth.ts, we'll leverage Clerk's Vue hooks:

useClerk(): Provides access to the Clerk client instance, which contains methods for authentication actions like signIn, signUp, and signOut.
useUser(): Provides reactive state about the current user, including isSignedIn (whether a user is logged in), isLoaded (whether Clerk has finished initializing), and the user object itself.

File: src/composables/useAuth.ts

// NEW: Entire file is new
import { ref, computed } from "vue";
import { useClerk, useUser } from "@clerk/vue";

export function useAuth() {
  const clerk = useClerk();
  const { isSignedIn, user, isLoaded } = useUser();
  const isLoading = ref(false);
  const error = ref("");

  // We will add our functions here

  return {
    isSignedIn: computed(() => isSignedIn.value),
    user: computed(() => user.value),
    isLoaded: computed(() => isLoaded.value),
    isLoading: computed(() => isLoading.value),
    error: computed(() => error.value),
  };
}

The Sign-In Flow

The signIn function handles user login. In Clerk's headless authentication, you call clerk.client.signIn.create() with the user's credentials. Clerk processes this and returns a result object with a status.

If result.status is "complete", the user is successfully authenticated. We then must call clerk.setActive({ session: result.createdSessionId }) to tell the Clerk SDK to activate this session in the client. This is a critical step for headless integration.
If the status is not "complete", or an error occurs, we handle it by setting an error message.

File: src/composables/useAuth.ts (add signIn function)

// ... (imports and setup) ...

  const signIn = async (email, password) => {
    isLoading.value = true;
    error.value = "";
    try {
      const result = await clerk.value.client.signIn.create({
        identifier: email,
        password: password,
      });

      if (result.status === "complete") {
        await clerk.value.setActive({ session: result.createdSessionId });
        return true;
      } else {
        error.value = "Sign in failed";
        return false;
      }
    } catch (err) {
      error.value = err.message || "Sign in failed";
      return false;
    } finally {
      isLoading.value = false;
    }
  };

  // ... (return statement) ...

The Sign-Out Flow

The signOut function is straightforward. Calling clerk.signOut() instructs the Clerk SDK to terminate the current user session and clear any local authentication state.

File: src/composables/useAuth.ts (add signOut function)

// ... (imports and signIn function) ...

  const signOut = async () => {
    isLoading.value = true;
    try {
      await clerk.value.signOut();
      return true;
    } catch (err) {
      console.error("Sign out error:", err);
      return false;
    } finally {
      isLoading.value = false;
    }
  };

  return {
    // ... (state) ...
    signIn,
    signOut,
  };

Updating Login and Profile Views

Now, we'll update src/views/LoginView.vue and src/views/ProfileView.vue to utilize our useAuth composable for handling sign-in and sign-out actions.

File: src/views/LoginView.vue

<template>
  <ion-page>
    <ion-header>
      <ion-toolbar>
        <ion-title>Sign In</ion-title>
      </ion-toolbar>
    </ion-header>
    <ion-content :fullscreen="true">
      <div class="container">
        <!-- Login Form -->
        <ion-card>
          <ion-card-header>
            <ion-card-title>Welcome Back</ion-card-title>
            <ion-card-subtitle>Sign in to your account</ion-card-subtitle>
          </ion-card-header>
          <ion-card-content>
            <ion-item>
              <ion-label position="stacked">Email</ion-label>
              <ion-input
                v-model="email"
                type="email"
                placeholder="Enter your email"
                :disabled="isLoading"
              ></ion-input>
            </ion-item>

            <ion-item>
              <ion-label position="stacked">Password</ion-label>
              <ion-input
                v-model="password"
                type="password"
                placeholder="Enter your password"
                :disabled="isLoading"
              ></ion-input>
            </ion-item>

            <div class="ion-padding">
              <ion-button
                @click="handleSignIn"
                expand="block"
                :disabled="isLoading || !email || !password"
              >
                <ion-spinner v-if="isLoading" name="crescent"></ion-spinner>
                <ion-icon v-else name="log-in-outline" slot="start"></ion-icon>
                Sign In
              </ion-button>

              <ion-button
                @click="navigateToSignUp"
                expand="block"
                fill="outline"
                :disabled="isLoading"
              >
                <ion-icon name="person-add-outline" slot="start"></ion-icon>
                Don't have an account? Sign Up
              </ion-button>
            </div>

            <!-- Error Display -->
            <ion-item v-if="error" color="danger">
              <ion-icon name="warning" slot="start"></ion-icon>
              <ion-label>{{ error }}</ion-label>
            </ion-item>
          </ion-card-content>
        </ion-card>
      </div>
    </ion-content>
  </ion-page>
</template>

<script setup lang="ts">
import { ref } from "vue";
import { useRouter } from "vue-router";
import {
  IonPage,
  IonHeader,
  IonToolbar,
  IonTitle,
  IonContent,
  IonCard,
  IonCardHeader,
  IonCardTitle,
  IonCardSubtitle,
  IonCardContent,
  IonItem,
  IonLabel,
  IonInput,
  IonButton,
  IonIcon,
  IonSpinner,
} from "@ionic/vue";
// NEW: Import useAuth
import { useAuth } from "../composables/useAuth";

const router = useRouter();
// NEW: Use auth composable
const { signIn, error: authError, isLoading } = useAuth();

// Form state
const email = ref("");
const password = ref("");
const error = ref("");

/**
 * Handle sign in form submission
 */
const handleSignIn = async () => {
  if (!email.value || !password.value) {
    error.value = "Please fill in all fields";
    return;
  }
  try {
    error.value = "";

    // NEW: Call signIn from useAuth
    const result = await signIn(email.value, password.value);

    if (result) {
      // Clear form
      email.value = "";
      password.value = "";
      // Navigate to profile
      router.push("/profile");
    } else {
      error.value = authError.value || "Invalid email or password";
    }
  } catch (err) {
    error.value = err instanceof Error ? err.message : "Sign in failed";
  }
};

/**
 * Navigate to sign up view
 */
const navigateToSignUp = () => {
  router.push("/signup");
};
</script>

<style scoped>
.container {
  padding: 16px;
  max-width: 400px;
  margin: 0 auto;
}

ion-item {
  --padding-start: 0;
  --inner-padding-end: 0;
}

ion-button {
  margin: 8px 0;
}
</style>

File: src/views/ProfileView.vue

<template>
  <ion-page>
    <ion-header>
      <ion-toolbar>
        <ion-title>Profile</ion-title>
        <ion-buttons slot="end">
          <ion-button @click="handleSignOut" color="danger">
            <ion-icon name="log-out-outline" slot="start"></ion-icon>
            Sign Out
          </ion-button>
        </ion-buttons>
      </ion-toolbar>
    </ion-header>
    <ion-content :fullscreen="true">
      <div class="container">
        <!-- User Profile Card -->
        <ion-card>
          <ion-card-content>
            <div class="profile-container">
              <!-- Avatar at the top -->
              <ion-avatar class="profile-avatar">
                <img
                  v-if="user?.imageUrl"
                  :src="user.imageUrl"
                  :alt="
                    user ? `${user.firstName} ${user.lastName}` : 'User Avatar'
                  "
                />
                <div v-else class="avatar-placeholder">
                  {{ (user?.firstName || "U").charAt(0).toUpperCase() }}
                </div>
              </ion-avatar>

              <!-- User details below avatar -->
              <div class="profile-details">
                <h2 class="welcome-text">
                  Welcome, {{ user?.firstName || "User" }}!
                </h2>
                <p class="user-email">
                  {{
                    user?.emailAddresses[0]?.emailAddress ||
                    "Email not provided"
                  }}
                </p>

                <div class="user-info">
                  <p>
                    <strong>Name:</strong>
                    {{ user?.firstName }} {{ user?.lastName }}
                  </p>
                  <p>
                    <strong>Email:</strong>
                    {{
                      user?.emailAddresses[0]?.emailAddress || "Not provided"
                    }}
                  </p>
                  <p>
                    <strong>User ID:</strong> {{ user?.id || "Not available" }}
                  </p>
                  <p>
                    <strong>Member since:</strong>
                    {{ formatDate(new Date()) }}
                  </p>
                </div>
              </div>
            </div>
          </ion-card-content>
        </ion-card>

        <!-- Auth Actions Component -->
        <AuthActions />
      </div>
    </ion-content>
  </ion-page>
</template>

<script setup lang="ts">
import { useRouter } from "vue-router";
import {
  IonPage,
  IonHeader,
  IonToolbar,
  IonTitle,
  IonContent,
  IonCard,
  IonCardContent,
  IonButton,
  IonButtons,
  IonIcon,
  IonAvatar,
} from "@ionic/vue";
// NEW: Import useAuth
import { useAuth } from "../composables/useAuth";
import AuthActions from "../components/AuthActions.vue";

const router = useRouter();
// NEW: Use auth composable
const { user, signOut } = useAuth();

/**
 * Handle user sign out
 */
const handleSignOut = async () => {
  // NEW: Call signOut from useAuth
  await signOut();
  router.push("/login");
};

/**
 * Format date for display
 */
const formatDate = (date: Date | null | undefined) => {
  if (!date) return "Not available";
  return new Date(date).toLocaleDateString("en-US", {
    year: "numeric",
    month: "long",
    day: "numeric",
  });
};
</script>

<style scoped>
.container {
  padding: 16px;
}

.profile-container {
  text-align: center;
  padding: 20px;
}

.profile-avatar {
  width: 120px;
  height: 120px;
  margin: 0 auto 20px;
  --border-radius: 50%;
}

.profile-avatar img {
  width: 100%;
  height: 100%;
  object-fit: cover;
  border-radius: 50%;
}

.avatar-placeholder {
  width: 100%;
  height: 100%;
  background: linear-gradient(
    135deg,
    var(--ion-color-primary),
    var(--ion-color-secondary)
  );
  border-radius: 50%;
  display: flex;
  align-items: center;
  justify-content: center;
  font-size: 48px;
  font-weight: bold;
  color: white;
}

.profile-details {
  text-align: center;
}

.welcome-text {
  margin: 0 0 8px 0;
  font-size: 24px;
  font-weight: 600;
  color: var(--ion-color-dark);
}

.user-email {
  margin: 0 0 20px 0;
  font-size: 16px;
  color: var(--ion-color-medium);
  text-transform: uppercase;
  letter-spacing: 0.5px;
}

.user-info {
  text-align: left;
  background: var(--ion-color-light);
  border-radius: 12px;
  padding: 16px;
  margin-top: 20px;
}

.user-info p {
  margin: 12px 0;
  font-size: 14px;
  line-height: 1.4;
}

.user-info strong {
  color: var(--ion-color-primary);
  font-weight: 600;
}
</style>

Checkpoint: Testing Login/Logout

At this point, you should be able to run the app and test the login and logout functionality. Run npm run dev to start the development server. You can create a user directly in your Clerk dashboard to test the login.

Step 4: Create Accounts & Handle Verification

Now let's add the signUp flow. This is a multi-step process involving:

Creating the user.
If required, prompting the user to verify their email address.
Completing the verification to grant the user a session.

The Sign-Up Logic in `useAuth.ts`

In our useAuth.ts composable, the signUp function will handle step 1. When we call clerk.client.signUp.create(), Clerk attempts to create the user.

If result.status is "complete", the user is created and immediately authenticated.
If result.status is "missing_requirements", it means the user needs to verify their email. Clerk then sends an email with a verification code, and we call result.prepareEmailAddressVerification() to prepare for the next step. This is Clerk telling our frontend, "The user is created, but now you need to prove they own this email address before I give them a full session."

The Verification Logic in `useAuth.ts`

The handleVerification function will handle step 3. It takes the code the user provides (from their email) and sends it to Clerk's signUpAttempt.attemptEmailAddressVerification() endpoint. If the verification is successful (verification.status === "complete"), the user is fully verified, and we then call clerk.setActive() to establish their session.

Let's add these functions to our composable:

File: src/composables/useAuth.ts (add signUp and handleVerification functions)

// ... (imports and other functions) ...

  const signUp = async (email, password, firstName, lastName) => {
    isLoading.value = true;
    error.value = "";

    try {
      const result = await clerk.value.client.signUp.create({
        emailAddress: email,
        password: password,
        firstName: firstName,
        lastName: lastName,
      });

      if (result.status === "complete") {
        await clerk.value.setActive({ session: result.createdSessionId });
        return true;
      } else if (result.status === "missing_requirements") {
        // Clerk requires email verification
        await result.prepareEmailAddressVerification({
          strategy: "email_code",
        });
        error.value = "Email verification required";
        return false;
      } else {
        error.value = "Sign up failed";
        return false;
      }
    } catch (err) {
      error.value = err.message || "Sign up failed";
      return false;
    } finally {
      isLoading.value = false;
    }
  };

  const handleVerification = async (code) => {
    isLoading.value = true;
    error.value = "";

    try {
      const signUpAttempt = clerk.value.client.signUp;
      if (!signUpAttempt) {
        throw new Error("No sign-up attempt found");
      }

      const verification = await signUpAttempt.attemptEmailAddressVerification({
        code: code,
      });

      if (verification.status === "complete") {
        // Verification successful, activate the session
        await clerk.value.setActive({ session: verification.createdSessionId });
        return true;
      } else {
        error.value = "Verification failed";
        return false;
      }
    } catch (err) {
      error.value = err.message || "Verification failed";
      return false;
    }
  };

  return {
    // ... (state and other functions) ...
    signUp,
    handleVerification,
  };

Updating the Sign-Up View (`SignUpView.vue`)

Now we need to update our SignUpView.vue to handle this multi-step flow. This involves both template (UI) and script (logic) changes.

Template Changes for Verification

First, we'll add a new section to our template that will only be shown when the user needs to verify their email. We'll use a v-if="needsVerification" directive to control its visibility. This section will contain an input field for the verification code and a button to submit it.

File: src/views/SignUpView.vue (Template)

<template>
  <ion-page>
    <ion-header>
      <ion-toolbar>
        <ion-title>Create Account</ion-title>
      </ion-toolbar>
    </ion-header>
    <ion-content :fullscreen="true">
      <!-- NEW: Add this div for CAPTCHA, Clerk will render into it -->
      <div id="clerk-captcha"></div>

      <div class="container">
        <!-- Sign Up Form -->
        <ion-card>
          <ion-card-header>
            <ion-card-title>Create Your Account</ion-card-title>
            <ion-card-subtitle>Join us today</ion-card-subtitle>
          </ion-card-header>
          <ion-card-content>
            <ion-item>
              <ion-label position="stacked">Email</ion-label>
              <ion-input
                v-model="email"
                type="email"
                placeholder="Enter your email"
                :disabled="isLoading"
              ></ion-input>
            </ion-item>

            <ion-item>
              <ion-label position="stacked">First Name</ion-label>
              <ion-input
                v-model="firstName"
                type="text"
                placeholder="Enter your first name"
                :disabled="isLoading"
              ></ion-input>
            </ion-item>

            <ion-item>
              <ion-label position="stacked">Last Name</ion-label>
              <ion-input
                v-model="lastName"
                type="text"
                placeholder="Enter your last name"
                :disabled="isLoading"
              ></ion-input>
            </ion-item>

            <ion-item>
              <ion-label position="stacked">Password</ion-label>
              <ion-input
                v-model="password"
                type="password"
                placeholder="Enter your password"
                :disabled="isLoading"
              ></ion-input>
            </ion-item>

            <ion-item>
              <ion-label position="stacked">Confirm Password</ion-label>
              <ion-input
                v-model="confirmPassword"
                type="password"
                placeholder="Confirm your password"
                :disabled="isLoading"
              ></ion-input>
            </ion-item>

            <div class="ion-padding">
              <ion-button
                @click="handleSignUp"
                expand="block"
                :disabled="
                  isLoading || !email || !password || !firstName || !lastName
                "
              >
                <ion-spinner v-if="isLoading" name="crescent"></ion-spinner>
                <ion-icon
                  v-else
                  name="person-add-outline"
                  slot="start"
                ></ion-icon>
                Create Account
              </ion-button>

              <ion-button
                @click="navigateToLogin"
                expand="block"
                fill="outline"
                :disabled="isLoading"
              >
                <ion-icon name="log-in-outline" slot="start"></ion-icon>
                Already have an account? Sign In
              </ion-button>
            </div>

            <!-- NEW: Verification code input section -->
            <div v-if="needsVerification" class="ion-padding">
              <ion-item>
                <ion-label position="stacked">Verification Code</ion-label>
                <ion-input
                  v-model="verificationCode"
                  type="text"
                  placeholder="Enter code from email"
                  :disabled="isLoading"
                ></ion-input>
              </ion-item>
              <ion-button
                @click="handleVerify"
                expand="block"
                :disabled="isLoading || !verificationCode"
              >
                <ion-spinner v-if="isLoading" name="crescent"></ion-spinner>
                <ion-icon
                  v-else
                  name="checkmark-outline"
                  slot="start"
                ></ion-icon>
                Verify Account
              </ion-button>
            </div>

            <!-- Error Display -->
            <ion-item v-if="localError" color="danger">
              <ion-icon name="warning" slot="start"></ion-icon>
              <ion-label>{{ localError }}</ion-label>
            </ion-item>
          </ion-card-content>
        </ion-card>
      </div>
    </ion-content>
  </ion-page>
</template>

Script Changes for Verification Flow

Now, let's update the script. When our handleSignUp function calls the signUp method from our composable, if it returns false and the error message indicates "verification required", we will set needsVerification to true. This will make our new UI section appear, prompting the user for the code they received in their email. The handleVerify function will then take this code and complete the verification.

File: src/views/SignUpView.vue (Script)

<script setup lang="ts">
import { ref } from "vue";
import { useRouter } from "vue-router";
import {
  IonPage,
  IonHeader,
  IonToolbar,
  IonTitle,
  IonContent,
  IonCard,
  IonCardHeader,
  IonCardTitle,
  IonCardSubtitle,
  IonCardContent,
  IonItem,
  IonLabel,
  IonInput,
  IonButton,
  IonIcon,
  IonSpinner,
} from "@ionic/vue";
// NEW: Import useAuth
import { useAuth } from "../composables/useAuth";

const router = useRouter();
// NEW: Use auth composable
const { signUp, handleVerification, error: authError, isLoading } = useAuth();

// Form state
const email = ref("");
const password = ref("");
const confirmPassword = ref("");
const firstName = ref("");
const lastName = ref("");
const localError = ref("");
// NEW: Add state for verification UI
const needsVerification = ref(false);
const verificationCode = ref("");

/**
 * Handles sign up form submission.
 */
const handleSignUp = async () => {
  if (!email.value || !password.value || !firstName.value || !lastName.value) {
    localError.value = "Please fill in all fields";
    return;
  }
  if (password.value !== confirmPassword.value) {
    localError.value = "Passwords do not match";
    return;
  }
  try {
    localError.value = "";
    // NEW: Call signUp from useAuth
    const result = await signUp(email.value, password.value, firstName.value, lastName.value);
    if (result) {
      clearForm();
      router.push("/profile");
    } else {
      localError.value = authError.value || "Sign up failed";
      // NEW: If verification is required, show the verification UI
      if (localError.value.includes("verification")) {
        needsVerification.value = true;
      }
    }
  } catch (err) {
    localError.value = err instanceof Error ? err.message : "Sign up failed";
  }
};

// NEW: Add handleVerify method for email code submission
/**
 * Handles verification code submission.
 */
const handleVerify = async () => {
  if (!verificationCode.value) {
    localError.value = "Please enter the verification code";
    return;
  }
  try {
    localError.value = "";
    const result = await handleVerification(verificationCode.value);
    if (result) {
      needsVerification.value = false;
      clearForm();
      router.push("/profile");
    } else {
      localError.value = authError.value || "Verification failed";
    }
  } catch (err) {
    localError.value = err instanceof Error ? err.message : "Verification failed";
  }
};

// NEW: Add clearForm method to reset all form fields and state
/**
 * Clears all form fields and resets local state.
 */
const clearForm = () => {
  email.value = "";
  password.value = "";
  confirmPassword.value = "";
  firstName.value = "";
  lastName.value = "";
  localError.value = "";
  verificationCode.value = "";
  needsVerification.value = false;
};

/**
 * Navigates to the login view.
 */
const navigateToLogin = () => {
  router.push("/login");
};
</script>

Checkpoint: Testing Account Creation

Now you can test the full sign-up flow, including email verification. Try creating a new account, check your email for the code, and then enter it into the app.

Step 5: Handle Auth State with `Suspense` and Watchers

To ensure our app is reactive to authentication state changes (e.g., when a user logs in or out in another tab) and to provide a smooth loading experience, we will use Vue's Suspense feature and a watcher. This setup will show a loading spinner while Clerk is initializing and then automatically redirect the user based on their authentication status.

First, create a LoadingSpinner.vue component in src/components. This component will be displayed while Clerk is loading.

File: src/components/LoadingSpinner.vue

<!-- NEW: Entire file is new -->
<template>
  <ion-page>
    <ion-content class="loading-content">
      <div class="loading-container">
        <ion-spinner name="crescent" color="primary"></ion-spinner>
        <h2>Loading...</h2>
        <p>Initializing authentication</p>
      </div>
    </ion-content>
  </ion-page>
</template>

<script setup lang="ts">
import { IonPage, IonContent, IonSpinner } from "@ionic/vue";
</script>

<style scoped>
.loading-content { --background: var(--ion-color-light); }
.loading-container { display: flex; flex-direction: column; align-items: center; justify-content: center; height: 100vh; }
</style>

Next, create an AppContent.vue component in src/components. This component will wait for Clerk to be fully loaded (isLoaded) and then watches the isSignedIn state and the current route to perform redirects.

File: src/components/AppContent.vue

<!-- NEW: Entire file is new -->
<template>
  <ion-router-outlet />
</template>

<script setup lang="ts">
import { watch } from "vue";
import { useRouter, useRoute } from "vue-router";
import { IonRouterOutlet } from "@ionic/vue";
import { useAuth } from "../composables/useAuth";

const router = useRouter();
const route = useRoute();
const { isSignedIn, isLoaded } = useAuth();

// Wait for Clerk to be fully loaded before rendering the main content
await new Promise((resolve) => {
  const unwatch = watch(isLoaded, (loaded) => {
    if (loaded) { unwatch(); resolve(); }
  }, { immediate: true });
});

// Watch for changes in authentication state or route to handle redirects
watch([isSignedIn, route], ([signedIn, currentRoute]) => {
  const protectedRoutes = ["/profile"]; // Routes that require authentication
  const guestRoutes = ["/login", "/signup"]; // Routes that should redirect if user is signed in

  // If trying to access a protected route and not signed in, redirect to login
  if (protectedRoutes.includes(currentRoute.path) && !signedIn) {
    router.replace("/login");
    return;
  }
  // If trying to access a guest route and already signed in, redirect to profile
  if (guestRoutes.includes(currentRoute.path) && signedIn) {
    router.replace("/profile");
    return;
  }
}, { immediate: true });
</script>

Finally, update App.vue to use Vue's Suspense feature. This allows us to display the LoadingSpinner while AppContent (which is asynchronous due to waiting for Clerk to load) is being prepared.

File: src/App.vue

<template>
  <ion-app>
    <!-- NEW: Use Suspense to handle loading state -->
    <Suspense>
      <!-- Main Content -->
      <template #default>
        <AppContent />
      </template>

      <!-- Fallback Content -->
      <template #fallback>
        <LoadingSpinner />
      </template>
    </Suspense>
  </ion-app>
</template>

<script setup lang="ts">
import { IonApp } from "@ionic/vue";
import { defineAsyncComponent } from "vue";
import LoadingSpinner from "./components/LoadingSpinner.vue";

// Define the main app content as an async component
const AppContent = defineAsyncComponent(() => import("@/components/AppContent.vue"));
</script>

Checkpoint: Testing the Watcher

Your app will now show a loading spinner on startup and handle redirects automatically based on the authentication state. Test closing and reopening the app after logging in to see the session persistence in action.

Step 6: Capacitor Integration

This project is already set up with Capacitor, which allows you to build and deploy your web app to mobile devices.

How to Build

To create a production build of your web app, run:

npm run build

This command compiles your Vue application and places the optimized output in the dist folder.

How to Deploy to a Device

To deploy your app to a connected Android or iOS device, you can use the following Capacitor commands:

Android:

npx cap sync android
npx cap run android

iOS:

npx cap sync ios
npx cap run ios

These commands will synchronize your web build with the native project and then launch the app on your connected device or emulator.

Quirks and Platform-Specific Changes

When building for mobile, you sometimes need to make platform-specific configuration changes to ensure everything works correctly.

Android (`AndroidManifest.xml`)

For Android, you need to allow cleartext traffic in your android/app/src/main/AndroidManifest.xml file. This is often necessary for development environments or when communicating with certain APIs that might not enforce HTTPS.

File: android/app/src/main/AndroidManifest.xml

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android">

    <application
        android:allowBackup="true"
        android:icon="@mipmap/ic_launcher"
        android:label="@string/app_name"
        android:roundIcon="@mipmap/ic_launcher_round"
        android:supportsRtl="true"
        android:theme="@style/AppTheme"
        android:usesCleartextTraffic="true"> <!-- NEW: Allow cleartext traffic -->

        <activity
            android:configChanges="orientation|keyboardHidden|keyboard|screenSize|locale|smallestScreenSize|screenLayout|uiMode"
            android:name=".MainActivity"
            android:label="@string/title_activity_main"
            android:theme="@style/AppTheme.NoActionBarLaunch"
            android:launchMode="singleTask"
            android:exported="true">

            <intent-filter>
                <action android:name="android.intent.action.MAIN" />
                <category android:name="android.intent.category.LAUNCHER" />
            </intent-filter>

        </activity>

        <provider
            android:name="androidx.core.content.FileProvider"
            android:authorities="${applicationId}.fileprovider"
            android:exported="false"
            android:grantUriPermissions="true">
            <meta-data
                android:name="android.support.FILE_PROVIDER_PATHS"
                android:resource="@xml/file_paths"></meta-data>
        </provider>
    </application>

    <!-- Permissions -->

    <uses-permission android:name="android.permission.INTERNET" />
</manifest>

iOS (`Info.plist`)

For iOS, you need to add the WKAppBoundDomains key to your ios/App/App/Info.plist file. This is crucial for allowing the web view (where your Ionic app runs) to communicate with your Clerk instance, especially for authentication redirects. You will also need to allow arbitrary loads for the Clerk domains under NSAppTransportSecurity.

File: ios/App/App/Info.plist

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>CFBundleDevelopmentRegion</key>
    <string>en</string>
    <key>CFBundleDisplayName</key>
    <string>clerk-ionic-app-template</string>
    <key>CFBundleExecutable</key>
    <string>$(EXECUTABLE_NAME)</string>
    <key>CFBundleIdentifier</key>
    <string>$(PRODUCT_BUNDLE_IDENTIFIER)</string>
    <key>CFBundleInfoDictionaryVersion</key>
    <string>6.0</string>
    <key>CFBundleName</key>
    <string>$(PRODUCT_NAME)</string>
    <key>CFBundlePackageType</key>
    <string>APPL</string>
    <key>CFBundleShortVersionString</key>
    <string>1.0</string>
    <key>CFBundleVersion</key>
    <string>1</string>
    <key>LSRequiresIPhoneOS</key>
    <true/>
    <key>UILaunchStoryboardName</key>
    <string>LaunchScreen</string>
    <key>UIMainStoryboardFile</key>
    <string>Main</string>
    <key>UIRequiredDeviceCapabilities</key>
    <array>
        <string>armv7</string>
    </array>
    <key>UISupportedInterfaceOrientations</key>
    <array>
        <string>UIInterfaceOrientationPortrait</string>
        <string>UIInterfaceOrientationLandscapeLeft</string>
        <string>UIInterfaceOrientationLandscapeRight</string>
    </array>
    <key>UISupportedInterfaceOrientations~ipad</key>
    <array>
        <string>UIInterfaceOrientationPortrait</string>
        <string>UIInterfaceOrientationPortraitUpsideDown</string>
        <string>UIInterfaceOrientationLandscapeLeft</string>
        <string>UIInterfaceOrientationLandscapeRight</string>
    </array>
    <key>UIViewControllerBasedStatusBarAppearance</key>
    <true/>
    <!-- NEW: Add WKAppBoundDomains for Clerk -->
    <key>WKAppBoundDomains</key>
    <array>
        <string>your-clerk-instance.clerk.accounts.dev</string>
    </array>
    <!-- NEW: Add NSAppTransportSecurity to allow arbitrary loads for Clerk domains -->
    <key>NSAppTransportSecurity</key>
    <dict>
        <key>NSAllowsArbitraryLoads</key>
        <true/>
    </dict>
</dict>
</plist>

Note: Replace your-clerk-instance.clerk.accounts.dev with your actual Clerk instance URL.

Conclusion

Congratulations! You have successfully added headless authentication to your Ionic Vue application with Clerk. You now have a secure and robust authentication solution that works seamlessly on the web and mobile devices.

We covered the basic functionality, including sign-in, sign-up with email verification, and session management. We also touched upon debugging common issues and configuring platform-specific settings for Capacitor. While we didn't cover features like "forgot password" or "reset password," these can be added to make your solution even more complete.

Hopefully, you found this tutorial helpful. If you did, please make sure you like and subscribe, and I'll see you next time!

Your First Complete Login System in React Native with Expo and Clerk

Aaron K Saunders — Mon, 08 Sep 2025 20:09:14 +0000

Let's build a real, production-ready login system together. We'll create custom screens, handle email verification, manage passwords, and protect our app's routes. No scary jargon, just step-by-step guidance.

Link To Source Code

Introduction

So, you're building a mobile app. Awesome! One of the first things you'll probably need is a way for users to sign up and log in. This is called authentication, and while it sounds simple, building it from scratch securely can be a real headache. There are so many things to worry about: password hashing, session tokens, security risks... it's a lot.

But don't worry! In this guide, we're going to build a complete, secure, and user-friendly authentication system for your React Native app. We'll use two amazing tools, Expo and Clerk, to make our lives way easier.

By the time we're done, you'll have a fully working app where users can:

Sign up and sign in with custom-designed screens
Verify their email address to activate their account
Reset their password if they forget it
Change their password from within the app
Access special screens only available to logged-in users

Ready? Let's dive in!

What is Clerk? (Your Security Team in a Box)

Clerk is a service that handles all the complicated user management and login stuff for you. Think of it as your expert security team, ready to go. Instead of spending weeks writing complex code, Clerk gives you simple tools to plug into your app.

What Makes Clerk So Cool?

All The Features: It has everything from simple email/password login to social logins (Google, Apple), multi-factor authentication (MFA), and more.
You Control the Look: Unlike some services that force you into ugly, pre-made login boxes, Clerk lets you build your own UI. Your app, your style.
Top-Notch Security: The Clerk team lives and breathes security. They handle all the scary stuff like data encryption and compliance, so you don't have to lose sleep over it.
Amazing for Developers: Their documentation is clear, it works great with modern tools like TypeScript, and it just makes sense.

So, Why Not Build It Myself?

Honestly, you could, but it's a ton of work and it's very easy to make a mistake that could compromise your users' data. Using Clerk saves you months of effort and helps you avoid common security pitfalls. It lets you focus on building the features that make your app unique.

What is Expo? (The Easiest Way to Build a Mobile App)

Expo is a platform and a set of tools built on top of React Native that makes building mobile apps incredibly fast and fun. It takes away many of the typical headaches associated with mobile development.

Why Do Developers Love Expo?

Super Fast Start: You can create and run a new app on your phone in just a few minutes.
No Native Code Headaches: For most apps, you won't need to open Xcode or Android Studio. You can just write JavaScript/TypeScript and Expo handles the rest.
The Expo Go App: This is a magical app for your phone. It lets you test your project instantly just by scanning a QR code.
Awesome Built-in Tools: Need to use the camera, GPS, or notifications? Expo provides simple JavaScript APIs for all of that.

Why is Expo Perfect for Us?

Expo lowers the barrier to entry. It lets us focus on building our app's features and user interface without getting bogged down in complicated native configurations.

Why Clerk + Expo? (The Perfect Partnership)

When you combine Clerk and Expo, you get a development experience that feels like a superpower. You can build a beautiful, secure, and feature-rich mobile app in a fraction of the time it would normally take.

Speed: Go from a new project to a fully authenticated app in hours, not weeks.
Security: Clerk handles the security, Expo makes development smooth.
Customization: You have full control over the user experience.
Scalability: This setup works just as well for a weekend project as it does for an app with millions of users.
Clerk Documentation: clerk.com/docs
Expo Documentation: docs.expo.dev

Let's Get Building: Project Setup

Alright, enough talk! Let's get our hands dirty and set up our project.

1. Create Your Expo App

Open your terminal and run this command. It will create a new, blank Expo project for us using TypeScript (which helps us catch errors early!).

npx create-expo-app my-clerk-app --template blank-typescript
cd my-clerk-app

2. Install the Magic Ingredients

Next, we need to install Clerk and a couple of other packages it depends on.

# This is the main Clerk library for Expo
npm install @clerk/clerk-expo

# These are helper libraries Clerk needs to work its magic
npx expo install expo-local-authentication expo-auth-session

3. Set Up Your Secret Key

Clerk needs a "Publishable Key" to connect your app to your Clerk account.

First, create a new file in the root of your project called .env.

Then, add this line to it. You'll get your key from the Clerk Dashboard after signing up for a free account.

# .env
EXPO_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_test_your_publishable_key_here

Super Important: This .env file is for your secret keys. Never commit it to a public GitHub repository!

4. A Quick Tweak to `app.json`

We just need to let Expo know we're using one of the new packages we installed. Open your app.json file and add the plugins section.

{
  "expo": {
    "plugins": [
      "expo-local-authentication"
    ]
  }
}

Integrating Clerk into Our App

Now for the most important part: wrapping our entire app with Clerk so it can manage our authentication state everywhere. We'll do this in the root layout file.

The Root Layout: The Brains of Our App

This file (app/_layout.tsx) is the main entry point for our app's navigation. It decides what the user sees based on whether they are logged in or not. It's a big file, so let's break down what it's doing.

// app/_layout.tsx
import React, { useEffect } from "react";
import { ClerkProvider, useAuth } from "@clerk/clerk-expo";
import { Stack, useRouter, useSegments } from "expo-router";
import * as SecureStore from "expo-secure-store";
import * as SplashScreen from "expo-splash-screen";
import { ActivityIndicator, View, Text } from "react-native";

// This tells the splash screen to stay visible until we're ready
SplashScreen.preventAutoHideAsync();

/**
 * We need a secure place to store the user's session token.
 * `expo-secure-store` is perfect because it encrypts the data on the device.
 * This little object tells Clerk how to save and retrieve that token.
 */
const tokenCache = {
  async getToken(key: string) {
    try {
      return SecureStore.getItemAsync(key);
    } catch (err) {
      return null;
    }
  },
  async saveToken(key: string, value: string) {
    try {
      return SecureStore.setItemAsync(key, value);
    } catch (err) {
      return;
    }
  },
};

// Let's grab our Clerk Publishable Key from the .env file
const CLERK_PUBLISHABLE_KEY = process.env.EXPO_PUBLIC_CLERK_PUBLISHABLE_KEY;

if (!CLERK_PUBLISHABLE_KEY) {
  throw new Error("Missing Clerk Publishable Key. Please add it to your .env file.");
}

// These are just some nice-to-haves from Expo Router
export { ErrorBoundary } from "expo-router";
export const unstable_settings = { initialRouteName: "(tabs)" };

/**
 * This is our main layout component. It's the "bouncer" for our app,
 * deciding who gets to go where based on their login status.
 */
const InitialLayout = () => {
  // These hooks are our main tools from Clerk and Expo Router
  const { isLoaded, isSignedIn } = useAuth(); // Clerk's hook to check auth status
  const segments = useSegments(); // Expo Router's hook to know where the user is
  const router = useRouter(); // Expo Router's hook to navigate the user

  // This effect hides the splash screen once Clerk has loaded
  useEffect(() => {
    if (isLoaded) {
      SplashScreen.hideAsync();
    }
  }, [isLoaded]);

  // This is the core logic that handles our routing!
  useEffect(() => {
    if (!isLoaded) return; // Wait until Clerk is ready

    const inTabsGroup = segments[0] === "(tabs)";

    if (isSignedIn && !inTabsGroup) {
      // If the user is signed in and not in the main app area,
      // send them to the home screen.
      router.replace("/(tabs)");
    } else if (!isSignedIn) {
      // If the user is not signed in, send them to the sign-in screen.
      router.replace("/sign-in");
    }
  }, [isLoaded, isSignedIn, segments, router]);

  // While Clerk is loading, we'll show a simple loading spinner
  if (!isLoaded) {
    return (
      <View style={{ flex: 1, justifyContent: "center", alignItems: "center" }}>
        <ActivityIndicator size="large" />
        <Text style={{ marginTop: 10 }}>Loading...</Text>
      </View>
    );
  }

  // Once loaded, we define our app's screens
  return (
    <Stack>
      <Stack.Screen name="(tabs)" options={{ headerShown: false }} />
      <Stack.Screen name="sign-in" options={{ headerShown: false }} />
      <Stack.Screen name="sign-up" options={{ headerShown: false }} />
      <Stack.Screen name="forgot-password" options={{ headerShown: false }} />
      <Stack.Screen
        name="change-password"
        options={{
          presentation: "modal",
          headerShown: true,
          title: "\"Change Password\","
          headerBackTitle: "Profile",
        }}
      />
    </Stack>
  );
};

/**
 * This is the root component of our app.
 * We wrap everything in the `ClerkProvider` so that all our components
 * can access the user's authentication state.
 */
export default function RootLayout() {
  return (
    <ClerkProvider
      publishableKey={CLERK_PUBLISHABLE_KEY!}
      tokenCache={tokenCache}
    >
      <InitialLayout />
    </ClerkProvider>
  );
}

What We Just Did:

ClerkProvider: We wrapped our entire app in this. It’s like a context provider that holds all the user information and makes it available everywhere.
Secure Token Storage: We told Clerk to use expo-secure-store, which is the safest place on a device to keep sensitive info like a login token.
Smart Routing: The InitialLayout component acts as a traffic controller. It waits for Clerk to load, then checks if the user is signed in. If they are, it sends them to the main app ((tabs)). If not, it sends them to the sign-in screen. This protects our app's private screens.

Creating Our Custom Login Screens

Now for the fun part: building the screens the user will actually see!

The Sign-In Screen

Here, we'll create a simple form for users to enter their email and password.

// app/sign-in.tsx
import React, { useState } from "react";
import {
  View,
  TextInput,
  Button,
  Text,
  StyleSheet,
  Pressable,
} from "react-native";
import { useSignIn } from "@clerk/clerk-expo";
import { Link, useRouter } from "expo-router";

export default function SignInScreen() {
  // Clerk's hook for handling the sign-in process
  const { signIn, setActive, isLoaded } = useSignIn();
  const router = useRouter();

  // State variables to hold the user's input and manage UI state
  const [emailAddress, setEmailAddress] = useState("");
  const [password, setPassword] = useState("");
  const [error, setError] = useState("");
  const [isLoading, setIsLoading] = useState(false);

  // This function is called when the user presses the "Sign In" button
  const onSignInPress = async () => {
    if (!isLoaded) return; // Wait for Clerk to be ready

    setError("");
    setIsLoading(true);

    try {
      // Start the sign-in process with Clerk
      const signInAttempt = await signIn.create({
        identifier: emailAddress,
        password,
      });

      // If sign-in is complete, we set the session as active
      if (signInAttempt.status === "complete") {
        await setActive({ session: signInAttempt.createdSessionId });
        // And navigate the user to the main part of the app
        router.replace("/(tabs)");
      } else {
        // This can happen in multi-factor auth flows
        setError("Sign-in incomplete. Please try again.");
      }
    } catch (err: any) {
      // This is our error handling. We can show a friendly message.
      const errorMessage =
        err.errors?.[0]?.longMessage || "An error occurred. Please try again.";
      setError(errorMessage);
    } finally {
      setIsLoading(false);
    }
  };

  return (
    <View style={styles.container}>
      <Text style={styles.title}>Sign In</Text>

      {error ? (
        <View style={styles.errorContainer}>
          <Text style={styles.errorText}>{error}</Text>
        </View>
      ) : null}

      <TextInput
        autoCapitalize="none"
        value={emailAddress}
        placeholder="Email..."
        onChangeText={setEmailAddress}
        style={styles.input}
        editable={!isLoading}
      />
      <TextInput
        value={password}
        placeholder="Password..."
        secureTextEntry
        onChangeText={setPassword}
        style={styles.input}
        editable={!isLoading}
      />
      <Button
        title={isLoading ? "Signing In..." : "Sign In"}
        onPress={onSignInPress}
        disabled={isLoading}
      />
      <Link href="/forgot-password" asChild>
        <Pressable style={styles.link} disabled={isLoading}>
          <Text style={styles.linkText}>Forgot Password?</Text>
        </Pressable>
      </Link>
      <Link href="/sign-up" asChild>
        <Pressable style={styles.link} disabled={isLoading}>
          <Text style={styles.linkText}>Don't have an account? Sign Up</Text>
        </Pressable>
      </Link>
    </View>
  );
}

// Add some basic styling to make it look nice
const styles = StyleSheet.create({
  container: {
    flex: 1,
    justifyContent: "center",
    padding: 20,
  },
  title: "{"
    fontSize: 28,
    fontWeight: "bold",
    textAlign: "center",
    marginBottom: 30,
    color: "#333",
  },
  input: {
    borderWidth: 1,
    borderColor: "#ccc",
    padding: 12,
    marginBottom: 15,
    borderRadius: 5,
    fontSize: 16,
  },
  errorContainer: {
    backgroundColor: "#ffebee",
    borderColor: "#f44336",
    borderWidth: 1,
    borderRadius: 5,
    padding: 12,
    marginBottom: 15,
  },
  errorText: {
    color: "#f44336",
    fontSize: 14,
    textAlign: "center",
  },
  link: {
    marginTop: 15,
    alignItems: "center",
  },
  linkText: {
    color: "#007AFF",
    fontSize: 16,
  },
});

The Sign-Up Screen with Email Verification

Signing up is a two-step process: first, the user creates an account. Second, they verify their email with a code we send them. This is a great security practice.

// app/sign-up.tsx
import React, { useState } from "react";
import {
  View,
  TextInput,
  Button,
  Text,
  StyleSheet,
  Pressable,
} from "react-native";
import { useSignUp } from "@clerk/clerk-expo";
import { Link, useRouter } from "expo-router";

export default function SignUpScreen() {
  const { isLoaded, signUp, setActive } = useSignUp();
  const router = useRouter();

  // State for user inputs
  const [firstName, setFirstName] = useState("");
  const [lastName, setLastName] = useState("");
  const [emailAddress, setEmailAddress] = useState("");
  const [password, setPassword] = useState("");

  // State for the verification flow
  const [pendingVerification, setPendingVerification] = useState(false);
  const [code, setCode] = useState("");
  const [error, setError] = useState("");
  const [isLoading, setIsLoading] = useState(false);

  // Step 1: Create the user account
  const onSignUpPress = async () => {
    if (!isLoaded) return;

    setError("");
    setIsLoading(true);

    try {
      // Create the user with Clerk
      await signUp.create({
        emailAddress,
        password,
        firstName,
        lastName,
      });

      // Send the verification email
      await signUp.prepareEmailAddressVerification({ strategy: "email_code" });

      // Move to the verification screen
      setPendingVerification(true);
    } catch (err: any) {
      const errorMessage =
        err.errors?.[0]?.longMessage || "An error occurred. Please try again.";
      setError(errorMessage);
    } finally {
      setIsLoading(false);
    }
  };

  // Step 2: Verify the email code
  const onPressVerify = async () => {
    if (!isLoaded) return;

    setError("");
    setIsLoading(true);

    try {
      // Attempt to verify the code the user entered
      const signUpAttempt = await signUp.attemptEmailAddressVerification({
        code,
      });

      if (signUpAttempt.status === "complete") {
        // If successful, set the session active and navigate
        await setActive({ session: signUpAttempt.createdSessionId });
        router.replace("/(tabs)");
      } else {
        setError("Verification incomplete. Please try again.");
      }
    } catch (err: any) {
      const errorMessage =
        err.errors?.[0]?.longMessage || "Invalid verification code.";
      setError(errorMessage);
    } finally {
      setIsLoading(false);
    }
  };

  return (
    <View style={styles.container}>
      {!pendingVerification ? (
        // Show the sign-up form
        <>
          <Text style={styles.title}>Sign Up</Text>

          {error ? (
            <View style={styles.errorContainer}>
              <Text style={styles.errorText}>{error}</Text>
            </View>
          ) : null}

          <TextInput
            value={firstName}
            placeholder="First Name..."
            onChangeText={setFirstName}
            style={styles.input}
            editable={!isLoading}
          />
          <TextInput
            value={lastName}
            placeholder="Last Name..."
            onChangeText={setLastName}
            style={styles.input}
            editable={!isLoading}
          />
          <TextInput
            autoCapitalize="none"
            value={emailAddress}
            placeholder="Email..."
            onChangeText={setEmailAddress}
            style={styles.input}
            editable={!isLoading}
          />
          <TextInput
            value={password}
            placeholder="Password..."
            secureTextEntry
            onChangeText={setPassword}
            style={styles.input}
            editable={!isLoading}
          />
          <Button
            title={isLoading ? "Creating Account..." : "Sign Up"}
            onPress={onSignUpPress}
            disabled={isLoading}
          />
          <Link href="/sign-in" asChild>
            <Pressable style={styles.link} disabled={isLoading}>
              <Text style={styles.linkText}>Have an account? Sign In</Text>
            </Pressable>
          </Link>
        </>
      ) : (
        // Show the email verification form
        <>
          <Text style={styles.title}>Verify Your Email</Text>
          <Text style={styles.subtitle}>
            Enter the verification code sent to {emailAddress}
          </Text>

          {error ? (
            <View style={styles.errorContainer}>
              <Text style={styles.errorText}>{error}</Text>
            </View>
          ) : null}

          <TextInput
            value={code}
            placeholder="Verification Code..."
            onChangeText={setCode}
            style={styles.input}
            editable={!isLoading}
            keyboardType="number-pad"
          />
          <Button
            title={isLoading ? "Verifying..." : "Verify Email"}
            onPress={onPressVerify}
            disabled={isLoading}
          />
        </>
      )}
    </View>
  );
}

// Use similar styles as the sign-in screen...
const styles = StyleSheet.create({
    container: { flex: 1, justifyContent: 'center', padding: 20 },
    title: "{ fontSize: 28, fontWeight: 'bold', textAlign: 'center', marginBottom: 20 },"
    subtitle: "{ textAlign: 'center', marginBottom: 20, fontSize: 16, color: '#666' },"
    input: { borderWidth: 1, borderColor: '#ccc', padding: 12, marginBottom: 15, borderRadius: 5, fontSize: 16 },
    errorContainer: { backgroundColor: '#ffebee', padding: 12, borderRadius: 5, marginBottom: 15 },
    errorText: { color: '#f44336', textAlign: 'center' },
    link: { marginTop: 15, alignItems: 'center' },
    linkText: { color: '#007AFF', fontSize: 16 }
});

Change Password Modal

This screen will allow a logged-in user to change their password. We'll present it as a modal (a screen that slides up from the bottom).

// app/change-password.tsx
import React, { useState } from "react";
import { View, TextInput, Button, Text, StyleSheet, ScrollView } from "react-native";
import { useUser } from "@clerk/clerk-expo";
import { useRouter } from "expo-router";

export default function ChangePasswordScreen() {
  // The `useUser` hook gives us access to the currently logged-in user
  const { user } = useUser();
  const router = useRouter();

  const [currentPassword, setCurrentPassword] = useState("");
  const [newPassword, setNewPassword] = useState("");
  const [confirmPassword, setConfirmPassword] = useState("");
  const [error, setError] = useState("");
  const [isLoading, setIsLoading] = useState(false);

  const onChangePasswordPress = async () => {
    if (!user) return;

    // Basic client-side validation
    if (newPassword !== confirmPassword) {
      setError("New passwords do not match.");
      return;
    }
    if (newPassword.length < 8) {
        setError("New password must be at least 8 characters long.");
        return;
    }

    setError("");
    setIsLoading(true);

    try {
      // Clerk's `user` object has a handy method for this!
      await user.updatePassword({
        currentPassword,
        newPassword,
      });

      // If successful, close the modal
      router.back();
    } catch (err: any) {
      const errorMessage =
        err.errors?.[0]?.longMessage || "An error occurred. Please try again.";
      setError(errorMessage);
    } finally {
      setIsLoading(false);
    }
  };

  return (
    <ScrollView contentContainerStyle={styles.container}>
      <Text style={styles.title}>Change Password</Text>

       {error ? (
        <View style={styles.errorContainer}>
          <Text style={styles.errorText}>{error}</Text>
        </View>
      ) : null}

      <TextInput
        value={currentPassword}
        placeholder="Current password..."
        secureTextEntry
        onChangeText={setCurrentPassword}
        style={styles.input}
      />
      <TextInput
        value={newPassword}
        placeholder="New password..."
        secureTextEntry
        onChangeText={setNewPassword}
        style={styles.input}
      />
      <TextInput
        value={confirmPassword}
        placeholder="Confirm new password..."
        secureTextEntry
        onChangeText={setConfirmPassword}
        style={styles.input}
      />

      <Button
        title={isLoading ? "Updating..." : "Update Password"}
        onPress={onChangePasswordPress}
        disabled={isLoading}
      />
    </ScrollView>
  );
}

// Use similar styles...
const styles = StyleSheet.create({
    container: { flexGrow: 1, justifyContent: 'center', padding: 20 },
    title: "{ fontSize: 28, fontWeight: 'bold', textAlign: 'center', marginBottom: 20 },"
    input: { borderWidth: 1, borderColor: '#ccc', padding: 12, marginBottom: 15, borderRadius: 5, fontSize: 16 },
    errorContainer: { backgroundColor: '#ffebee', padding: 12, borderRadius: 5, marginBottom: 15 },
    errorText: { color: '#f44336', textAlign: 'center' },
});

Building the Protected Part of Our App

Now that users can log in, let's create the screens they see after logging in. Our _layout.tsx file already protects this area.

A Welcoming Home Screen

This will be the first thing a user sees after logging in.

// app/(tabs)/index.tsx
import React from "react";
import { StyleSheet, Text, View, Button } from "react-native";
import { useUser, useClerk } from "@clerk/clerk-expo";

export default function HomeScreen() {
  // `useUser` gives us all the details about the logged-in user
  const { user } = useUser();
  const { signOut } = useClerk();

  return (
    <View style={styles.container}>
      <Text style={styles.title}>Welcome Back!</Text>
      <Text style={styles.userInfo}>
        Hello, {user?.firstName || "User"}!
      </Text>
      <Text style={styles.userEmail}>
        Your email is: {user?.primaryEmailAddress?.emailAddress}
      </Text>
      <View style={styles.separator} />
      <Button title="Sign Out" onPress={() => signOut()} />
    </View>
  );
}

const styles = StyleSheet.create({
  container: {
    flex: 1,
    alignItems: "center",
    justifyContent: "center",
    padding: 20,
  },
  title: "{"
    fontSize: 24,
    fontWeight: "bold",
    marginBottom: 20,
  },
  userInfo: {
    fontSize: 18,
    marginBottom: 10,
  },
  userEmail: {
    fontSize: 16,
    color: "#666",
  },
  separator: {
    marginVertical: 30,
    height: 1,
    width: "80%",
    backgroundColor: "#eee",
  },
});

A Detailed Profile Screen

Here, we can display more user information and provide a link to our "Change Password" modal.

// app/(tabs)/two.tsx (or you can rename it to profile.tsx)
import React from "react";
import { StyleSheet, Text, View, ScrollView, Pressable } from "react-native";
import { useUser, useClerk } from "@clerk/clerk-expo";
import { useRouter } from "expo-router";

export default function ProfileScreen() {
  const { user } = useUser();
  const { signOut } = useClerk();
  const router = useRouter();

  return (
    <ScrollView contentContainerStyle={styles.container}>
      <Text style={styles.title}>Your Profile</Text>

      <View style={styles.section}>
        <Text style={styles.sectionTitle}>Personal Information</Text>
        <Text>Full Name: {user?.fullName || "N/A"}</Text>
        <Text>Email: {user?.primaryEmailAddress?.emailAddress || "N/A"}</Text>
        <Text>Account Created: {user?.createdAt?.toLocaleDateString() || "N/A"}</Text>
      </View>

      <View style={styles.section}>
        <Text style={styles.sectionTitle}>Actions</Text>

        <Pressable
          style={styles.actionButton}
          onPress={() => router.push("/change-password")}
        >
          <Text style={styles.actionButtonText}>Change Password</Text>
        </Pressable>

        <Pressable
          style={[styles.actionButton, styles.signOutButton]}
          onPress={() => signOut()}
        >
          <Text style={styles.actionButtonText}>Sign Out</Text>
        </Pressable>
      </View>
    </ScrollView>
  );
}

const styles = StyleSheet.create({
    container: {
        flexGrow: 1,
        padding: 20,
        backgroundColor: '#f5f5f5'
    },
    title: "{"
        fontSize: 28,
        fontWeight: "bold",
        marginBottom: 30,
        textAlign: "center",
    },
    section: {
        backgroundColor: 'white',
        padding: 20,
        borderRadius: 10,
        marginBottom: 20,
    },
    sectionTitle: {
        fontSize: 18,
        fontWeight: '600',
        marginBottom: 10
    },
    actionButton: {
        backgroundColor: "#007AFF",
        paddingVertical: 12,
        borderRadius: 8,
        alignItems: "center",
        marginBottom: 15,
    },
    signOutButton: {
        backgroundColor: "#f44336",
    },
    actionButtonText: {
        color: "white",
        fontSize: 16,
        fontWeight: "600",
    },
});

Testing Your App

Now's the time to try everything out! Run your app with npx expo start and test all the scenarios:

Sign Up: Create a new account and verify your email.
Sign Out: Log out of the account.
Sign In: Log back in with the credentials you just created.
Wrong Password: Try logging in with the wrong password to see the error message.
Forgot Password: Use the forgot password flow.
Change Password: Go to the profile screen and change your password.

We Did It! What's Next?

Congratulations! You've just built a complete, secure, and professional authentication system in a React Native app. That's a huge accomplishment!

You now have a solid foundation to build the rest of your app on. Clerk and Expo handled all the heavy lifting, allowing us to focus on creating a great user experience with custom screens and smooth navigation.

Where to Go From Here?

This is just the beginning. You could easily add more features like:

Social Logins: Let users sign in with Google, Apple, or GitHub.
Biometrics: Add Face ID or Touch ID for super-quick logins.
User Profiles: Allow users to update their first name, last name, or profile picture.

Key Takeaways

Don't reinvent the wheel: Services like Clerk save you massive amounts of time and prevent security headaches.
User experience is key: Always provide clear feedback, loading states, and helpful error messages.
Expo is your friend: It makes React Native development faster and more enjoyable.

The complete source code for a project like this is often available on GitHub. You can use it as a reference as you continue to build out your own amazing application.

Need More Help or Want to Learn More?

If you enjoyed this tutorial, that's awesome! I love helping developers build cool things. I share more in-depth tutorials and tips on React Native and mobile development on my YouTube channel.

My Services

If you or your team need a little extra help:

Technical Guidance: I can help you with app architecture, performance, and making the right tech choices.
Full App Development: I can help bring your app idea to life, from concept to App Store launch.
Code Reviews: I can review your existing codebase to ensure it's secure, scalable, and follows best practices.

Feel free to connect with me on LinkedIn or email info@clearlyinnovative.com.

Happy coding! Now go and build something amazing with your new authentication powers!

aaronksaunders / expo-clerk-auth

Clerk Authentication Demo - Expo React Native App

A complete React Native application demonstrating headless Clerk authentication implementation with custom UI components, email verification, and comprehensive error handling.

🚀 Features

🔐 Authentication Features

Custom Sign-In Screen - Email/password authentication with error handling
Custom Sign-Up Screen - User registration with first/last name fields
Email Verification - Complete verification flow with code input
Forgot Password - Password reset via email with confirmation flow
Change Password - Secure password update for authenticated users
Secure Token Storage - Uses Expo SecureStore for token persistence
Automatic Routing - Smart navigation based on authentication state
Error Handling - User-friendly error messages for all authentication flows

📱 User Interface

Home Screen - Personalized welcome with user information
Profile Screen - Detailed user account information and status
Loading States - Visual feedback during authentication processes
Responsive Design - Clean, modern UI with proper styling
Navigation - Tab-based navigation…

View on GitHub

The True Cost of an AI Engineer: A Deep Dive into Replit Agent vs. Lovable.dev

Aaron K Saunders — Mon, 08 Sep 2025 14:49:14 +0000

The promise of AI software engineers is no longer a distant dream; it's a practical reality. Two of the most compelling players in this space are Replit Agent and Lovable. Both can take a high-level prompt and build functional applications, but they represent two fundamentally different philosophies.

Hiring one is not just about features—it's a strategic decision that impacts your workflow, flexibility, and most importantly, your monthly bill.

So, which AI engineer should you hire for your next commercial project? Let's break it down.

The Core Philosophies: Ecosystem vs. Specialist

Before we talk numbers, we have to understand the core difference in their approach.

Replit Agent: The All-in-One Ecosystem

Think of Replit as a fully-managed, high-tech workshop. When you subscribe to their Core plan, you don't just get an AI engineer; you get the entire workshop. This includes the cloud-based IDE, integrated hosting, databases, object storage, and the AI Agent who is a native expert on that specific environment. It’s a bundled, all-in-one package designed for simplicity and speed within a single, unified platform.

Lovable: The Specialist for Your Custom Stack

Lovable operates like a world-class freelance specialist you hire to work with your existing tools. It integrates into your preferred workflow (like VS Code and GitHub) and is an expert in the modern web stack (React, Next.js, Vercel, Supabase). You aren't buying into an ecosystem; you're hiring a focused expert to build components within the stack you already know and control.

The Head-to-Head Cost Breakdown: A Commercial App

Let's get practical. We need to build a commercial web application with the following requirements:

A production-ready database with daily backups.
Object storage for user file uploads.
Social media authentication (e.g., "Sign in with Google").
Transactional email for signups and notifications.
Commercial-use hosting.

Here’s how the initial monthly costs stack up.

Table 1: Initial Monthly Cost Breakdown (Commercial)

Component	The Replit Ecosystem	The Lovable + Custom Stack	Notes
AI Software Engineer	Included in Core Plan	~$29 / month (Lovable Starter Plan)	Replit's Agent is part of the platform. Lovable's cost is for AI work credits.
Database (PostgreSQL)	Included in Core Plan	~$25 / month (Supabase Pro Plan)	Supabase Pro is needed for daily backups and to avoid inactivity pauses on a commercial app.
Object Storage	Included in Core Plan	Included in Supabase Pro Plan	Supabase Pro includes a generous starting amount of storage and bandwidth.
Social Authentication	Manual Implementation	Included in Supabase Pro Plan	Key Difference: On Replit, you must code the auth logic yourself. Supabase provides a fully managed service for Google, GitHub, etc., saving significant development time.
Transactional Email	$0 (e.g., Resend Free Tier)	$0 (e.g., Resend Free Tier)	Both stacks require a third-party email provider. Free tiers are often sufficient at launch.
Hosting	Included in Core Plan	~$20 / month (Vercel Pro Plan)	Vercel's Pro plan is required for commercial use.
Platform / IDE	~$25 / month (Replit Core Plan)	$0 (VS Code is free)	The Replit cost covers the entire integrated development and cloud environment.
Total Starting Cost	~$25 / month	~$74 / month	For a commercial launch, the all-in-one Replit model presents a significantly lower initial monthly cost.

At first glance, Replit is the clear winner on price. But the story changes when you look at the value and scaling strategy.

Table 2: Scaling and Value Proposition (Commercial)

Aspect	The Replit Ecosystem	The Lovable + Custom Stack
Cost Model	All-in-One Subscription. Highly cost-effective at the start. One bill covers the platform and infrastructure.	Modular & Multi-Vendor. Higher initial cost, but you get best-in-class, specialized services for each component.
Developer Experience	High Simplicity. The entire stack is pre-integrated. However, features like social auth must be built and maintained manually by the developer (or the AI agent).	High Velocity. Services like Supabase Auth are managed for you, drastically reducing development and maintenance time for complex features. The trade-off is managing multiple services.
Flexibility & Control	Moderate. You operate within the Replit ecosystem. Scaling means buying more "Compute Units" or upgrading your Replit plan.	High. You have granular control over each part of your stack. You can swap out any component and are not tied to a single platform.
Scaling Path	As your app grows, you will purchase more Compute Units from Replit. If your email volume grows, you will upgrade your third-party email plan.	Costs scale per-service. You upgrade Vercel, Supabase, Lovable, and your email provider independently as each one meets its limit. This is efficient if only one part of your app is resource-intensive.

Key Strategic Questions Answered

1. Can I run my commercial MVP on a free tier to save money?

While technically possible, it is strongly not recommended. For services like Supabase, the free tier has critical limitations for a commercial product, including inactivity pausing (which ruins user experience) and no database backups (which is a massive business risk). The ~$25/month for a Pro plan should be considered a non-negotiable insurance policy for your business.

2. Can I find a cheaper database than Supabase Pro?

Yes. Services like Neon (~$19/mo) or Render (~$7/mo) offer excellent, cheaper Postgres databases. However, they are just databases. You lose the powerful, time-saving features of Supabase like managed Auth and Storage, forcing you to build and maintain those solutions yourself. The small monthly saving often comes at a much higher cost in development time.

Conclusion: How to Choose Your AI Engineer

The decision comes down to a simple trade-off: simplicity vs. flexibility.

Choose Replit Agent if:

You want the lowest possible starting cost for a commercial project.
You value the simplicity of a single, predictable bill and a fully integrated platform.
You want to minimize time spent on infrastructure management and are happy to work within one powerful ecosystem.

Choose Lovable if:

You value flexibility and want to use a specific, best-in-class stack (Vercel, Supabase, etc.).
You want granular control to scale each part of your infrastructure independently.
You believe the time saved by using managed services like Supabase Auth is worth the higher initial monthly cost.

There is no wrong answer, only what's right for your project, your team, and your budget.

Need Help Navigating This New Landscape?

Choosing the right AI engineer and tech stack is a major strategic decision with long-term implications for your product's scalability, cost, and development speed.

If you're looking for a second opinion or need help architecting your project to best leverage these powerful new tools, I offer advisory services to help teams make the right choice.

Feel free to reach out to discuss your project.

LinkedIn: Aaron K Saunders
Email: info@clearlyinnovative.com
YouTube https://www.youtube.com/@AaronSaundersCI

Forem: Aaron K Saunders

A Complete Guide to Building a Payment System with Payload CMS and Lemon Squeezy

The Architectural Shift: Why Next.js API Routes?

The Full Video Tutorial

What We'll Cover in the Video

Don't Skip the Debugging Chapter!

Wrapping Up

📚 USEFUL RESOURCES

Source Code

aaronksaunders / payload-lemon-1

Payload CMS + LemonSqueezy Integration Example

Payload Lemon - E-commerce with Payload CMS & Lemon Squeezy

🚀 Features

📋 Prerequisites

🛠️ Installation

1. Clone and Install Dependencies

2. Environment Setup

Simplifying Auth and Role-Based Routing with Stack.Protected in Expo Router

Why Stack.Protected Is a Game Changer

The Power of Declarative Protection

Example Directory Structure

Why Name Files index.tsx in Segments?

Why Segment Layout Redirects Are Still Flawed

Role-Based Route Protection with Stack.Protected

Final Thoughts

I Asked an AI to Build a Mobile App. It Chose Ionic Capacitor and Surprised Me

Phase 1: The Initial Prompt and Impressive Scaffolding

Where the AI Became a True Co-Pilot: Conversational Debugging

The Surprise Twist: The AI's Job Was Done, But Mine Wasn't

My Manual "Last Mile" with Capacitor

Final Thoughts: An Accelerator, Not an Automator

Can AI Really Build a Full-Stack Mobile App? A Brutally Honest Test of Bolt.new V2

TanStack Start to Mobile: Building Robust Apps with Capacitor

Introduction: Why TanStack Start for Your Next Mobile Adventure?

The Core Idea: One Start App + Mobile Client Using API Routes

What We're Building

Step 1: Project Setup - Initialize TanStack Start

Initial package.json Notes

Step 2: Editing Existing Route Files

Step 3: Updating the Root Route for Mobile Support

Step 4: Configure Vite for Mobile Development

Step 5: Adding Capacitor for Mobile Development

Step 6: Adding Mobile Development Scripts

Development Workflow: Testing Your Mobile App

Troubleshooting: Why server functions don't work in the mobile app

Key Takeaways

Conclusion

aaronksaunders / tanstack-capacitor-mobile-1

tanstackStart with Ionic Capacitor for Fullstack Mobile Development, basic template

Understanding the TanStack Start + Capacitor Mobile App Project

Getting Started with the TasnstackStart Project

Building For Production

Testing

Styling

Routing

How to Instantly Unblock Your AI Dev Tool: The GitHub Issues Prompt

ChatGPT Mobile App Tutorial: Vue, Convex & Capacitor (Step-by-Step)

40 years in tech… and I feel like I’m just getting started. 😉

Run Payload Jobs on Vercel (Serverless) — Step‑by‑Step Migration

The "Why": Serverless vs. Long-Running Processes

The Solution: How to Run Scheduled Jobs on Vercel

Step 1: Disable autoRun in Payload Config

Step 2: Create a Secure API Endpoint to Trigger the Job

Step 3: Create a Secure API Endpoint to Trigger the Job

Step 4: Configure environment variables

Step 5: Configure Vercel Cron Jobs

Test Locally

Vercel deployment checklist

Summary

Reference Links

Official Documentation

Related Resources

Building a Mobile App with Ionic, Vue, and Clerk

Building a Headless Authentication App with Ionic, Vue, and Clerk

Demo of the Final Application

Create Account Flow

Profile Page Features

Session Persistence

Sign Out and Re-Login

Starting Point: The clerk-tutorial-start Project

Why `Stack.Protected` Is a Game Changer

Why Name Files `index.tsx` in Segments?

Role-Based Route Protection with `Stack.Protected`

Initial `package.json` Notes

Step 1: Disable `autoRun` in Payload Config

Starting Point: The `clerk-tutorial-start` Project

Step 2: Integrate Clerk Plugin in `main.ts`

Step 3: Implement Login/Logout with `useAuth.ts` Composable

The Sign-Up Logic in `useAuth.ts`

The Verification Logic in `useAuth.ts`

Updating the Sign-Up View (`SignUpView.vue`)

Step 5: Handle Auth State with `Suspense` and Watchers

Android (`AndroidManifest.xml`)

iOS (`Info.plist`)

4. A Quick Tweak to `app.json`