Adding Home-Screen Quick Actions to a Rork App — dynamic items without cold-launch drops

Unify iOS and Android with expo-quick-actions

A standard Rork app is generated as React Native (Expo), so expo-quick-actions lets you handle iOS UIApplicationShortcutItem and Android App Shortcuts through one API. First, registering dynamic items.

// quickActions.ts
import * as QuickActions from 'expo-quick-actions';
import { Platform } from 'react-native';
 
export async function setQuickActions(isLoggedIn: boolean) {
  const items = [
    {
      id: 'new-entry',
      title: 'New Entry',
      icon: Platform.OS === 'ios' ? 'symbol:square.and.pencil' : 'shortcut_new',
      params: { route: '/entry/new' }, // carry the destination in params
    },
  ];
 
  if (isLoggedIn) {
    items.push({
      id: 'resume-last',
      title: 'Resume',
      icon: Platform.OS === 'ios' ? 'symbol:arrow.uturn.left' : 'shortcut_resume',
      params: { route: '/entry/last' },
    });
  }
 
  await QuickActions.setItems(items);
}

Carrying the destination route in params is the key. Rather than a switch per action type, writing "where to go" into the item itself keeps the receiving side simple as items grow.

Prevent cold-launch drops with hold-and-replay

This is the center of the design. An action arrives in two ways.

On a cold launch the first action sits in QuickActions.initial. You read it at startup, but at that instant navigation usually isn't ready. So make it "hold, then replay once the router is ready."

// useQuickActionRouting.ts
import { useEffect, useRef } from 'react';
import * as QuickActions from 'expo-quick-actions';
import { router } from 'expo-router';
 
export function useQuickActionRouting(isRouterReady: boolean) {
  const pending = useRef<string | null>(null);
 
  // Shared handler: hold or run immediately
  const handle = (action: QuickActions.Action | null) => {
    const route = action?.params?.route as string | undefined;
    if (!route) return;
    if (isRouterReady) {
      router.push(route);
    } else {
      pending.current = route; // can't navigate yet, so hold
    }
  };
 
  // The initial action on cold launch (once)
  useEffect(() => {
    handle(QuickActions.initial ?? null);
    const sub = QuickActions.addListener(handle); // warm launch
    return () => sub.remove();
  }, []);
 
  // Replay the held action the moment the router becomes ready
  useEffect(() => {
    if (isRouterReady && pending.current) {
      router.push(pending.current);
      pending.current = null;
    }
  }, [isRouterReady]);
}

Pass isRouterReady something that means "safe to navigate" — auth resolved, layout mounted. Holding the cold-launch action in pending and replaying it exactly once in the readiness useEffect was the reliable way to avoid drops.

Suppress duplicate firing and double navigation

In practice, right after reading initial on a cold launch, the listener would also deliver the same action, navigating to the same screen twice. To prevent this, remember the processed action IDs.

const consumed = useRef<Set<string>>(new Set());
 
const handle = (action: QuickActions.Action | null) => {
  if (!action) return;
  const key = `${action.id}:${action.params?.route}`;
  if (consumed.current.has(key)) return; // ignore if already processed
  consumed.current.add(key);
  // ...navigation
};

Keying on the ID alone would ignore a deliberate second tap of the same item, so combining it with route was safer. It also handles repeated invocations on warm launch naturally.

Don't leave stale dynamic items behind

Dynamic items need updating when app state changes. Two things that paid off in practice:

• Clear dynamic items on logout. If "Resume" lingers and a different account logs in, it jumps to the previous user's data. Reset to a minimal static-equivalent set in your logout flow with setItems
• Track data deletion. If the record "Resume" points to is deleted, either remove that dynamic item or provide a fallback at the destination for "no longer exists"

// Reset dynamic items to the initial state on logout
async function onLogout() {
  await setQuickActions(false); // drop login-dependent items
}

Quick actions aren't a flashy feature, but being able to call a frequent operation in one move quietly raises how often it's used. The hard part of the implementation isn't the feature itself — it's the receiving-side design that doesn't drop the action arriving on cold launch. Build the three carefully — hold-and-replay, duplicate suppression, and state-aware cleanup — and you get a path that works reliably as a pre-launch move. I hope it helps anyone tackling the same problem.