YouVersion Platform React SDK

https://github.com/youversion/platform-sdk-react
Admin
A comprehensive React SDK for integrating YouVersion Platform features into web applications,...
Tokens:47,230
Snippets:387
Trust Score:6.5
License:Apache-2.0
Update:1 month ago
Show doc for...
Tokens:
Raw
### Setup commands for YouVersion SDK demo

Source: https://github.com/youversion/platform-sdk-react/blob/main/examples/vite-react/README.md

Setup commands for the demo app. Copy the environment template, add your YouVersion App Key, optionally set locale and default language ID, then install dependencies and start the dev server.

```bash
cp .env.example .env.local
# Add your YouVersion App Key to .env.local
# Optional: VITE_YVP_LOCALE and VITE_YVP_DEFAULT_LANGUAGE_ID (e.g. es)
pnpm install
pnpm dev
```

--------------------------------

### Run example app with pnpm dev:web

Source: https://github.com/youversion/platform-sdk-react/blob/main/CONTRIBUTING.md

Starts the example app in watch mode for local development.

```bash
# Run the example app with watch mode
pnpm dev:web
```

--------------------------------

### Install @youversion/platform-core with pnpm

Source: https://github.com/youversion/platform-sdk-react/blob/main/packages/core/README.md

Install the SDK with pnpm. Requires an App Key from platform.youversion.com.

```bash
pnpm add @youversion/platform-core
```

--------------------------------

### Set up UI package environment

Source: https://github.com/youversion/platform-sdk-react/blob/main/CONTRIBUTING.md

Copies the example environment file for the UI package. Update the app key variable in the new .env.local file.

```bash
cp ./packages/ui/.env.example ./packages/ui/.env.local
```

--------------------------------

### Install @youversion/platform-react-hooks with pnpm

Source: https://github.com/youversion/platform-sdk-react/blob/main/packages/hooks/README.md

Install the package using pnpm. Requires an App Key from platform.youversion.com.

```bash
pnpm add @youversion/platform-react-hooks
```

--------------------------------

### Set up core package environment

Source: https://github.com/youversion/platform-sdk-react/blob/main/CONTRIBUTING.md

Copies the example environment file for the core package. Update the app key variable in the new .env.local file.

```bash
cp ./packages/core/.env.example ./packages/core/.env.local
```

--------------------------------

### Start Vite demo with pnpm --filter vite-react dev

Source: https://github.com/youversion/platform-sdk-react/blob/main/docs/cursor-cloud.md

Starts the Vite demo on 127.0.0.1:5173. The first command is the recommended way; the second is equivalent. Do not add an extra '--' before '--host' because Vite would then ignore the host flag and listen on localhost (often ::1 only), causing curl to fail.

```bash
pnpm --filter vite-react dev --host 127.0.0.1 --port 5173
```

```bash
pnpm --filter vite-react exec vite --host 127.0.0.1 --port 5173
```

--------------------------------

### Install @youversion/platform-react-ui with pnpm

Source: https://github.com/youversion/platform-sdk-react/blob/main/packages/ui/README.md

Installs the @youversion/platform-react-ui package for your project, enabling the use of pre-built Bible components.

```bash
pnpm add @youversion/platform-react-ui
```

--------------------------------

### Install @youversion packages with pnpm

Source: https://github.com/youversion/platform-sdk-react/blob/main/README.md

Install the three NPM packages from this monorepo. Use the UI components package for ready-to-use components, the hooks package for React hooks, and the core package for direct API access.

```bash
pnpm add @youversion/platform-react-ui
```

```bash
pnpm add @youversion/platform-react-hooks
```

```bash
pnpm add @youversion/platform-core
```

--------------------------------

### Clone and install dependencies

Source: https://github.com/youversion/platform-sdk-react/blob/main/CONTRIBUTING.md

Clones the repository and installs dependencies with pnpm. Requires Node.js >= 22.13.0 and pnpm >= 11.0.0.

```bash
git clone https://github.com/youversion/platform-sdk-react.git
cd platform-sdk-react

# Install dependencies
pnpm install
```

--------------------------------

### Usage example with YouVersionProvider and usePassage

Source: https://github.com/youversion/platform-sdk-react/blob/main/packages/hooks/README.md

Shows how to wrap your app with YouVersionProvider and use the usePassage hook to fetch a Bible passage. The provider's permittedVersionIds, excludedVersionIds, and permittedLanguageTags limit which Bible versions hooks will load.

```tsx
import { YouVersionProvider, usePassage } from '@youversion/platform-react-hooks';

// `permittedVersionIds`, `excludedVersionIds`, and `permittedLanguageTags`
// on the provider limit which Bible versions hooks will load.

function BibleVerse() {
  const { passage, loading } = usePassage({ versionId: 3034, usfm: 'JHN.3.16' });
  if (loading) return <div>Loading...</div>;
  return <div dangerouslySetInnerHTML={{ __html: passage?.content || '' }} />;
}

function App() {
  return (
    <YouVersionProvider
      appKey="YOUR_APP_KEY"
      permittedVersionIds={[111, 3034]}
      excludedVersionIds={[4212]}
      permittedLanguageTags={['en']}
    >
      <BibleVerse />
    </YouVersionProvider>
  );
}
```

--------------------------------

### Run local i18n and lint checks

Source: https://github.com/youversion/platform-sdk-react/blob/main/docs/i18n-guidelines.md

Run the i18n parity check, the hardcoded string lint for components, and the locale ownership gate self-test. The first command fails on missing or extra translation keys, interpolation token mismatches, and unregistered locale files; it only warns on missing upstream-owned keys and orphan en keys. The second lints components only, and the third runs a bash-only self-test with no install required.

```bash
pnpm check:i18n
```

```bash
pnpm lint
```

```bash
pnpm test:ci-scripts
```

--------------------------------

### Enable Corepack for pinned pnpm

Source: https://github.com/youversion/platform-sdk-react/blob/main/README.md

Enable Corepack once to get the pinned-pnpm guarantee. Note that Node 25+ no longer bundles Corepack, so on newer Node install it first with `npm install -g corepack` or rely on the pnpm fallback with a locally-installed pnpm that satisfies `engines.pnpm`.

```bash
corepack enable
```

--------------------------------

### Import React keys into platform-localization

Source: https://github.com/youversion/platform-sdk-react/blob/main/docs/i18n-guidelines.md

Run this command in the platform-localization repository to import existing React keys from the en.json file into platform-localization for the first time. The path points to the English locale bundle in this repo.

```bash
# In platform-localization
npm run import:react -- /path/to/platform-sdk-react/packages/ui/src/i18n/locales/en.json
```

--------------------------------

### Bundle size and tree-shaking commands (pnpm size, size:build, size:visualize, size:why, check:tree-shaking)

Source: https://github.com/youversion/platform-sdk-react/blob/main/CONTRIBUTING.md

Commands for bundle-size and tree-shaking analysis. Requires a full build first because size-limit and the tree-shaking fixture import from packages/*/dist. pnpm size:why is an alias for pnpm size:visualize because size-limit --why is unavailable with preset-small-lib. pnpm check:tree-shaking verifies single-symbol consumer bundles exclude unused-export sentinels and CI asserts package.json sideEffects.

```bash
pnpm build && pnpm size
```

```bash
pnpm size:build
```

```bash
pnpm size:visualize
```

```bash
pnpm size:why
```

```bash
pnpm check:tree-shaking
```

--------------------------------

### Server convenience wrapper for transformBibleHtml using jsdom

Source: https://github.com/youversion/platform-sdk-react/blob/main/packages/core/CLAUDE.md

Use the @youversion/platform-core/server entry point for server-side rendering. Requires installing jsdom as a dependency.

```typescript
// Server convenience (uses jsdom, requires: npm install jsdom)
import { transformBibleHtml } from '@youversion/platform-core/server';

const result = transformBibleHtml(html);
```

--------------------------------

### Use ApiClient and BibleClient with env values

Source: https://github.com/youversion/platform-sdk-react/blob/main/docs/cursor-cloud.md

Loads the core environment variables and uses them to create an ApiClient and BibleClient, then fetches a Bible passage. The runtime client reads only the config object you pass; test scripts load the env file via dotenv-cli. Auth/highlights also require a YouVersion account and a registered redirect URL (http://localhost:5173 for the demo).

```bash
set -a && . packages/core/.env.local && set +a
cd packages/core
```

```javascript
import { ApiClient, BibleClient } from '@youversion/platform-core';

const apiClient = new ApiClient({
  appKey: process.env.YVP_APP_KEY,
  apiHost: process.env.YVP_API_HOST,
});
const bibleClient = new BibleClient(apiClient);
await bibleClient.getPassage(3034, 'JHN.3.16', 'text');
```

--------------------------------

### Manual publishing workflow (emergency only)

Source: https://github.com/youversion/platform-sdk-react/blob/main/PUBLISHING.md

Manual publishing is not supported with trusted publishing and should only be used as an emergency fallback. Requires NPM account with publish access to @youversion scope and configured as a trusted publisher. Includes steps to create a changeset, version packages, build, and publish.

```bash
# 1. Create changeset
pnpm changeset

# 2. Version packages
pnpm version-packages

# 3. Build all packages
pnpm build

# 4. Publish (requires NPM authentication and account to be added as trusted publisher)
npm login
pnpm release
```

--------------------------------

### Build packages

Source: https://github.com/youversion/platform-sdk-react/blob/main/CONTRIBUTING.md

Builds all packages in dependency order, or specific packages with build:core and build:react.

```bash
pnpm build

# Build specific packages
pnpm build:core    # Build core
pnpm build:react   # Build React SDK (hooks + ui)
```
Tokens:
Raw