Quick Start Guide

This guide will walk you through creating your first Loopar application, from initial setup to building your first component.

Complete the Setup Wizard

After installation, navigate to your application URL (e.g., http://localhost:3000) to complete the initial setup.

Configure Database

Choose your database type and enter connection details:Supported Databases:

SQLite - Perfect for development (no additional setup required)
MySQL - Popular open-source database
MariaDB - MySQL-compatible database

{
  "type": "sqlite",
  "storage": "./database.sqlite"
}

For quick start, we recommend SQLite as it requires no additional database server setup.

Define Project Settings

Enter your project information:

Project Name: Display name for your application
Admin Email: Administrator email address
Admin Password: Secure password for admin account
Site Title: Title displayed in browser

Complete Installation

Click “Complete Setup” and wait for the wizard to:

Initialize the database
Create admin user
Set up default modules
Configure the workspace

Understanding the CLI

Loopar includes a powerful CLI for managing your application. All commands are available through the loopar-cli.js script.

Basic Commands

# Start development server
pnpm run dev
# or
yarn run dev

CLI Implementation

The CLI uses PM2 for process management:

bin/loopar-cli.js

const commands = {
  dev() {
    console.log(chalk.cyan(`Starting ${namespace}core site.`));
    pm2Command(`node bin/ensure-site.js && pm2 start bin/loopar.ecosystem.config.mjs --namespace ${namespace} --silent && node bin/loopar-status.js --env development`);
  },
  
  start(siteName) {
    console.log(chalk.cyan('Starting core site.'));
    pm2Command(`node bin/ensure-site.js && pm2 start bin/loopar.ecosystem.config.mjs --namespace ${namespace} --silent && node bin/loopar-status.js --env production`);
  },
  
  stop(siteName) {
    console.log(chalk.yellow('Stopping all sites...'));
    pm2Command(`pm2 stop all --namespace ${namespace}`);
  },
  
  restart(siteName) {
    console.log(chalk.cyan('Restarting all sites...'));
    pm2Command(`pm2 restart all --namespace ${namespace}`);
  }
};

Create Your First Component

Loopar includes a comprehensive component library. Let’s explore how components work.

Component Structure

All components are located in packages/loopar/src/components/. Here’s how components are structured:

Basic Component Example

Let’s look at the Button component:

packages/loopar/src/components/button.jsx

import {Button} from "@cn/components/ui/button";
import {useDocument} from "@context/@/document-context";
import loopar from "loopar";

const buttons = {
  primary: "primary",
  secondary: "secondary",
  default: "default",
  ghost: "ghost",
  destructive: "destructive",
};

export default function MetaButton(props){
  const data = props.data || {};
  const {docRef} = useDocument();

  const handleClick = (e) => {
    e.preventDefault();
    
    if (data.action && docRef) {
      if(!docRef[data.action]) 
        loopar.throw("Action not Defined",`Action ${data.action} not found in model`)
      docRef[data.action]();
    }
  }

  const getVariant = () => {
    return buttons[data.variant] || buttons.default;
  }

  return (
    <Button
      {...loopar.utils.renderizableProps(props)}
      variant={getVariant()}
      onClick={handleClick}
      className={props.className}
    >
      {data.label || "Button"}
    </Button>
  );
}

Components use the data prop for configuration and loopar.utils.renderizableProps() for common rendering properties.

Advanced Component - Card

The Card component shows how to use Droppable areas:

packages/loopar/src/components/card.jsx

import {
  Card as CardComponent,
  CardContent,
  CardFooter,
  CardHeader,
  CardTitle,
} from "@cn/components/ui/card"
import {Droppable} from "@droppable";
import {cn} from "@cn/lib/utils";
import loopar from "loopar";

export default function Card(props) {
  const data = props.data || {};

  return (
    <CardComponent 
      className={cn(props.className, "transition-all hover:shadow-lg h-full")}
    >
      <CardHeader>
        <CardTitle>{data.label}</CardTitle>
        {data.description && <CardDescription>{data.description}</CardDescription>}
      </CardHeader>
      <Droppable
        Component={CardContent}
        {...props}
      />
      {props.footer && (
        <CardFooter className="flex justify-between">
          {props.footer}
        </CardFooter>
      )}
    </CardComponent>
  )
}

Key features:

Uses Shadcn UI components as base
Droppable component allows child elements in the designer
Supports labels, descriptions, and footers
Hover effects with Tailwind CSS

Using Components in Your App

Components are automatically loaded through the component loader:

packages/loopar/src/components-loader.jsx

// Components are dynamically imported and registered
const components = {
  Button: () => import('./components/button.jsx'),
  Card: () => import('./components/card.jsx'),
  Input: () => import('./components/input.jsx'),
  // ... more components
};

Available Components

Loopar includes these pre-built components:

Layout

Container
Row
Col
Div
Card

Form Elements

Button
Input
Checkbox
Date/DateTime
Color Picker

Display

Banner
Carousel
Dialog
Divider
Image

Data

Table
List
Form View

Design

Designer
Direct Preview
Workspace

Special

Markdown
HTML
Custom

Build Your First Page

Access the Workspace

After logging in, navigate to the Loopar workspace:

http://localhost:3000/desk

Create a New Document

The workspace provides tools to:

Create new documents/pages
Design layouts visually
Configure components
Manage data models

Use the Designer

The visual designer (packages/loopar/src/components/designer/) allows you to:

Drag and drop components
Configure component properties
Preview in real-time
Save and publish

Configure Component Properties

Each component has metaFields that define configurable properties:

MetaButton.metaFields = () => {
  return [{
    group: "form",
    elements: {
      action: {
        element: INPUT,
        data: {
          description: "Define action like save, print..."
        }
      },
      variant: {
        element: SELECT,
        data: {
          options: Object.keys(buttons).map((button) => ({
            option: button,
            value: buttons[button]
          }))
        }
      }
    }
  }];
}

Application Context

Loopar provides context for managing application state:

app/App.tsx

const App = ({ __META__ }: RootLayoutProps) => {
  const { cookieManager } = __META__.services;

  return (
    <CookiesProvider manager={cookieManager} updater={setUpdate}>
      <Main __META__={__META__} />
    </CookiesProvider>
  )
}

const Main = ({ __META__ }: RootLayoutProps) => {
  const { components, Document } = __META__;
  const { Workspace, View } = components;

  return (
    <WorkspaceProvider
      __META__={__META__}
      Documents={{
        [Document.name]: {
          ...__META__,
          View,
          active: true,
        }
      }}
    >
      <Workspace menuData={__META__.menu_data} />
    </WorkspaceProvider>
  );
}

Key concepts:

__META__: Contains application metadata, services, and configuration
WorkspaceProvider: Manages document state and navigation
CookiesProvider: Handles authentication and session management
Document: Current page/view being rendered

Working with Data

Loopar uses Sequelize for database operations:

// Database configuration is in packages/db-env
// Supports: MySQL, MariaDB, SQLite
import { Sequelize } from '@sequelize/core';

// Models are automatically loaded from your application structure
// You can define custom models and relationships

Development Workflow

Start Development Server

pnpm run dev

This starts the server with hot module reloading enabled.

Make Changes

Edit components in packages/loopar/src/components/ or create custom components in your app directory.

View Changes

Changes are automatically reflected in the browser. Check the logs:

pnpm run logs

Build for Production

When ready to deploy:

pnpm run build
pnpm run start

Next Steps

Project Structure

Deep dive into Loopar’s architecture and directory organization

Components

Explore all available components and their APIs

Database

Learn about data modeling and database operations

CLI Commands

Learn about CLI commands for deployment

Need Help? Visit the Loopar documentation or check the GitHub repository for more resources.

Getting Started

Core Concepts

Visual Designer

Components

Database

Building Applications

Quick Start

Quick Start Guide

Complete the Setup Wizard

Understanding the CLI

Basic Commands

CLI Implementation

Create Your First Component

Component Structure

Available Components

Layout

Form Elements

Display

Data

Design

Special

Build Your First Page

Application Context

Working with Data

Development Workflow

Next Steps

Project Structure

Components

Database

CLI Commands

Build docs developers (and LLMs) love

Getting Started

Core Concepts

Visual Designer

Components

Database

Building Applications

​Quick Start Guide

​Complete the Setup Wizard

​Understanding the CLI

​Basic Commands

​CLI Implementation

​Create Your First Component

​Component Structure

​Available Components

Layout

Form Elements

Display

Data

Design

Special

​Build Your First Page

​Application Context

​Working with Data

​Development Workflow

​Next Steps

Project Structure

Components

Database

CLI Commands

Build docs developers (and LLMs) love

Quick Start Guide

Complete the Setup Wizard

Understanding the CLI

Basic Commands

CLI Implementation

Create Your First Component

Component Structure

Available Components

Build Your First Page

Application Context

Working with Data

Development Workflow

Next Steps