@aguacerowx/react-native

Welcome to the official React Native SDK for AguaceroWX.

Installation

npm install @aguacerowx/react-native

Important Prerequisite: Mapbox SDK v11

This library is built on top of @rnmapbox/maps and requires the Mapbox Maps SDK v11 for both iOS and Android. You must perform the following manual setup steps to configure your project correctly.

iOS Setup

You must explicitly enable Mapbox SDK v11 in your iOS project.

Modify your Podfile

Open your project's ios/Podfile and add the following lines near the top of the file. This tells the @rnmapbox/maps library to use a v11 version of the native SDK.

# Add these lines near the top of your ios/Podfile
require_relative '../node_modules/@rnmapbox/maps/scripts/mapbox-rb'
$RNMapboxMapsVersion = '~> 11.0' # This enforces Mapbox SDK v11
use_mapbox_maps!

Enable Modular Headers (Required for New Architecture)

If you're using React Native's new architecture (newArchEnabled: true), you must enable modular headers.

For Expo Projects (Recommended)

If you're using Expo, add the expo-build-properties plugin to your app.config.js or app.config.ts:

npm install expo-build-properties

Then add it to your Expo config:

// app.config.ts
export default {
  // ... other config
  plugins: [
    // ... other plugins
    [
      'expo-build-properties',
      {
        ios: {
          useFrameworks: 'static',
          useModularHeaders: true,  // Add this line
        },
      },
    ],
  ],
};

Then run:

npx expo prebuild --clean

For Non-Expo React Native Projects

Option 1: Enable modular headers globally (Recommended)

Add this line after the platform :ios line in your ios/Podfile:

platform :ios, '13.4'
use_modular_headers!  # Add this line

prepare_react_native_project!

Option 2: Enable modular headers in post_install hook

Add this code inside your post_install do |installer| block:

post_install do |installer|
  # Enable modular headers for libzstd
  installer.pods_project.targets.each do |target|
    if target.name == 'libzstd'
      target.build_configurations.each do |config|
        config.build_settings['DEFINES_MODULE'] = 'YES'
      end
    end
  end
  
  # ... rest of your existing post_install code
end

Install Pods

After saving the Podfile, navigate to your ios directory in the terminal and run a fresh pod installation.

cd ios
pod install

Android Setup

Android requires configuration for Mapbox credentials and an additional native dependency.

Configure Mapbox Credentials

You will need a secret token with DOWNLOADS:READ scope and a public token.

In your android/gradle.properties file, add your secret token:

# android/gradle.properties
MAPBOX_DOWNLOADS_TOKEN=sk.xxxxxxxxxx

In your android/app/build.gradle file, add your public token inside the defaultConfig block:

// android/app/build.gradle
android {
    defaultConfig {
        // ... other configs
        buildConfigField "String", "MAPBOX_ACCESS_TOKEN", "\"pk.xxxxxxxxxx\""
    }
}

After completing these steps, your application should be correctly configured to use the library. For more detailed information or troubleshooting, please refer to the official @rnmapbox/maps documentation.

Weather models

Grid model keys are the same as aguacero-frontend (GFS, ICON, HRRR, ECMWF, ensembles, marine, air quality, and more). Import MODEL_CONFIGS from @aguacerowx/javascript-sdk, or see that package's MODELS.md catalog.

SPC Mesoscale Analysis is a first-class data type: switchMode({ mode: 'sfcoa', variable: 'cape_0' }) (see the javascript-sdk README).

Satellite

Satellite mode uses the same tiled catalog as aguacero.com: processing-info frames and BMX tiles. It does not use the old full-frame KTX files.

await weatherManager.switchMode({
  mode: 'satellite',
  satelliteId: 'GOES19-EAST',
  satelliteSector: 'GOES-EAST CONUS',
  satelliteProduct: 'C13',
});

setSatelliteSelection({ satelliteId, sector, satelliteProduct }) on AguaceroCore accepts the same ids. Short sector tokens (conus, pacific, m1, japan, rapid_scan, indian_ocean, q4) resolve to the labels below.

Import the lists from @aguacerowx/javascript-sdk: SATELLITE_INSTRUMENTS, SATELLITE_IMAGERY_CHANNELS, SATELLITE_L2_CHANNELS, GOES_SATELLITE_CHANNEL_LABELS.

Sectors

| Instrument id | Sectors | | --- | --- | | GOES19-EAST | GOES-EAST FULL DISK, GOES-EAST CONUS, GOES-EAST MESOSCALE 1, GOES-EAST MESOSCALE 2 | | GOES18-WEST | GOES-WEST FULL DISK, GOES-WEST PACIFIC, GOES-WEST MESOSCALE 1, GOES-WEST MESOSCALE 2 | | HIMAWARI9 | HIMAWARI FULL DISK, HIMAWARI JAPAN, HIMAWARI TARGET | | METEOSAT12 | EUMETSAT FULL DISK, EUMETSAT EUROPE, EUMETSAT AFRICA, EUMETSAT QUARTER 1, EUMETSAT QUARTER 2, EUMETSAT QUARTER 3 | | METEOSAT11 | EUMETSAT RAPID SCAN | | METEOSAT9 | EUMETSAT INDIAN OCEAN |

Europe and Rapid Scan use the mesoscale timeline (2 minutes). Full disk, Africa, and Indian Ocean use 10 minutes. CONUS, Pacific, Japan, and quarters 1–3 use 5 minutes.

Products

Imagery channels (SATELLITE_IMAGERY_CHANNELS) are C01–C16 plus the RGB recipes: true_color, false_color, natural_color, geocolor, overview, day_land_cloud_fire, day_cloud_phase, day_cloud_type, day_snow_fog, day_convection, day_microphysics, cloud_phase_eumetsat, sandwich, air_mass, tropical_airmass, dust, dust_cvd, volcanic_ash, so2, fire_temperature, microphysics_24h, ntmicro, blowing_snow, rocket_plume, simple_water_vapor, differential_water_vapor.

GOES Level-2 products (SATELLITE_L2_CHANNELS) match the website menus:

• Clouds: ACHA_HT, ACHP_PRES, ACTP_PHASE, ACM_BCM, ACM_PROB, CCL_TCF, CCL_CL, CCL_CF1, CCL_CF2, CCL_CF3, CCL_CF4, CCL_CF5
• Fire: FDC_MASK, FDC_FRP, FDC_TEMP, FDC_AREA
• Stability: DSI_CAPE, DSI_LI, DSI_TT, DSI_KI, DSI_SI
• Atmosphere: TPW, AOD, ADP_SMOKE, ADP_DUST, RRQPE
• Land: LST, LSA, FSC

Level-2 products are GOES-East and GOES-West only. Himawari and Meteosat serve the imagery channels.

The native map draws single-band channels and Level-2 products with the same colormaps as the website. RGB recipes (GeoColor and the other composites) are rendered by @aguacerowx/mapsgl. The React Native map does not composite those recipes.

shaderSmoothingEnabled still controls satellite fill smoothing. onStateChange includes satelliteSource (the tiled frame list) and satelliteTimeToFileMap (timestamp → source key).

Smoothing

WeatherLayerManager exposes two different methods:

• setShaderSmoothing(enabled) — global. Updates AguaceroCore state and applies to the grid layer (spatial sampling), NEXRAD polar gate smoothing (nexradGateSmoothing), and satellite fill. This is the method to use for radar smoothing. It does not toggle colormap interpolation.
• setSmoothing(enabled) — grid layer only (GridRenderLayer). Type-checks, but does not reach NEXRAD or satellite.

shaderSmoothingEnabled is preserved across setNexradProduct / setNexradSite / setNexradTilt / switchMode. Each NEXRAD rebuild (product, site, or tilt) derives polar gate smoothing from that flag; colormap interpolation stays on its own setting. setShaderSmoothing is not required to re-apply gate smoothing. onStateChange reports the value in effect.