Getting Started

Requirements

Before you begin, make sure you have:

• Bun v1.2.x+ - Install Bun
• Nailgun CLI - Install Nailgun

Installation

Clone the Zodula monorepo to get started:

bun install --global nailgun

git clone https://github.com/zodula/zodula my-app

cd my-app

bun install

This will clone the complete Zodula framework monorepo with all the necessary components.

Development Server

Start the development server:

nailgun dev

The server will start at http://localhost:3000 with:

• OpenAPI JSON: GET /openapi.json
• API Reference UI: GET /openapi
• Admin Interface: Built-in desk UI for data management

Key Commands

Zodula exposes commands through nailgun. Here are the most common ones:

# Scaffold new apps, doctypes, or actions
nailgun scaffold

# Apply migrations and load fixtures
nailgun migrate

# Create admin user
nailgun admin create-user --email me@example.com --password secret --roles "System Admin"

Development Workflow

1. Edit DocTypes in apps/*/doctypes/*
2. Apply changes: nailgun migrate

Auto-Generated APIs

Zodula automatically generates REST APIs for your DocTypes:

• List Records: GET /api/resources/{Doctype}
• API Documentation: GET /openapi

TypeScript SDK

Use the built-in TypeScript SDK for type-safe database operations:

// Query data
const users = await $zodula
  .doctype("User")
  .select()
  .where("email", "=", "me@example.com");

// Create records
const user = await $zodula
  .doctype("User")
  .insert({ email: "me@example.com", password: "secret" });

Next Steps

• Learn about DocTypes - the core building blocks
• Explore Actions - custom API endpoints
• Set up Fixtures - sample data for development

Important Notice

Version 0 is experimental. This version may have breaking changes and data loss during updates. Use only for development and testing.

This version is not recommended for production environments. Please use only in development projects where data can be easily restored or recreated.