BaseFlow

Local-first Backend as a Service - spin up a complete backend infrastructure locally in under 2 minutes

What is BaseFlow?

BaseFlow is a local-first backend development tool that gives you a complete backend infrastructure running on your machine. No Docker, no cloud, no complexity. Just install and start building.

Features

• 🚀 2-Minute Setup - From zero to running backend
• 💾 SQLite Database - Lightweight, no configuration needed
• 🎨 Beautiful Dashboard - Web UI at localhost:5555
• 🔐 Authentication - JWT-based auth system
• 📁 File Storage - Local file management
• 🔄 Hot Reloading - Changes reflect immediately
• 📦 Type-Safe SDK - Auto-generated client
• 🌐 REST API - Full CRUD operations
• 🔌 Offline First - Works without internet
• ⚡ Fast - Starts in seconds

Quick Start

Install

npm install -g baseflow

Create Project

baseflow init my-app
cd my-app

Start Development Server

# Terminal 1: Start backend server
baseflow dev

# Terminal 2: Start dashboard (optional)
cd dashboard
npm install  # first time only
npm run dev

This will:

• Backend server on localhost:5555
• Dashboard on localhost:5173 (Vite dev server)
• Watch for schema changes
• Generate type-safe SDK
• Hot reload for both backend and dashboard

Define Your Schema

Edit baseflow/schema.js:

const { defineTable } = require('baseflow');

const users = defineTable('users', {
  id: 'integer primary autoincrement',
  name: 'text required',
  email: 'text required unique',
  created_at: 'datetime default(now)'
});

const posts = defineTable('posts', {
  id: 'integer primary autoincrement',
  title: 'text required',
  content: 'text',
  user_id: 'integer foreign(users.id)',
  created_at: 'datetime default(now)'
});

module.exports = { users, posts };

Use in Your App

npm install @baseflow/client

import { createClient } from '@baseflow/client';

const baseflow = createClient({
  url: 'http://localhost:5555'
});

// Query data
const { data } = await baseflow.from('users').select('*');

// Insert data
await baseflow.from('users').insert({
  name: 'John Doe',
  email: '[email protected]'
});

// Update data
await baseflow.from('users')
  .update({ name: 'Jane Doe' })
  .eq('id', 1);

// Delete data
await baseflow.from('users').delete().eq('id', 1);

CLI Commands

baseflow init <project>     # Initialize new project
baseflow dev                # Start development server
baseflow status             # Show project status
baseflow backup             # Create database backup
baseflow restore <name>     # Restore from backup
baseflow export             # Export database to JSON
baseflow import <file>      # Import database from JSON
baseflow list-backups       # List all backups
baseflow offline            # Check offline capabilities

Dashboard

The dashboard is included as source code in your project at dashboard/.

Run it with:

cd dashboard
npm install  # first time only
npm run dev

Access at http://localhost:5173

Features:

• 📊 Database browser (view/edit tables)
• 🔍 Schema visualizer (interactive diagram)
• 📁 File manager (upload/download files)
• ⚙️ Settings and configuration
• 📈 Real-time statistics
• 🎨 Fully customizable (React + Vite + Tailwind)

Project Structure

my-app/
├── baseflow/
│   ├── schema.js          # Database schema definition
│   └── config.json        # Project configuration
├── dashboard/             # Dashboard source (React + Vite)
│   ├── src/               # Dashboard components
│   ├── package.json       # Dashboard dependencies
│   └── vite.config.js     # Vite configuration
├── .baseflow/             # Generated files (gitignored)
│   ├── database.sqlite    # SQLite database
│   ├── storage/           # Uploaded files
│   └── generated/         # Auto-generated SDK
├── src/                   # Your application code
└── package.json

Schema Definition

BaseFlow uses a simple, code-first schema definition:

Field Types

• integer - Integer numbers
• text - Text strings
• real - Floating point numbers
• blob - Binary data
• datetime - Date and time
• boolean - True/false values

Constraints

• required - Field cannot be null
• unique - Field must be unique
• primary - Primary key
• autoincrement - Auto-increment (integers only)
• default(value) - Default value
• foreign(table.field) - Foreign key reference

Example

const users = defineTable('users', {
  id: 'integer primary autoincrement',
  email: 'text required unique',
  name: 'text required',
  age: 'integer',
  is_active: 'boolean default(true)',
  created_at: 'datetime default(now)'
});

Authentication

BaseFlow includes a built-in JWT-based authentication system:

// Register user
const { user, token } = await baseflow.auth.register({
  email: '[email protected]',
  password: 'secure-password'
});

// Login
const { user, token } = await baseflow.auth.login({
  email: '[email protected]',
  password: 'secure-password'
});

// Get current user
const user = await baseflow.auth.getUser(token);

// Logout
await baseflow.auth.logout(token);

File Storage

Upload and manage files:

// Upload file
const file = document.querySelector('input[type="file"]').files[0];
const { data } = await baseflow.storage.upload('avatars', file);

// Download file
const blob = await baseflow.storage.download(data.id);

// List files
const { data: files } = await baseflow.storage.list('avatars');

// Delete file
await baseflow.storage.delete(fileId);

Why BaseFlow?

vs Supabase Local

• ✅ No Docker required
• ✅ Faster setup (< 2 min vs 10+ min)
• ✅ Lighter weight (SQLite vs PostgreSQL)
• ✅ Better hot reloading

vs Firebase Emulator

• ✅ Simpler API
• ✅ SQL-based (more familiar)
• ✅ Better dashboard
• ✅ No Google account needed

vs PocketBase

• ✅ More flexible schema
• ✅ Better TypeScript support
• ✅ Familiar REST API
• ✅ Better documentation

Requirements

• Node.js 16 or higher
• npm or yarn

License

MIT

Links

• npm Package
• GitHub Repository
• Documentation
• Issues

Support

• GitHub Issues: Report bugs or request features
• Discussions: Ask questions and share ideas

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Made with ❤️ by the BaseFlow Team