@fadlee/pocketbase-bin


A Node.js wrapper for PocketBase that automatically downloads and manages PocketBase binaries with latest version detection.

Features

- 🚀 Automatic Binary Management: Downloads the correct PocketBase binary for your platform
- 🔄 Latest Version Detection: Automatically fetches and uses the latest PocketBase release
- 🎯 Version Pinning: Support for specific version requirements
- 🌍 Cross-Platform: Works on macOS, Linux, and Windows (x64 and ARM64)
- ⚡ Zero Configuration: Works out of the box with sensible defaults
- 🔧 Environment Variables: Configurable via environment variables
- 📦 NPX/Bunx Compatible: Can be used directly with npx or bunx without installation

Installation

$3

``bash
npm install -g @fadlee/pocketbase-bin
`

$3

`bash
npm install @fadlee/pocketbase-bin
`

$3

`bash


With npm/npx

npx @fadlee/pocketbase-bin serve

With bun/bunx

bunx @fadlee/pocketbase-bin serve
`

Usage

$3

`bash


Start PocketBase server with latest version

pocketbase serve

Or with npx

npx @fadlee/pocketbase-bin serve

Or with bunx

bunx @fadlee/pocketbase-bin serve
`

$3

`bash


Use a specific version

pocketbase --pb-version 0.28.4 serve

Or with environment variable

POCKETBASE_VERSION=0.28.4 pocketbase serve
`

$3

`bash


Start the server

pocketbase serve

Start with custom host and port

pocketbase serve --http=0.0.0.0:8090

Create admin user

pocketbase admin create

Import collections

pocketbase admin import collections.json

Show help

pocketbase --help
`

Configuration

$3

- --pb-version : Use a specific PocketBase version (e.g., --pb-version 0.28.4)

$3

- POCKETBASE_VERSION: Set the default PocketBase version to use

$3

`bash


Use latest version (default)

npx @fadlee/pocketbase-bin serve
bunx @fadlee/pocketbase-bin serve

Use specific version via flag

npx @fadlee/pocketbase-bin --pb-version 0.28.4 serve
bunx @fadlee/pocketbase-bin --pb-version 0.28.4 serve

Use specific version via environment variable

POCKETBASE_VERSION=0.28.4 npx @fadlee/pocketbase-bin serve
POCKETBASE_VERSION=0.28.4 bunx @fadlee/pocketbase-bin serve

Start server on custom port

npx @fadlee/pocketbase-bin serve --http=localhost:9090
bunx @fadlee/pocketbase-bin serve --http=localhost:9090
`

How It Works

1. Version Detection: The wrapper checks for a requested version via --pb-version flag or POCKETBASE_VERSION environment variable. If none specified, it fetches the latest release from GitHub.

2. Binary Download: Downloads the appropriate PocketBase binary for your platform (OS and architecture) from the official GitHub releases.

3. Caching: Downloaded binaries are cached locally with version tracking to avoid unnecessary re-downloads.

4. Execution: Passes all arguments directly to the PocketBase binary, maintaining full compatibility with PocketBase CLI.

Supported Platforms

- Operating Systems: macOS, Linux, Windows
- Architectures: x64 (AMD64), ARM64
- Node.js: >= 14.0.0

File Structure

When you run the wrapper, it creates the following files in your current directory:

`
.
├── pocketbase # The PocketBase binary (Unix)
├── pocketbase.exe # The PocketBase binary (Windows)
├── .pocketbase-version # Version tracking file
├── pb_data/ # PocketBase data directory (created by PocketBase)
└── pb_logs/ # PocketBase logs directory (created by PocketBase)
`

Development

$3

`
├── bin/
│ └── runner.js # Main executable script
├── lib/
│ └── downloader.js # Binary download and management logic
├── package.json # Package configuration
└── README.md # This file
`

$3

`bash


Clone the repository

git clone https://github.com/fadlee/pocketbase-bin.git
cd pocketbase-bin

Install dependencies

npm install

Test the wrapper

npm test
`

Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

$3

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature`)
5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE.md file for details.

Related Projects

- PocketBase - The official PocketBase project
- PocketBase JavaScript SDK - Official JavaScript/TypeScript SDK

Support

If you encounter any issues or have questions:

1. Check the PocketBase documentation
2. Search existing GitHub issues
3. Create a new issue if needed

Changelog

See CHANGELOG.md for a list of changes and version history.

---

Note: This is an unofficial wrapper for PocketBase. For official PocketBase documentation and support, visit pocketbase.io.