3.3.0 (Jan 19, 2025)

Changelog v3.3.0

🎨 New Feature: Uniwind Styling Option

This release adds Uniwind as a third styling option alongside NativeWind and Unistyles.

What is Uniwind?

Uniwind is a Tailwind CSS solution for React Native that offers:

• Tailwind v4 support with CSS-first configuration
• Type-safe styling with automatic TypeScript generation
• Live theme switching with Uniwind.setTheme()
• CSS variables for dynamic theming
• 3-theme system (light/dark/premium) out of the box

Styling Options

When running the CLI, you now have 3 choices:

1. NativeWind - Tailwind CSS v3 for React Native (2-theme: light/dark)
2. Unistyles - Type-safe styling with breakpoints (3-theme: light/dark/premium)
3. Uniwind - Tailwind CSS v4 with live theming (3-theme: light/dark/premium) ✨ NEW

---

🔧 Technical Changes

Uniwind Configuration

Dependencies Added

{
  "uniwind": "1.2.4",
  "tailwindcss": "4.1.16",
  "postcss": "8.5.6",
  "lightningcss": "1.30.2",
  "react-native-gesture-handler": "2.28.0",
  "react-native-keyboard-controller": "1.18.5"
}

Metro Config

const { withUniwindConfig } = require('uniwind/metro');

module.exports = withUniwindConfig(config, {
  cssEntryFile: './app/global.css',
  extraThemes: ['premium'],
});

Theme System

• Uses @layer theme with @variant light/dark/premium blocks in CSS
• Uniwind.setTheme() for live theme switching
• useUniwind() hook for accessing current theme
• MMKV persistence for theme preference

File Structure

app/
├── global.css          # Tailwind v4 CSS with theme variants
├── _layout.tsx         # Imports global.css, uses withUniwind HOC
└── (tabs)/
    ├── _layout.tsx     # Uses useUniwindTheme for navigation colors
    ├── index.tsx       # Styled with Tailwind classes
    └── settings.tsx    # Theme toggle button

components/
├── container.tsx       # SafeAreaView wrapped with withUniwind
└── theme-toggle.tsx    # 3-theme cycle with haptic feedback

lib/
├── mmkvStorage.ts      # MMKV storage instance
└── use-uniwind-theme.ts # Theme hook with persistence

constants/
├── themes.ts           # Theme icons and config
└── uniwind-themes.ts   # Color definitions per theme

---

🐛 Bug Fixes

Uniwind Serialization Error

• Fixed "Failed to serialize javascript object" error
• Caused by Tailwind scanning node_modules and native iOS files
• Solution: @source directives in CSS to limit scan scope

Theme Not Updating Live

• Fixed by using Uniwind.setTheme() instead of updateCSSVariables()
• Added extraThemes: ['premium'] in metro config for custom themes
• Proper @variant blocks in @layer theme for CSS variables

---

📦 Migration from v3.1.x

If you have an existing project, generate a new one with Uniwind to see the correct configuration, then:

1. Install new dependencies:

   bun add uniwind@1.2.4 tailwindcss@4 postcss lightningcss

2. Update metro.config.js to use withUniwindConfig

3. Move global.css to app/global.css with proper @layer theme syntax

4. Update _layout.tsx to import ./global.css and use Uniwind.setTheme()

---

📚 Documentation

• Uniwind Quickstart
• Uniwind Theming
• Uniwind Components
• updateCSSVariables API

---

Full Changelog: v3.1.0...v3.2.0

3.1.0 (Jan 19, 2026)

🔧 Fast Expo App v3.1.0 - Stability & Dependency Fixes

🛠️ Patch Release - Critical Bug Fixes

This is a minor release focused on fixing critical dependency issues, navigation errors, and ensuring stable project generation. All version specifiers are now exact (no ^ or ~) for reproducible builds.

---

✨ What's Fixed

🔗 React Query Persistence (NEW Dependencies)

Added missing dependencies for proper React Query + MMKV persistence:

"@tanstack/react-query-persist-client": "5.90.7",
"@tanstack/query-sync-storage-persister": "5.90.7"

DevDependencies:

"@dev-plugins/react-native-mmkv": "0.4.0"

These are now mandatory since MMKV is always included. The QueryProvider now properly persists queries to MMKV storage with dev tools support.

🧭 Navigation Context Error Fix

Fixed: [Error: Couldn't find a LinkingContext context]

Updated @react-navigation/native and added missing peer dependencies:

"@react-navigation/native": "7.1.8",        // was 7.1.6
"@react-navigation/bottom-tabs": "7.4.0",   // NEW
"@react-navigation/elements": "2.6.3"       // NEW

This resolves the LinkingContext error that occurred with expo-router 6.0.14+.

💎 Unistyles v3 Compatibility

Updated to latest stable Unistyles v3:

"react-native-unistyles": "3.0.21"  // was 2.8.0

Fixed: Module manager now correctly sets the same version as the template, ensuring consistent builds.

📦 Expo SDK Updates

"expo": "54.0.31",           // was 54.0.23
"expo-linking": "8.0.11"     // was 8.0.8

---

🔒 Exact Version Pinning

All dependencies now use exact versions (no ^ or ~):

Dependency	Before	After
@tanstack/react-query	^5.90.7	5.90.7
react-native-unistyles	^3.0.18	3.0.21
react-native-worklets	^0.5.1	0.5.1
zustand	^5.0.2	5.0.2
expo-haptics	~14.0.0	14.0.0
react-native-edge-to-edge	^1.0.0	1.0.0
react-native-gesture-handler	~2.28.0	2.28.0
react-native-keyboard-controller	^1.18.5	1.18.5
expo-dev-client	~6.0.17	6.0.17

This ensures reproducible builds and prevents unexpected breaking changes from minor version updates.

---

🏗️ CLI Improvements

Module Manager Sync

The module-manager.ts now uses the same versions as the template package.json:

// Before: Version mismatch
deps['react-native-unistyles'] = '3.0.18'; // CLI
// template had 2.8.0

// After: Consistent versions
deps['react-native-unistyles'] = '3.0.21'; // Both match

Build Process

• ✅ Templates are now copied with correct dependency versions
• ✅ No more version conflicts between CLI and generated projects
• ✅ Clean builds without peer dependency warnings

---

📋 Full Dependency Changes

Dependencies Added

"@tanstack/react-query-persist-client": "5.90.7",
"@tanstack/query-sync-storage-persister": "5.90.7",
"@react-navigation/bottom-tabs": "7.4.0",
"@react-navigation/elements": "2.6.3"

Dependencies Updated

"@react-navigation/native": "7.1.6" → "7.1.8",
"expo": "54.0.23" → "54.0.31",
"expo-linking": "8.0.8" → "8.0.11",
"react-native-unistyles": "2.8.0" → "3.0.21",
"@dev-plugins/react-native-mmkv": "0.0.3" → "0.4.0"

---

🐛 Bugs Fixed

Issue	Status
LinkingContext context error on app start	✅ Fixed
React Query not persisting to MMKV	✅ Fixed
Version mismatch between CLI and template	✅ Fixed
Unistyles v3 initialization issues	✅ Fixed
MMKV DevTools not working	✅ Fixed
Inconsistent dependency versions	✅ Fixed

---

🚀 Upgrade Guide

For New Projects

Simply run:

bunx fast-expo-app@3.1.0

For Existing v3.0.0 Projects

Update your package.json:

# Add missing dependencies
bun add @tanstack/react-query-persist-client@5.90.7 @tanstack/query-sync-storage-persister@5.90.7 @react-navigation/bottom-tabs@7.4.0 @react-navigation/elements@2.6.3

# Update existing dependencies
bun add @react-navigation/native@7.1.8 react-native-unistyles@3.0.21

# Add dev dependency
bun add -D @dev-plugins/react-native-mmkv@0.4.0

# Reinstall
rm -rf node_modules && bun install

---

📊 Stats

• 5 critical bugs fixed
• 4 new dependencies added
• 6 dependencies updated
• 9 versions pinned to exact
• 100% version consistency between CLI and templates

---

🔗 Links

• npm: https://www.npmjs.com/package/fast-expo-app
• GitHub: https://github.com/Teczer/expo-react-native-nativewind-typescript-boilerplate
• Website: https://fast-expo-app-web.vercel.app/

---

📦 Installation

# Using Bun (recommended)
bunx fast-expo-app@3.1.0

# Or using npm
npx fast-expo-app@3.1.0

---

Full Changelog: v3.0.0...v3.1.0

---

Made with ♥ by Teczer

⭐ Star the repo if you find it useful!

3.0.0 (Dec 1, 2025)

🎉 Fast Expo App v3.0.0 - Dual Styling & Enhanced Architecture

🚀 Major Release - Dual Styling System

This is a major release introducing a powerful dual styling system, mandatory MMKV storage, and significant architectural improvements. Choose between NativeWind v4 or Unistyles v3 during project creation!

---

✨ What's New

🎨 Dual Styling System (NEW!)

Choose your preferred styling solution during CLI setup:

NativeWind v4 🌊

• Tailwind CSS for React Native
• Utility-first approach with className
• 2-theme system (light/dark)
• MMKV-persisted theme preferences
• Centralized color utilities in utils/colors.ts
• Perfect for developers familiar with Tailwind

Unistyles v3 💎

• Type-safe styling with StyleSheet.create
• 3-theme system (light/dark/premium)
• Runtime theme switching with full TypeScript support
• MMKV-persisted theme preferences
• Breakpoints and responsive design
• Better performance for complex UIs
• Theme configs in constants/themes.ts

💾 Mandatory MMKV Storage

MMKV is now always included (no longer optional):

• ~30x faster than AsyncStorage
• Nitro Modules for native performance
• Used for theme persistence
• Zustand integration (optional)
• React Query persistence (optional)

🌓 Enhanced Theme System

For Unistyles:

// 3 themes with smooth cycling
light → dark → premium → light

// Haptic feedback on theme change
// MMKV persistence
// Runtime switching with UnistylesRuntime

For NativeWind:

// 2 themes with toggle
light ↔ dark

// Haptic feedback on theme change
// MMKV persistence
// usePersistedColorScheme hook

🏗️ Better Project Architecture

New Structure:

your-app/
├── lib/                      # Core utilities
│   ├── mmkvStorage.ts       # MMKV storage (mandatory)
│   ├── query-client.ts      # React Query config
│   ├── use-persisted-color-scheme.ts  # NativeWind theme hook
│   └── zustand.ts           # Zustand store (optional)
├── providers/                # React providers (NEW!)
│   └── query-provider.tsx   # React Query provider
├── utils/                    # Utilities (NEW!)
│   └── colors.ts            # Color utilities (NativeWind)
├── constants/                # Constants (NEW!)
│   └── themes.ts            # Theme configs (Unistyles)
├── components/               # React components
│   ├── container.tsx        # Container with SafeArea
│   ├── theme-toggle.tsx     # Theme toggle button
│   └── external-link.tsx    # External link component
└── app/                      # Expo Router screens

Key Changes:

• ✅ providers/ folder for React providers (moved from lib/)
• ✅ utils/ folder for utility functions
• ✅ constants/ folder for theme configurations
• ✅ All components use kebab-case naming
• ✅ Conditional file generation based on styling choice

🔧 Conditional Generation

The CLI now generates only what you need:

• ✅ NativeWind files OR Unistyles files (not both)
• ✅ Module-specific files only if selected
• ✅ Clean output with no unused code
• ✅ Proper imports and configurations

⚡ Performance Enhancements

New dependencies for better UX:

• react-native-worklets - High-performance animations
• expo-haptics - Native haptic feedback on theme toggle
• react-native-edge-to-edge - Modern edge-to-edge display
• Optimized imports - Absolute paths with @/ prefix

---

🔄 Breaking Changes from v2.x

1. MMKV is Mandatory

• ❌ No longer optional in CLI
• ✅ Always included by default
• Used for theme persistence

2. Styling Choice Required

• ❌ Can't skip styling selection
• ✅ Must choose NativeWind OR Unistyles

3. File Structure Changed

• lib/query-provider.tsx → providers/query-provider.tsx
• lib/utils.ts → utils/ (for NativeWind colors)
• New constants/ folder for theme configs

4. Theme System Redesigned

• ✅ MMKV persistence for both styling options
• ✅ Haptic feedback on theme change
• ✅ 3 themes for Unistyles (light/dark/premium)
• ✅ 2 themes for NativeWind (light/dark)

5. Component Naming

• ❌ PascalCase: ToggleTheme.tsx, Container.tsx
• ✅ kebab-case: theme-toggle.tsx, container.tsx

6. Unistyles Configuration

• ✅ unistyles.ts moved to project root
• ✅ index.js entry point for proper initialization
• ✅ package.json main field updated to index.js

---

📦 Migration from v2.x

If you have an existing v2.x project:

1. Generate a new v3.0.0 project

   bunx fast-expo-app@latest

2. Copy your custom code

   • Move screens from app/
   • Copy custom components
   • Migrate business logic

3. Update imports

   // Old
   import { QueryProvider } from '@/lib/query-provider';
   
   // New
   import { QueryProvider } from '@/providers/query-provider';

4. Adopt new theme system

   • Use MMKV for theme persistence
   • Update theme toggle components
   • Leverage new theme configurations

---

🎯 Features Comparison

Feature	NativeWind v4	Unistyles v3
Styling	Utility classes	StyleSheet API
Type Safety	⚠️ Limited	✅ Full TypeScript
Themes	2 (light/dark)	3 (light/dark/premium)
Performance	✅ Good	✅ Excellent
Learning Curve	Easy (Tailwind)	Medium
Bundle Size	Larger	Smaller
Breakpoints	✅ Yes	✅ Yes
Persistence	✅ MMKV	✅ MMKV
Haptic Feedback	✅ Yes	✅ Yes

---

🛠️ Technical Improvements

CLI Enhancements

• ✅ Conditional file generation based on styling choice
• ✅ Better error handling and validation
• ✅ Improved module management
• ✅ Cleaner output with no unused files

Code Quality

• ✅ Full TypeScript strict mode
• ✅ ESLint + Prettier pre-configured
• ✅ Consistent naming conventions
• ✅ Better file organization

Documentation

• ✅ Updated AGENTS.md with v3.0.0 details
• ✅ Comprehensive README.md
• ✅ New npm package README
• ✅ Migration guide included

---

📊 Stats

• 169 commits since v2.0.1
• Dual styling system with 2 complete implementations
• 3-theme support for Unistyles
• MMKV integration for both styling options
• Conditional generation for clean projects
• Documentation: 3,000+ lines updated

---

🎨 Code Examples

NativeWind Theme Toggle

import { usePersistedColorScheme } from '@/lib/use-persisted-color-scheme';

export function ThemeToggle() {
  const { colorScheme, setColorScheme } = usePersistedColorScheme();
  
  const toggle = () => {
    Haptics.impactAsync(Haptics.ImpactFeedbackStyle.Light);
    setColorScheme(colorScheme === 'light' ? 'dark' : 'light');
  };
  
  return <Pressable onPress={toggle}>...</Pressable>;
}

Unistyles Theme Cycling

import { UnistylesRuntime } from 'react-native-unistyles';
import { mmkvStorage } from '@/lib/mmkvStorage';

const handleThemeChange = () => {
  Haptics.impactAsync(Haptics.ImpactFeedbackStyle.Light);
  
  const nextTheme = currentTheme === 'light' ? 'dark' 
    : currentTheme === 'dark' ? 'premium' 
    : 'light';
  
  mmkvStorage.setItem('app-theme', nextTheme);
  UnistylesRuntime.setTheme(nextTheme);
};

---

🙏 Acknowledgments

Special thanks to:

• NativeWind team for v4 improvements
• Unistyles team for v3 architecture
• MMKV for blazing-fast storage
• Community feedback and contributions

---

🔗 Links

• npm: https://www.npmjs.com/package/fast-expo-app
• GitHub: https://github.com/Teczer/expo-react-native-nativewind-typescript-boilerplate
• Website: https://fast-expo-app-web.vercel.app/
• Documentation: See AGENTS.md for complete details

---

📦 Installation

# Using Bun (recommended)
bunx fast-expo-app@latest

# Or using npm
npx fast-expo-app@latest

---

🎉 What's Next?

• 🔮 More optional modules (Sentry, Analytics, etc.)
• 🎨 Additional theme presets
• 📱 More component examples
• 🧪 E2E testing setup option
• 🌍 i18n support

---

Full Changelog: v2.0.1...v3.0.0

---

Made with ♥ by Teczer

⭐ Star the repo if you find it useful!

2.0.0 (Nov 10, 2025)

🚀 Fast Expo App v2.0.0 - Major Update

November 10, 2025

This is a major update with significant improvements to the boilerplate, including upgraded dependencies, new optional modules, and enhanced developer experience.

✨ What's New

Core Updates

• Upgraded to Expo SDK 54 with latest features and improvements
• Upgraded to React Native 0.81 with New Architecture fully enabled
• TypeScript 5.9 with improved type safety
• NativeWind v4.1 for modern Tailwind CSS styling

New Features

• ✅ MMKV v4 - Ultra-fast storage with Nitro Modules (~30x faster than AsyncStorage)
• ✅ TanStack Query v5 - Powerful data fetching and server state management
• ✅ expo-dev-client - Enhanced debugging with native logs and Network Inspector
• ✅ React Native Worklets - Better performance for animations and async operations

Developer Experience

• 🎯 Added dev script for faster development with dev client
• 🎯 Improved MMKV implementation with createMMKV API
• 🎯 Added QueryClientProvider with optimized defaults
• 🎯 Better SafeAreaView configuration with react-native-safe-area-context
• 🎯 Comprehensive AGENTS.md documentation for AI assistants
• 🎯 Fixed iOS linker issues with zlib

Configuration Improvements

• ⚙️ New Architecture fully enabled across iOS and Android
• ⚙️ Optimized Query Client with sensible defaults
• ⚙️ Fixed Metro bundler configuration
• ⚙️ Updated Podfile with proper linker flags

📦 Updated Dependencies

{
  "expo": "~54.0.23",
  "react-native": "0.81.5",
  "react": "19.1.0",
  "nativewind": "^4.1.23",
  "react-native-mmkv": "^4.0.0",
  "@tanstack/react-query": "^5.90.7",
  "expo-dev-client": "~6.0.17",
  "expo-constants": "~18.0.10",
  "react-native-worklets": "0.5.1"
}

🔧 Breaking Changes

• MMKV: Now uses createMMKV() instead of new MMKV()
• New Architecture: Fully enabled - requires pod install and clean build
• React: Upgraded to v19 - may require updates to third-party libraries

📚 Documentation

• Added comprehensive AGENTS.md for AI-assisted development
• Updated README with latest features and setup instructions
• Added React Query usage examples

🙏 Contributors

Special thanks to:

• @neiltalap for suggesting expo-dev-client and debugging tools + update README

🔗 Links

• Boilerplate: https://github.com/Teczer/expo-react-native-nativewind-typescript-boilerplate
• CLI Package: https://github.com/Teczer/fast-expo-app
• Demo: https://fast-expo-app-web.vercel.app/

Made with ♥ by Teczer

2.0.1 (Nov 11, 2025)

🎉 Fast Expo App v2.0.1 - Monorepo Architecture

🏗️ Major Restructuring

This release marks a complete architectural overhaul of the project, transforming it into a professional monorepo following industry best practices (inspired by create-expo-stack).

✨ What's New

📦 Monorepo Structure

The project has been restructured into a modern monorepo with clear separation of concerns:

fast-expo-app-monorepo/
├── cli/                    # 🛠️  CLI source code
│   ├── src/               # TypeScript source
│   ├── templates/base/    # React Native boilerplate
│   └── modules/           # Future optional modules
├── packages/
│   └── fast-expo-app/     # 📦 Published npm package
├── www/                   # 🌐 Landing website (Next.js)
└── scripts/               # 🔧 Automation scripts

🚀 Performance Improvements

• ⚡ 10x Faster Project Creation: CLI now copies local template instead of cloning from GitHub
• 🎯 Smart File Copying: Automatically ignores build artifacts, node_modules, and development files
• 💾 Optimized Template: Removed unnecessary files from the template (Pods, build folders, etc.)

🛠️ Developer Experience

New Commands

# Test CLI locally during development
bun run cli

# Build only what you need
bun run build:cli    # Build CLI package only
bun run build:www    # Build website only

# Automated publishing with version bumping
bun run publish:patch   # 2.0.0 → 2.0.1
bun run publish:minor   # 2.0.0 → 2.1.0
bun run publish:major   # 2.0.0 → 3.0.0

# Easy setup
bun run get_started     # Install all dependencies
bun run clean           # Clean all build artifacts

Turborepo Integration

• ⚡ Parallel task execution
• 💾 Smart caching
• 🎯 Selective builds
• 🔄 Incremental compilation

📝 Documentation Overhaul

• AGENTS.md: Complete technical documentation for AI assistants (953 lines)
• README.md: Updated with new monorepo structure and commands
• QUICK_START.md: New quick start guide for contributors
• CONTRIBUTING.md: Comprehensive contribution guidelines

🔧 Tooling & Configuration

Added

• .npmrc: npm registry configuration
• publish.ts: Automated version bumping and publishing
• .gitignore: Enhanced for monorepo structure
• turbo.json: Turborepo pipeline configuration
• scripts/get_started.sh: One-command dependency installation
• scripts/clean.sh: Comprehensive cleanup script

Improved

• CLI Error Handling: Better validation and error messages
• Template Copying: Smart ignore patterns for build artifacts
• Git Workflow: Proper .gitignore files in each workspace
• Type Safety: Full TypeScript coverage with strict mode

🎨 Website Package

New Next.js 15 landing page at /www/:

• ✨ Modern animated UI components
• 🌙 Dark mode support
• 📱 Fully responsive design
• ⚡ Optimized for Vercel deployment

🔄 Breaking Changes

Project Structure

The repository structure has completely changed. If you were contributing or using the repo directly:

• CLI source moved from root → /cli/src/
• Template moved from root → /cli/templates/base/
• npm package now in /packages/fast-expo-app/

For End Users

No breaking changes! The CLI usage remains the same:

npx fast-expo-app@latest
# or
bunx fast-expo-app@latest

📊 Stats

• 169 files changed
• Complete monorepo restructure
• Documentation: 2,700+ lines
• Automated workflows added

🙏 Acknowledgments

This release was inspired by the excellent architecture of create-expo-stack and modern monorepo best practices.

🔗 Links

• npm Package: https://www.npmjs.com/package/fast-expo-app
• Website: https://fast-expo-app-web.vercel.app/
• Documentation: See AGENTS.md for complete technical details

📦 Installation

npx fast-expo-app@latest

Or with Bun:

bunx fast-expo-app@latest

---

Full Changelog: v2.0.0...v2.0.1