agentleFS
fatihkanfatihkan/badi/.claude/skills-vault/expo-notifications/SKILL.md

expo-notifications

Skill8 starsChanged 3 months agoMITView on GitHub

expo-notifications setup, push tokens, FCM + APNs credentials, categories, scheduled notifications, channels, and the permission flow. Triggers on expo-notifications, push notification, fcm, apns, push token, notification permission, notification channel, notification category, action button, scheduled notification, local notification, badge, silent push.

  • Sends data out

The file

We split this skill into the rules it gives an agent

2 rules. About 0 are common, 2 are distinctive, and 0 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈2

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 0

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Permission-request timing: when the feature needs it, not right when the app opens

    line 240
  2. Distinctive:

    No channel → Android 8+ silently drops it

    line 252

≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

expo-notifications

Push and local notification setup with expo-notifications. iOS (APNs) + Android (FCM) credentials, permission flow, channels (Android 8+), categories, and scheduled notifications.

What It Does

  • expo-notifications setup and permission request
  • Getting the Expo Push Token + sending it to the backend
  • iOS APNs Auth Key and Android FCM Service Account
  • Notification categories + action buttons
  • Scheduled / repeating notifications
  • Channels (Android 8+) and importance levels
  • Background notification handler and silent push

Setup

npx expo install expo-notifications expo-device expo-constants

app.json:

{
  "expo": {
    "plugins": [
      ["expo-notifications", {
        "icon": "./assets/notification-icon.png",
        "color": "#ffffff",
        "sounds": ["./assets/notification-sound.wav"]
      }]
    ],
    "ios": {
      "infoPlist": {
        "UIBackgroundModes": ["remote-notification"]
      }
    },
    "android": {
      "googleServicesFile": "./google-services.json"
    }
  }
}

Permission + Token

import * as Notifications from "expo-notifications";
import * as Device from "expo-device";
import Constants from "expo-constants";
import { Platform } from "react-native";

Notifications.setNotificationHandler({
  handleNotification: async () => ({
    shouldShowAlert: true,
    shouldPlaySound: true,
    shouldSetBadge: true,
  }),
});

export async function registerForPushNotificationsAsync(): Promise<string | undefined> {
  if (!Device.isDevice) {
    console.warn("Push notifications require a physical device");
    return;
  }

  if (Platform.OS === "android") {
    await Notifications.setNotificationChannelAsync("default", {
      name: "Default",
      importance: Notifications.AndroidImportance.MAX,
      vibrationPattern: [0, 250, 250, 250],
      lightColor: "#FF231F7C",
    });
  }

  const { status: existing } = await Notifications.getPermissionsAsync();
  let finalStatus = existing;
  if (existing !== "granted") {
    const { status } = await Notifications.requestPermissionsAsync();
    finalStatus = status;
  }
  if (finalStatus !== "granted") return;

  const projectId = Constants.expoConfig?.extra?.eas?.projectId;
  const token = (await Notifications.getExpoPushTokenAsync({ projectId })).data;
  return token;
}

iOS APNs Credentials

Via EAS:

eas credentials -p ios
# > Push Notifications: Setup
# > APNs Auth Key (.p8)

App Store Connect > Keys > APNs Auth Key:

  • A single key can be used across all apps
  • Downloadable once — keep a backup

Android FCM Credentials

# 1. Firebase Console > Project Settings > Service Accounts
# 2. "Generate new private key" → download google-services.json
# 3. Put it at the project root
# 4. eas credentials -p android > Service Account upload

app.json:

{
  "android": { "googleServicesFile": "./google-services.json" }
}

ADD google-services.json to .gitignore (don't commit it; inject via EAS Secrets or CI).

Local & Scheduled Notification

// Immediately
await Notifications.scheduleNotificationAsync({
  content: { title: "Test", body: "Hello", sound: true },
  trigger: null,
});

// after 60 s
await Notifications.scheduleNotificationAsync({
  content: { title: "Reminder", body: "Drink some water" },
  trigger: { seconds: 60 },
});

// Specific time
await Notifications.scheduleNotificationAsync({
  content: { title: "Morning" },
  trigger: { hour: 9, minute: 0, repeats: true },
});

// Calendar trigger (iOS only, advanced)
await Notifications.scheduleNotificationAsync({
  content: { title: "Monday" },
  trigger: { weekday: 2, hour: 9, minute: 0, repeats: true },
});

Categories + Action Buttons

await Notifications.setNotificationCategoryAsync("message", [
  {
    identifier: "reply",
    buttonTitle: "Reply",
    textInput: { submitButtonTitle: "Send", placeholder: "Message..." },
  },
  {
    identifier: "mark_read",
    buttonTitle: "Mark read",
    options: { opensAppToForeground: false },
  },
]);

await Notifications.scheduleNotificationAsync({
  content: { title: "New message", body: "...", categoryIdentifier: "message" },
  trigger: null,
});

Action handler:

Notifications.addNotificationResponseReceivedListener((response) => {
  const action = response.actionIdentifier;
  const userInput = (response as any).userText;
  // ...
});

Android Channels (8+)

await Notifications.setNotificationChannelAsync("messages", {
  name: "Messages",
  importance: Notifications.AndroidImportance.HIGH,
  vibrationPattern: [0, 250, 250, 250],
  lightColor: "#FF231F7C",
  sound: "default",
});

await Notifications.setNotificationChannelAsync("silent", {
  name: "Silent notifications",
  importance: Notifications.AndroidImportance.LOW,
});

A channel is MANDATORY for Android 8+. Without a channel, notifications aren't shown.

Sending a Push (Expo Push Service)

curl -X POST https://exp.host/--/api/v2/push/send \
  -H "Content-Type: application/json" \
  -d '{
    "to": "ExponentPushToken[xxx]",
    "title": "Hello",
    "body": "Test",
    "sound": "default",
    "categoryId": "message",
    "data": { "screen": "/posts/42" }
  }'

Backend SDK: expo-server-sdk (Node.js).

Deep Link via Notification

const responseListener = Notifications.addNotificationResponseReceivedListener((res) => {
  const path = res.notification.request.content.data?.screen;
  if (path) router.push(path);
});

Best Practices

  • Permission-request timing: when the feature needs it, not right when the app opens
  • Always set up channels (Android 8+)
  • Silent push for badge updates (contentAvailable: true)
  • Listen for token refresh: addPushTokenListener
  • Store the token on the backend (user + device key)
  • Test device: a real device is required (simulators don't receive push)
  • Define sound files in the plugin so they're embedded in the build

Common Failure Patterns

  • iOS push not arriving: APNs Auth Key missing, no "Push Notifications" capability
  • Android push not arriving: google-services.json missing, FCM Service Account wrong
  • No channel → Android 8+ silently drops it
  • No UIBackgroundModes: ["remote-notification"] → silent push won't arrive
  • In production, Notifications.scheduleNotificationAsync with { seconds: 1 } instead of trigger: null → safer
  • Permission request flood → the user denies; tell them to re-enable it manually

Hard Refusal

  • Permission abuse without user consent (asking every hour)
  • Spam/misleading push content (ASC + Play Store rule)
  • Sending health/finance data in an unencrypted push payload
  • Forcing marketing push with no opt-out
  • Cross-referencing a tracking ID with the push token (GDPR)

Output Format

  1. Setup commands (copy-paste)
  2. Permission flow code
  3. iOS + Android credentials steps
  4. Channel and category setup
  5. Test command (curl)
  6. Risk: permission abuse, store rule

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.