∴ 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 i -g @bitbons.ai/bit

2. Create your masterpiece:

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

3. Start to see logs coming in:

   bit logs # bit is already running both containers for you

That's it! Visit your creation at:

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

🎮 Command Center

During Development

Command	Description
new [options] <project-name>	Create a new project [--pb ] [--astro ]
bit start	Start development environment
bit stop	Stop all services
bit restart [--skip-build] [target]	Restart and rebuild services [web, pb, empty for all]
bit logs	View containers logs
bit down	Delete all containers and volumes
bit help [command]	If you need help remembering how to do it

Ready for the World?

Command	What it Does
bit deploy	Ship everything (parallel deployment). Same as bit deploy all
bit deploy web	Ship frontend
bit deploy pb	Ship backend
bit deploy --watch	Wait and verify the deployment is healthy
bit deploy --dry-run	Show what would happen without making any changes

If your app doesn't exist in fly.io, it will launch first, then deploy. You can use --watch to verify deployment health.

📐 Project Blueprint

my-project/
├── .env.development    # Development-only variables (not committed)
├── apps/
│   ├── web/           # Astro frontend
│   │   ├── src/
│   │   ├── .env      # Public environment variables
│   │   └── fly.toml  # Frontend deploy config
│   └── pb/           # PocketBase backend
│       ├── pb_data/  # Database and storage
│       └── 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

For now, you can deploy in fly.io automagically:

1. Get the fly.io CLI:

   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, to deploy both web and pb

   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

Important

If you want to point your domain to the web app, Add a CNAME entry for your domain pointing to your fly.io web app, and add a free ssl certificate for the domain. Here's how to do it in details.

🧑‍💻 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.