ignite-parse-auth-kit 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Kwaku Ansah
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,492 @@
+# Ignite Parse Auth Kit
+
+A comprehensive React Native (Expo) template powered by Ignite CLI and Parse Server, providing production-ready authentication solutions including email/password authentication, Google Sign-In integration, session persistence, and password reset functionality.
+
+[![Build Status](https://img.shields.io/github/actions/workflow/status/neweracy/IgniteParseAuthKit/ci.yml?branch=main&style=flat-square)](https://github.com/neweracy/IgniteParseAuthKit/actions)
+[![codecov](https://codecov.io/gh/neweracy/IgniteParseAuthKit/graph/badge.svg?token=JCS7VCWX7E)](https://codecov.io/gh/neweracy/IgniteParseAuthKit)
+[![npm version](https://img.shields.io/npm/v/ignite-parse-auth-kit.svg?style=flat-square)](https://www.npmjs.com/package/ignite-parse-auth-kit)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square)](LICENSE)
+[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square)](CONTRIBUTING.md)
+
+---
+
+## Table of Contents
+
+- [Features](#features)
+- [Quick Start](#quick-start)
+- [Installation via npm](#installation-via-npm)
+- [Usage Guide](#usage-guide)
+- [Configuration](#configuration)
+- [Project Structure](#project-structure)
+- [Development](#development)
+- [Contributing](#contributing)
+- [License](#license)
+- [Support & Contact](#support--contact)
+- [Changelog](#changelog)
+
+---
+
+## Features
+
+### Authentication & Security
+
+- **Email/Password Authentication** - Complete signup and login flow with real-time validation
+- **Google Sign-In Integration** - Seamless OAuth via Expo AuthSession
+- **Password Reset** - Built-in password recovery using Parse Server
+- **Session Persistence** - Fast session restore using MMKV storage
+- **Server Health Monitoring** - Pre-flight checks before authentication actions
+
+### Developer Experience
+
+- **React Native + Expo** - Cross-platform development with modern tooling
+- **TypeScript Support** - Fully typed AuthContext and API responses
+- **Path Aliases** - Clean imports with `@/...` syntax
+- **Offline-First Ready** - Parse local datastore enabled for offline capabilities
+- **Production Ready** - Comprehensive error handling and loading states
+
+---
+
+## Quick Start
+
+### Installation via npm (Recommended)
+
+The easiest way to create a new project is using npx:
+
+```bash
+# Create a new project
+npx ignite-parse-auth-kit my-app
+
+# Navigate to the project
+cd my-app
+
+# Start developing
+npx expo start
+```
+
+#### CLI Options
+
+```bash
+# Skip automatic dependency installation
+npx ignite-parse-auth-kit my-app --skip-install
+
+# Use npm instead of yarn
+npx ignite-parse-auth-kit my-app --use-npm
+
+# Use bun instead of yarn
+npx ignite-parse-auth-kit my-app --use-bun
+
+# Specify a custom directory
+npx ignite-parse-auth-kit my-app --directory ./projects
+```
+
+### Alternative Installation Methods
+
+#### Using GitHub Template
+
+1. **Use this template**
+   - Click the "Use this template" button on GitHub
+   - Or visit: `https://github.com/neweracy/IgniteParseAuthKit/generate`
+   - Create your new repository from this template
+
+2. **Clone your new repository**
+   ```bash
+   git clone https://github.com/your-username/your-new-repo-name.git
+   cd your-new-repo-name
+   ```
+
+3. **Install dependencies**
+   ```bash
+   yarn install
+   # or
+   npm install
+   ```
+
+4. **Configure environment variables**
+   ```bash
+   # Edit app/config/config.dev.ts with your Parse Server configuration
+   ```
+
+5. **Start the development server**
+   ```bash
+   npx expo start
+   ```
+
+6. **Launch on device/simulator**
+   - Press `i` for iOS Simulator
+   - Press `a` for Android Emulator
+   - Scan QR code with Expo Go for physical device testing
+
+### Prerequisites
+
+Ensure you have the following installed on your development machine:
+
+- **Node.js** LTS (v18 or higher)
+- **Package Manager** - Yarn, npm, or bun
+- **Expo CLI** - Comes with npx (no global install needed)
+- **Mobile Development Environment**:
+  - **iOS**: Xcode (macOS only)
+  - **Android**: Android Studio
+
+---
+
+## Usage Guide
+
+### Authentication Methods
+
+The AuthContext provides a comprehensive API for handling all authentication scenarios:
+
+### Code Examples
+
+#### Email/Password Login
+
+```tsx
+import { useAuth } from '@/context/AuthContext'
+
+export function LoginScreen() {
+  const { setAuthEmail, setAuthPassword, login, isLoading, error } = useAuth()
+
+  const handleLogin = async () => {
+    setAuthEmail('user@example.com')
+    setAuthPassword('password123')
+    
+    const result = await login()
+    if (!result.success) {
+      console.error('Login failed:', result.error)
+    } else {
+      console.log('Login successful!')
+    }
+  }
+
+  return (
+    <View>
+      {/* Your login form UI here */}
+      <Button title="Login" onPress={handleLogin} disabled={isLoading} />
+      {error && <Text style={{ color: 'red' }}>{error}</Text>}
+    </View>
+  )
+}
+```
+
+#### User Registration
+
+```tsx
+import { useAuth } from '@/context/AuthContext'
+
+export function RegisterScreen() {
+  const { setAuthEmail, setAuthPassword, signUp, isLoading, error } = useAuth()
+
+  const handleSignUp = async () => {
+    setAuthEmail('newuser@example.com')
+    setAuthPassword('securePassword123')
+    
+    const result = await signUp('unique_username')
+    if (result.success) {
+      console.log('Account created successfully!')
+    } else {
+      console.error('Registration failed:', result.error)
+    }
+  }
+
+  return (
+    <View>
+      {/* Your registration form UI here */}
+      <Button title="Sign Up" onPress={handleSignUp} disabled={isLoading} />
+      {error && <Text style={{ color: 'red' }}>{error}</Text>}
+    </View>
+  )
+}
+```
+
+#### Password Reset
+
+```tsx
+import { useAuth } from '@/context/AuthContext'
+
+export function PasswordResetScreen() {
+  const { requestPasswordReset } = useAuth()
+  const [email, setEmail] = useState('')
+
+  const handlePasswordReset = async () => {
+    const result = await requestPasswordReset(email)
+    if (result.success) {
+      Alert.alert('Success', result.message || 'Password reset email sent!')
+    } else {
+      Alert.alert('Error', result.error || 'Failed to send reset email')
+    }
+  }
+
+  return (
+    <View>
+      <TextInput
+        value={email}
+        onChangeText={setEmail}
+        placeholder="Enter your email"
+        keyboardType="email-address"
+      />
+      <Button title="Reset Password" onPress={handlePasswordReset} />
+    </View>
+  )
+}
+```
+
+#### Google Sign-In
+
+```tsx
+import { useAuth } from '@/context/AuthContext'
+
+export function GoogleSignInScreen() {
+  const { googleSignIn } = useAuth()
+
+  const handleGoogleSignIn = async () => {
+    try {
+      // You'll need to implement getGoogleAuthResponse using Expo AuthSession
+      const googleResponse = await getGoogleAuthResponse()
+      
+      const result = await googleSignIn(googleResponse)
+      if (result.success) {
+        console.log('Google sign-in successful!')
+      } else {
+        console.error('Google sign-in failed:', result.error)
+      }
+    } catch (error) {
+      console.error('Google sign-in error:', error)
+    }
+  }
+
+  return (
+    <View>
+      <Button title="Sign in with Google" onPress={handleGoogleSignIn} />
+    </View>
+  )
+}
+```
+
+#### Server Health Check
+
+```tsx
+import { useAuth } from '@/context/AuthContext'
+import { useEffect } from 'react'
+
+export function ServerStatusComponent() {
+  const { checkServerStatus } = useAuth()
+
+  useEffect(() => {
+    const verifyServerConnection = async () => {
+      const status = await checkServerStatus()
+      
+      if (status.isRunning) {
+        console.log('✅ Parse Server is running')
+      } else {
+        console.error('❌ Server unavailable:', status.message)
+      }
+    }
+
+    verifyServerConnection()
+  }, [checkServerStatus])
+
+  return null
+}
+```
+
+---
+
+## Configuration
+
+### Environment Variables
+
+Create a `.env` file in your project root with the following required variables:
+
+```env
+# Parse Server Configuration (Required)
+EXPO_PUBLIC_SERVER_URL=https://your-parse-server.herokuapp.com/parse
+EXPO_PUBLIC_APP_ID=your_unique_app_identifier
+EXPO_PUBLIC_JAVASCRIPT_KEY=your_javascript_key
+
+# Optional: Google Sign-In Configuration
+GOOGLE_CLIENT_ID=your-google-oauth-client-id
+
+# Optional: Development Settings
+NODE_ENV=development
+```
+
+> **⚠️ Security Note**: Never commit sensitive keys to version control. Use Expo's secure environment variable handling for production deployments.
+
+### TypeScript Configuration
+
+The template includes pre-configured path aliases for clean imports:
+
+**tsconfig.json**
+```json
+{
+  "compilerOptions": {
+    "baseUrl": ".",
+    "paths": {
+      "@/*": ["app/*"],
+      "@/components/*": ["app/components/*"],
+      "@/context/*": ["app/context/*"],
+      "@/lib/*": ["app/lib/*"]
+    }
+  }
+}
+```
+
+**babel.config.js**
+```javascript
+module.exports = function (api) {
+  api.cache(true)
+  
+  return {
+    presets: ['babel-preset-expo'],
+    plugins: [
+      [
+        'module-resolver',
+        {
+          root: ['./'],
+          alias: {
+            '@': './app',
+          },
+          extensions: ['.ts', '.tsx', '.js', '.jsx', '.json'],
+        },
+      ],
+    ],
+  }
+}
+```
+
+### Parse Server Setup
+
+The Parse SDK is initialized in `app/lib/Parse/parse.ts` with the following configuration:
+
+- **AsyncStorage Integration** - For React Native compatibility
+- **Local Datastore** - Enabled for offline-first capabilities
+- **Runtime Validation** - Environment variables are validated on app start
+- **Error Handling** - Comprehensive error boundaries for Parse operations
+
+---
+
+## Project Structure
+
+```text
+ignite-parse-auth-kit/
+├── app/                          # Main application directory
+│   ├── components/               # Reusable UI components
+│   ├── context/                  # React Context providers
+│   │   └── AuthContext.tsx          # Central authentication state
+│   ├── lib/                      # Core libraries and utilities
+│   │   ├── Parse/
+│   │   │   └── parse.ts             # Parse SDK initialization
+│   │   └── utils/
+│   │       ├── validation.ts        # Form validation helpers
+│   │       └── storage.ts           # MMKV storage wrapper
+│   ├── screens/                  # Application screens
+│   │   ├── LoginScreen.tsx          # Email/password login
+│   │   ├── RegisterScreen.tsx       # User registration
+│   │   ├── ForgotPasswordScreen.tsx # Password recovery
+│   │   └── DashboardScreen.tsx      # Protected route example
+│   ├── navigators/               # Navigation configuration
+│   │   ├── AuthNavigator.tsx        # Authentication flow
+│   │   ├── AppNavigator.tsx         # Main app navigation
+│   │   └── types.ts                 # Navigation type definitions
+│   └── types/                    # TypeScript type definitions
+│       ├── auth.ts                  # Authentication types
+│       └── api.ts                   # API response types
+├── assets/                       # Static assets (images, fonts)
+├── .env.example                  # Environment variables template
+├── app.json                      # Expo configuration
+├── package.json                  # Dependencies and scripts
+└── README.md                     # This file
+```
+
+---
+
+## Development
+
+### Available Scripts
+
+```bash
+# Start development server
+npm start
+
+# Start with cache cleared
+npm run start:clear
+
+# Run on iOS simulator
+npm run ios
+
+# Run on Android emulator
+npm run android
+
+# Run tests
+npm test
+
+# Type checking
+npm run type-check
+
+# Linting
+npm run lint
+
+# Build for production
+npm run build
+```
+
+### Development Workflow
+
+1. **Feature Development** - Create feature branches from `main`
+2. **Testing** - Run tests and manual testing on both platforms
+3. **Code Quality** - Ensure TypeScript compliance and linting passes
+4. **Documentation** - Update relevant documentation for new features
+
+---
+
+## Contributing
+
+We welcome contributions from the community! Here's how you can help:
+
+### Getting Started
+
+1. **Use this template** to create your own repository
+2. **Clone** your new repository locally
+3. **Create** a feature branch: `git checkout -b feat/your-feature-name`
+4. **Make** your changes and improvements
+5. **Test** thoroughly on both iOS and Android
+6. **Submit** a pull request to the original template repository
+
+### Contribution Guidelines
+
+- Follow [Conventional Commits](https://www.conventionalcommits.org/) format
+- Include tests for new features
+- Update documentation for API changes
+- Keep PRs focused and atomic
+- Ensure all CI checks pass
+
+### Commit Message Format
+```
+type(scope): description
+
+feat(auth): add biometric authentication support
+fix(login): resolve session persistence issue
+docs(readme): update installation instructions
+```
+
+---
+
+## License
+
+This project is licensed under the **MIT License**. See the [LICENSE](LICENSE) file for complete details.
+
+```
+MIT License - Copyright (c) 2024 Ignite Parse Auth Kit
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files...
+```
+
+---
+
+## Support & Contact
+
+### Getting Help
+
+- **Bug Reports**: [GitHub Issues](https://github.com/your-org/ignite-parse-auth-kit/issues)
+- **Feature Requests**: [GitHub Discussions](https://github.com/your-org/ignite-parse-auth-kit/discussions)
+- **Documentation**: [Wiki](https://github.com/your-org/ignite-parse-auth-kit/wiki)

package/app/app.tsx

@@ -0,0 +1,116 @@
+/* eslint-disable import/first */
+/**
+ * Welcome to the main entry point of the app. In this file, we'll
+ * be kicking off our app.
+ *
+ * Most of this file is boilerplate and you shouldn't need to modify
+ * it very often. But take some time to look through and understand
+ * what is going on here.
+ *
+ * The app navigation resides in ./app/navigators, so head over there
+ * if you're interested in adding screens and navigators.
+ */
+if (__DEV__) {
+  // Load Reactotron in development only.
+  // Note that you must be using metro's `inlineRequires` for this to work.
+  // If you turn it off in metro.config.js, you'll have to manually import it.
+  require("./devtools/ReactotronConfig.ts")
+}
+import "./utils/gestureHandler"
+
+import { useEffect, useState } from "react"
+import { useFonts } from "expo-font"
+import * as Linking from "expo-linking"
+import { KeyboardProvider } from "react-native-keyboard-controller"
+import { initialWindowMetrics, SafeAreaProvider } from "react-native-safe-area-context"
+
+import { AuthProvider } from "./context/AuthContext" // @demo remove-current-line
+import { initI18n } from "./i18n"
+import { AppNavigator } from "./navigators/AppNavigator"
+import { useNavigationPersistence } from "./navigators/navigationUtilities"
+import { ThemeProvider } from "./theme/context"
+import { customFontsToLoad } from "./theme/typography"
+import { loadDateFnsLocale } from "./utils/formatDate"
+import 'react-native-get-random-values';
+import * as storage from "./utils/storage"
+
+export const NAVIGATION_PERSISTENCE_KEY = "NAVIGATION_STATE"
+
+// Web linking configuration
+const prefix = Linking.createURL("/")
+const config = {
+  screens: {
+    Login: {
+      path: "",
+    },
+    Welcome: "welcome",
+    Demo: {
+      screens: {
+        DemoShowroom: {
+          path: "showroom/:queryIndex?/:itemIndex?",
+        },
+        DemoDebug: "debug",
+        DemoPodcastList: "podcast",
+        DemoCommunity: "community",
+      },
+    },
+  },
+}
+
+/**
+ * This is the root component of our app.
+ * @param {AppProps} props - The props for the `App` component.
+ * @returns {JSX.Element} The rendered `App` component.
+ */
+export function App() {
+  const {
+    initialNavigationState,
+    onNavigationStateChange,
+    isRestored: isNavigationStateRestored,
+  } = useNavigationPersistence(storage, NAVIGATION_PERSISTENCE_KEY)
+
+  const [areFontsLoaded, fontLoadError] = useFonts(customFontsToLoad)
+  const [isI18nInitialized, setIsI18nInitialized] = useState(false)
+
+  useEffect(() => {
+    initI18n()
+      .then(() => setIsI18nInitialized(true))
+      .then(() => loadDateFnsLocale())
+  }, [])
+
+  // Before we show the app, we have to wait for our state to be ready.
+  // In the meantime, don't render anything. This will be the background
+  // color set in native by rootView's background color.
+  // In iOS: application:didFinishLaunchingWithOptions:
+  // In Android: https://stackoverflow.com/a/45838109/204044
+  // You can replace with your own loading component if you wish.
+  if (!isNavigationStateRestored || !isI18nInitialized || (!areFontsLoaded && !fontLoadError)) {
+    return null
+  }
+
+  const linking = {
+    prefixes: [prefix],
+    config,
+  }
+
+  // otherwise, we're ready to render the app
+  return (
+    <SafeAreaProvider initialMetrics={initialWindowMetrics}>
+      <KeyboardProvider>
+        {/* @demo remove-block-start */}
+        <AuthProvider>
+          {/* @demo remove-block-end */}
+          <ThemeProvider>
+            <AppNavigator
+              linking={linking}
+              initialState={initialNavigationState}
+              onStateChange={onNavigationStateChange}
+            />
+          </ThemeProvider>
+          {/* @demo remove-block-start */}
+        </AuthProvider>
+        {/* @demo remove-block-end */}
+      </KeyboardProvider>
+    </SafeAreaProvider>
+  )
+}