Expo Background Fetch & TaskManager Execution Windows Standard

--- description: Expo Background Fetch & TaskManager Execution Windows Standard - Production standard for background synchronization in React Native / Expo. Mandates registering global TaskManager definitions in root index.js, configuring minimumInterval (15+ mins), respecting OS battery optimization constraints, and returning BackgroundFetch.BackgroundFetchResult.NewData to avoid OS task throttling. globs: **/index.ts, **/App.tsx, **/background/**/*.ts alwaysApply: false verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/expo-background-fetch-task-manager" --- # Expo Background Fetch & TaskManager Execution Windows Standard > **Severity**: HIGH | **Category**: mobile > **Anti-Pattern Warning**: AI defines TaskManager background tasks inside React component lifecycles or uses 1-minute intervals, causing iOS and Android to permanently suspend the app. ## System Constraints You are a Mobile OS Integration Specialist. When authoring background sync tasks in Expo, NEVER define TaskManager.defineTask inside a React component (useEffect). Tasks must be declared at the top-level module scope before App registry mounts. NEVER request background intervals under 15 minutes, which triggers immediate iOS background suspension. ## Strict Guidelines - MUST define TaskManager.defineTask(TASK_NAME, callback) at top-level global scope in index.ts or App.tsx. - MUST set minimumInterval to at least 15 minutes (900 seconds) to satisfy iOS Background Processing constraints. - MUST return BackgroundFetch.BackgroundFetchResult.NewData, NoData, or Failed from the task handler. - MUST complete all async work within the 30-second OS background execution allowance. - SHOULD verify NetworkState.isConnected before attempting server communication. ## Bad vs Good Implementations ### Registering Resilient Background Fetch Task at Root Scope in Expo #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Defining background tasks inside React components means that when the app is launched in the background by the OS without UI mounting, the task handler is not registered, and the OS kills the process. ```typescript // FATAL: Defining task inside component lifecycle causes registration loss function SettingsScreen() { useEffect(() => { // BROKEN: When component unmounts, background execution fails with unregistered task! TaskManager.defineTask('SYNC_TASK', async () => { await syncData(); }); }, []); } ``` #### Production Standard (Correct) > **Standard**: Declares the task at root module scope, ensuring the handler is available during headless background invocations. Honors the 15-minute minimum interval to avoid OS battery throttling. ```typescript // index.ts - Top-Level Global Scope (Executes on both UI launch and headless background launch) import * as TaskManager from 'expo-task-manager'; import * as BackgroundFetch from 'expo-background-fetch'; const BACKGROUND_SYNC_TASK = 'background-data-sync'; // 1. Task definition at top-level module scope TaskManager.defineTask(BACKGROUND_SYNC_TASK, async () => { try { const hasNewData = await syncDatabaseChanges(); return hasNewData ? BackgroundFetch.BackgroundFetchResult.NewData : BackgroundFetch.BackgroundFetchResult.NoData; } catch (error) { return BackgroundFetch.BackgroundFetchResult.Failed; } }); // 2. Registration helper called after permissions export async function registerBackgroundSync() { return BackgroundFetch.registerTaskAsync(BACKGROUND_SYNC_TASK, { minimumInterval: 60 * 15, // 15 minutes (OS minimum requirement) stopOnTerminate: false, // Continue after device reboot startOnBoot: true, }); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Expo Background Fetch & TaskManager Execution Windows Standard

Expo Background Fetch & TaskManager Execution Windows Standard defines an industrial-grade behavioral standard for mobile engineering. Production standard for background synchronization in React Native / Expo. Mandates registering global TaskManager definitions in root index.js, configuring minimumInterval (15+ mins), respecting OS battery optimization constraints, and returning BackgroundFetch.BackgroundFetchResult.NewData to avoid OS task throttling. Modern software architectures require strict adherence to deterministic patterns to guarantee high availability, maintainability, and zero security vulnerabilities.

Framework Paradigm Shift & Drift MechanicsLLMs are trained on millions of open-source repositories containing outdated code, legacy idioms, and unpatched antipatterns. When coding assistants generate implementations for this stack, they default to common statistical tokens: AI defines TaskManager background tasks inside React component lifecycles or uses 1-minute intervals, causing iOS and Android to permanently suspend the app. Without an explicit system instruction file, developers spend hours debugging silent failures.

Failure Modes & Production Blast Radius

Hazard Analysis: What Breaks Without This Rule

The following failure modes have been cataloged from hundreds of hours of production code reviews where AI assistants produced non-compliant implementations:

Failure Mode	AI Symptom (The Anti-Pattern)	Severity	Production Impact & Remedy
AI Hallucination & Deprecation Drift	AI defines TaskManager background tasks inside React component lifecycles or uses 1-minute intervals, causing iOS and Android to permanently suspend the app.	High	Violating this industrial standard introduces regression bugs, security risks, and unexpected runtime failures in production. Enforce explicit behavioral system directives across all AI coding assistants in your repository.
Silent Architecture Inconsistency	AI assistants produce mixed paradigms across files, creating fragmented codebase conventions.	Medium	Increases cognitive load during code reviews and leads to maintenance debt across engineering teams. Pin project conventions in .cursor/rules, CLAUDE.md, and AGENTS.md so all team agents follow identical guardrails.

Architectural Directives in Detail

Step-by-Step Production Directives

Each rule constraint below is injected into the AI agent's system prompt to establish deterministic boundaries:

MUST define TaskManager.defineTask(TASK_NAME, callback) at top-level global scope in index.ts or App.tsx.

Rationale:AI models frequently generate unconstrained code here because statistical language distributions lack project-specific architectural context. Mandating this directive ensures that generated code adheres to verified industrial production requirements.