PackRat 🎒

PackRat is the ultimate adventure planner designed for those who love to explore the great outdoors. Our app helps users plan and organize their trips with ease, whether it's a weekend camping trip, a day hike, or a cross-country road trip.

With PackRat, you can create and manage trips, discover new destinations, and stay informed with up-to-date weather forecasts. Our app integrates with Mapbox to provide you with accurate maps and directions to your destinations, as well as suggestions for popular outdoor activities based on the location and season of your trip.

So pack your bags, grab your friends, and get ready for your next adventure with PackRat!

Build & CI:

Repository Info:

Table of Contents

• PackRat 🎒
  • Table of Contents
  • Overview 🌐
  • Documentation 📚
  • Features 🚀
  • Technologies used 💻
  • 🗂 Folder layout
  • 🆕 Add new dependencies
    • Pure JS dependencies
    • Native dependencies
    • Mobile app dependencies
    • API dependencies
    • Web app dependencies
  • Dependency management
  • Local installation 📲
    • Dependencies
    • GitHub Packages Authentication
    • Environment Setup
    • Git Hooks Setup
    • Installation & Development
    • Debugging 🐛
  • API Architecture
  • Contributing 🤝
  • User Stories:
  • User Features:
    • Registration and Authentication:
    • Main Dashboard:
    • Destination Search:
    • Accessing Profile Information:
    • Profile User Overview:
    • Favorite Trips and Packs:
    • Profile Management:
    • Appearance Theme Customization:
    • Profile Editing:
  • Pack Features:
    • Pack Creation and Access Settings:
    • Adding Items to Packs:
    • Pack Scoring System:
    • Navigating to the Dashboard:
  • Trip Features:
    • Trip Creation and Management:
    • Setting up a Trip:
    • Accessing Saved Trips:
    • Viewing Trip Details:
  • Items Feature:
    • Dashboard:
    • Adding Items:
  • Feed Feature:
    • Exploring Backpackers:
    • Pack List Interaction:
    • Item Management:
    • Returning to Feed Dashboard:
  • 👏 Special Thanks
  • License 📝

Overview 🌐

With PackRat, you can:

• Create and manage trips.
• Discover new destinations.
• Stay informed with up-to-date weather forecasts.
• Access accurate maps and directions with our integration to Mapbox.
• Get suggestions for popular outdoor activities based on your trip's location and season.

So pack your bags, grab your friends, and get ready for your next adventure with PackRat!

Documentation 📚

Features 🚀

• Create and manage trips: users can create new trips and manage existing ones by adding details such as dates, locations, and activities.
• Map integration: PackRat integrates with Mapbox to provide users with accurate maps and directions to their destinations.
• Activity suggestions: the app suggests popular outdoor activities based on the location and season of the trip.
• Packing list: users can create and manage packing lists for their trips to ensure they have everything they need.
• Weather forecast: PackRat provides up-to-date weather forecasts for the trip location to help users prepare accordingly.
• User authentication: the app uses user authentication to ensure privacy and data security.

Technologies used 💻

PackRat is built using the following modern technologies:

• React Native + Expo: Cross-platform mobile development with Expo Router
• Next.js: Server-side rendering for web applications (landing page and guides)
• Hono.js: Fast, lightweight web framework running on Cloudflare Workers
• PostgreSQL + Drizzle ORM: Type-safe database operations with Neon serverless database
• Jotai + TanStack Query: Modern state management and data fetching
• AI SDK + OpenAI: AI-powered features and content generation
• Bun: Fast JavaScript runtime and package manager
• Biome: Modern linting and formatting toolchain
• TypeScript: Full type safety across the entire stack
• Tailwind CSS + NativeWind: Utility-first styling for web and mobile
• Mapbox: Location data platform for mobile and web applications

🗂 Folder layout

The main folders are:

• apps/ - Applications

  • expo/ - React Native mobile app with Expo Router
    • app/ - App router screens and layouts
    • features/ - Feature-based modules (auth, packs, etc.)
    • components/ - Reusable UI components
    • atoms/ - Jotai atoms for global state
    • providers/ - React context providers
    • lib/ - Utility libraries and configurations
    • assets/ - Images, fonts, and other static assets
  • landing/ - Next.js landing page website
  • guides/ - Next.js documentation and guides site

• packages/ - Shared packages across apps

  • api/ - Hono.js API server running on Cloudflare Workers
    • src/ - Source code with routes, middleware, and services
    • drizzle/ - Database schema and migrations
    • test/ - API tests
  • ui/ - Shared UI components and design system

🆕 Add new dependencies

Pure JS dependencies

For pure JavaScript libraries that work across all platforms (mobile, web, API):

# Install in the root to share across all apps
bun add lodash

# Or install in specific package if only used there
cd packages/api
bun add dayjs

These dependencies work without platform-specific code and can be safely used in any JavaScript environment.

Native dependencies

For React Native modules that require platform-specific code (Android/iOS):

cd apps/expo
bun add react-native-reanimated

# Don't forget to rebuild after adding native dependencies
bun --cwd apps/expo run expo prebuild --clean

Native dependencies often require additional configuration and may need platform-specific setup. Always check the library's installation guide for React Native.

Mobile app dependencies

For React Native dependencies, install them in the Expo app:

cd apps/expo
bun add react-native-reanimated

API dependencies

For API/server dependencies:

cd packages/api
bun add hono

Web app dependencies

For Next.js apps (landing/guides):

cd apps/landing  # or apps/guides
bun add next

Dependency management

Use ManypKG to check for dependency issues across the monorepo:

bun check:deps
bun fix:deps

Local installation 📲

PackRat is a modern monorepo with mobile, web, and API applications. Follow the steps below to install and run the applications.

Dependencies

• Bun - Primary package manager and runtime
• Node.js - Required for some tooling
• Expo CLI - For mobile development
• Wrangler CLI - For API deployment
• GitHub CLI - For authenticating with GitHub packages

GitHub Packages Authentication

PackRat uses private packages from GitHub Package Registry. You need to authenticate to install dependencies:

Local Development

1. Install GitHub CLI:

   # macOS
   brew install gh
   
   # Windows
   winget install --id GitHub.cli
   
   # Linux - see https://github.com/cli/cli#installation

2. Authenticate with GitHub CLI:

   gh auth login

3. Add the read:packages scope to your authentication:

   gh auth refresh -h github.com -s read:packages

4. Dependencies will now install automatically:

   bun install

   Note: The preinstall script automatically configures GitHub authentication using the GitHub CLI token. The script maps your GitHub CLI token to PACKRAT_NATIVEWIND_UI_GITHUB_TOKEN which is used by bunfig.toml for package authentication.

CI/CD

For GitHub Actions and other CI platforms:

1. Create a Personal Access Token (PAT) with read:packages scope
2. Add it as a secret named PACKRAT_NATIVEWIND_UI_GITHUB_TOKEN in your repository settings
3. Pass it as an environment variable in your workflow:

   - name: Install dependencies
     env:
       PACKRAT_NATIVEWIND_UI_GITHUB_TOKEN: ${{ secrets.PACKRAT_NATIVEWIND_UI_GITHUB_TOKEN }}
     run: bun install

Note: The default GITHUB_TOKEN provided by GitHub Actions does not have access to packages in other repositories, even within the same organization. A custom PAT is required.

Environment Setup

1. Clone the repository:
   HTTPS:

git clone https://github.com/PackRat-AI/PackRat.git

SSH:

git clone git@github.com:PackRat-AI/PackRat.git

2. Navigate to the PackRat directory:

cd PackRat

3. Set up environment variables:

   This project uses a centralized environment configuration strategy. All environment variables are defined in a single source of truth (e.g. .env.local) located at the root of the project.

   A .dev.vars file will be automatically generated for development tools.

   Run bun install to regenerate .dev.vars whenever environment variables are changed.

   Only variables prefixed with PUBLIC_ will be bundled into the Expo app (e.g., PUBLIC_API_URL). These are safe to expose in the client environment.

   ⚠️ Do not include secrets (e.g., private API keys) in PUBLIC_ variables — they may be exposed in the bundled app.

Git Hooks Setup

PackRat uses Lefthook for git hooks to ensure code quality. The hooks are automatically installed when you run bun install.

• Pre-push hook: Runs bun format to check code formatting before pushing
• Configuration: See lefthook.yml in the root directory

If you need to skip hooks temporarily, use:

git push --no-verify

Installation & Development

Install dependencies

From the root directory:

bun install

Running the applications

You can run each application independently:

Mobile App (Expo):

# Start Expo development server
bun expo

# Or run directly on device/simulator
bun android  # for Android
bun ios       # for iOS

API Server:

# Start API in development mode
bun api

Landing Page:

cd apps/landing
bun dev

Guides Site:

cd apps/guides
bun dev

Development workflow

For mobile development, you'll typically run:

# Terminal 1: Start the API
bun api

# Terminal 2: Start the mobile app
bun expo

Debugging 🐛

Common Issues

Expo/Mobile App Issues:

# Doctor check for Expo setup
bun --cwd apps/expo run expo-doctor

# Fix dependencies
bun --cwd apps/expo run expo install --fix

# Clean build
bun --cwd apps/expo run expo prebuild --clean

# Clear cache
bun expo --clear

Dependency Issues:

# Check monorepo dependencies
bun check:deps

# Fix dependency mismatches
bun fix:deps

# Clean and reinstall
bun clean
bun install

API/Cloudflare Issues:

• Check that your wrangler.jsonc is configured correctly in packages/api/
• Ensure your Cloudflare environment variables are set
• Use bun api to start the development server locally

Code Quality

PackRat uses modern tools for code quality and consistency:

# Format all code
bun format

# Lint and fix issues
bun lint

# Type checking
bun check-types

# Check dependency consistency
bun check:deps

The project uses Lefthook for git hooks - these run automatically on push to ensure code quality.

API Architecture

The PackRat API is built with:

• Hono.js - Fast, lightweight web framework
• Cloudflare Workers - Serverless edge computing platform
• Drizzle ORM - Type-safe database operations
• PostgreSQL - Database hosted on Neon
• OpenAI integration - AI-powered features

See packages/api/ for the complete API implementation.

Contributing 🤝

Contributions to PackRat are welcome! To contribute, follow these steps:

1. Clone this repository.
2. Create a new branch.
3. Make your changes and commit them.
4. Push your changes to the remote branch.
5. Open a pull request.
6. Wait for your pull request to be reviewed and merged.
7. Celebrate! 🎉

User Stories:

👏 Special Thanks

• React Native Developers
• OpenStreetMap Developers
• RN MapBox Developers
• Cloudflare Developers
• Yusuke Wada - Creator of Hono.js
• Nate Birdman - Creator of Tamagui
• Fernando Rojo - Creator of Zeego
• Tanner Linsley - Creator of TanStack
• Timothy Miller - Creator of T4 Stack
• Expo Developers - Office hours
• Shopify Developers

License 📝

PackRat is licensed under the terms of the GNU General Public License v3.0. See LICENSE for more information.