### Run Next.js Development Server

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

Starts the Next.js development server to run the example application. This can be initiated from the monorepo root or the specific example directory.

```bash
pnpm dev:web
# or
npm run dev
# or
pnpm dev
```

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

### Install Dependencies with pnpm

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

Installs project dependencies using pnpm, a fast, reliable, and efficient package manager for Node.js.

```bash
pnpm install
```

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

### Install @youversion/platform-react-ui Package

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

This command installs the `@youversion/platform-react-ui` package using pnpm. Ensure you have pnpm installed and configured to add the package to your project.

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

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

### Install @youversion/platform-core Package

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

Installs the @youversion/platform-core package using pnpm. This is the first step to integrating the YouVersion Platform SDK into your project.

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

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

### Next.js Main Page with Example Components

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

Renders the main page of the Next.js example application, demonstrating the use of components from the YouVersion Platform React UI package.

```typescript
import {
  BibleVerseDisplay,
  BibleSearch,
  ChapterNavigation,
} from "@youversion/platform-react-ui";

export default function Home() {
  return (
    <main className="container mx-auto p-4">
      <h1 className="text-3xl font-bold mb-6">Bible Explorer</h1>

      <div className="mb-8">
        <h2 className="text-2xl font-semibold mb-4">Verse Display</h2>
        <BibleVerseDisplay verseRef="GEN.1.1" />
      </div>

      <div className="mb-8">
        <h2 className="text-2xl font-semibold mb-4">Bible Search</h2>
        <BibleSearch />
      </div>

      <div className="mb-8">
        <h2 className="text-2xl font-semibold mb-4">Chapter Navigation</h2>
        <ChapterNavigation passageReference="PSALM.23" />
      </div>
    </main>
  );
}
```

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

### Configure Environment Variables for YouVersion Platform

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

Copies the environment variable template and prompts the user to add their YouVersion Platform application key.

```bash
cp .env.example .env.local
NEXT_PUBLIC_YVP_APP_KEY=your_APP_KEY_here
```

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

### TypeScript Configuration Example (tsup)

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

Example of how TypeScript is configured for bundling packages using tsup. This configuration ensures efficient and correctly structured output for published packages.

```javascript
// Example tsup.config.js (details may vary)
import { defineConfig } from 'tsup';

export default defineConfig({
  entry: ['src/index.ts'],
  format: ['cjs', 'esm'],
  dts: true, // Generates .d.ts files
  splitting: true,
  clean: true,
  external: ['react', 'react-dom'], // Example externals
});

```

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

### TypeScript Configuration Example

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

Example of a TypeScript configuration file, likely located in the tools/tsconfig/ directory for shared configurations.

```json
{
  "compilerOptions": {
    "target": "es2018",
    "module": "esnext",
    "lib": ["dom", "dom.iterable", "esnext"],
    "jsx": "react-jsx",
    "declaration": true,
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "isolatedModules": true,
    "noEmit": true,
    "noUnusedLocals": true,
    "noUnusedParameters": true
  },
  "include": ["src"],
  "exclude": ["node_modules", "dist"]
}
```

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

### Start Development Environment (pnpm)

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

Commands to initiate the development server for specific parts of the SDK. The `dev:web` command is used for React SDK development.

```bash
pnpm dev:web
```

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

### Manual Package Publishing Steps

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

A sequence of commands for manually publishing packages from a local machine, intended for emergency use only. Requires NPM account access and prior configuration as a trusted publisher.

```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
```

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

### Lint-staged Configuration Example

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

Configuration for lint-staged, specifying which linters and formatters to run on staged files. Includes ESLint and Prettier.

```json
{
  "*.{js,jsx,ts,tsx}": [
    "eslint --fix",
    "prettier --write"
  ],
  "*.{json,css,scss,md}": [
    "prettier --write"
  ]
}
```

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

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

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

Installs the @youversion/platform-react-hooks package using pnpm. This is the primary step to begin using the package in your React project.

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

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

### Install YouVersion Platform React SDK Packages

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

Installs the necessary YouVersion Platform React SDK packages (UI components, hooks, or core API) using pnpm. Ensure Node.js version is >= 20.0.0.

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

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

### Setup YouVersionProvider for React Hooks (TypeScript)

Source: https://context7.com/youversion/platform-sdk-react/llms.txt

Wraps the root of a React application with the YouVersionProvider to make the YouVersion API client available to descendant components via React hooks. This setup is necessary for using hooks from the '@youversion/platform-react-hooks' package. Requires an application key.

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

function App() {
  return (
    <YouVersionProvider appKey="YOUR_APP_KEY">
      <YourComponents />
    </YouVersionProvider>
  );
}
```

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

### Build Specific Packages

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

Builds individual packages within the monorepo. Examples include 'core' and 'react' SDK.

```bash
pnpm build:core

```

```bash
pnpm build:react
```

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

### List Git Tags for @youversion Scope

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

Fetches all tags from the remote repository and then lists tags that match the pattern '@youversion/*'. This is useful for verifying published package versions.

```bash
git fetch --tags
git tag -l "@youversion/*"
```

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

### Next.js Layout with Providers

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

Sets up the root layout for a Next.js application, including essential providers like `BibleSDKProvider` and `YVPProvider` required for the YouVersion Platform React SDK.

```typescript
import type { Metadata } from "next";
import { Inter } from "next/font/google";
import "./globals.css";
import {
  BibleSDKProvider,
  YVPProvider,
} from "@youversion/platform-react-ui";

const inter = Inter({ subsets: ["latin"] });

export const metadata: Metadata = {
  title: "YouVersion Platform React UI Example",
  description: "A Next.js example app for the YouVersion Platform React UI SDK",
};

export default function RootLayout({
  children,
}: Readonly<{ children: React.ReactNode }>,
) {
  return (
    <html lang="en">
      <body className={inter.className}>
        <BibleSDKProvider>
          <YVPProvider>
            {children}
          </YVPProvider>
        </BibleSDKProvider>
      </body>
    </html>
  );
}
```

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

### Install, Build, Test, and Lint Dependencies (pnpm)

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

Essential commands for managing project dependencies and running quality checks using pnpm. Requires pnpm version 9.0.0 or higher.

```bash
pnpm install
pnpm build
pnpm test
pnpm typecheck
pnpm lint
pnpm format
```

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

### Pre-commit Hook Example (Husky)

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

Configuration for Husky pre-commit hooks, which trigger lint-staged to run linters and formatters on staged files before a commit.

```yaml
husky:
  hooks:
    "pre-commit": "lint-staged"
```

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

### Unpublish a Package Version (NPM)

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

Command to unpublish a specific version of an NPM package. This action is irreversible after 72 hours. It's recommended to publish a patch version with fixes instead.

```bash
npm unpublish @youversion/package-name@version
```

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

### Get Books and Chapters

Source: https://context7.com/youversion/platform-sdk-react/llms.txt

Retrieves Bible book metadata and chapter information for a specific version. Allows filtering books by canon type and fetching details for specific books or chapters.

```APIDOC
## Get Books and Chapters

### Description
Retrieves Bible book metadata and chapter information for a specific version.

### Method
`GET`

### Endpoint
`/bibles/{version_id}/books` and `/bibles/{version_id}/books/{book_id}/chapters` (used internally by `bibleClient.getBooks()`, `bibleClient.getBook()`, `bibleClient.getChapters()`, `bibleClient.getChapter()`)

### Parameters
#### Path Parameters (for `bibleClient.getBooks()`, `bibleClient.getBook()`, `bibleClient.getChapters()`, `bibleClient.getChapter()`)
- **versionId** (number | string) - Required - The ID of the Bible version.
- **bookId** (string) - Required (for `getBook`, `getChapters`, `getChapter`) - The ID of the book (e.g., 'JHN', 'GEN').
- **chapterNumber** (number) - Required (for `getChapter`) - The number of the chapter.

#### Query Parameters (for `bibleClient.getBooks()`)
- **filter** (string) - Optional - Filter books by canon type ('old_testament' or 'new_testament').

### Request Example
```typescript
import { ApiClient, BibleClient } from '@youversion/platform-core';

const apiClient = new ApiClient({ appKey: 'YOUR_APP_KEY' });
const bibleClient = new BibleClient(apiClient);

// Get all books for a version
const books = await bibleClient.getBooks(111);
books.data.forEach(book => {
  console.log(`${book.id}: ${book.title}`); // "GEN: Genesis"
});

// Filter by canon
const oldTestament = await bibleClient.getBooks(111, 'old_testament');
const newTestament = await bibleClient.getBooks(111, 'new_testament');

// Get specific book details
const john = await bibleClient.getBook(111, 'JHN');
console.log(john.title); // "John"
console.log(john.chapter_count); // 21

// Get chapters for a book
const chapters = await bibleClient.getChapters(111, 'JHN');
console.log(chapters.data.length); // 21

// Get specific chapter
const chapter = await bibleClient.getChapter(111, 'JHN', 3);
console.log(chapter.number); // 3
console.log(chapter.verse_count); // 36
```

### Response
#### Success Response (200)
- **Get Books**: Returns an array of book objects.
  - **id** (string) - The book identifier (e.g., 'GEN').
  - **title** (string) - The full title of the book.
  - **abbreviation** (string) - The abbreviation for the book.
  - **chapter_count** (number) - The number of chapters in the book.
  - **verses_per_chapter** (array) - An array indicating the verse count for each chapter.
  - **book_order** (number) - The order of the book in the Bible.
- **Get Chapters**: Returns an array of chapter objects for a given book.
  - **number** (number) - The chapter number.
  - **verse_count** (number) - The number of verses in the chapter.
- **Get Specific Book/Chapter**: Returns a single book or chapter object with detailed information.

#### Response Example (Get Books)
```json
{
  "data": [
    {
      "id": "GEN",
      "title": "Genesis",
      "abbreviation": "Gen.",
      "chapter_count": 50,
      "verses_per_chapter": [38, 22, 25, 26, 32, 24, 24, 22, 17, 20, 15, 20, 1, 23, 19, 16, 28, 31, 38, 30, 34, 41, 35, 43, 40, 25, 24, 22, 35, 43, 36, 42, 17, 35, 29, 30, 36, 30, 35, 31, 34, 38, 57, 53, 56, 33, 41, 47, 50],
      "book_order": 1
    }
    // ... more books
  ]
}
```
```

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

### Initialize ApiClient and BibleClient in TypeScript

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

Demonstrates how to initialize the ApiClient and BibleClient from the @youversion/platform-core SDK in TypeScript. It requires an app key and shows basic usage for fetching Bible versions and passages.

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

const apiClient = new ApiClient({
  appKey: 'YOUR_APP_KEY',
});
const bibleClient = new BibleClient(apiClient);

// Find available Bible versions in English
const versions = await bibleClient.getVersions('en*');
console.log(versions.data[0].title);

// Fetch the html text of John 3:16 in that first Bible version
const passage = await bibleClient.getPassage(versions.data[0].id, 'JHN.3.16');
console.log(passage.content);
```

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

### Build All Packages

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

Builds all packages within the monorepo in the correct order, managed by Turbo for orchestration and caching.

```bash
pnpm build
```

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

### Get Bible Versions

Source: https://context7.com/youversion/platform-sdk-react/llms.txt

Fetches available Bible translations filtered by language ranges with optional license filtering. Returns a list of Bible versions.

```APIDOC
## Get Bible Versions

### Description
Fetches available Bible translations filtered by language ranges with optional license filtering.

### Method
`GET`

### Endpoint
`/versions` (used internally by `bibleClient.getVersions()`)

### Parameters
#### Query Parameters (for `bibleClient.getVersions()`)
- **languageRanges** (string | string[]) - Required - A string or array of strings representing language codes or wildcards (e.g., 'en*', ['en*', 'es*']).
- **licenseId** (number) - Optional - A license ID to filter versions by.

### Request Example
```typescript
import { ApiClient, BibleClient } from '@youversion/platform-core';

const apiClient = new ApiClient({ appKey: 'YOUR_APP_KEY' });
const bibleClient = new BibleClient(apiClient);

// Get English versions
const englishVersions = await bibleClient.getVersions('en*');
console.log(englishVersions.data[0].title); // "King James Version"
console.log(englishVersions.data[0].localized_abbreviation); // "KJV"

// Get multiple language versions
const multiLangVersions = await bibleClient.getVersions(['en*', 'es*']);

// Filter by license
const licensedVersions = await bibleClient.getVersions('en*', 12345);
```

### Response
#### Success Response (200)
- **data** (array) - An array of Bible version objects.
  - **id** (string) - The unique identifier for the Bible version.
  - **title** (string) - The full title of the Bible version.
  - **localized_abbreviation** (string) - The localized abbreviation for the Bible version.
  - ... (other version details)

#### Response Example
```json
{
  "data": [
    {
      "id": "111",
      "title": "New International Version",
      "localized_abbreviation": "NIV",
      "language": {
        "name": "English",
        "script": "Latn",
        "canonical_name": "en-US"
      },
      "license": {
        "id": 12345,
        "name": "Example License"
      }
      // ... other fields
    }
    // ... more versions
  ]
}
```
```

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

### Release Packages

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

Builds all packages and publishes them to the NPM registry.

```bash
pnpm release
```

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

### Deprecate a Package Version (NPM)

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

Command to mark a specific version of an NPM package as deprecated, providing a reason and suggesting an alternative version. This helps users transition to newer, more stable versions.

```bash
npm deprecate @youversion/package-name@1.0.0 "Use 1.0.1+ - fixes critical bug"
```

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

### Initialize API Client

Source: https://context7.com/youversion/platform-sdk-react/llms.txt

Creates an HTTP client for interacting with YouVersion Platform APIs with configurable timeout and authentication. The BibleClient is then initialized using this API client.

```APIDOC
## Initialize API Client

### Description
Creates an HTTP client for interacting with YouVersion Platform APIs with configurable timeout and authentication.

### Method
Instantiate `ApiClient` and `BibleClient` classes.

### Endpoint
N/A (Client-side initialization)

### Parameters
#### Request Body (for ApiClient constructor)
- **appKey** (string) - Required - Your application's API key.
- **timeout** (number) - Optional - Request timeout in milliseconds (default: 10000).
- **apiHost** (string) - Optional - The host for the YouVersion Platform API (default: 'api.youversion.com').
- **installationId** (string) - Optional - An identifier for the application installation.

### Request Example
```typescript
import { ApiClient, BibleClient } from '@youversion/platform-core';

const apiClient = new ApiClient({
  appKey: 'YOUR_APP_KEY',
  timeout: 10000, // optional, default 10000ms
  apiHost: 'api.youversion.com', // optional
  installationId: 'my-app-instance', // optional
});

const bibleClient = new BibleClient(apiClient);
```

### Response
#### Success Response (200)
N/A (Client-side initialization)

#### Response Example
N/A
```

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

### Get Bible Passage

Source: https://context7.com/youversion/platform-sdk-react/llms.txt

Fetches a passage (single verse, verse range, or full chapter) in HTML or plain text format. Supports filtering by version and including/excluding headings and notes.

```APIDOC
## Get Bible Passage

### Description
Fetches a passage (single verse, verse range, or full chapter) in HTML or plain text format.

### Method
`GET`

### Endpoint
`/bibles/{version_id}/passages/{passage_reference}` (used internally by `bibleClient.getPassage()`)

### Parameters
#### Path Parameters (for `bibleClient.getPassage()`)
- **versionId** (number | string) - Required - The ID of the Bible version.
- **passageReference** (string) - Required - The reference for the passage (e.g., 'JHN.3.16', 'GEN.1', 'JHN.3.1-5').

#### Query Parameters (for `bibleClient.getPassage()`)
- **contentType** (string) - Optional - The desired content type ('html' or 'text', defaults to 'html').
- **includeHeadings** (boolean) - Optional - Whether to include chapter/section headings (defaults to false).
- **includeNotes** (boolean) - Optional - Whether to include footnotes or other notes (defaults to false).

### Request Example
```typescript
import { ApiClient, BibleClient } from '@youversion/platform-core';

const apiClient = new ApiClient({ appKey: 'YOUR_APP_KEY' });
const bibleClient = new BibleClient(apiClient);

// Get single verse (John 3:16 in NIV - version 111)
const verse = await bibleClient.getPassage(111, 'JHN.3.16');
console.log(verse.content); // HTML formatted verse text
console.log(verse.reference); // "John 3:16"

// Get verse range
const verses = await bibleClient.getPassage(111, 'JHN.3.1-5');

// Get entire chapter
const chapter = await bibleClient.getPassage(111, 'GEN.1');

// Get plain text with options
const plainText = await bibleClient.getPassage(
  111,
  'JHN.3.16',
  'text',
  true,  // include_headings
  true   // include_notes
);
```

### Response
#### Success Response (200)
- **content** (string) - The requested passage content (HTML or plain text).
- **reference** (string) - The canonical reference of the fetched passage.
- **next_chapter** (object | null) - Information about the next chapter, if available.
- **previous_chapter** (object | null) - Information about the previous chapter, if available.

#### Response Example
```json
{
  "content": "<p class=\"Verse\">16 For God so loved the world, that he gave his only begotten Son, that whosoever believeth in him should not perish, but have everlasting life.</p>",
  "reference": "John 3:16",
  "next_chapter": {
    "book_id": "JHN",
    "chapter_number": 4,
    "passage_reference": "JHN.4"
  },
  "previous_chapter": {
    "book_id": "JHN",
    "chapter_number": 2,
    "passage_reference": "JHN.2"
  }
}
```
```

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

### Initialize YouVersion Platform API Client (TypeScript)

Source: https://context7.com/youversion/platform-sdk-react/llms.txt

Initializes an HTTP client for interacting with YouVersion Platform APIs. Supports configurable timeout, authentication, and API host. It also demonstrates initializing a Bible client using the API client.

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

// Create API client with app key
const apiClient = new ApiClient({
  appKey: 'YOUR_APP_KEY',
  timeout: 10000, // optional, default 10000ms
  apiHost: 'api.youversion.com', // optional
  installationId: 'my-app-instance', // optional
});

// Initialize Bible client
const bibleClient = new BibleClient(apiClient);
```

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

### Theming with @youversion/platform-react-ui

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

Shows how to implement theming (light/dark mode) for `@youversion/platform-react-ui` components. This involves using the `YVPProvider` with a `theme` prop and managing the theme state. It also includes a button to toggle the theme.

```tsx
import { useState } from 'react';
import { YouVersionProvider, YVPProvider, BibleTextView } from '@youversion/platform-react-ui';

export default function App() {
  const [theme, setTheme] = useState<'light' | 'dark'>('light');

  return (
    <YouVersionProvider appKey="YOUR_APP_KEY">
      <YVPProvider config={{ appKey: "YOUR_APP_KEY" }} theme={theme}>
        <button onClick={() => setTheme(theme === 'light' ? 'dark' : 'light')}>
          Toggle theme
        </button>
        <BibleTextView reference="JHN.1.1-4" versionId={111} />
      </YVPProvider>
    </YouVersionProvider>
  );
}
```

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

### Create a Changeset

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

Generates a changeset file to record changes for version updates and changelog generation.

```bash
pnpm changeset
```

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

### Run Individual Package Tests with Coverage

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

Runs tests for a specific package and generates a coverage report. Uses pnpm filters to target packages.

```bash
pnpm --filter @youversion/platform-core test:coverage

```

```bash
pnpm --filter @youversion/platform-react-hooks test:coverage
```

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

### Run Tests

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

Executes tests across all packages in the monorepo. Sequential execution is used to ensure clear and understandable output.

```bash
pnpm test
```

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

### Basic Usage of @youversion/platform-react-ui Components

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

Demonstrates the basic integration of `@youversion/platform-react-ui` components within a React application. It requires wrapping the application with `YouVersionProvider` and providing an `appKey`. The `BibleTextView` component is used to display Bible text.

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

function App() {
  return (
    <YouVersionProvider appKey={\"YOUR_APP_KEY\"}>
      <BibleTextView reference=\"JHN.1.1-4\" versionId={111} />
    </YouVersionProvider>
  );
}
```

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

### Build Specific Packages (pnpm)

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

Commands to build individual packages within the monorepo. This is useful for focused development or testing specific components.

```bash
pnpm build:core
pnpm build:react
```

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

### Interact with YouVersion Bible API Client

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

Demonstrates fetching Bible data using the ApiClient and BibleClient from '@youversion/platform-core'. Includes finding available Bible versions and fetching passage content. Requires an appKey for initialization.

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

const apiClient = new ApiClient({ appKey: 'YOUR_APP_KEY' });
const bibleClient = new BibleClient(apiClient);

// Find available Bible versions in English
const versions = await bibleClient.getVersions('en*');
console.log(versions.data[0].title);

// Fetch the html text of John 3:16 in that first Bible version
const passage = await bibleClient.getPassage(versions.data[0].id, 'JHN.3.16');
console.log(passage.content);
```

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

### Fetch Bible Data and Navigation Hooks

Source: https://context7.com/youversion/platform-sdk-react/llms.txt

Demonstrates using hooks from '@youversion/platform-react-hooks' to fetch Bible book and chapter metadata. It includes state management for the current book and chapter, and utility functions for navigating between chapters with `useChapterNavigation`. Assumes `useState` is available in the scope.

```tsx
import {
  useBooks,
  useBook,
  useChapters,
  useChapter,
  useChapterNavigation
} from '@youversion/platform-react-hooks';

function BibleNavigator({ versionId }: { versionId: number }) {
  const [book, setBook] = useState('GEN');
  const [chapter, setChapter] = useState(1);

  const { books } = useBooks(versionId);
  const { book: bookData } = useBook(versionId, book);
  const { chapters } = useChapters(versionId, book);
  const { chapter: chapterData } = useChapter(versionId, book, chapter);

  const { hasNext, hasPrevious, goToNext, goToPrevious } = useChapterNavigation({
    versionId,
    currentBook: book,
    currentChapter: chapter,
    onNavigate: (newBook, newChapter) => {
      setBook(newBook);
      setChapter(newChapter);
    }
  });

  return (
    <div>
      <select value={book} onChange={e => setBook(e.target.value)}>
        {books?.data.map(b => (
          <option key={b.id} value={b.id}>{b.title}</option>
        ))}
      </select>

      <select value={chapter} onChange={e => setChapter(Number(e.target.value))}>
        {chapters?.data.map(c => (
          <option key={c.number} value={c.number}>Chapter {c.number}</option>
        ))}
      </select>

      <div>
        <button onClick={goToPrevious} disabled={!hasPrevious}>
          Previous
        </button>
        <span>{bookData?.title} {chapter}</span>
        <button onClick={goToNext} disabled={!hasNext}>
          Next
        </button>
      </div>

      <p>Verse count: {chapterData?.verse_count}</p>
    </div>
  );
}
```

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

### Run Package-Specific Tests with Coverage (pnpm)

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

Commands to execute tests for individual packages and generate code coverage reports. Utilizes the `--filter` flag to target specific packages.

```bash
pnpm --filter @youversion/platform-core test:coverage
pnpm --filter @youversion/platform-react-hooks test:coverage
```

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

### User Authentication with OAuth using YouVersion SDK (TypeScript)

Source: https://context7.com/youversion/platform-sdk-react/llms.txt

Implements a PKCE-based OAuth flow for user sign-in and authentication. It covers configuring the platform, initiating the sign-in redirect, handling the authentication callback, retrieving user information from tokens, checking token expiration, and signing out. Requires platform configuration with an app key.

```typescript
import {
  YouVersionAPIUsers,
  YouVersionPlatformConfiguration
} from '@youversion/platform-core';

// Configure platform
YouVersionPlatformConfiguration.appKey = 'YOUR_APP_KEY';

// Initiate sign-in (redirects to YouVersion)
await YouVersionAPIUsers.signIn(
  'https://myapp.com/callback',
  ['read_highlights', 'write_highlights'] // optional scopes
);

// Handle callback on redirect page
const result = await YouVersionAPIUsers.handleAuthCallback();
if (result) {
  console.log(`Signed in as: ${result.name}`);
  console.log(`User ID: ${result.yvpUserId}`);
  console.log(`Access Token: ${result.accessToken}`);
  console.log(`Expires: ${result.expiryDate}`);
}

// Get user info from stored token
const userInfo = YouVersionAPIUsers.userInfo(
  YouVersionPlatformConfiguration.idToken!
);
console.log(userInfo.name);
console.log(userInfo.email);
console.log(userInfo.avatar_url);

// Check token expiration
if (YouVersionAPIUsers.isTokenExpired()) {
  await YouVersionAPIUsers.refreshTokens();
}

// Auto-refresh if needed
const refreshed = await YouVersionAPIUsers.refreshTokenIfNeeded();

// Sign out
YouVersionAPIUsers.signOut();
```

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

### Monorepo Package Structure

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

Illustrates the directory structure of the monorepo, highlighting the 'packages' directory where core, hooks, and UI SDKs are located, along with 'tools' for shared configurations and 'scripts' for build utilities.

```tree
├── packages/
│   ├── core/       # @youversion/platform-core - Published core package
│   ├── hooks/      # @youversion/platform-react-hooks - Published React hooks
│   └── ui/         # @youversion/platform-react-ui - Published React SDK
├── tools/                 # Shared configs (TypeScript, ESLint, Jest)
└── scripts/              # Build and development scripts
```

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

### Release Process (pnpm Changesets)

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

Commands for managing package versions, creating changelogs, and publishing new releases using the Changesets tool. This process ensures unified versioning across all packages.

```bash
pnpm changeset
pnpm version-packages
pnpm release
```

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

### Lint Code

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

Runs ESLint across the project to enforce code quality and style consistency.

```bash
pnpm lint
```

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

### Retrieve Supported Languages with YouVersion SDK (TypeScript)

Source: https://context7.com/youversion/platform-sdk-react/llms.txt

Fetches a list of all languages supported by the YouVersion platform, with options to filter by country and paginate results. It also demonstrates how to retrieve details for a specific language, including those with specific scripts. Requires an initialized ApiClient and LanguagesClient.

```typescript
import { ApiClient, LanguagesClient } from '@youversion/platform-core';

const apiClient = new ApiClient({ appKey: 'YOUR_APP_KEY' });
const languagesClient = new LanguagesClient(apiClient);

// Get all languages
const languages = await languagesClient.getLanguages();
languages.data.forEach(lang => {
  console.log(`${lang.id}: ${lang.name} (${lang.local_name})`);
});

// Get languages by country
const usLanguages = await languagesClient.getLanguages({ country: 'US' });

// Pagination
const page1 = await languagesClient.getLanguages({ page_size: 50 });
const page2 = await languagesClient.getLanguages({
  page_size: 50,
  page_token: page1.next_page_token
});

// Get specific language details
const english = await languagesClient.getLanguage('en');
console.log(english.name); // "English"
console.log(english.local_name); // "English"

// Language with script
const serbian = await languagesClient.getLanguage('sr-Latn');
```

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

### Code Quality: Pre-commit Hooks (Husky & lint-staged)

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

Configuration overview for pre-commit hooks using Husky and lint-staged. These tools ensure code quality by automatically linting and formatting staged files before each commit.

```bash
# Example package.json script for lint-staged
"lint-staged": {
  "*.{js,jsx,ts,tsx}": [
    "eslint --fix",
    "prettier --write"
  ]
}

```

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

### Version Packages

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

Updates package versions based on the created changesets.

```bash
pnpm version-packages
```

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

### Format Code

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

Applies code formatting rules using Prettier to ensure consistent code style throughout the project.

```bash
pnpm format
```

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

### Fetch Bible Books and Chapters (TypeScript)

Source: https://context7.com/youversion/platform-sdk-react/llms.txt

Retrieves metadata for Bible books and chapter information for a given Bible version. Supports filtering books by canon (e.g., 'old_testament', 'new_testament') and fetching details for specific books or chapters.

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

const apiClient = new ApiClient({ appKey: 'YOUR_APP_KEY' });
const bibleClient = new BibleClient(apiClient);

// Get all books for a version
const books = await bibleClient.getBooks(111);
books.data.forEach(book => {
  console.log(`${book.id}: ${book.title}`); // "GEN: Genesis"
});

// Filter by canon
const oldTestament = await bibleClient.getBooks(111, 'old_testament');
const newTestament = await bibleClient.getBooks(111, 'new_testament');

// Get specific book details
const john = await bibleClient.getBook(111, 'JHN');
console.log(john.title); // "John"
console.log(john.chapter_count); // 21

// Get chapters for a book
const chapters = await bibleClient.getChapters(111, 'JHN');
console.log(chapters.data.length); // 21

// Get specific chapter
const chapter = await bibleClient.getChapter(111, 'JHN', 3);
console.log(chapter.number); // 3
console.log(chapter.verse_count); // 36
```

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

### Theme Customization with CSS Variables - React & CSS

Source: https://context7.com/youversion/platform-sdk-react/llms.txt

Shows how to customize the styling of YouVersion components using CSS variables and the theme provider. This allows for deep integration of the SDK's look and feel with your application's design system.

```tsx
import { YouVersionProvider, YVPProvider } from '@youversion/platform-react-ui';
import './custom-theme.css';

function App() {
  return (
    <YouVersionProvider appKey="YOUR_APP_KEY">
      <YVPProvider 
        config={{ appKey: "YOUR_APP_KEY" }}
        theme="dark"
      >
        <YourComponents />
      </YVPProvider>
    </YouVersionProvider>
  );
}
```

```css
/* custom-theme.css */
[data-yv-sdk] {
  /* Colors */
  --yv-primary: #3b82f6;
  --yv-background: #ffffff;
  --yv-foreground: #0f172a;
  --yv-muted: #64748b;
  --yv-muted-foreground: #475569;
  --yv-card: #f8fafc;
  --yv-border: #e2e8f0;

  /* Typography */
  --yv-font-sans: system-ui, -apple-system, sans-serif;
  --yv-font-serif: Georgia, Cambria, serif;
  --yv-reader-font-size: 18px;
  --yv-reader-line-height: 1.75;

  /* Spacing */
  --yv-reader-padding: 2rem;
}

[data-yv-sdk][data-yv-theme="dark"] {
  --yv-background: #0f172a;
  --yv-foreground: #f8fafc;
  --yv-card: #1e293b;
  --yv-border: #334155;
}
```

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

### Customizing @youversion/platform-react-ui with CSS Variables

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

Illustrates how to customize the appearance of `@youversion/platform-react-ui` components using CSS variables. These variables can be overridden to change primary colors, background colors, font sizes, and other styling aspects.

```css
[data-yv-sdk] {
  --yv-primary: #your-primary-color;
  --yv-background: #your-background-color;
  --yv-reader-font-size: 18px;
}
```

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

### Manage Authentication with useYVAuth Hook

Source: https://context7.com/youversion/platform-sdk-react/llms.txt

The `useYVAuth` hook provides a comprehensive authentication flow, including sign-in, sign-out, callback processing, and retrieval of user information. It manages authentication states like loading and isAuthenticated, simplifying OAuth integration.

```tsx
import { useYVAuth } from '@youversion/platform-react-hooks';
import { useEffect } from 'react';

function AuthenticatedApp() {
  const { auth, signIn, signOut, processCallback, userInfo } = useYVAuth();

  // Handle OAuth callback on callback page
  useEffect(() => {
    processCallback()
      .then(result => {
        if (result) {
          console.log('Authenticated:', result.name);
          // Redirect to app
        }
      })
      .catch(err => console.error('Auth failed:', err));
  }, [processCallback]);

  const handleSignIn = async () => {
    await signIn({
      redirectUrl: 'https://myapp.com/callback',
      scopes: ['read_highlights', 'write_highlights']
    });
  };

  if (auth.isLoading) {
    return <div>Authenticating...</div>;
  }

  if (!auth.isAuthenticated) {
    return (
      <button onClick={handleSignIn}>
        Sign In with YouVersion
      </button>
    );
  }

  return (
    <div>
      <h1>Welcome, {userInfo?.name}!</h1>
      <img src={userInfo?.avatar_url} alt="Profile" />
      <p>{userInfo?.email}</p>
      <button onClick={signOut}>Sign Out</button>
    </div>
  );
}
```

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

### Manage Bible Highlights with useHighlights Hook

Source: https://context7.com/youversion/platform-sdk-react/llms.txt

The `useHighlights` hook simplifies managing Bible verse highlights. It supports creating, retrieving, and deleting highlights, and automatically handles loading and error states. It can also filter highlights by passage ID and requires version ID for operations.

```tsx
import { useHighlights } from '@youversion/platform-react-hooks';

function HighlightManager() {
  const {
    highlights,
    loading,
    error,
    createHighlight,
    deleteHighlight,
    refetch
  } = useHighlights({
    version_id: 111,
    passage_id: 'JHN.3' // optional filter
  });

  const handleHighlight = async (passage: string, color: string) => {
    await createHighlight({
      version_id: 111,
      passage_id: passage,
      color: color.replace('#', '') // remove # prefix
    });
    refetch();
  };

  const handleDelete = async (passage: string) => {
    await deleteHighlight(passage, { version_id: 111 });
    refetch();
  };

  if (loading) return <div>Loading highlights...</div>;
  if (error) return <div>Error loading highlights</div>;

  return (
    <div>
      <h2>My Highlights</h2>
      {highlights?.data.map(h => (
        <div key={h.passage_id} style={{ backgroundColor: `#${h.color}` }}>
          <span>{h.passage_id}</span>
          <button onClick={() => handleDelete(h.passage_id)}>Remove</button>
        </div>
      ))}
      <button onClick={() => handleHighlight('JHN.3.16', 'ffff00')}>
        Highlight John 3:16
      </button>
    </div>
  );
}
```

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

### Bible Reader Component with Theming - React

Source: https://context7.com/youversion/platform-sdk-react/llms.txt

Demonstrates the usage of the YouVersion BibleReader component, including version and chapter pickers, navigation, and theming capabilities. It shows both a default configuration and a controlled version where state manages the displayed Bible content.

```tsx
import {
  YouVersionProvider,
  YVPProvider,
  BibleReader
} from '@youversion/platform-react-ui';
import { useState } from 'react';

function App() {
  const [theme, setTheme] = useState<'light' | 'dark'>('light');

  return (
    <YouVersionProvider appKey="YOUR_APP_KEY">
      <YVPProvider config={{ appKey: "YOUR_APP_KEY" }} theme={theme}>
        <BibleReader.Root
          defaultBook="JHN"
          defaultChapter="3"
          defaultVersionId={111}
          fontFamily="Georgia, serif"
          fontSize={18}
          lineHeight={1.6}
          showVerseNumbers={true}
          background={theme}
        >
          <BibleReader.Toolbar border="bottom" />
          <BibleReader.Content />
        </BibleReader.Root>

        <button onClick={() => setTheme(theme === 'light' ? 'dark' : 'light')}> 
          Toggle Theme
        </button>
      </YVPProvider>
    </YouVersionProvider>
  );
}

// Controlled version with state
function ControlledReader() {
  const [book, setBook] = useState('JHN');
  const [chapter, setChapter] = useState('3');
  const [versionId, setVersionId] = useState(111);

  return (
    <YouVersionProvider appKey="YOUR_APP_KEY">
      <BibleReader.Root
        book={book}
        chapter={chapter}
        versionId={versionId}
        onBookChange={setBook}
        onChapterChange={setChapter}
        onVersionChange={setVersionId}
      >
        <BibleReader.Toolbar border="top" />
        <BibleReader.Content />
      </BibleReader.Root>
    </YouVersionProvider>
  );
}
```

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

### Manage User Highlights with YouVersion SDK (TypeScript)

Source: https://context7.com/youversion/platform-sdk-react/llms.txt

Handles the creation, retrieval, and deletion of Bible verse highlights for an authenticated user. Supports filtering highlights by version and passage, creating/updating highlights with specific colors, and using explicit access tokens. Requires an initialized ApiClient and HighlightsClient.

```typescript
import {
  ApiClient,
  HighlightsClient,
  YouVersionPlatformConfiguration
} from '@youversion/platform-core';

const apiClient = new ApiClient({ appKey: 'YOUR_APP_KEY' });
const highlightsClient = new HighlightsClient(apiClient);

// Get all highlights for authenticated user
const highlights = await highlightsClient.getHighlights();
highlights.data.forEach(h => {
  console.log(`${h.passage_id}: ${h.color}`);
});

// Filter by version
const nivHighlights = await highlightsClient.getHighlights({
  version_id: 111
});

// Filter by passage
const chapterHighlights = await highlightsClient.getHighlights({
  passage_id: 'JHN.3'
});

// Create or update highlight (yellow: ffff00)
const highlight = await highlightsClient.createHighlight({
  version_id: 111,
  passage_id: 'JHN.3.16',
  color: 'ffff00'
});

// Create highlight for verse range
const rangeHighlight = await highlightsClient.createHighlight({
  version_id: 111,
  passage_id: 'JHN.3.16-17',
  color: 'ff0000' // red
});

// Delete highlight
await highlightsClient.deleteHighlight('JHN.3.16', {
  version_id: 111
});

// Explicit token usage (overrides stored token)
const myHighlights = await highlightsClient.getHighlights(
  { version_id: 111 },
  'explicit_access_token_here'
);
```

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

### Fetch Bible Versions (TypeScript)

Source: https://context7.com/youversion/platform-sdk-react/llms.txt

Fetches available Bible translations, allowing filtering by language ranges (e.g., 'en*', 'es*') and optional license ID. The results contain details like title and localized abbreviation.

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

const apiClient = new ApiClient({ appKey: 'YOUR_APP_KEY' });
const bibleClient = new BibleClient(apiClient);

// Get English versions
const englishVersions = await bibleClient.getVersions('en*');
console.log(englishVersions.data[0].title); // "King James Version"
console.log(englishVersions.data[0].localized_abbreviation); // "KJV"

// Get multiple language versions
const multiLangVersions = await bibleClient.getVersions(['en*', 'es*']);

// Filter by license
const licensedVersions = await bibleClient.getVersions('en*', 12345);
```