nextjs-firebase-starter - GitLite

KO | EN

gitlite — search

#react #ai #llm #machine-learning #deep-learning #docker #java #windows #awesome #cli #security #pytorch #mcp #ios

nextjs-firebase-starter

(★ 158)

A production-ready starter template for building full-stack web applications with Next.js 15, React 19, and Firebase. This template ships with email/password authentication, Firestore data helpers, a route-protected admin page, and a global auth context so you can skip the boilerplate.

파일 탐색기

최종 버전 다운로드 (.zip)

- - bug_report.md
  - feature_request.md
- - automerge.yml
  - dependabot-rebase-cascade.yml
  - dependency-review.yml
  - label.yml
  - merge-gatekeeper.yml
  - release.yml
- dependabot.yml
- labeler.yml
- next.svg
- vercel.svg
- - favicon.ico
  - globals.css
  - layout.tsx
  - page.tsx
- - AuthContext.tsx
- - config.ts
.eslintrc.json
.gitignore
CHANGELOG.md
CODE_OF_CONDUCT.md
CONTRIBUTING.md
LICENSE
next.config.js
package-lock.json
package.json
postcss.config.mjs
README.md
SECURITY.md
tailwind.config.js
tsconfig.json

# 설치 가이드

1. 코드 내려받기

git clone https://github.com/milliorn/nextjs-firebase-starter

깃허브에서 프로젝트 코드 전체를 내 컴퓨터로 내려받습니다.

cd nextjs-firebase-starter

방금 내려받은 프로젝트 폴더 안으로 이동합니다.

2. Node.js

쉬움 추천

사전 준비물

Git GitHub에서 프로젝트 코드를 내려받으려면 필요합니다.
Node.js npm 명령어를 쓰려면 Node.js가 설치되어 있어야 합니다. LTS(장기지원) 버전을 추천합니다.

npm install

package.json에 명시된 라이브러리들을 내려받아 설치합니다.

npm run dev

개발/실행 서버를 켭니다.

npm run build

배포용으로 코드를 최적화해서 빌드 파일을 생성합니다.

npm run start

개발/실행 서버를 켭니다.

✅ 명령어 실행 후 터미널에 나타나는 주소(보통 http://localhost:3000 형태)를 브라우저에서 열어보세요.

이 레포의 README에 적힌 실제 명령어를 그대로 가져왔습니다.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Next.js Firebase Starter

A production-ready starter template for building full-stack web applications with **Next.js 15**, **React 19**, and **Firebase**. This template ships with email/password authentication, Firestore data helpers, a route-protected admin page, and a global auth context so you can skip the boilerplate and start building.

---

## Tech Stack

| Layer          | Technology                                                       |
| -------------- | ---------------------------------------------------------------- |
| Framework      | [Next.js 15](https://nextjs.org/) (App Router)                   |
| UI Library     | [React 19](https://react.dev/)                                   |
| Styling        | [Tailwind CSS](https://tailwindcss.com/)                         |
| Language       | [TypeScript](https://www.typescriptlang.org/)                    |
| Backend / Auth | [Firebase](https://firebase.google.com/) (Auth + Firestore)      |
| Linting        | [ESLint](https://eslint.org/) + [Prettier](https://prettier.io/) |

---

## Features

- **Email / Password Authentication** - sign-up, sign-in, and sign-out flows backed by Firebase Auth
- **Global Auth Context** - a React context provider (`AuthContextProvider`) wraps the app and exposes the current user via `useAuthContext()`
- **Protected Routes** - the `/admin` route redirects unauthenticated users to the home page
- **Firestore Helpers** - typed `addData` and `getData` utilities for reading and writing documents
- **App Router** - built on the Next.js App Router with server components, layouts, and file-based routing
- **Inter Font** - automatically loaded and optimized via `next/font/google`

---

## Prerequisites

- **Node.js 18** or higher
- **npm** (bundled with Node.js)
- A [Firebase project](https://console.firebase.google.com/)

---

## Getting Started

### 1. Use the template

Click **Use this template** on GitHub to create your own repository, then clone it:

```bash
git clone https://github.com/<your-username>/<your-repo>.git
cd <your-repo>
npm install
```

### 2. Configure environment variables

Create a `.env.local` file in the project root:

```bash
cp .env.local.example .env.local   # if the example file exists, otherwise create it
```

Add your Firebase project credentials (see [Set Up Firebase](#set-up-firebase) below):

```env
NEXT_PUBLIC_FIREBASE_API_KEY=your_api_key
NEXT_PUBLIC_FIREBASE_AUTH_DOMAIN=your_auth_domain
NEXT_PUBLIC_FIREBASE_PROJECT_ID=your_project_id
NEXT_PUBLIC_FIREBASE_STORAGE_BUCKET=your_storage_bucket
NEXT_PUBLIC_FIREBASE_MESSAGING_SENDER_ID=your_messaging_sender_id
NEXT_PUBLIC_FIREBASE_APP_ID=your_app_id
```

> **Important:** `.env.local` is already listed in `.gitignore`. Never commit real credentials to version control.

### 3. Run the development server

```bash
npm run dev
```

Open [http://localhost:3000](http://localhost:3000) in your browser. The page hot-reloads as you edit files under `src/`.

---

## Set Up Firebase

1. Go to [https://console.firebase.google.com/](https://console.firebase.google.com/) and sign in with your Google account.
2. Click **Add project**, give it a name, and click **Create project**.
3. On the project overview page, click the **web** icon (`</>`) to register a web app.
4. Give the app a nickname and click **Register app**. Firebase will display your config object. Copy the values into `.env.local`.
5. In the left sidebar, go to **Build > Authentication > Sign-in method** and enable **Email/Password**.
6. _(Optional)_ Go to **Build > Firestore Database** and create a database to use the Firestore helpers.

---

## Project Structure

```text
src/
├── app/                        # Next.js App Router pages and layouts
│   ├── admin/
│   │   └── page.tsx            # Protected page, redirects unauthenticated users
│   ├── signin/
│   │   └── page.tsx            # Sign-in page
│   ├── signup/
│   │   └── page.tsx            # Sign-up page
│   ├── globals.css             # Global styles (Tailwind base imports)
│   ├── layout.tsx              # Root layout, wraps app in AuthContextProvider
│   └── page.tsx                # Home page
│
├── context/
│   └── AuthContext.tsx         # Auth context provider and useAuthContext hook
│
└── firebase/
    ├── config.ts               # Firebase app initialization (singleton)
    ├── auth/
    │   ├── signIn.ts           # signInWithEmailAndPassword wrapper
    │   └── signup.ts           # createUserWithEmailAndPassword wrapper
    └── firestore/
        ├── addData.ts          # setDoc helper with merge support
        └── getData.js          # getDoc helper
```

---

## Authentication

Authentication is handled through Firebase Auth and surfaced app-wide via a React context.

**`src/context/AuthContext.tsx`** subscribes to `onAuthStateChanged` and exposes `{ user }` to any component that calls `useAuthContext()`. The root layout wraps the entire app in this provider, so auth state is always available client-side.

**`src/firebase/auth/`** contains two thin async wrappers:

- `signIn(email, password)` - calls `signInWithEmailAndPassword` and returns `{ result, error }`
- `signup(email, password)` - calls `createUserWithEmailAndPassword` and returns `{ result, error }`

Both functions return a consistent `{ result, error }` shape so callers can handle errors without try/catch.

**Protected routes** - `src/app/admin/page.tsx` demonstrates the pattern: read `user` from `useAuthContext()` inside a `useEffect`, then call `router.push("/")` if the user is `null`.

---

## Firestore Helpers

Two utility functions live in `src/firebase/firestore/`:

| Function                        | Description                                                                            |
| ------------------------------- | -------------------------------------------------------------------------------------- |
| `addData(collection, id, data)` | Writes (or merges) a document at `collection/id` using `setDoc` with `{ merge: true }` |
| `getData(collection, id)`       | Reads a single document from `collection/id` using `getDoc`                            |

Both return `{ result, error }` for consistent error handling.

---

## Available Scripts

| Command           | Description                                                      |
| ----------------- | ---------------------------------------------------------------- |
| `npm run dev`     | Start the development server at `http://localhost:3000`          |
| `npm run build`   | Build the application for production                             |
| `npm run start`   | Start the production server (requires `build` first)             |
| `npm run lint`    | Run ESLint across the project                                    |
| `npm run release` | Bump the version and generate a changelog via `standard-version` |

---

## Deployment

### Vercel (recommended)

1. Push your repository to GitHub.
2. Import the project at [vercel.com/new](https://vercel.com/new).
3. Add all `NEXT_PUBLIC_FIREBASE_*` environment variables in the Vercel project settings.
4. Deploy. Vercel handles builds and previews automatically on every push.

### Other platforms

Set the same `NEXT_PUBLIC_FIREBASE_*` environment variables in your host's dashboard and run:

```bash
npm run build
npm run start
```

See the [Next.js deployment documentation](https://nextjs.org/docs/deployment) for platform-specific guidance.

---

## Contributing

Contributions are welcome. Please read [CONTRIBUTING.md](CONTRIBUTING.md) before opening a pull request. Bug reports and feature requests can be filed via [GitHub Issues](../../issues).

## Security

Please review [SECURITY.md](SECURITY.md) for the project's vulnerability disclosure policy.

## License

This project is licensed under the **MIT License**. See [LICENSE](LICENSE) for details.

---

## Resources

- [Next.js Documentation](https://nextjs.org/docs)
- [Firebase Documentation](https://firebase.google.com/docs)
- [Tailwind CSS Documentation](https://tailwindcss.com/docs)
- [TypeScript Documentation](https://www.typescriptlang.org/docs/)