react-native-custom-splash 2.0.0 → 2.1.0

package/README.md

@@ -37,7 +37,75 @@ your-project/
 
 ### Step 2: Configure in app.json
 
-Add the plugin configuration to your `app.json`:
+Choose one of the 4 configuration options below based on your needs:
+
+## 🎨 Configuration Examples
+
+### **Option 1: Single Full Image** (Most Common) ⭐
+
+Perfect for a complete branded splash screen with your custom design.
+
+```json
+{
+  "expo": {
+    "name": "YourApp",
+    "plugins": [
+      [
+        "react-native-custom-splash",
+        {
+          "image": "./assets/splash.png"
+        }
+      ]
+    ]
+  }
+}
+```
+
+**Project Structure:**
+```
+your-project/
+├── assets/
+│   └── splash.png          ← Your full-screen image (1242×2688px)
+└── app.json
+```
+
+---
+
+### **Option 2: Background Color + Center Logo**
+
+Great for a clean, minimal look with just your logo.
+
+```json
+{
+  "expo": {
+    "name": "YourApp",
+    "plugins": [
+      [
+        "react-native-custom-splash",
+        {
+          "backgroundColor": "#4F46E5",
+          "logo": "./assets/logo.png",
+          "logoWidth": 180
+        }
+      ]
+    ]
+  }
+}
+```
+
+**Project Structure:**
+```
+your-project/
+├── assets/
+│   └── logo.png            ← Your center logo (512×512px)
+└── app.json
+```
+
+---
+
+### **Option 3: Background Image + Center Logo**
+
+Maximum customization - background image with logo on top.
 
 ```json
 {
@@ -48,7 +116,7 @@ Add the plugin configuration to your `app.json`:
         "react-native-custom-splash",
         {
           "backgroundColor": "#FFFFFF",
-          "image": "./assets/splash-background.png",
+          "image": "./assets/splash-bg.png",
           "logo": "./assets/logo.png",
           "logoWidth": 150
         }
@@ -58,6 +126,39 @@ Add the plugin configuration to your `app.json`:
 }
 ```
 
+**Project Structure:**
+```
+your-project/
+├── assets/
+│   ├── splash-bg.png       ← Background image
+│   └── logo.png            ← Center logo
+└── app.json
+```
+
+---
+
+### **Option 4: Only Background Color**
+
+Simple solid color background.
+
+```json
+{
+  "expo": {
+    "name": "YourApp",
+    "plugins": [
+      [
+        "react-native-custom-splash",
+        {
+          "backgroundColor": "#FF6B6B"
+        }
+      ]
+    ]
+  }
+}
+```
+
+---
+
 ### Step 3: Run prebuild
 
 ```bash
@@ -90,79 +191,15 @@ function App() {
 }
 ```
 
-## ⚙️ Configuration Options
+## ⚙️ Configuration Options Reference
 
 | Option | Type | Default | Description |
 |--------|------|---------|-------------|
-| `backgroundColor` | `string` | `#FFFFFF` | Background color for the splash screen (hex color) |
-| `image` | `string` | `null` | Path to full background image (relative to project root) |
-| `logo` | `string` | `null` | Path to center logo image (relative to project root) |
+| `backgroundColor` | `string` | `#FFFFFF` | Background color (hex format: #RRGGBB) |
+| `image` | `string` | `null` | Path to full background image (optional) |
+| `logo` | `string` | `null` | Path to center logo image (optional) |
 | `logoWidth` | `number` | `150` | Width of the center logo in pixels |
 
-### Configuration Examples
-
-#### Only Background Color
-```json
-{
-  "plugins": [
-    [
-      "react-native-custom-splash",
-      {
-        "backgroundColor": "#FF6B6B"
-      }
-    ]
-  ]
-}
-```
-
-#### Background Color + Logo
-```json
-{
-  "plugins": [
-    [
-      "react-native-custom-splash",
-      {
-        "backgroundColor": "#1E3A8A",
-        "logo": "./assets/logo.png",
-        "logoWidth": 200
-      }
-    ]
-  ]
-}
-```
-
-#### Full Background Image + Logo
-```json
-{
-  "plugins": [
-    [
-      "react-native-custom-splash",
-      {
-        "backgroundColor": "#FFFFFF",
-        "image": "./assets/splash-bg.png",
-        "logo": "./assets/logo.png",
-        "logoWidth": 180
-      }
-    ]
-  ]
-}
-```
-
-#### Only Background Image (No Logo)
-```json
-{
-  "plugins": [
-    [
-      "react-native-custom-splash",
-      {
-        "backgroundColor": "#000000",
-        "image": "./assets/splash-full.png"
-      }
-    ]
-  ]
-}
-```
-
 ## 📱 API Reference
 
 ### `SplashScreen.hide(animated)`
@@ -301,18 +338,89 @@ Add your images to Android resources:
 
 ## ❓ Troubleshooting
 
+### ⚠️ Error: "Plugin is an unexpected object"
+
+**Full Error:**
+```
+PluginError: Plugin is an unexpected object, with keys: "backgroundColor, image, logoWidth".
+```
+
+**Cause:** Your plugin configuration is not properly wrapped in square brackets.
+
+**❌ Wrong:**
+```json
+{
+  "plugins": [
+    "react-native-custom-splash",
+    {
+      "backgroundColor": "#FF6B6B"
+    }
+  ]
+}
+```
+
+**✅ Correct:**
+```json
+{
+  "plugins": [
+    [
+      "react-native-custom-splash",
+      {
+        "backgroundColor": "#FF6B6B"
+      }
+    ]
+  ]
+}
+```
+
+**Key Point:** When passing configuration to a plugin, wrap BOTH the plugin name and the config object in square brackets `[]`.
+
+---
+
 ### Splash screen not showing
 - Make sure you run `npx expo prebuild --clean` after changing configuration
 - Check that your image paths in `app.json` are correct and files exist
-- Try cleaning your build: `cd ios && pod install && cd ..` for iOS
+- Verify images are in the `assets/` folder
+- Try cleaning your build:
+  - iOS: `cd ios && pod install && cd ..`
+  - Android: `cd android && ./gradlew clean && cd ..`
 
 ### Images not updating
 - Run `npx expo prebuild --clean` to force regeneration of native projects
-- Clear build caches and rebuild
+- Delete `ios/` and `android/` folders, then run `npx expo prebuild --clean` again
+- Clear build caches:
+  - iOS: `rm -rf ios/Pods ios/build`
+  - Android: `cd android && ./gradlew clean && cd ..`
+
+### Image paths not working
+- Use relative paths from project root: `"./assets/splash.png"` ✅
+- Don't use absolute paths: `"/Users/..."` ❌
+- Make sure the file extension matches (`.png`, `.jpg`)
+- Check file actually exists at that path
+
+### Background color not working
+- Use hex format: `"#FF6B6B"` ✅
+- Don't forget the `#`: `"FF6B6B"` ❌
+- Use 6-digit format: `"#FFFFFF"` ✅ not `"#FFF"` ❌
 
 ### TypeScript errors
 - Make sure you have `@types/react` and `@types/react-native` installed
 - The package includes TypeScript definitions
+- Try: `npm install --save-dev @types/react @types/react-native`
+
+### Pod install fails (iOS)
+```bash
+cd ios
+rm -rf Pods Podfile.lock
+pod install --repo-update
+cd ..
+```
+
+### Still having issues?
+1. Delete `node_modules/` and reinstall: `npm install` or `yarn install`
+2. Delete `ios/` and `android/` folders
+3. Run `npx expo prebuild --clean`
+4. Check the [GitHub Issues](https://github.com/vijaykishan312/react-native-custom-splash/issues)
 
 ## 📄 License
 

package/example/README.md

@@ -0,0 +1,175 @@
+# react-native-custom-splash Example App
+
+This example demonstrates how to use `react-native-custom-splash` in your Expo app.
+
+## 📁 Project Structure
+
+```
+example/
+├── assets/
+│   ├── splash-bg.png       ← Background image for splash
+│   ├── logo.png            ← Center logo
+│   ├── icon.png            ← App icon
+│   └── ...
+├── app.json                ← Configuration with plugin setup
+├── App.tsx                 ← Main app with SplashScreen usage
+└── package.json
+```
+
+## 🚀 Running the Example
+
+### 1. Install Dependencies
+
+```bash
+cd example
+npm install
+```
+
+### 2. Run Prebuild
+
+```bash
+npx expo prebuild --clean
+```
+
+### 3. Run on Device/Simulator
+
+**iOS:**
+```bash
+npx expo run:ios
+```
+
+**Android:**
+```bash
+npx expo run:android
+```
+
+## 🎨 Configuration Examples
+
+The example `app.json` is configured with **Option 3** (Background Image + Logo):
+
+```json
+{
+  "plugins": [
+    [
+      "react-native-custom-splash",
+      {
+        "backgroundColor": "#4F46E5",
+        "image": "./assets/splash-bg.png",
+        "logo": "./assets/logo.png",
+        "logoWidth": 180
+      }
+    ]
+  ]
+}
+```
+
+### Try Different Configurations:
+
+#### Option 1: Single Full Image (Simplest)
+```json
+{
+  "plugins": [
+    [
+      "react-native-custom-splash",
+      {
+        "image": "./assets/splash.png"
+      }
+    ]
+  ]
+}
+```
+
+#### Option 2: Color + Logo (Minimal)
+```json
+{
+  "plugins": [
+    [
+      "react-native-custom-splash",
+      {
+        "backgroundColor": "#4F46E5",
+        "logo": "./assets/logo.png",
+        "logoWidth": 180
+      }
+    ]
+  ]
+}
+```
+
+#### Option 4: Only Color (Fastest)
+```json
+{
+  "plugins": [
+    [
+      "react-native-custom-splash",
+      {
+        "backgroundColor": "#FF6B6B"
+      }
+    ]
+  ]
+}
+```
+
+**After changing configuration:**
+```bash
+npx expo prebuild --clean
+```
+
+## 💡 Usage in Code
+
+Check `App.tsx` to see how the splash screen is used:
+
+```typescript
+import SplashScreen from 'react-native-custom-splash';
+import { useEffect } from 'react';
+
+function App() {
+  useEffect(() => {
+    // Hide splash after 2 seconds
+    const timer = setTimeout(() => {
+      SplashScreen.hide(true); // true = with animation
+    }, 2000);
+    
+    return () => clearTimeout(timer);
+  }, []);
+  
+  // Your app content...
+}
+```
+
+## 🖼️ Image Guidelines
+
+### Background Image (`splash-bg.png`)
+- **Size:** 1242 x 2688 px (iPhone 13 Pro Max)
+- **Format:** PNG or JPG
+- **Aspect Ratio:** 9:19.5 (standard phone ratio)
+- **Design:** Center-weighted content
+
+### Logo (`logo.png`)
+- **Size:** 512 x 512 px (or your aspect ratio)
+- **Format:** PNG with transparency
+- **Design:** Will be scaled based on `logoWidth`
+
+## 🔧 Troubleshooting
+
+### Changes not reflecting?
+```bash
+# Clean everything and rebuild
+npx expo prebuild --clean
+cd ios && pod install && cd ..
+```
+
+### Images not showing?
+- Check image paths in `app.json` are correct
+- Ensure images exist in `assets/` folder
+- Run `npx expo prebuild --clean`
+
+### TypeScript errors?
+```bash
+npm install --save-dev @types/react @types/react-native
+```
+
+## 📚 Learn More
+
+- [Main README](../README.md)
+- [npm Package](https://www.npmjs.com/package/react-native-custom-splash)
+- [GitHub Repository](https://github.com/vijaykishan312/react-native-custom-splash)

package/example/app.json

@@ -0,0 +1,38 @@
+{
+    "expo": {
+        "name": "SplashScreenExample",
+        "slug": "splash-screen-example",
+        "version": "1.0.0",
+        "orientation": "portrait",
+        "icon": "./assets/icon.png",
+        "userInterfaceStyle": "light",
+        "assetBundlePatterns": [
+            "**/*"
+        ],
+        "ios": {
+            "supportsTablet": true,
+            "bundleIdentifier": "com.example.splashscreen"
+        },
+        "android": {
+            "adaptiveIcon": {
+                "foregroundImage": "./assets/adaptive-icon.png",
+                "backgroundColor": "#ffffff"
+            },
+            "package": "com.example.splashscreen"
+        },
+        "web": {
+            "favicon": "./assets/favicon.png"
+        },
+        "plugins": [
+            [
+                "react-native-custom-splash",
+                {
+                    "backgroundColor": "#4F46E5",
+                    "image": "./assets/splash-bg.png",
+                    "logo": "./assets/logo.png",
+                    "logoWidth": 180
+                }
+            ]
+        ]
+    }
+}

package/example/app.json.option1-full-image

@@ -0,0 +1,14 @@
+{
+  "expo": {
+    "name": "Example - Single Full Image",
+    "slug": "splash-example-full-image",
+    "plugins": [
+      [
+        "react-native-custom-splash",
+        {
+          "image": "./assets/splash.png"
+        }
+      ]
+    ]
+  }
+}

package/example/app.json.option2-color-logo

@@ -0,0 +1,16 @@
+{
+  "expo": {
+    "name": "Example - Color + Logo",
+    "slug": "splash-example-color-logo",
+    "plugins": [
+      [
+        "react-native-custom-splash",
+        {
+          "backgroundColor": "#4F46E5",
+          "logo": "./assets/logo.png",
+          "logoWidth": 180
+        }
+      ]
+    ]
+  }
+}

package/example/app.json.option3-image-logo

@@ -0,0 +1,17 @@
+{
+  "expo": {
+    "name": "Example - Image + Logo",
+    "slug": "splash-example-image-logo",
+    "plugins": [
+      [
+        "react-native-custom-splash",
+        {
+          "backgroundColor": "#FFFFFF",
+          "image": "./assets/splash-bg.png",
+          "logo": "./assets/logo.png",
+          "logoWidth": 150
+        }
+      ]
+    ]
+  }
+}

package/example/app.json.option4-color-only

@@ -0,0 +1,14 @@
+{
+  "expo": {
+    "name": "Example - Color Only",
+    "slug": "splash-example-color-only",
+    "plugins": [
+      [
+        "react-native-custom-splash",
+        {
+          "backgroundColor": "#FF6B6B"
+        }
+      ]
+    ]
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "react-native-custom-splash",
-    "version": "2.0.0",
+    "version": "2.1.0",
     "description": "A custom splash screen module for React Native with native iOS and Android support, fully compatible with Expo",
     "main": "src/index.js",
     "types": "src/index.d.ts",
@@ -44,6 +44,8 @@
         "plugin/",
         "app.plugin.js",
         "react-native-custom-splash.podspec",
+        "example/app.json*",
+        "example/README.md",
         "README.md",
         "LICENSE"
     ]

package/plugin/src/index.js

@@ -8,7 +8,53 @@ const {
 } = require('@expo/config-plugins');
 const path = require('path');
 const fs = require('fs');
-const { generateImageAsync } = require('@expo/image-utils');
+
+/**
+ * Validate and normalize plugin configuration
+ */
+function validateAndNormalizeConfig(props) {
+    // Check if props is valid
+    if (!props || typeof props !== 'object') {
+        console.warn('⚠️  react-native-custom-splash: No configuration provided, using defaults');
+        return {
+            backgroundColor: '#FFFFFF',
+            image: null,
+            logo: null,
+            logoWidth: 150,
+        };
+    }
+
+    // Validate backgroundColor
+    if (props.backgroundColor && !/^#[0-9A-Fa-f]{6}$/.test(props.backgroundColor)) {
+        console.warn(`⚠️  react-native-custom-splash: Invalid backgroundColor "${props.backgroundColor}", using default #FFFFFF`);
+        props.backgroundColor = '#FFFFFF';
+    }
+
+    // Validate logoWidth
+    if (props.logoWidth && (typeof props.logoWidth !== 'number' || props.logoWidth <= 0)) {
+        console.warn(`⚠️  react-native-custom-splash: Invalid logoWidth "${props.logoWidth}", using default 150`);
+        props.logoWidth = 150;
+    }
+
+    // Validate image path
+    if (props.image && typeof props.image !== 'string') {
+        console.warn(`⚠️  react-native-custom-splash: Invalid image path, must be a string`);
+        props.image = null;
+    }
+
+    // Validate logo path
+    if (props.logo && typeof props.logo !== 'string') {
+        console.warn(`⚠️  react-native-custom-splash: Invalid logo path, must be a string`);
+        props.logo = null;
+    }
+
+    return {
+        backgroundColor: props.backgroundColor || '#FFFFFF',
+        image: props.image || null,
+        logo: props.logo || null,
+        logoWidth: props.logoWidth || 150,
+    };
+}
 
 /**
  * Get plugin configuration from app.json
@@ -23,7 +69,7 @@ function getPluginConfig(config) {
     });
 
     if (Array.isArray(splashPlugin) && splashPlugin[1]) {
-        return splashPlugin[1];
+        return validateAndNormalizeConfig(splashPlugin[1]);
     }
 
     // Default configuration
@@ -308,6 +354,78 @@ const withSplashScreenAndroid = (config, pluginConfig) => {
     return config;
 };
 
+/**
+ * Create LaunchScreen.storyboard with splash configuration
+ */
+function createLaunchScreenStoryboard(hasImage, hasLogo, backgroundColor) {
+    const bgColor = backgroundColor.replace('#', '');
+    const r = parseInt(bgColor.substr(0, 2), 16) / 255;
+    const g = parseInt(bgColor.substr(2, 2), 16) / 255;
+    const b = parseInt(bgColor.substr(4, 2), 16) / 255;
+
+    const imageViewXML = hasImage ? `
+                <imageView clipsSubviews="YES" userInteractionEnabled="NO" contentMode="scaleAspectFill" horizontalHuggingPriority="251" verticalHuggingPriority="251" image="splash_image" translatesAutoresizingMaskIntoConstraints="NO" id="splashBgImage">
+                    <rect key="frame" x="0.0" y="0.0" width="414" height="896"/>
+                </imageView>` : '';
+
+    const logoViewXML = hasLogo ? `
+                <imageView clipsSubviews="YES" userInteractionEnabled="NO" contentMode="scaleAspectFit" horizontalHuggingPriority="251" verticalHuggingPriority="251" image="splash_logo" translatesAutoresizingMaskIntoConstraints="NO" id="splashLogo">
+                    <rect key="frame" x="132" y="348" width="150" height="150"/>
+                    <constraints>
+                        <constraint firstAttribute="width" constant="150" id="logoWidth"/>
+                        <constraint firstAttribute="height" constant="150" id="logoHeight"/>
+                    </constraints>
+                </imageView>` : '';
+
+    const imageConstraints = hasImage ? `
+                <constraint firstItem="splashBgImage" firstAttribute="top" secondItem="Ze5-6b-2t3" secondAttribute="top" id="bgTop"/>
+                <constraint firstItem="splashBgImage" firstAttribute="leading" secondItem="Ze5-6b-2t3" secondAttribute="leading" id="bgLeading"/>
+                <constraint firstItem="splashBgImage" firstAttribute="trailing" secondItem="Ze5-6b-2t3" secondAttribute="trailing" id="bgTrailing"/>
+                <constraint firstItem="splashBgImage" firstAttribute="bottom" secondItem="Ze5-6b-2t3" secondAttribute="bottom" id="bgBottom"/>` : '';
+
+    const logoConstraints = hasLogo ? `
+                <constraint firstItem="splashLogo" firstAttribute="centerX" secondItem="Ze5-6b-2t3" secondAttribute="centerX" id="logoCenterX"/>
+                <constraint firstItem="splashLogo" firstAttribute="centerY" secondItem="Ze5-6b-2t3" secondAttribute="centerY" id="logoCenterY"/>` : '';
+
+    const imageResources = [];
+    if (hasImage) imageResources.push('<image name="splash_image" width="1242" height="2688"/>');
+    if (hasLogo) imageResources.push('<image name="splash_logo" width="512" height="512"/>');
+
+    return `<?xml version="1.0" encoding="UTF-8"?>
+<document type="com.apple.InterfaceBuilder3.CocoaTouch.Storyboard.XIB" version="3.0" toolsVersion="21507" targetRuntime="iOS.CocoaTouch" propertyAccessControl="none" useAutolayout="YES" launchScreen="YES" useTraitCollections="YES" useSafeAreas="YES" colorMatched="YES" initialViewController="01J-lp-oVM">
+    <device id="retina6_1" orientation="portrait" appearance="light"/>
+    <dependencies>
+        <deployment identifier="iOS"/>
+        <plugIn identifier="com.apple.InterfaceBuilder.IBCocoaTouchPlugin" version="21505"/>
+        <capability name="Safe area layout guides" minToolsVersion="9.0"/>
+        <capability name="documents saved in the Xcode 8 format" minToolsVersion="8.0"/>
+    </dependencies>
+    <scenes>
+        <!--View Controller-->
+        <scene sceneID="EHf-IW-A2E">
+            <objects>
+                <viewController id="01J-lp-oVM" sceneMemberID="viewController">
+                    <view key="view" contentMode="scaleToFill" id="Ze5-6b-2t3">
+                        <rect key="frame" x="0.0" y="0.0" width="414" height="896"/>
+                        <autoresizingMask key="autoresizingMask" widthSizable="YES" heightSizable="YES"/>
+                        <subviews>${imageViewXML}${logoViewXML}
+                        </subviews>
+                        <viewLayoutGuide key="safeArea" id="6Tk-OE-BBY"/>
+                        <color key="backgroundColor" red="${r}" green="${g}" blue="${b}" alpha="1" colorSpace="custom" customColorSpace="sRGB"/>
+                        <constraints>${imageConstraints}${logoConstraints}
+                        </constraints>
+                    </view>
+                </viewController>
+                <placeholder placeholderIdentifier="IBFirstResponder" id="iYj-Kq-Ea1" userLabel="First Responder" sceneMemberID="firstResponder"/>
+            </objects>
+            <point key="canvasLocation" x="53" y="375"/>
+        </scene>
+    </scenes>
+    <resources>${imageResources.join('\n        ')}
+    </resources>
+</document>`;
+}
+
 /**
  * Plugin to configure iOS splash screen
  */
@@ -319,9 +437,12 @@ const withSplashScreenIOS = (config, pluginConfig) => {
             const iosProjectPath = config.modRequest.platformProjectRoot;
             const projectName = config.modRequest.projectName;
 
+            let hasImage = false;
+            let hasLogo = false;
+
             // Copy images to iOS assets
             if (pluginConfig.image) {
-                await copyImageToIOS(
+                hasImage = await copyImageToIOS(
                     projectRoot,
                     pluginConfig.image,
                     'splash_image',
@@ -331,7 +452,7 @@ const withSplashScreenIOS = (config, pluginConfig) => {
             }
 
             if (pluginConfig.logo) {
-                await copyImageToIOS(
+                hasLogo = await copyImageToIOS(
                     projectRoot,
                     pluginConfig.logo,
                     'splash_logo',
@@ -340,6 +461,23 @@ const withSplashScreenIOS = (config, pluginConfig) => {
                 );
             }
 
+            // Create LaunchScreen.storyboard
+            const launchScreenPath = path.join(
+                iosProjectPath,
+                projectName,
+                'LaunchScreen.storyboard'
+            );
+
+            const storyboardContent = createLaunchScreenStoryboard(
+                hasImage,
+                hasLogo,
+                pluginConfig.backgroundColor
+            );
+
+            fs.writeFileSync(launchScreenPath, storyboardContent);
+
+            console.log('✅ iOS LaunchScreen.storyboard created with splash images!');
+
             return config;
         },
     ]);
@@ -349,7 +487,17 @@ const withSplashScreenIOS = (config, pluginConfig) => {
  * Main plugin export
  */
 module.exports = (config, props = {}) => {
-    const pluginConfig = props || getPluginConfig(config);
+    // Validate the props parameter
+    let pluginConfig;
+
+    if (props && Object.keys(props).length > 0) {
+        // Props provided directly (from array syntax)
+        pluginConfig = validateAndNormalizeConfig(props);
+    } else {
+        // Try to get from config (fallback)
+        pluginConfig = getPluginConfig(config);
+    }
+
 
     return withPlugins(config, [
         [withSplashScreenAndroid, pluginConfig],