Prerequisites Before installing the SDK, ensure your environment meets these requirements:
Node.js Version 20.0.0 or higher Check your version:
React Version 19.1.0 or higher Required for hooks and UI packages
The SDK requires Node.js >= 20.0.0 and uses features from modern JavaScript. Older Node versions are not supported.
Get Your API Key Before installing the SDK, you’ll need an API key from the YouVersion Platform:
Create an application
From your dashboard, create a new application to receive your API key.
Copy your API key
Save your API key securely. You’ll need it to authenticate all requests. Never commit your API key to version control. Use environment variables or a secure secrets manager.
Choose Your Package The SDK provides three packages. Choose the one that fits your needs:
Install @youversion/platform-react-ui for the complete experience with pre-built components: npm install @youversion/platform-react-ui
This package includes both @youversion/platform-react-hooks and @youversion/platform-core as dependencies, so you get everything in one install.
What’s included:
All UI components (BibleTextView, BibleReader, VerseOfTheDay, etc.)
All React hooks for data fetching
Core API clients
Tailwind CSS styling (auto-injected)
Install @youversion/platform-react-hooks to build custom UI with managed data fetching: npm install @youversion/platform-react-hooks
This package includes @youversion/platform-core as a dependency.
What’s included:
All React hooks (usePassage, useVersion, useChapter, etc.)
YouVersionProvider for configuration
Core API clients
No UI components or styling
Install @youversion/platform-core for framework-agnostic API access: npm install @youversion/platform-core
This package has zero dependencies on React and can be used in Node.js, browsers, or any JavaScript environment.
What’s included:
Type-safe API clients (ApiClient, BibleClient, LanguagesClient, etc.)
Zod schema validation
OAuth 2.0 PKCE authentication
No React dependencies
Install All Three Packages For maximum flexibility, you can install all three packages separately:
npm install @youversion/platform-react-ui \ @youversion/platform-react-hooks \ @youversion/platform-core
Installing @youversion/platform-react-ui automatically includes the other two packages as dependencies, so separate installation is only needed if you want explicit control over versions.
Verify Installation After installing, verify the SDK is working:
Check package versions
View installed versions: npm list @youversion/platform-react-ui npm list @youversion/platform-react-hooks npm list @youversion/platform-core
Import in your code
Try importing the SDK in a React component: import { YouVersionProvider } from '@youversion/platform-react-ui' ; // or import { YouVersionProvider } from '@youversion/platform-react-hooks' ; // or import { ApiClient } from '@youversion/platform-core' ;
Environment Setup Store your API key securely using environment variables:
Next.js
Vite
Create React App
Other
Create a .env.local file in your project root: NEXT_PUBLIC_YOUVERSION_API_KEY = your_api_key_here
Use in your code: < YouVersionProvider appKey = { process . env . NEXT_PUBLIC_YOUVERSION_API_KEY } > { children } </ YouVersionProvider >
In Next.js, prefix client-side environment variables with NEXT_PUBLIC_ to expose them to the browser.
Create a .env file in your project root: VITE_YOUVERSION_API_KEY = your_api_key_here
Use in your code: < YouVersionProvider appKey = { import . meta . env . VITE_YOUVERSION_API_KEY } > { children } </ YouVersionProvider >
In Vite, prefix client-side environment variables with VITE_ to expose them to the browser.
Create a .env file in your project root: REACT_APP_YOUVERSION_API_KEY = your_api_key_here
Use in your code: < YouVersionProvider appKey = { process . env . REACT_APP_YOUVERSION_API_KEY } > { children } </ YouVersionProvider >
In Create React App, prefix client-side environment variables with REACT_APP_ to expose them to the browser.
For other frameworks, consult their documentation on environment variables. The key principle is:
Store your API key in a .env file
Add .env to your .gitignore
Use the framework’s environment variable syntax to access it
Never hardcode your API key in source code or commit it to version control.
TypeScript Configuration The SDK is built with TypeScript and includes type definitions. No additional setup is needed, but ensure your tsconfig.json has these settings:
{ "compilerOptions" : { "target" : "ES2020" , "lib" : [ "ES2020" , "DOM" , "DOM.Iterable" ], "jsx" : "react-jsx" , "module" : "ESNext" , "moduleResolution" : "bundler" , "strict" : true , "esModuleInterop" : true , "skipLibCheck" : true } }
The SDK uses modern JavaScript features and requires target: "ES2020" or higher.
Styling Setup (UI Package Only) If you’re using @youversion/platform-react-ui, styles are automatically injected when you import the package. No additional CSS imports or Tailwind configuration needed!
The UI package uses Tailwind CSS with a namespaced prefix (yv:) to prevent style conflicts. Styles are embedded in the JavaScript bundle and injected automatically:
// Styles are automatically injected when you import any UI component import { BibleTextView } from '@youversion/platform-react-ui' ; // No need to import CSS files or configure Tailwind
The SDK handles all styling internally, so your own Tailwind configuration (if any) won’t conflict.
Next Steps Now that you have the SDK installed, you’re ready to build your first Bible experience:
Quickstart Guide Display your first Bible verse in under 5 minutes
Architecture Overview Learn how the three packages work together
API Reference Explore the complete API documentation
Examples See real-world code examples
