react-native-typescript-boilerplate

AI-Ready. Production-grade React Native + TypeScript boilerplate with a built-in, provider-agnostic AI service layer. Wire up OpenAI, Anthropic Claude, Google Gemini — or any LLM — in minutes, not days.

[!TIP] Works great with AI coding assistants. This repo ships with purpose-built guidance files so Cursor, Claude Code, GitHub Copilot, Windsurf, and Gemini CLI all understand the project conventions out of the box:

File	Used by
CLAUDE.md	Claude Code
AGENTS.md	Windsurf · Codex CLI · Gemini CLI
.cursor/rules/	Cursor
.github/copilot-instructions.md	GitHub Copilot

[!NOTE] All screens, components, and mock data included in this boilerplate are for demonstration purposes only. They exist to showcase the architecture, theming, navigation, and AI service layer — not to be kept as-is. Feel free to delete any screen, component, or piece of mock data and replace it with your own.

---

Table of Contents

• Showcase
• What's New in v6
• What's Included
• Getting Started
• Path Aliases
• AI Service Layer
• Theme System
• Navigation
• Event Emitter
• Axios Hooks
• Localization
• Utilities
• AI Guidance Files
• Code Quality
• Project Structure

---

📸 Showcase

---

🤖 What's New in v6

• AI-Ready — provider-agnostic AI service layer for OpenAI, Anthropic, and Gemini
• useAIChat hook — multi-turn conversations with streaming support, zero boilerplate
• useAICompletion hook — single-shot completions for text generation, classification, summarization
• RNAIMessage component — role-aware chat bubble with live streaming cursor
• AI Chat screen — fully functional demo: provider switcher, API key input, model name input, streaming toggle
• AI Guidance Files — CLAUDE.md, AGENTS.md, .cursor/rules/, .github/copilot-instructions.md so every AI coding assistant understands this codebase
• @hooks path alias — clean imports for all custom hooks

---

🎉 What's New in v5

• React Native 0.84 + React 19 — latest stable versions
• New Architecture enabled by default (newArchEnabled=true, Bridgeless / JSI)
• Redesigned Boilerplate Explorer HomeScreen
• Full Montserrat font family bundled (18 weights)
• react-native-reanimated v4 + react-native-worklets
• Stricter TypeScript config with typed theme colors and navigation
• Husky v9 pre-commit hooks (prettier + lint on every commit, commitlint on commit message)

---

🐶 What's Included

AI Layer

Feature	Description
AI Service	Provider-agnostic sendAIMessage() + streamAIMessage() — works with OpenAI, Anthropic, Gemini, or any compatible API
useAIChat	Multi-turn conversation hook with history, streaming, error state, and system prompt management
useAICompletion	Single-shot completion hook — perfect for generation, summarization, translation, classification
RNAIMessage	Role-aware chat bubble component (user / assistant / system) with streaming cursor
AI Chat Screen	Live demo screen with provider selector, API key input, model name field, streaming toggle
AI Guidance Files	CLAUDE.md · AGENTS.md · .cursor/rules/ · .github/copilot-instructions.md

Core

Feature	Library
Navigation	@react-navigation/native · @react-navigation/stack · @react-navigation/bottom-tabs
Navigation helpers	react-navigation-helpers — push/pop/navigate without component refs
HTTP	axios + axios-hooks
Animations	react-native-reanimated v4 + react-native-gesture-handler
Icons	react-native-vector-icons + react-native-dynamic-vector-icons
Localization	i18next + react-i18next
Safe Area	react-native-safe-area-context
Splash Screen	react-native-splash-screen

Developer Experience

• Strict TypeScript — extended theme types, typed palette, path aliases
• Path aliases (@screens, @services, @hooks, @fonts, @theme, …)
• TextWrapper — typed h1–h6, bold, italic props, global font swap in one file
• EventEmitter singleton — pub/sub across screens without prop drilling
• Montserrat font family (18 weights) bundled
• ESLint + Prettier with auto import sorting
• Husky pre-commit: lint, format, and commitlint run automatically

---

🚀 Getting Started

1. Clone

git clone https://github.com/kuraydev/react-native-typescript-boilerplate.git my-app
cd my-app

2. Install dependencies

npm install

3. iOS — install pods

cd ios && pod install && cd ..

4. Android — set SDK path

Create android/local.properties:

# macOS / Linux
sdk.dir=/Users/<your-username>/Library/Android/sdk

# Windows
sdk.dir=C:\\Users\\<your-username>\\AppData\\Local\\Android\\Sdk

5. Run

# iOS
npm run ios

# Android
npm run android

Scripts

Command	Description
npm start	Start Metro bundler
npm run start:fresh	Start Metro with cache reset — use this after adding path aliases
npm run ios	Run on iOS simulator
npm run android	Run on Android emulator
npm run lint	ESLint
npm run prettier	Prettier — auto-format all files in src/
npm test	Jest
npm run prepare	Initialize Husky hooks (runs automatically after npm install)
npm run clean:showcase	Remove showcase/demo content and replace screens with minimal stubs

---

Start fresh — remove showcase content

The included screens (Home, Search, Notifications, Settings) are demo UIs that showcase the architecture. Once you've explored the boilerplate, run:

npm run clean:showcase

This will:

• Delete src/screens/home/mock/ (FeatureCards, UtilityItems, StackItems)
• Delete src/screens/home/components/ (CardItem)
• Replace each showcase screen with a minimal, compilable stub
• Leave AIChatScreen, all shared components, services, theme, and navigation wiring untouched

---

Rename the project

npx react-native-rename <YourAppName>

For a custom Android bundle identifier:

npx react-native-rename <YourAppName> -b com.yourcompany.appname

For iOS, change the bundle identifier in Xcode.

---

📁 Path Aliases

All aliases are defined in babel.config.js and tsconfig.json. Always prefer aliases over relative imports.

Alias	Resolves to
@screens/*	src/screens/*
@services/*	src/services/*
@hooks	src/hooks/index
@shared-components	src/shared/components
@shared-constants	src/shared/constants
@fonts	src/shared/theme/fonts
@font-size	src/shared/theme/font-size
@theme/*	src/shared/theme/*
@colors	src/shared/theme/colors
@models	src/services/models
@utils	src/utils
@assets	src/assets
@event-emitter	src/services/event-emitter
@api	src/services/api/index (stub)
@local-storage	src/services/local-storage (stub)

Example:

// Instead of: ../../../../shared/components/text-wrapper/TextWrapper
import Text from "@shared-components/text-wrapper/TextWrapper";

// Instead of: ../../hooks/useAIChat
import { useAIChat } from "@hooks";

After adding a new alias to both babel.config.js and tsconfig.json, run npm run start:fresh to reset Metro's cache.

---

🤖 AI Service Layer

The AI layer is provider-agnostic — the same API, types, and hooks work regardless of whether you're using OpenAI, Anthropic, Gemini, or any other LLM provider. Model names are never hardcoded; you supply whatever model string your API key supports.

Core types (src/services/ai/types.ts)

interface AIConfig {
  provider: "openai" | "anthropic" | "gemini";
  apiKey: string;
  model?: string;       // you supply the model — no defaults enforced
  temperature?: number; // defaults to 0.7
  maxTokens?: number;   // defaults to 1024
  systemPrompt?: string;
  baseURL?: string;     // override for proxies or local LLMs (e.g. Ollama)
}

interface AIMessage {
  id: string;
  role: "user" | "assistant" | "system";
  content: string;
  timestamp: number;
}

useAIChat — multi-turn conversations

import { useAIChat } from "@hooks";

const {
  messages,        // AIMessage[] — full conversation history
  isLoading,       // true while awaiting a full response
  isStreaming,     // true while tokens are arriving
  error,           // Error | null
  sendMessage,     // (content: string) => Promise<void> — full response
  streamMessage,   // (content: string) => Promise<void> — live tokens
  clearMessages,
  setSystemPrompt,
} = useAIChat({
  config: {
    provider: "openai",  // or "anthropic" or "gemini"
    apiKey: userApiKey,
    model: "your-model", // you decide — e.g. "gpt-4o-mini"
  },
});

// Full response — UI updates once reply is complete
await sendMessage("Explain React hooks in one paragraph");

// Streaming — the last assistant message updates token by token
await streamMessage("Write a React Native FlatList example");

// Inject a system instruction at any time
setSystemPrompt("You are a concise senior React Native engineer.");

useAICompletion — single-shot completions

import { useAICompletion } from "@hooks";

const { complete, result, isLoading, error, reset } = useAICompletion({
  config: { provider: "anthropic", apiKey: key, model: "your-model" },
  systemPrompt: "Classify sentiment as: positive, neutral, or negative.",
});

const sentiment = await complete(userReview);

Calling the service directly

import { sendAIMessage, streamAIMessage, buildUserMessage, buildSystemMessage } from "@services/ai";

const messages = [
  buildSystemMessage("You are a helpful assistant."),
  buildUserMessage("Hello!"),
];

// Full response
const response = await sendAIMessage(messages, config);
console.log(response.message.content);
console.log(response.usage?.totalTokens);

// Streaming
awai