README.md

StaticBackend

StaticBackend is a simple backend server API that helps you create web applications. It handles most of the building blocks you'll need on the backend.

• Authentication (docs →)
• Account->users management (docs →)
• Database CRUD, queries and full-text search (docs →)
• Realtime/Websockets (docs →)
• File storage (docs →)
• server-side functions (docs →)
• Schedule jobs
• Send mails/sms (docs →)
• Caching (docs →)
• Handle forms (docs →)
• Resize images & convert URL to PDF (docs →)

Table of content

• Install
  • Local development
  • Frontend client
  • Backend clients
  • Go package
• Usage
  • JavaScript example
  • Go client example
  • Go package example
• Documentation
• Deployment
  • Render
  • Heroku
  • Docker
• Get support
• Contributing
• How you can help

Install

You'll want to install different pieces depending on what you want to build. Here's what you can install:

Local development

Our CLI includes a fully functional development server. You don't need to install anything else.

$ npm install -g @staticbackend/cli

You may install the CLI manually as well.

This will install as the backend program. Start the development server with:

$ backend server

This command creates a new application and an admin user for you. You'll receive a PublicKey and a RootToken.

All HTTP request to the API requires a public key. The root token allows you to sign in to the dashboard for this application as the owner.

Frontend client

Add the library to your dependencies:

$ npm install @staticbackend/js

Inside your module:

import { Backend } from "@staticbackend/js";
const bkn = new Backend("dev_memory_pk", "dev");

dev_memory_pk is the default local development public key and dev is the default region / host for the instance you're targetting.

You may also include the library inside a <script tag if you're not using a module system:

<script src="https://cdn.jsdelivr.net/npm/@staticbackend/[email protected]/dist/backend.min.js"></script>
<script>
	const bkn = new sb.Backend("dev_memory_pk", "dev");
</script>

Backend clients

We've pre-built backend client libraries you may use directly:

Node:

$ npm install @staticbackend/backend

Go:

$ go get github.com/staticbackendhq/backend-go

View the Go package documentation

Python:

$ pip install staticbackend

Go package

You can import a Go package directly into your Go program and build your application with the same building blocks without hosting the API separately.

$ go get github.com/staticbackendhq/core/backend

View the Go package document

Usage

You may build web and mobile applications using StaticBackend as your main backend API.

StaticBackend is a multi-tenant platform allowing you to host multiple isolated applications.

You need an instance of the backend API running via the CLI for local development or running as a normal process with required dependencies.

You create your first application before you can start.

Using the CLI:

$ backend server

Using the source code:

$ git clone https://github.com/staticbackendhq/core
$ cd core
$ cp .local.env .env
$ make start

Visit http://localhost:8099 and create an application.

Javascript example

Note that the Nodejs client library has the same API / function names as the JavaScript library.

import { Backend } from "@staticbackend/js";

const bkn = new Backend("dev_memory_pk", "dev");

let token = "";

login = async () => {
	const res = await bkn.register("[email protected]", "password");
	if (!res.ok) {
		console.error(res.content);
		return;
	}
	token = res.content;

	createTask();
}

createTask = async () => {
	const task = {
		desc: "Do something for XYZ",
		done: false
	};

	const res = bkn.create(token, "tasks", task);
	if (!res.ok) {
		console.error(res.content);
		return;
	}
	console.log(res.content);
}

Go client example

package main

import (
	"fmt"
	"github.com/staticbackendhq/backend-go"
)

func main() {
	backend.PublicKey = "dev_memory_pk"
	backend.Region = "dev"

	token, err := backend.Login("[email protected]", "devpw1234")
	// no err handling in example

	task := new(struct{
		ID string `json:"id"`
		AccountID string `json:"accountId"`
		Title string `json:"title"`
		Done bool `json:"done"`
	})
	task.Title = "A todo item"
	err = backend.Create(token, "tasks", task, &task)
	// task.ID and task.AccountID would be filled with proper values
}

Go package example

// using the cache & pub/sub
backend.Cache.Set("key", "value")

msg := model.Command{Type: "chan_out", Channel: "#lobby", Data: "hello world"}
backend.Cache.Publish(msg)

// use the generic Collection for strongly-typed CRUD and querying
type Task struct {
	ID string `json:"id"`
	Title string `json:"title"`
}
// auth is the currently authenticated user performing the action.
// base is the current tenant's database to execute action
// "tasks" is the collection name
tasks := backend.Collection[Task](auth, base, "tasks")
newTask, err := tasks.Create(Task{Title: "testing"})
// newTask.ID is filled with the unique ID of the created task in DB

View a full example in the doc.

Documentation

We're trying to have the best experience possible reading our documentation.

Please help us improve if you have any feedback.

• Documentation with code samples for client libraries and CURL
• Go client library package
• Go importable package
• Self-host guide
• Install the CLI

Examples:

• To-do list example
• Realtime collaboration
• Live chat using server-side function & real-time component
• Jamstack Bostom talk

Deployment

To deploy StaticBackend you'll need the following:

• Either PostgreSQL or MongoDB
• Redis

StaticBackend is a single file binary you can run as a systemd daemon.

Here's some quick way to deploy an instance.

Render

Heroku

Docker

If you have Docker and Docker Compose ready, here's how to run StaticBackend:

$ git clone https://github.com/staticbackendhq/core
$ cd core
$ cp .demo.env .env
$ docker build . -t staticbackend:latest
$ docker-compose -f docker-compose-demo.yml up

Open a browser at http://localhost:8099 to create your first application.

For production, you'll want to configure environment variables found in .env file.

• Self-hosting guide
• Video showing how to self-host
• Detailed blog post on how to self-host

Get support

You may use the following channels to get help and support.

• Discord: for any help and joining the conversation.
• GitHub issues: To report bugs / contributing code.
• GitHub Discussions: For ideas, feature requests and general discussions.

Contributing

If you have any feedback (good or bad) we'd be more than happy to talk. Please use the Discussions tab.

Same for contributing. The easiest is to get in touch first. We're working to make it easier to contribute code. If you'd like to work on something precise let us know.

Here are videos made specifically for people wanting to contribute:

• Intro, setup, running tests, project structure
• backend package and v1.4.1 refactor and changes

Check the contributing file for details.

How you can help

If you're looking to help the project, here are multiple ways:

• Use it and share your experiences.
• Sponsor the development via GitHub sponsors.
• Spread the words, a tweet, a blog post, any mention is helpful.
• Join the Discord server.