ExpoUploadDemo

Project Description

This is a standalone native Expo module designed to test Flickr photo upload functionality with background processing capabilities. The module implements native background services to handle photo uploads even when the app is not in the foreground, ensuring reliable and efficient media uploads.

This module is packaged as an npm package, allowing any Expo project to easily integrate Flickr background upload functionality by simply installing the package.

Key Features

• Background Photo Upload: Utilizes native background services to upload photos to Flickr
• Android Implementation: Uses WorkManager for reliable background task execution
• iOS Implementation: Leverages URLSession background transfers for reliable uploads
• Native Platform Support: Supports Android and iOS platforms only (web is not supported)
• Expo Integration: Built as an Expo module for easy integration into React Native projects

iOS Implementation (Recommended Approach)

URLSession Background Transfers

The iOS implementation uses URLSession created with URLSessionConfiguration.background(withIdentifier:) to handle background uploads:

Key Features:

• Uploads continue running even if the app is backgrounded or killed
• The system automatically relaunches your app to deliver completion events
• Must upload from a file URL (not in-memory Data)
• For multipart uploads, the body is streamed/written to a temporary file first

Network Configuration:

• allowsConstrainedNetworkAccess - Control uploads on constrained networks
• allowsExpensiveNetworkAccess - Manage uploads on expensive connections
• isDiscretionary - Allow system to optimize transfer timing
• waitsForConnectivity - Wait for network availability

Session Reconnection:

• Reconnect to the session after relaunch using the same identifier
• Handle background events in: application(_:handleEventsForBackgroundURLSession:completionHandler:)

Purpose

This module serves as a testing ground for implementing robust background upload functionality, specifically targeting Flickr's API. It demonstrates best practices for handling long-running upload tasks that need to continue executing even when the user switches apps or the device goes to sleep.

Installation

Note: This module only supports iOS and Android. Web platform is not supported.

npm install expo-upload-demo

or

yarn add expo-upload-demo

After installation, rebuild your native projects:

npx expo prebuild --clean

Platform Compatibility

| Platform | Support | |----------|---------| | iOS | ✅ Yes | | Android | ✅ Yes | | Web | ❌ No |

This module will throw an error if imported on web platform.

Usage

// Recommended: Use the named export for better auto-imports
import { ExpoUploadDemo } from 'expo-upload-demo';

// Alternative named imports (all work the same)
import { ExpoUploadDemoModule, ExpoUploadDemoView } from 'expo-upload-demo';

// Default import (backward compatibility)
import ExpoUploadDemoModule from 'expo-upload-demo';

// Example usage
const greeting = ExpoUploadDemoModule.hello();
// or
const greeting = ExpoUploadDemo.hello();

// TODO: Add more usage examples once the API is finalized

Troubleshooting Auto-Import

If TypeScript auto-import doesn't suggest the module:

1. Update to the latest version:

   npm install expo-upload-demo@latest

2. Restart TypeScript Server in VS Code:

   • Press Cmd+Shift+P (Mac) or Ctrl+Shift+P (Windows/Linux)
   • Type "TypeScript: Restart TS Server"
   • Press Enter

3. Clear your project's TypeScript cache:

   # Delete node_modules and reinstall
   rm -rf node_modules
   npm install

4. Rebuild native code:

   npx expo prebuild --clean

5. Manually add the import once, and IntelliSense should remember it for future use:

   import { ExpoUploadDemo } from 'expo-upload-demo';
   // or
   import { ExpoUploadDemoModule } from 'expo-upload-demo';

Development

To work on this module locally:

# Install dependencies
npm install

# Build the module
npm run build

# Run the example app
cd example
npm install
npx expo run:ios
# or
npx expo run:android

Testing Locally Before Publishing

Method 1: Using npm pack (Recommended)

This method creates a tarball file that closely simulates installing from npm.

Step 1: Create the Package File

In your module directory:

cd /path/to/expo-upload-demo-module

# Build the module first
npm run build

# Create a tarball (.tgz file)
npm pack

This creates a file like: expo-upload-demo-0.1.3.tgz

Step 2: Install in Your Expo Project

cd /path/to/your/expo/project

# Install from the local .tgz file (use absolute path)
npm install /path/to/expo-upload-demo-module/expo-upload-demo-0.1.3.tgz

# Or use relative path if projects are nearby
npm install ../expo-upload-demo-module/expo-upload-demo-0.1.3.tgz

# Rebuild native code
npx expo prebuild --clean

# Run your app
npx expo run:ios
# or
npx expo run:android

Step 3: Test Changes

When you make changes to the module:

# In module directory
npm run build && npm pack

# In your Expo project
npm install /path/to/expo-upload-demo-0.1.3.tgz --force
npx expo prebuild --clean

Pros: Closest to real npm install experience
Cons: Need to reinstall after each change

Method 2: Using npm link (For Active Development)

This method creates a symlink for faster iteration during development.

Step 1: Create a Global Link

In your module directory:

cd /path/to/expo-upload-demo-module

# Build the module
npm run build

# Create a global symlink
npm link

You should see output like: ...global/node_modules/expo-upload-demo -> ...

Step 2: Link in Your Expo Project

cd /path/to/your/expo/project

# Link to the global package
npm link expo-upload-demo

# Rebuild native code
npx expo prebuild --clean

# Run your app
npx expo run:ios
# or
npx expo run:android

Step 3: Develop with Auto-Updates

When you make changes to the module:

# In module directory
npm run build

# The changes are automatically available in your linked Expo project
# You may need to restart the Metro bundler

Step 4: Unlink When Done

# In your Expo project
cd /path/to/your/expo/project
npm unlink expo-upload-demo

# Install from npm instead
npm install expo-upload-demo

To remove the global link:

# In module directory
cd /path/to/expo-upload-demo-module
npm unlink

Pros: Fast iteration, no reinstall needed
Cons: Can cause module resolution issues, not production-like

Which Method Should You Use?

| Method | Best For | When to Use | |--------|----------|-------------| | npm pack | Final testing before publish | Testing the exact package that will be published | | npm link | Active development | Rapid iteration while developing features |

Recommendation: Use npm link during development, then test with npm pack before publishing to npm.

Publishing to npm

This package is published to npm. Follow these steps to publish a new version:

Step 1: Prepare Your npm Account

# Create an npm account at https://www.npmjs.com/signup if you don't have one

# Login to npm from the terminal
npm login
# Enter your username, password, and email when prompted

Step 2: Update Version Number

Update the version in package.json following Semantic Versioning:

# For a patch release (bug fixes): 0.1.0 -> 0.1.1
npm version patch

# For a minor release (new features): 0.1.0 -> 0.2.0
npm version minor

# For a major release (breaking changes): 0.1.0 -> 1.0.0
npm version major

Or manually edit the version in package.json:

{
  "version": "0.1.0"  // Update this
}

Step 3: Build the Module

# Clean previous builds
npm run clean

# Build the module (compiles TypeScript)
npm run build

Step 4: Test Locally (Optional but Recommended)

# Create a tarball to test the package
npm pack

# This creates a file like expo-upload-demo-0.1.0.tgz
# Install it in a test project:
# npm install /path/to/expo-upload-demo-0.1.0.tgz

Step 5: Publish to npm

# Publish the package (prepublishOnly script runs automatically)
npm publish

# For first-time public packages, you might need:
npm publish --access public

Step 6: Verify Publication

# Check your package on npm
npm view expo-upload-demo

# Or visit: https://www.npmjs.com/package/expo-upload-demo

Step 7: Commit and Tag (Recommended)

# Commit the version change
git add package.json
git commit -m "Bump version to 0.1.0"

# Create a git tag
git tag v0.1.0

# Push to repository
git push origin main --tags

Publishing Checklist

Before publishing, ensure:

• ✅ package.json has correct version, description, and repository
• ✅ README.md is up to date with usage instructions
• ✅ LICENSE file exists
• ✅ Code builds without errors (npm run build)
• ✅ You're logged into npm (npm whoami)
• ✅ .npmignore excludes unnecessary files
• ✅ All changes are committed to git

Updating an Existing Package

To publish updates:

# 1. Make your changes to the code

# 2. Update version
npm version patch  # or minor/major

# 3. Build
npm run build

# 4. Publish
npm publish

# 5. Push to git
git push origin main --tags