{"id":31263842,"url":"https://github.com/aaronksaunders/ionic-vue-clerk-tutorial-start","last_synced_at":"2025-09-23T12:07:50.821Z","repository":{"id":314288264,"uuid":"1054553392","full_name":"aaronksaunders/ionic-vue-clerk-tutorial-start","owner":"aaronksaunders","description":"Clerk in Vue.js \u0026 Capacitor for mobile app auth demonstration","archived":false,"fork":false,"pushed_at":"2025-09-20T19:30:09.000Z","size":500,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-09-20T21:21:16.557Z","etag":null,"topics":["capacitor","capacitorjs","clerk","clerk-auth","ionic-framework","vue","vuejs"],"latest_commit_sha":null,"homepage":"https://youtu.be/EBGPINHP_xs","language":"Vue","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/aaronksaunders.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-11T02:28:44.000Z","updated_at":"2025-09-20T19:30:13.000Z","dependencies_parsed_at":"2025-09-11T17:11:11.202Z","dependency_job_id":"d68bf912-f1d4-4962-a839-04f0aed3ab1f","html_url":"https://github.com/aaronksaunders/ionic-vue-clerk-tutorial-start","commit_stats":null,"previous_names":["aaronksaunders/ionic-vue-clerk-tutorial-start"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/aaronksaunders/ionic-vue-clerk-tutorial-start","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aaronksaunders%2Fionic-vue-clerk-tutorial-start","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aaronksaunders%2Fionic-vue-clerk-tutorial-start/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aaronksaunders%2Fionic-vue-clerk-tutorial-start/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aaronksaunders%2Fionic-vue-clerk-tutorial-start/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/aaronksaunders","download_url":"https://codeload.github.com/aaronksaunders/ionic-vue-clerk-tutorial-start/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aaronksaunders%2Fionic-vue-clerk-tutorial-start/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":276572123,"owners_count":25665909,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-23T02:00:09.130Z","response_time":73,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["capacitor","capacitorjs","clerk","clerk-auth","ionic-framework","vue","vuejs"],"created_at":"2025-09-23T12:07:45.304Z","updated_at":"2025-09-23T12:07:50.812Z","avatar_url":"https://github.com/aaronksaunders.png","language":"Vue","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Ionic Vue Clerk Tutorial - Starting Point\n\n[See Video Here](https://youtu.be/EBGPINHP_xs)\n\nA clean Ionic Vue application designed as a **tutorial starting point** for learning how to integrate Clerk authentication. This app provides a basic foundation with mock authentication that you'll replace with real Clerk functionality during the tutorial.\n\n\u003e **🚀 Quick Start**: This is the `main` branch - the tutorial starting point. For the completed implementation with real Clerk integration, check out the `finished-code` branch.\n\n## 📋 Current Code State\n\nThis branch contains **intentionally basic code** designed for learning:\n\n### **What's Included (Mock Implementation)**\n- **Basic UI Components** - Login, signup, and profile views with Ionic components\n- **Mock Authentication** - Simple functions that simulate auth behavior\n- **Basic Routing** - Simple router setup without authentication guards\n- **Tutorial Structure** - Clean, minimal codebase ready for enhancement\n- **Basic Documentation** - Simple comments explaining the tutorial purpose\n\n### **What's NOT Included (Tutorial Goals)**\n- **Real Clerk Integration** - You'll add this during the tutorial\n- **Authentication Guards** - You'll implement route protection\n- **Session Management** - You'll add real session handling\n- **Error Handling** - You'll implement comprehensive error handling\n- **Loading States** - You'll add Suspense and loading components\n- **JSDoc Documentation** - You'll add comprehensive documentation\n- **TypeScript Type Safety** - You'll improve type definitions\n\n## 🌿 Branch Structure\n\nThis repository contains two main branches with different levels of completion:\n\n### **`main` Branch - Tutorial Starting Point**\nThe main branch contains the **tutorial starting point** with:\n- **Mock Authentication** - Simulated authentication for learning purposes\n- **Basic UI Components** - Login, signup, and profile views\n- **Tutorial Structure** - Clean foundation for following the tutorial\n- **Mock Composables** - Simple authentication functions to be replaced\n- **Basic Documentation** - Tutorial-focused README and comments\n\n**Use this branch when:**\n- Starting the tutorial from scratch\n- Learning Clerk integration step-by-step\n- Following the tutorial guide\n\n### **`finished-code` Branch - Completed Implementation**\nThe finished-code branch contains the **completed tutorial** with:\n- **Real Clerk Integration** - Production-ready authentication service\n- **Comprehensive JSDoc** - Every function and component fully documented\n- **TypeScript Type Safety** - Zero `any` types, full type coverage\n- **Mobile Optimization** - Capacitor-ready for iOS and Android\n- **Suspense Support** - Async component loading with proper fallback states\n- **Session Management** - Real session refresh and state management\n- **Error Handling** - Proper error handling throughout the application\n\n**Use this branch when:**\n- You want to see the final result\n- You need a reference implementation\n- You want to skip the tutorial and use the completed code\n\n### **Switching Between Branches**\n\n```bash\n# Switch to tutorial starting point\ngit checkout main\n\n# Switch to completed implementation\ngit checkout finished-code\n\n# See what's different between branches\ngit diff main..finished-code\n```\n\n### **Getting Started**\n\n**For Tutorial Learning:**\n1. Start on the `main` branch (you're already here!)\n2. Follow the tutorial step-by-step\n3. Replace mock functions with real Clerk integration\n4. Add comprehensive documentation and error handling\n\n**For Production Use:**\n1. Switch to the `finished-code` branch\n2. Set up your Clerk publishable key in `.env`\n3. Run `npm install` and `npm run dev`\n4. You have a production-ready app with full Clerk integration\n\n**For Reference:**\n- Use `finished-code` branch as a reference while following the tutorial\n- Compare your progress with the completed implementation\n- See examples of proper JSDoc documentation and TypeScript usage\n\n### **Branch History**\n\nThe repository was structured this way to support both tutorial learning and production use:\n\n1. **Original Development**: The tutorial was completed on the main branch\n2. **Branch Creation**: A `finished-code` branch was created to preserve the completed work\n3. **Main Reset**: The main branch was reset to the tutorial starting point\n4. **Current State**: \n   - `main` = Clean tutorial starting point\n   - `finished-code` = Completed implementation with all improvements\n\nThis allows new users to start fresh with the tutorial while keeping the completed work available for reference or immediate use.\n\n## 🚀 Current Features (Tutorial Starting Point)\n\n### **Mock Authentication System**\n- **Login View** - Basic sign-in form (no real authentication yet)\n- **Sign Up View** - Basic registration form (no real validation yet)\n- **Profile View** - Basic profile display (shows mock user data)\n- **Auth Actions** - Basic buttons for testing (no real functionality yet)\n- **No Route Protection** - All routes are currently accessible\n\n### **Basic Technical Setup**\n- **Vue 3** - Modern reactive framework with Composition API\n- **Ionic Vue** - Mobile-first UI framework with native components\n- **TypeScript** - Basic type setup (will be enhanced during tutorial)\n- **Vite** - Fast build tool and development server\n- **Mock Composables** - Simple functions that return mock data\n\n### **Tutorial-Ready Structure**\n- **Clean Codebase** - Minimal, easy-to-understand code\n- **Clear Comments** - Basic documentation explaining tutorial purpose\n- **Modular Design** - Components and composables ready for enhancement\n- **No Dependencies** - No external auth libraries (you'll add Clerk)\n\n## 🛠️ Tech Stack\n\n- **Vue 3** - Progressive JavaScript framework\n- **Ionic Vue** - Mobile-first UI framework\n- **TypeScript** - Type-safe JavaScript development\n- **Vite** - Fast build tool and development server\n\n## 📱 Platforms\n\n- **Web** - Modern browsers (Chrome, Firefox, Safari, Edge)\n- **iOS** - Native iOS app via Capacitor (iOS 13+)\n- **Android** - Native Android app via Capacitor (API 21+)\n\n## 🚀 Quick Start\n\n### Prerequisites\n\n- **Node.js** 18+ \n- **npm** or **yarn**\n\n### Installation\n\n1. **Install dependencies**\n   ```bash\n   npm install\n   ```\n\n2. **Set up environment variables (for Clerk integration)**\n   ```bash\n   cp .env.example .env\n   # Edit .env with your Clerk publishable key when ready to integrate\n   ```\n\n3. **Run the development server**\n   ```bash\n   npm run dev\n   ```\n\n4. **Open in browser**\n   - Navigate to `http://localhost:3000`\n   - Test the mock authentication flow\n\n## 🏗️ Project Architecture\n\n### **Current Project Structure (Tutorial Starting Point)**\n\n```\nsrc/\n├── main.ts                    # Basic app entry point (no Clerk setup yet)\n├── App.vue                    # Simple root component (no auth logic yet)\n├── components/\n│   ├── AuthActions.vue        # Basic buttons (no real functionality)\n│   └── LoadingSpinner.vue     # Basic loading component\n├── composables/\n│   ├── useAuth.ts             # Mock authentication functions\n│   └── useMobileAuth.ts       # Mock mobile features\n├── lib/\n│   ├── auth.ts                # Simple auth exports\n│   └── README.md              # Auth library documentation\n├── views/\n│   ├── LoginView.vue          # Basic login form (no real auth)\n│   ├── SignUpView.vue         # Basic signup form (no real validation)\n│   └── ProfileView.vue        # Basic profile display (mock data)\n├── router/\n│   └── auth.ts                # Basic router (no auth guards)\n└── theme/\n    └── variables.css          # Ionic theme variables\n```\n\n### **What Each File Contains (Current State)**\n\n- **`main.ts`** - Basic Vue app setup, no Clerk integration\n- **`App.vue`** - Simple router outlet, no authentication logic\n- **`useAuth.ts`** - Mock functions that always return false/success\n- **`useMobileAuth.ts`** - Mock mobile detection functions\n- **Views** - Basic forms with no real validation or authentication\n- **Router** - Simple routing without authentication guards\n- **Components** - Basic UI components with placeholder functionality\n\n### Mock Authentication Flow\n\n```mermaid\ngraph TD\n    A[App Starts] --\u003e B[Check Auth State]\n    B --\u003e|Not Authenticated| C[LoginView]\n    B --\u003e|Authenticated| D[ProfileView]\n    \n    C --\u003e|Sign In| E[Mock useAuth.signIn]\n    C --\u003e|Sign Up| F[SignUpView]\n    F --\u003e|Create Account| G[Mock useAuth.signUp]\n    G --\u003e|Email Verification| H[Enter Verification Code]\n    H --\u003e|Verify Code| I[Mock useAuth.verifyEmailCode]\n    \n    E --\u003e|Success| J[Update Mock State]\n    I --\u003e|Success| J\n    J --\u003e|State Update| D\n    \n    D --\u003e|Sign Out| K[Mock useAuth.signOut]\n    K --\u003e|State Update| C\n```\n\n## 🧪 Testing the Current Mock Implementation\n\n### **What You Can Test Now (Mock Behavior)**\n\n1. **Basic Navigation**\n   - Navigate between `/login`, `/signup`, and `/profile`\n   - All routes are currently accessible (no auth guards yet)\n\n2. **Form Interactions**\n   - Fill out login and signup forms\n   - Click buttons (they won't actually authenticate yet)\n   - See basic form validation (client-side only)\n\n3. **UI Components**\n   - Test Ionic components and styling\n   - See responsive design on different screen sizes\n   - Test basic user interactions\n\n### **What You CAN'T Test Yet (Tutorial Goals)**\n\n1. **Real Authentication** - Forms don't actually sign users in/out\n2. **Route Protection** - All routes are accessible without authentication\n3. **Session Management** - No real user sessions or state persistence\n4. **Error Handling** - No real error states or user feedback\n5. **Loading States** - No loading indicators during operations\n\n### **Mock Behavior Notes**\n\n- **All forms return success** - Mock functions always return `true`\n- **No real validation** - Forms accept any input\n- **No persistence** - Page refresh resets all state\n- **No real user data** - Profile shows placeholder information\n\n**This is intentional!** The tutorial will teach you how to replace these mock functions with real Clerk authentication.\n\n## 🔧 Development\n\n### Available Scripts\n\n```bash\n# Development server\nnpm run dev\n\n# Build for production\nnpm run build\n\n# Preview production build\nnpm run preview\n\n# Lint code\nnpm run lint\n```\n\n### **Current Mock Authentication Composable**\n\nThe `useAuth` composable currently provides **mock functionality only**:\n\n```typescript\nimport { useAuth } from './composables/useAuth';\n\nconst {\n  // State (Mock)\n  isSignedIn,    // Computed: always false (mock)\n  user,          // Computed: null (mock)\n  isLoaded,      // Computed: always true (mock)\n  isLoading,     // Computed: always false (mock)\n  error,         // Computed: empty string (mock)\n  \n  // Methods (Mock - Always Return Success)\n  signIn,        // Mock: always returns true\n  signUp,        // Mock: always returns true\n  signOut,       // Mock: always returns true\n  handleVerification, // Mock: always returns true\n  getUserProfile, // Mock: returns null\n  getSession,    // Mock: returns null\n  refreshSession, // Mock: always returns true\n} = useAuth();\n```\n\n### **Mock Behavior Explanation**\n\n- **All methods return success** - This is intentional for tutorial purposes\n- **No real state management** - State doesn't persist between page refreshes\n- **No real validation** - Forms accept any input\n- **No error handling** - No real error states or user feedback\n\n**During the tutorial, you'll replace these mock functions with real Clerk integration!**\n\n## 📚 Tutorial Expectations\n\n### **What You'll Learn**\n1. **Clerk Integration** - How to set up and configure Clerk authentication\n2. **Real Authentication** - Replace mock functions with real auth logic\n3. **Route Protection** - Implement authentication guards and navigation\n4. **Session Management** - Handle user sessions and state persistence\n5. **Error Handling** - Add comprehensive error handling and user feedback\n6. **Loading States** - Implement Suspense and loading components\n7. **Documentation** - Add JSDoc comments and improve TypeScript types\n8. **Mobile Optimization** - Prepare for Capacitor deployment\n\n### **Tutorial Progression**\n- **Start Here** - This clean, basic codebase\n- **Follow Steps** - Replace mock functions one by one\n- **Test Progress** - See real authentication working\n- **Add Features** - Enhance with error handling and loading states\n- **Complete** - End up with production-ready code like `finished-code` branch\n\n### **Reference Implementation**\n- Use the `finished-code` branch as a reference\n- Compare your progress with the completed implementation\n- See examples of proper JSDoc documentation and TypeScript usage\n\n## 🔧 Environment Configuration\n\n### .env File Setup\n\nThe project includes a `.env.example` file with all necessary environment variables for Clerk integration:\n\n```bash\n# Copy the example file\ncp .env.example .env\n\n# Required: Clerk publishable key (get from https://dashboard.clerk.com/)\nVITE_CLERK_PUBLISHABLE_KEY=pk_test_your_publishable_key_here\n\n# Optional: Custom URLs and domains\nVITE_CLERK_DOMAIN=your-custom-domain.clerk.accounts.dev\nVITE_CLERK_SIGN_IN_URL=/login\nVITE_CLERK_SIGN_UP_URL=/signup\nVITE_CLERK_AFTER_SIGN_IN_URL=/profile\nVITE_CLERK_AFTER_SIGN_UP_URL=/profile\n```\n\n**Important Notes:**\n- Use `VITE_` prefix for environment variables (Vite requirement)\n- Never commit `.env` files (they're in `.gitignore`)\n- Restart dev server after changing environment variables\n- Use `pk_test_` keys for development, `pk_live_` for production\n\n## 📚 Next Steps\n\nThis tutorial app is designed to be the starting point for learning Clerk integration. Follow the tutorial to:\n\n1. **Install Clerk** - Add Clerk dependencies\n2. **Configure Clerk** - Set up authentication service\n3. **Replace Mock Auth** - Swap mock functions for real Clerk\n4. **Add Email Code Verification** - Implement real email verification (mobile-friendly)\n5. **Add Suspense** - Implement production-ready loading states\n\n## 🔍 Branch Comparison\n\n### **Key Differences Between Branches**\n\n| Feature | `main` Branch | `finished-code` Branch |\n|---------|---------------|------------------------|\n| **Authentication** | Mock functions | Real Clerk integration |\n| **Documentation** | Basic comments | Comprehensive JSDoc |\n| **TypeScript** | Basic types | Full type safety, zero `any` |\n| **Error Handling** | Basic | Comprehensive error handling |\n| **Loading States** | Basic | Suspense with fallback components |\n| **Session Management** | Mock | Real Clerk session management |\n| **Mobile Features** | Basic | Full Capacitor optimization |\n| **Code Quality** | Tutorial level | Production ready |\n\n### **File Structure Differences**\n\n**Main Branch:**\n```\nsrc/\n├── components/\n│   └── AuthActions.vue        # Basic mock actions\n├── composables/\n│   ├── useAuth.ts             # Mock authentication\n│   └── useMobileAuth.ts       # Mock mobile features\n└── views/\n    ├── LoginView.vue          # Basic login form\n    ├── SignUpView.vue         # Basic signup form\n    └── ProfileView.vue        # Basic profile display\n```\n\n**Finished-Code Branch:**\n```\nsrc/\n├── components/\n│   ├── AppContent.vue         # Router with auth protection\n│   ├── AuthActions.vue        # Enhanced auth actions\n│   └── LoadingSpinner.vue     # Loading state component\n├── composables/\n│   ├── useAuth.ts             # Real Clerk integration\n│   └── useMobileAuth.ts       # Enhanced mobile features\n├── lib/\n│   └── auth.ts                # Auth library exports\n└── views/\n    ├── LoginView.vue          # Enhanced with real auth\n    ├── SignUpView.vue         # Enhanced with verification\n    └── ProfileView.vue        # Enhanced with real user data\n```\n\n**Why Email Codes vs Email Links?**\n- ✅ **Mobile-friendly** - Works seamlessly with Capacitor and mobile apps\n- ✅ **No cross-origin issues** - Avoids `capacitor://localhost` vs `https://` protocol conflicts\n- ✅ **Copy/paste friendly** - Users can easily copy codes from email\n- ✅ **Offline capable** - Works once code is received, no browser dependency\n\n## 🐛 Troubleshooting\n\n### Common Issues\n\n1. **App not loading**\n   - Check if all dependencies are installed: `npm install`\n   - Ensure Node.js version is 18+\n   - Check browser console for any errors\n\n2. **Forms not working as expected**\n   - **This is normal!** Forms are currently mock implementations\n   - They won't actually authenticate users (this is intentional)\n   - Check browser console to see mock function calls\n\n3. **Navigation issues**\n   - All routes are currently accessible (no auth guards yet)\n   - This is the expected behavior for the tutorial starting point\n   - Route protection will be added during the tutorial\n\n4. **No real authentication**\n   - **This is expected!** The app uses mock authentication\n   - Real Clerk integration will be added during the tutorial\n   - Check the `finished-code` branch to see the completed implementation\n\n## 📄 License\n\nThis project is licensed under the MIT License.\n\n## Author\n\nCreated by Aaron K. Saunders\n\n- 🎥 [YouTube Channel](https://www.youtube.com/channel/UCMCcqbJpyL3LAv3PJeYz2bg/)\n- 🐦 [Twitter](https://x.com/aaronksaunders)\n- 💼 [LinkedIn](https://www.linkedin.com/in/aaronksaunders/)\n- 🌐 [GitHub](https://github.com/aaronksaunders)\n\n## 🙏 Acknowledgments\n\n- [Ionic](https://ionicframework.com) for the mobile-first UI framework\n- [Vue.js](https://vuejs.org) for the progressive JavaScript framework\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faaronksaunders%2Fionic-vue-clerk-tutorial-start","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faaronksaunders%2Fionic-vue-clerk-tutorial-start","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faaronksaunders%2Fionic-vue-clerk-tutorial-start/lists"}