A minimalist, production-ready starter for building full-stack applications with Next.js and PocketBase.
- 🚀 Quick Start
- 🧰 Core Features
- 📦 Installation Methods
- 📄 Project Structure
- 🔧 Available Commands
- 🔐 Setting Up PocketBase Admin
- 🛠 Advanced Features
- 📝 Development
- 📚 Learn More
- ❓ Troubleshooting
- 📄 License
# Create a new project using bunx
bunx pocketnext@latest my-app
# OR use bun create (recommended)
bun create pocketnext my-app
# Navigate to your project
cd my-app
# Start the development environment
bun devPocketNext offers a streamlined project creation experience with pre-configured profiles:
| Profile | Description |
|---|---|
| Minimal | Basic setup with essential features only |
| Standard | Recommended setup for most projects (default) |
| Production | Full setup with CI/CD and deployment configuration |
| Custom | Choose each option individually |
You can select a profile during the interactive setup or specify it directly:
# Create a project with minimal configuration
bunx pocketnext@latest my-app --profile=minimal
# Create a production-ready project
bunx pocketnext@latest my-app --profile=production
# Quick setup with sensible defaults
bunx pocketnext@latest my-app --quickAll commands support these options:
| Option | Description |
|---|---|
--profile=<profile> |
Select project setup profile (minimal, standard, production, custom) |
--quick |
Quick setup with minimal prompts |
--use-npm/yarn/pnpm/bun |
Choose a package manager |
-y, --yes |
Skip interactive prompts and use defaults |
--skip-install |
Skip package installation |
--scripts <option> |
Automate PocketBase setup (runAndKeep or runAndDelete) |
--pb-version <version> |
Install specific PocketBase version |
--help |
Show all available options |
# Example with multiple options
bunx pocketnext@latest my-app --profile=production --use-bun --skip-install# Clone the repository
git clone https://github.com/kacperkwapisz/pocketnext.git
cd pocketnext
# Option 1: Copy the template folder to your project location
cp -r templates/default /path/to/your-project
cd /path/to/your-project
# Option 2: Or use the CLI directly from the repository
bun install
bun build
bun start my-app # This runs the CLI to create a new project
# After either option, set up the project
cd my-app # If using Option 2
bun install
bun setup # Downloads PocketBase
bun dev # Start development environmentVisit:
- Frontend: http://localhost:3000
- PocketBase Admin: http://localhost:8090/_/
| Feature | Description |
|---|---|
| ⚡ Next.js 15 | Latest version with App Router |
| 🔄 PocketBase Backend | Database, auth, file storage, and real-time API |
| 🎨 Tailwind CSS | Utility-first CSS framework |
| 🔍 TypeScript | Full type safety for your codebase |
| 🛠️ Dev Tools | Live reload for both frontend and backend |
| 💻 Interactive CLI | Customizable project creation |
| 📱 Responsive Design | Mobile-first approach |
| 🔒 Authentication | Built-in auth system via PocketBase |
| 🔥 Hot Reload | Fast refresh for rapid development |
| 🏗️ Robust Setup | Multi-strategy template handling for reliability |
PocketNext can be installed in several ways:
# Using bun (recommended)
bun create pocketnext my-app
# Using bunx
bunx pocketnext@latest my-app
# Using npx
npx pocketnext@latest my-apppocketnext/
├── src/ # Source code for CLI
│ ├── core/ # Core functionality
│ ├── utils/ # Utility functions
│ └── types/ # TypeScript types
├── templates/ # Project templates
├── public/ # Static assets
├── scripts/ # Helper scripts
└── dist/ # Compiled CLI code (generated)
your-project/
├── public/ # Static assets
├── scripts/ # Helper scripts
├── src/
│ ├── app/ # Next.js application with App Router
│ │ ├── api/ # API routes
│ │ ├── auth/ # Auth-related pages
│ │ └── (routes)/ # Application routes
│ ├── components/ # React components
│ │ ├── ui/ # UI components
│ │ └── layout/ # Layout components
│ └── lib/ # Shared utilities
│ └── pocketbase/ # PocketBase client & types
├── pocketbase/ # PocketBase binary (generated)
├── .env # Environment variables
└── docker-compose.yml # Docker configuration (if selected)
| Command | Description |
|---|---|
bun dev |
Start Next.js and PocketBase for development |
bun dev:next |
Start only Next.js development server |
bun dev:pb |
Start only PocketBase server |
bun dev:pb:admin |
Start PocketBase with admin setup prompt |
bun build |
Build Next.js for production |
bun start |
Start Next.js production server |
bun setup |
Install dependencies and download PocketBase |
bun setup:db |
Only download PocketBase |
bun setup:admin |
Set up PocketBase admin credentials interactively |
bun typegen |
Generate TypeScript types from PocketBase schema |
bun lint |
Run ESLint to check code quality |
For security reasons, the default PocketBase setup doesn't include admin credentials. You have several options:
-
Interactive Setup:
bun setup:admin
This will prompt you for admin email and password, with an option to save to your .env file.
-
Run with Admin Prompt:
bun dev:pb:admin
Similar to above but runs PocketBase after setup.
-
Use Environment Variables: Add to your .env file:
PB_ADMIN_EMAIL=your-email@example.com PB_ADMIN_PASSWORD=your-secure-passwordThen run with admin mode:
bun dev:pb:admin -
First-Run Setup: Just run PocketBase normally and create admin account through the web UI:
bun dev:pb
Then visit http://localhost:8090/\_/ and follow the setup instructions.
🐳 Docker Deployment
This project includes a production-ready Docker setup for deployment.
# Copy the example environment file
cp .env.example .env
# Build and start containers
docker-compose up -dThe Docker setup provides:
- Separate containers for Next.js and PocketBase
- Health checks for reliability
- Volume mounting for persistent data
- Environment variable configuration
🚢 CI/CD with GitHub Actions
Pre-configured GitHub workflows for continuous integration and deployment:
- CI Workflow: Builds and tests your application
- Deployment to Coolify: Automatically deploys to Coolify hosting
To enable Coolify deployment:
- Add
COOLIFY_WEBHOOKandCOOLIFY_TOKENsecrets to your GitHub repository - Use the
docker-compose.coolify.ymlin your Coolify configuration
🧪 Type Generation
Generate TypeScript types from your PocketBase schema:
bun typegenThis creates types in src/lib/pocketbase/types.ts for type-safe database operations.
🔄 Real-time Subscriptions
PocketBase offers real-time subscriptions to collection changes:
// In your Next.js component
import { pb } from "@/lib/pocketbase";
// Subscribe to changes
const unsubscribe = pb.collection("posts").subscribe("*", (data) => {
console.log("New data received:", data);
// Update your UI with the new data
});
// Clean up when done
useEffect(() => {
return () => unsubscribe();
}, []);This enables building reactive applications that update in real-time.