∴ bit → your stack sidekick

Zero to Full-Stack in Seconds! Create production-ready applications with a single command.

✨ What's in the Box?

Bit sets you up with a modern, battle-tested stack:

• 🌿 Monorepo - Simple, organized and scalable from day one (apps/pb and apps/web)
• 🐋 Docker - Development environment that "just works"
• 📦 PocketBase Backend - Full-featured backend with admin UI
• ✨ Astro Frontend - Blazing-fast web performance for pages and api endpoints (SSR by default on bit)
• 🍞 Bun - Incredibly fast JavaScript runtime and toolkit for modern web development (powers bit's DX)

🚀 Get Started in 30 Seconds

1. Install Bit:

   npm install -g @mauricio.wolff/bit

2. Create your masterpiece:

   bit new my-awesome-project
   cd my-awesome-project

3. Choose your style:

   bit start # Press Ctrl+C to detach and keep services running

That's it! Visit your creation at:

• ✨ Frontend: http://localhost:4321
• 👔 Admin Dashboard: http://localhost:8090/\_/

🎮 Command Center

During Development

Command	Description
bit new <name>	Create a new project
bit start	Start development environment
bit stop	Stop all services
bit logs	View containers logs
bit down	Delete all containers and volumes
bit deploy [target]	Deploy to production

Ready for the World?

Command	What it Does
bit deploy	Ship everything
bit deploy web	Ship frontend
bit deploy pb	Ship backend

If your app doesn't exist in fly.io, it will launch first, then deploy.

📐 Project Blueprint

my-project/
├── apps/
│   ├── web/          # Astro frontend
│   │   ├── src/
│   │   └── fly.toml  # Frontend deploy config
│   └── pb/           # PocketBase backend
│       ├── pb_data/
│       ├── pb_migrations/
│       └── fly.toml   # Backend deploy config
├── docker-compose.yml # Development environment
└── README.md

🪄 Power User Features

Auto-Magic Admin Setup

Create ~/.bit.conf to use one email/password for PB's superuser (and to fastrack creation):

{
  "pocketbase": {
    "admin": {
      "email": "pb-admin@your-domain.com",
      "password": "your-secure-password"
    }
  }
}

🚢 Deploy Like a Pro

We've partnered with fly.io for smooth deployments:

1. Get the tools:

   curl -L https://fly.io/install.sh | sh

2. Log in:

   fly auth login

3. Ship it:

   bit deploy # From your project's root directory

   or

   bit deploy pb # Deploy PocketBase (db / backend) only
   bit deploy web # Deploy Astro (Frontend / api) only

Deploying PocketBase to fly.io in real time

🧑‍💻 For the Builders

Want to make Bit even better? Here's how:

git clone https://github.com/bitbonsai/bit.git
cd bit
npm install
npm link
bit new test-project # Test your changes

📋 Before You Start

Make sure you have:

• 🐋 Docker Desktop
• ✈️ Fly.io CLI
• 🍞 Bun (recommended) or npm

🆘 Need Help?

Common hiccups and quick fixes:

• 🐋 Docker not running? Fire up Docker Desktop
• 🔌 Port conflicts? Check if 4321 or 8090 are free
• 🔐 Permission issues? Double-check Docker permissions
• 🫧 Start fresh? Run bun run clean

🤝 Join the Community

Got ideas? Found a bug? We love pull requests!

⚖️ License

MIT License - go wild! See LICENSE for the fine print.