{"id":25925196,"url":"https://github.com/kacperkwapisz/pocketnext","last_synced_at":"2025-07-13T01:13:29.441Z","repository":{"id":280203541,"uuid":"941283605","full_name":"kacperkwapisz/pocketnext","owner":"kacperkwapisz","description":"⚡ Minimalist Next.js + PocketBase starter with TypeScript, Tailwind CSS, and Docker support","archived":false,"fork":false,"pushed_at":"2025-03-07T22:37:43.000Z","size":1436,"stargazers_count":8,"open_issues_count":1,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-06-29T09:48:12.399Z","etag":null,"topics":["docker","fullstack","nextjs","pocketbase","starter-template","tailwindcss","typescript"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kacperkwapisz.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2025-03-01T23:13:33.000Z","updated_at":"2025-06-26T09:40:19.000Z","dependencies_parsed_at":"2025-03-02T00:20:33.311Z","dependency_job_id":"5c01c824-e55f-45f6-9b6e-c9c495860419","html_url":"https://github.com/kacperkwapisz/pocketnext","commit_stats":null,"previous_names":["kacperkwapisz/pocketnext"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/kacperkwapisz/pocketnext","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kacperkwapisz%2Fpocketnext","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kacperkwapisz%2Fpocketnext/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kacperkwapisz%2Fpocketnext/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kacperkwapisz%2Fpocketnext/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kacperkwapisz","download_url":"https://codeload.github.com/kacperkwapisz/pocketnext/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kacperkwapisz%2Fpocketnext/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":265077549,"owners_count":23707706,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["docker","fullstack","nextjs","pocketbase","starter-template","tailwindcss","typescript"],"created_at":"2025-03-03T18:35:41.286Z","updated_at":"2025-07-13T01:13:29.412Z","avatar_url":"https://github.com/kacperkwapisz.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# PocketNext\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/pocketnext-demo.gif\" alt=\"PocketNext CLI Demo\" width=\"650\"\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://www.npmjs.com/package/pocketnext\"\u003e\u003cimg src=\"https://img.shields.io/npm/v/pocketnext.svg?style=flat-square\" alt=\"npm version\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://www.npmjs.com/package/pocketnext\"\u003e\u003cimg src=\"https://img.shields.io/npm/dm/pocketnext.svg?style=flat-square\" alt=\"npm downloads\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/kacperkwapisz/pocketnext/blob/main/LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/github/license/kacperkwapisz/pocketnext?style=flat-square\" alt=\"license\"\u003e\u003c/a\u003e\n  \u003cimg src=\"https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square\" alt=\"PRs welcome\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/Next.js-15-black?style=flat-square\" alt=\"Next.js 15\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/PocketBase-latest-blue?style=flat-square\" alt=\"PocketBase\"\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  A minimalist, production-ready starter for building full-stack applications with \u003ca href=\"https://nextjs.org\"\u003eNext.js\u003c/a\u003e and \u003ca href=\"https://pocketbase.io\"\u003ePocketBase\u003c/a\u003e.\n\u003c/p\u003e\n\n## 📋 Table of Contents\n\n- [🚀 Quick Start](#-quick-start)\n  - [Using the CLI (Recommended)](#using-the-cli-recommended)\n  - [CLI Options](#cli-options)\n  - [Manual Setup](#manual-setup)\n- [🧰 Core Features](#-core-features)\n- [📦 Installation Methods](#-installation-methods)\n- [📄 Project Structure](#-project-structure)\n- [🔧 Available Commands](#-available-commands)\n- [🔐 Setting Up PocketBase Admin](#-setting-up-pocketbase-admin)\n- [🛠 Advanced Features](#-advanced-features-optional)\n- [📝 Development](#-development)\n- [📚 Learn More](#-learn-more)\n- [❓ Troubleshooting](#-troubleshooting)\n- [📄 License](#-license)\n\n## 🚀 Quick Start\n\n### Using the CLI (Recommended)\n\n```bash\n# Create a new project using bunx\nbunx pocketnext@latest my-app\n\n# OR use bun create (recommended)\nbun create pocketnext my-app\n\n# Navigate to your project\ncd my-app\n\n# Start the development environment\nbun dev\n```\n\n### Project Profiles\n\nPocketNext offers a streamlined project creation experience with pre-configured profiles:\n\n| Profile        | Description                                        |\n| -------------- | -------------------------------------------------- |\n| **Minimal**    | Basic setup with essential features only           |\n| **Standard**   | Recommended setup for most projects (default)      |\n| **Production** | Full setup with CI/CD and deployment configuration |\n| **Custom**     | Choose each option individually                    |\n\nYou can select a profile during the interactive setup or specify it directly:\n\n```bash\n# Create a project with minimal configuration\nbunx pocketnext@latest my-app --profile=minimal\n\n# Create a production-ready project\nbunx pocketnext@latest my-app --profile=production\n\n# Quick setup with sensible defaults\nbunx pocketnext@latest my-app --quick\n```\n\n### CLI Options\n\nAll commands support these options:\n\n| Option                    | Description                                                          |\n| ------------------------- | -------------------------------------------------------------------- |\n| `--profile=\u003cprofile\u003e`     | Select project setup profile (minimal, standard, production, custom) |\n| `--quick`                 | Quick setup with minimal prompts                                     |\n| `--use-npm/yarn/pnpm/bun` | Choose a package manager                                             |\n| `-y, --yes`               | Skip interactive prompts and use defaults                            |\n| `--skip-install`          | Skip package installation                                            |\n| `--scripts \u003coption\u003e`      | Automate PocketBase setup (runAndKeep or runAndDelete)               |\n| `--pb-version \u003cversion\u003e`  | Install specific PocketBase version                                  |\n| `--help`                  | Show all available options                                           |\n\n```bash\n# Example with multiple options\nbunx pocketnext@latest my-app --profile=production --use-bun --skip-install\n```\n\n### Manual Setup\n\n```bash\n# Clone the repository\ngit clone https://github.com/kacperkwapisz/pocketnext.git\ncd pocketnext\n\n# Option 1: Copy the template folder to your project location\ncp -r templates/default /path/to/your-project\ncd /path/to/your-project\n\n# Option 2: Or use the CLI directly from the repository\nbun install\nbun build\nbun start my-app  # This runs the CLI to create a new project\n\n# After either option, set up the project\ncd my-app  # If using Option 2\nbun install\nbun setup  # Downloads PocketBase\nbun dev    # Start development environment\n```\n\nVisit:\n\n- **Frontend**: [http://localhost:3000](http://localhost:3000)\n- **PocketBase Admin**: [http://localhost:8090/\\_/](http://localhost:8090/_/)\n\n## 🧰 Core Features\n\n\u003cdiv align=\"center\"\u003e\n\n| Feature                   | Description                                      |\n| ------------------------- | ------------------------------------------------ |\n| **⚡ Next.js 15**         | Latest version with App Router                   |\n| **🔄 PocketBase Backend** | Database, auth, file storage, and real-time API  |\n| **🎨 Tailwind CSS**       | Utility-first CSS framework                      |\n| **🔍 TypeScript**         | Full type safety for your codebase               |\n| **🛠️ Dev Tools**          | Live reload for both frontend and backend        |\n| **💻 Interactive CLI**    | Customizable project creation                    |\n| **📱 Responsive Design**  | Mobile-first approach                            |\n| **🔒 Authentication**     | Built-in auth system via PocketBase              |\n| **🔥 Hot Reload**         | Fast refresh for rapid development               |\n| **🏗️ Robust Setup**       | Multi-strategy template handling for reliability |\n\n\u003c/div\u003e\n\n## 📦 Installation Methods\n\nPocketNext can be installed in several ways:\n\n```bash\n# Using bun (recommended)\nbun create pocketnext my-app\n\n# Using bunx\nbunx pocketnext@latest my-app\n\n# Using npx\nnpx pocketnext@latest my-app\n```\n\n## 📄 Project Structure\n\n### CLI Project Structure\n\n```\npocketnext/\n├── src/                # Source code for CLI\n│   ├── core/           # Core functionality\n│   ├── utils/          # Utility functions\n│   └── types/          # TypeScript types\n├── templates/          # Project templates\n├── public/             # Static assets\n├── scripts/            # Helper scripts\n└── dist/               # Compiled CLI code (generated)\n```\n\n### Generated Project Structure\n\n```\nyour-project/\n├── public/             # Static assets\n├── scripts/            # Helper scripts\n├── src/\n│   ├── app/            # Next.js application with App Router\n│   │   ├── api/        # API routes\n│   │   ├── auth/       # Auth-related pages\n│   │   └── (routes)/   # Application routes\n│   ├── components/     # React components\n│   │   ├── ui/         # UI components\n│   │   └── layout/     # Layout components\n│   └── lib/            # Shared utilities\n│       └── pocketbase/ # PocketBase client \u0026 types\n├── pocketbase/         # PocketBase binary (generated)\n├── .env                # Environment variables\n└── docker-compose.yml  # Docker configuration (if selected)\n```\n\n## 🔧 Available Commands\n\n| Command            | Description                                       |\n| ------------------ | ------------------------------------------------- |\n| `bun dev`          | Start Next.js and PocketBase for development      |\n| `bun dev:next`     | Start only Next.js development server             |\n| `bun dev:pb`       | Start only PocketBase server                      |\n| `bun dev:pb:admin` | Start PocketBase with admin setup prompt          |\n| `bun build`        | Build Next.js for production                      |\n| `bun start`        | Start Next.js production server                   |\n| `bun setup`        | Install dependencies and download PocketBase      |\n| `bun setup:db`     | Only download PocketBase                          |\n| `bun setup:admin`  | Set up PocketBase admin credentials interactively |\n| `bun typegen`      | Generate TypeScript types from PocketBase schema  |\n| `bun lint`         | Run ESLint to check code quality                  |\n\n## 🔐 Setting Up PocketBase Admin\n\nFor security reasons, the default PocketBase setup doesn't include admin credentials. You have several options:\n\n1. **Interactive Setup**:\n\n   ```bash\n   bun setup:admin\n   ```\n\n   This will prompt you for admin email and password, with an option to save to your .env file.\n\n2. **Run with Admin Prompt**:\n\n   ```bash\n   bun dev:pb:admin\n   ```\n\n   Similar to above but runs PocketBase after setup.\n\n3. **Use Environment Variables**:\n   Add to your .env file:\n\n   ```\n   PB_ADMIN_EMAIL=your-email@example.com\n   PB_ADMIN_PASSWORD=your-secure-password\n   ```\n\n   Then run with admin mode: `bun dev:pb:admin`\n\n4. **First-Run Setup**:\n   Just run PocketBase normally and create admin account through the web UI:\n   ```bash\n   bun dev:pb\n   ```\n   Then visit http://localhost:8090/\\_/ and follow the setup instructions.\n\n## 🛠 Advanced Features (Optional)\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003e🐳 Docker Deployment\u003c/b\u003e\u003c/summary\u003e\n\nThis project includes a production-ready Docker setup for deployment.\n\n```bash\n# Copy the example environment file\ncp .env.example .env\n\n# Build and start containers\ndocker-compose up -d\n```\n\nThe Docker setup provides:\n\n- Separate containers for Next.js and PocketBase\n- Health checks for reliability\n- Volume mounting for persistent data\n- Environment variable configuration\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003e🚢 CI/CD with GitHub Actions\u003c/b\u003e\u003c/summary\u003e\n\nPre-configured GitHub workflows for continuous integration and deployment:\n\n- **CI Workflow**: Builds and tests your application\n- **Deployment to Coolify**: Automatically deploys to [Coolify](https://coolify.io/) hosting\n\nTo enable Coolify deployment:\n\n1. Add `COOLIFY_WEBHOOK` and `COOLIFY_TOKEN` secrets to your GitHub repository\n2. Use the `docker-compose.coolify.yml` in your Coolify configuration\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003e🧪 Type Generation\u003c/b\u003e\u003c/summary\u003e\n\nGenerate TypeScript types from your PocketBase schema:\n\n```bash\nbun typegen\n```\n\nThis creates types in `src/lib/pocketbase/types.ts` for type-safe database operations.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003e🔄 Real-time Subscriptions\u003c/b\u003e\u003c/summary\u003e\n\nPocketBase offers real-time subscriptions to collection changes:\n\n```typescript\n// In your Next.js component\nimport { pb } from \"@/lib/pocketbase\";\n\n// Subscribe to changes\nconst unsubscribe = pb.collection(\"posts\").subscribe(\"*\", (data) =\u003e {\n  console.log(\"New data received:\", data);\n  // Update your UI with the new data\n});\n\n// Clean up when done\nuseEffect(() =\u003e {\n  return () =\u003e unsubscribe();\n}, []);\n```\n\nThis enables building reactive applications that update in real-time.\n\n\u003c/details\u003e\n\n## 📝 Development\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003e📜 Changelog\u003c/b\u003e\u003c/summary\u003e\n\nSee the [CHANGELOG.md](CHANGELOG.md) for a detailed list of changes in each version.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003e🧑‍💻 Contributing\u003c/b\u003e\u003c/summary\u003e\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n1. Fork the repository\n2. Create your feature branch: `git checkout -b feature/amazing-feature`\n3. Commit your changes: `git commit -m 'Add some amazing feature'`\n4. Push to the branch: `git push origin feature/amazing-feature`\n5. Open a Pull Request\n\n\u003c/details\u003e\n\n## ❓ Troubleshooting\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eCommon Issues\u003c/b\u003e\u003c/summary\u003e\n\n### PocketBase fails to start\n\nCheck if port 8090 is already in use:\n\n```bash\nlsof -i :8090\n```\n\nIf so, you can change the port in the `.env` file:\n\n```\nPB_PORT=8091\n```\n\n### Next.js build fails\n\nIf you encounter issues during build, ensure all dependencies are installed:\n\n```bash\nbun install\n```\n\nAlso check for any TypeScript errors:\n\n```bash\nbun typecheck\n```\n\n### Template fetching issues\n\nIf you encounter problems with template fetching:\n\n1. Ensure you have Git installed and available in your PATH\n2. Check your internet connection\n3. If you're behind a firewall or proxy, try using the `--quick` flag which uses simpler fetching strategies\n4. As a last resort, you can manually clone the repository and copy the template directly:\n\n```bash\n# Clone the repository\ngit clone https://github.com/kacperkwapisz/pocketnext.git\n\n# Copy the template to your project location\ncp -r pocketnext/templates/default my-app\n\n# Navigate to your project and set it up\ncd my-app\nbun install\nbun setup:db  # Download PocketBase\n```\n\n### Type errors with PocketBase collections\n\nIf you're experiencing type errors when accessing PocketBase collections, regenerate the types:\n\n```bash\nbun typegen\n```\n\n\u003c/details\u003e\n\n## 📚 Learn More\n\n- [Next.js Documentation](https://nextjs.org/docs)\n- [PocketBase Documentation](https://pocketbase.io/docs/)\n- [Tailwind CSS Documentation](https://tailwindcss.com/docs)\n- [TypeScript Documentation](https://www.typescriptlang.org/docs/)\n\n## 📄 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n\u003c!-- ---\n\n\u003cp align=\"center\"\u003e\n  Made with ❤️ by \u003ca href=\"https://github.com/kacperkwapisz\"\u003eKacper Kwapisz\u003c/a\u003e\n\u003c/p\u003e --\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkacperkwapisz%2Fpocketnext","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkacperkwapisz%2Fpocketnext","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkacperkwapisz%2Fpocketnext/lists"}