🔥 firestack-cli

One command. All platforms & frameworks. Zero Firebase setup headache.

Automatically configure Firebase for Next.js, Expo, React (Vite / CRA), Bare React Native, Remix, Astro, and SvelteKit — across Android, iOS, and Web.

npx firestack-cli setup

📖 Table of Contents

• Why firestack-cli?
• Framework Support
• Install
• Quick Start
• Commands
• How It Works
• Doctor & Fix
• Safety Principles
• Development
• Contributing
• License

✨ Why firestack-cli?

Setting up Firebase across different frameworks and platforms is tedious:

• Next.js: Register web app → generate NEXT_PUBLIC_* in .env.local → initialize singleton src/lib/firebase.ts → setup Auth & Firestore.
• Expo: Register iOS & Android apps → download google-services.json & GoogleService-Info.plist → configure app.json plugins & EXPO_PUBLIC_* env vars.
• React (Vite / CRA): Register web app → configure VITE_* / REACT_APP_* in .env → initialize client SDK.
• Bare React Native: Patch root and app build.gradle → drop plist in Xcode folder → setup @react-native-firebase/app.

firestack-cli automates all of that with intelligent framework detection and direct Firebase API integration.

Your Project (Next.js / Expo / Vite / React Native / Remix)
                           │
                           ▼
                     firestack-cli
                           │
         ┌─────────────────┼─────────────────┐
         ▼                 ▼                 ▼
   Web Frameworks         Expo          Bare React Native
 (Next.js/Vite/CRA)   (iOS/Android/Web)   (Android/iOS Native)
         │                 │                 │
   .env / lib/firebase   app.json + plists   Gradle + plists
         │                 │                 │
         └─────────────────┼─────────────────┘
                           ▼
                   Firebase Ready 🔥

🌟 Framework Support

| Framework | Detection Trigger | Config File Location | Env Vars Format | SDK Configured | |---|---|---|---|---| | Next.js (App & Pages) | next | src/lib/firebase.ts / lib/firebase.ts | NEXT_PUBLIC_FIREBASE_* in .env.local | firebase (JS SDK) | | Expo (Managed & Bare) | expo, app.json | app.json + google-services.json + GoogleService-Info.plist | EXPO_PUBLIC_FIREBASE_* in .env | @react-native-firebase or firebase | | React (Vite) | vite + react | src/lib/firebase.ts / src/firebase.ts | VITE_FIREBASE_* in .env | firebase (JS SDK) | | Create React App | react-scripts | src/firebase.ts | REACT_APP_FIREBASE_* in .env | firebase (JS SDK) | | Bare React Native | react-native | android/app/google-services.json & ios/.../GoogleService-Info.plist | Native Gradle / Plist | @react-native-firebase/app | | Remix / Astro / Svelte | package matches | src/lib/firebase.ts / app/lib/firebase.ts | Framework-specific env prefix | firebase (JS SDK) |

📦 Install

Use without installing (recommended)

npx firestack-cli setup
# or
bunx firestack-cli setup

Install globally

# npm
npm install -g firestack-cli

# bun
bun add -g firestack-cli

# pnpm
pnpm add -g firestack-cli

Prerequisites

| Requirement | Purpose | |---|---| | Firebase CLI | API access — npm i -g firebase-tools | | firebase login | Authenticate before running setup | | Node.js ≥ 18 | Runtime |

🚀 Quick Start

From the root of your project:

npx firestack-cli setup

The CLI auto-detects your framework and guides you through every step:

🔥 Firebase Setup CLI for Web, React Native & Expo

✔ Project analyzed
  Framework: Next.js (App Router)
  Package manager: bun
  TypeScript: yes

✔ Firebase CLI v15.8.0 found
✔ Authenticated as [email protected]

? Select a Firebase project to connect: › my-awesome-app
? Which Firebase services do you want to initialize in code?
  ✔ Authentication (auth)
  ✔ Cloud Firestore (db)
  ✔ Cloud Storage (storage)

◆ Configuring Firebase for Next.js (App Router)
✔ Created .env.local with NEXT_PUBLIC_FIREBASE_* variables
✔ Firebase client initialized at src/lib/firebase.ts

◆ Dependency Management
✔ Installed missing dependencies (firebase)

🎉 Firebase configuration complete!

🧩 Commands

| Command | Description | |---|---| | firestack setup | Interactive Firebase setup wizard | | firestack doctor | Diagnose configuration & env issues (read-only) | | firestack fix | Auto-fix all detected problems | | firestack fix env | Fix environment variables (.env.local / .env) | | firestack fix web | Fix Web / JS SDK configuration | | firestack fix android | Fix Android native configuration | | firestack fix ios | Fix iOS native configuration | | firestack fix deps | Install missing Firebase dependencies | | firestack --help | Show help | | firestack --version | Show version |

🧠 How It Works

1 · Multi-Framework Detection

firestack-cli inspects your project before making changes:

• Framework — Next.js (App / Pages router), Expo (with Expo Router), Vite, CRA, Remix, Astro, SvelteKit, Bare React Native
• Package manager — Bun, npm, pnpm, or Yarn
• Environment format — .env.local (Next.js) or .env (Vite/Expo) with appropriate variable prefixes
• Native folders — android/ and ios/ presence for mobile builds
• Firebase services — Auth, Firestore, Storage, Realtime DB, and Analytics

2 · Environment Variables & Client Boilerplate

• Generates .env.local or .env: Safely appends or updates FIREBASE_* credentials while preserving all your existing non-Firebase environment variables.
• Generates Type-Safe Client Module: Creates src/lib/firebase.ts (or .js) with singleton guards and typed exports for auth, db, storage, and analytics.

3 · Native Mobile Configuration (Expo & Bare RN)

• Android: Downloads google-services.json, patches build.gradle classpath inside buildscript {}, applies plugin in android/app/build.gradle.
• iOS: Downloads GoogleService-Info.plist, places it in Xcode target folders, and updates app.json.
• Expo Prebuild: Detects missing native folders and offers to run expo prebuild --no-install.

🩺 Doctor & Fix

Doctor — read-only diagnostics

npx firestack-cli doctor

🔥 Firebase Doctor

Project
  ✔ Framework: Next.js (App Router) (bun)
  ✔ Firebase CLI: Installed (v15.8.0)
  ✔ Firebase authentication: Authenticated as [email protected]

Environment
  ✔ .env.local: Environment configuration file found

Web
  ✔ Firebase configuration: Configuration module found (src/lib/firebase.ts)

Dependencies
  ✔ firebase (JS SDK): Installed

No problems detected! Your Firebase setup is healthy.

Fix — automated remediation

npx firestack-cli fix          # fix all issues
npx firestack-cli fix env      # fix .env / .env.local variables
npx firestack-cli fix web      # fix client boilerplate
npx firestack-cli fix android  # fix Android native
npx firestack-cli fix ios      # fix iOS native
npx firestack-cli fix deps     # install missing packages

🛡️ Safety Principles

• No passwords — uses official firebase login OAuth session
• No silent overwrites — existing google-services.json and GoogleService-Info.plist are backed up as .bak before replacement
• Env safety — .env.local and .env parsing preserves all existing environment variables
• No shell injection — all subprocess execution uses shell: false with argument validation
• Path traversal protection — paths from app.json are validated against root boundary
• Idempotent — running setup multiple times never duplicates Gradle plugins or env keys

🧪 Development & Testing

# Clone
git clone https://github.com/tharunpoongavanam/firestack-cli.git
cd firestack-cli

# Install
bun install

# Run tests (44 tests across 7 suites)
bun test

# Build for distribution
bun run build

📄 License

MIT © Tharun Poongavanam

npm · GitHub · Issues

Made with ❤️ for the Web & Mobile React community