Skip to content
Extra-ChillPublic

About

Turn any WordPress site into a React Native app.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

wp-native

Build decoupled applications on WordPress abilities. wp-native-client is a universal TypeScript client for discovering and executing the Abilities API from Gutenberg blocks, browsers, React Native, and Node. wp-native-shell adds an Expo/React Native app shell, wp-native-gutenberg embeds GutenbergKit, and the wp-native-auth plugin provides generic token authentication for headless clients.

WordPress owns the behavior, schemas, data, and permissions. Each consumer owns its UI. The same ability can therefore power a Gutenberg block, a native screen, or another headless application without putting site-specific knowledge into this framework.

Status

Pre-1.0. APIs may still change before 1.0. Current versions are on npm: wp-native-client, wp-native-shell. wp-native-gutenberg is unpublished until GutenbergKit's license is clarified (see its README). wp-native-auth ships as a WordPress plugin from plugins/wp-native-auth.

Production consumers:

Quick install

# React Native app (the common case)
npm install wp-native-shell wp-native-client

# Add the GutenbergKit block editor to an Expo app
npm install wp-native-gutenberg

# Gutenberg blocks or Node scripts (no React Native)
npm install wp-native-client

Peer dependencies (for wp-native-shell):

  • react >= 19
  • react-native >= 0.80
  • expo-router >= 6
  • react-native-gesture-handler >= 2

The client requires the Abilities API available in WordPress 6.9+. Install wp-native-auth when a headless client needs its token lifecycle; same-origin Gutenberg consumers can instead use WordPress's existing cookie and nonce authentication.

Hello world

wp-native-shell provides context providers and an auth gate. Your consumer app owns the navigation via expo-router's filesystem routing.

// app/_layout.tsx
import { Slot } from 'expo-router';
import { WPNativeApp } from 'wp-native-shell';
import type { WPNativeConfig } from 'wp-native-shell';

const config: WPNativeConfig = {
  api: {
    baseUrl: 'https://example.com/wp-json',
    clientId: 'example-app',
  },
  tokenStorage: {
    // Plug in your RN storage adapter (expo-secure-store, MMKV, etc.)
    getItem: async (_key) => null,
    setItem: async (_key, _value) => {},
    removeItem: async (_key) => {},
  },
  navigation: {
    sections: [
      { id: 'feed', label: 'Feed', ability: 'wp/post.list' },
    ],
  },
};

export default function RootLayout() {
  return (
    <WPNativeApp config={config} loginScreen={LoginScreen}>
      <Slot />
    </WPNativeApp>
  );
}

<WPNativeApp> composes (outer to inner): ThemeProvider > AuthProvider > NavigationConfigProvider > BrowserHandoffProvider > AuthGate > {children}. The auth gate renders your loginScreen when logged out, a loading fallback during token initialization, and children (your expo-router <Slot/>) when authenticated.

The consumer mounts the drawer and section screens via expo-router's filesystem — see the shell contract for the full pattern.

Architecture

For a React Native consumer, the layers compose as follows:

┌─────────────────────────────────────────────────────────────┐
│              Consumer App (React Native + expo-router)      │
│                                                             │
│   <WPNativeApp config={...}>{<Slot/>}</WPNativeApp>         │
│   Consumer owns routes, drawer layout, screens              │
└────────────────────┬────────────────────────────────────────┘
                     │
                     ▼
┌─────────────────────────────────────────────────────────────┐
│                  wp-native-shell                            │
│   Context providers (auth, theme, navigation, handoff),     │
│   AuthGate, DrawerContent slot, generic ability-driven      │
│   screens (AbilityList, AbilityDetail, SectionScreen)       │
└─────┬───────────────────────────────────────┬───────────────┘
      │                                       │
      ▼                                       ▼
┌──────────────────┐               ┌──────────────────────────┐
│ wp-native-client │               │   wp-native-auth         │
│                  │ ◄── talks to ─►   (WordPress plugin)     │
│ Universal client │   WordPress   │                          │
│   • discover()   │               │   9 abilities:           │
│   • execute()    │               │   login, continue-login, │
│   • auth         │               │   register, refresh,     │
│                  │               │   logout, me, sessions,  │
│ Three transports │               │   revoke, browser-handoff│
│   • FetchTransport               │                          │
│   • AuthFetchTransport           │   Token lifecycle,       │
│   • WpApiFetchTransport          │   device sessions,       │
│     (Gutenberg)  │               │   refresh rotation       │
└──────────────────┘               └──────────────────────────┘

The client doesn't know what abilities exist on a given WordPress site — it asks. client.discover() fetches the site's ability catalog, including input/output schemas and behavioral annotations. client.execute('ability-name', args) invokes any ability by name. For routes that aren't abilities yet, such as multipart uploads, client.request() calls a plain REST route through the same transport and auth. Site-specific names live in consumer configuration and code, never in wp-native-client.

The transport depends on the consumer:

  • WpApiFetchTransport wraps @wordpress/api-fetch for Gutenberg and other same-origin WordPress interfaces.
  • AuthFetchTransport manages access/refresh tokens for React Native and other headless clients.
  • FetchTransport supports public abilities or externally managed authentication in browsers and Node.

Project layout

wp-native/
├── packages/
│   ├── shell/          wp-native-shell — React Native app shell
│   ├── api-client/     wp-native-client — universal abilities client
│   ├── gutenberg/      wp-native-gutenberg — GutenbergKit Expo bridge
│   ├── meta/           wp-native — meta package (redirects to the real ones)
│   └── theme/          Design token primitives
├── plugins/
│   └── wp-native-auth/ WordPress plugin — token auth (9 abilities)
└── docs/               Roadmap + audit docs

Documentation

The in-repo contract files are the deep-dive material for each topic:

Document What it covers
SHELL.md Full shell surface — auth, theme, navigation, app composition, browser handoff
SCREENS.md Generic ability-driven screens — AbilityList, AbilityDetail, adapters
EXPO-ROUTER-REBASE.md Architecture decision record for the expo-router migration
SCHEMAS.md All 9 auth abilities — input/output schemas, error codes, extension hooks
ROADMAP.md Current state, architectural principles, and next milestones
EC-ABILITIES-AUDIT.md Historical Extra Chill ability inventory that informed the initial migration

Compatibility

Dependency Minimum version
WordPress 6.9+ (Abilities API)
React >= 19
React Native >= 0.80
expo-router >= 6
react-native-gesture-handler >= 2

Releasing

Releases are automated, and nobody tags or publishes by hand.

  • Merges to main use conventional commits. fix: cuts a patch, feat: a minor, and a breaking change a major.
  • .github/workflows/release.yml runs Homeboy's release workflow on every merge. For each package whose files changed (packages/*/homeboy.json), it bumps the version, writes the CHANGELOG, tags <package>-v<version>, creates a GitHub release, and publishes to npm.
  • npm authenticates through Trusted Publishing (GitHub OIDC), so no npm token is stored anywhere. Each package needs a one-time trust entry on npm: npm trust github <package> --repo Extra-Chill/wp-native --file release.yml --yes (npm 11.10+).
  • To release a single package with an explicit bump, run the Release workflow manually with component and bump. Use dry-run to preview.
  • CHANGELOGs and version fields are owned by the release workflow. Don't edit them in PRs.
  • wp-native-gutenberg is "private": true and is never published until its license question is settled.

License

MIT

About

Turn any WordPress site into a React Native app.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages