Caracal Starter

Introduction

An overview of why we built the Caracal starter, its features, and the libraries used.

Welcome to the Caracal Expo / React Native Starter Kit!

Motivation

The goal of this starter kit is to streamline the process of building React Native apps. It provides a resource for creating high-quality apps faster and with less effort, while ensuring projects adhere to consistent code standards and architectural principles.

The benefits of using this starter kit are numerous. It provides a consistent foundation that makes it easy to switch between projects and focus on business logic rather than boilerplate code. Because it promotes consistency, it makes apps easier to maintain and scale.

Philosophy

When creating this starter kit, we had several guiding principles in mind:

  • Production-ready: We wanted to ensure that this starter was ready for real-world use, providing a solid foundation for building production-grade apps.
  • Developer experience and productivity: Our focus was on creating a starter that would enhance the developer experience and increase productivity.
  • Minimal code and dependencies: We aimed to keep the codebase and dependencies as small as possible.
  • Well-maintained third-party libraries: We included only well-maintained and reliable third-party libraries, to provide stability and support for our projects.

Key Features

Core Framework & Performance

  • Latest Expo SDK 57 with Custom Dev Client: Leverage the best of the Expo ecosystem while maintaining full control over your app.
  • React 19 with React Compiler enabled: Automatic optimization without manual memoization.
  • New Architecture enabled: Fabric renderer, TurboModules, and JSI for superior performance.
  • TypeScript for enhanced code quality and bug prevention through static type checking.

Navigation & Routing

  • Expo Router with typed routes and route groups for type-safe, file-based navigation.
  • 30 interactive component showcases organized in route groups for learning and reference.

UI & Styling

  • Production-ready UI with HeroUI Native (30+ components) and Uniwind for TailwindCSS styling.
  • 6 custom components (Image, Text, Input, List, Modal, StatusBar) for specialized needs.
  • Dark mode support with system preference detection.

State Management & Data

  • Zustand for global client state with selectors pattern for optimal performance.
  • React Query v5 with react-query-kit for type-safe server state management.
  • MMKV for fast, encrypted storage (30x faster than AsyncStorage).
  • Robust form handling with react-hook-form and zod validation.

Development Experience

  • Multi-environment build support (Development, Staging, Production) with environment-specific configs.
  • Clean project structure with absolute imports (@/) for easier navigation.
  • VSCode recommended extensions, settings, and snippets for enhanced productivity.
  • Husky for Git Hooks to automate code quality checks.
  • Lint-staged: Run ESLint and TypeScript checks on staged files only.
  • pnpm enforced for fast, disk-efficient package management.

Testing & Quality

  • Unit testing with Jest and React Native Testing Library.
  • E2E testing with Maestro (3 workflow variants included).
  • 14 GitHub Actions workflows for automated building, releasing, testing, and quality checks.
  • Expo Doctor integration for health checks and dependency validation.

Internationalization & Accessibility

  • i18next for localization with ESLint validation of translation files.
  • Accessibility-first component design with ARIA support.

Additional Features

  • Automatic image compression in PRs to reduce bundle size.
  • Deep linking configured for all routes out of the box.
  • Advanced keyboard handling with react-native-keyboard-controller.
  • Smooth animations with Reanimated.
  • Error boundaries with react-error-boundary for graceful error handling.

Is this starter for me?

Yes!

This starter kit is designed to benefit a wide range of React Native developers, from beginners to experienced professionals. Here's why it might be a good fit for you:

  1. For beginners: It provides a solid foundation with best practices and common solutions, helping you learn industry-standard approaches to React Native development.

  2. For experienced developers: It offers a well-structured, production-ready setup that can save you time and effort in project initialization and configuration.

  3. For teams: It ensures consistency across projects and team members, making it easier to onboard new developers and maintain code quality.

  4. For explorers: Even if you prefer not to use starter kits, this project can serve as a valuable reference. You can explore the codebase, documentation, and architectural decisions to gain insights and potentially adopt specific solutions for your own projects.

  5. For learners: The starter kit incorporates up-to-date libraries and patterns, offering an opportunity to familiarize yourself with current best practices in the React Native ecosystem.

  6. For AI-assisted development: This starter kit works well with AI coding tools. It provides a solid structure and best practices that can guide AI-generated code, helping ensure that AI assistance leads to high-quality, maintainable code that fits well within your project.

Remember, you don't have to use the entire starter kit as-is. Feel free to cherry-pick ideas, configurations, or code snippets that align with your project needs.

Why Expo and not React Native CLI?

We have been using Expo as our main framework since the introduction of Continuous Native Generation (CNG) and we are happy with the experience.

"As of today, the only recommended community framework for React Native is Expo. Folks at Expo have been investing in the React Native ecosystem since the early days of React Native and as of today, we believe the developer experience offered by Expo is best in class." — React Native core team

Still hesitating? Check out this article or this video.

Stay up to date

If you want to stay up to date with the latest developments in our starter kit, you can either watch the repository or hit the "star" button. This will allow you to receive notifications whenever new updates are available.

We value the feedback and contributions of our users, and we encourage you to let us know if you have any suggestions for improving our starter kit.

Libraries Used

Core Framework

Navigation & Routing

UI & Styling

State Management & Data Fetching

Forms & Validation

Storage

Animations & Interactions

Lists & Performance

Internationalization

Developer Experience

Testing

Package Management

  • pnpm (enforced via preinstall script)

Contributors

This starter is maintained by Tuan Anh Le and new contributors are welcome. If you're interested in getting involved, please don't hesitate to open an issue or submit a pull request on GitHub.

FAQ

If you have any questions about the starter, please open an issue or visit the FAQ.

Create a new App

Let's create a new React Native project with Caracal starter.

On this page

MotivationPhilosophyKey FeaturesCore Framework & PerformanceNavigation & RoutingUI & StylingState Management & DataDevelopment ExperienceTesting & QualityInternationalization & AccessibilityAdditional FeaturesIs this starter for me?Why Expo and not React Native CLI?Stay up to dateLibraries UsedCore FrameworkNavigation & RoutingUI & StylingState Management & Data FetchingForms & ValidationStorageAnimations & InteractionsLists & PerformanceInternationalizationDeveloper ExperienceTestingPackage ManagementContributorsFAQ