Skip to main content

​
Installation

Loopar Framework can be installed using two methods: automatic installation with NPX or manual installation from the Git repository.

​
Prerequisites

Loopar requires Node.js 22.12.0 or higher. Make sure you have the correct version installed before proceeding.
Check your Node.js version: 
node --version
If you need to upgrade, visit nodejs.org or use a version manager like nvm. The fastest way to get started with Loopar is using npx:
1

Run the installer

Execute the NPX command with your project name and optional port:
sudo npx loopar-env project-name --port 8080
Replace project-name with your desired project name and 8080 with your preferred port (default is 3000).
The sudo prefix may be required depending on your system permissions.
2

Wait for installation

The installer will:
  • Download the Loopar Framework
  • Install all dependencies
  • Create the initial project structure
  • Set up the dev environment
3

Server starts automatically

Your development server will start automatically after installation completes.
✅ Dev site created: sites/dev
   URL: http://localhost:8080
4

Complete setup wizard

Navigate to http://localhost:8080 in your browser. You’ll see a setup wizard where you can:
  • Configure your database type (MariaDB, MySQL, or SQLite)
  • Enter database connection details
  • Define your project settings

​
Manual Installation

For more control over the installation process, you can clone the repository manually.

​
Clone from Git

1

Clone the repository

git clone https://github.com/alphabit-technology/loopar-framework.git project-name
cd project-name
2

Install dependencies

Loopar uses a monorepo structure with workspaces. You can use either pnpm (recommended) or yarn:
pnpm install
Do not use npm for installation. The project is configured with pnpm workspaces and requires either pnpm or yarn for proper dependency management.
3

Start development server

pnpm run dev
This command will:
  • Run the preinstall script to clean lock files
  • Execute ensure-site.js to create a dev site if needed
  • Start the application with PM2
  • Begin tailing logs

​
Installation Process Details

​
Preinstall Script

During installation, Loopar runs cleanup to ensure a fresh environment:
bin/installer-clean.js
import { rm } from 'fs/promises';

async function cleanDistFolder() {
  try {
    await rm('../package-lock.json', { recursive: true, force: true });
    await rm('../yarn.lock', { recursive: true, force: true });
    await rm('../pnpm-lock.yaml', { recursive: true, force: true });
  } catch (error) {
    console.error('An error occurred while installer clean:', error);
  }
}

cleanDistFolder();
This ensures compatibility by removing existing lock files from other package managers.

​
Dev Site Creation

After installation, the ensure-site.js script automatically creates a development site:
bin/ensure-site.js
const sitesDir = path.join(process.cwd(), 'sites', 'dev');

if (!existsSync(sitesDir)) {
  await fs.mkdir(sitesDir, { recursive: true });
}

// Creates directory structure:
// sites/dev/
//   ├── .env
//   ├── config/
//   ├── sessions/
//   └── public/uploads/
The generated .env file contains:
.env
PORT=3000
NAME=dev
TENANT_ID=dev
NODE_ENV=development

​
Verify Installation

Once installation is complete, verify everything is working:
1

Check server status

pnpm run list
# or
yarn run list
This shows all running PM2 processes.
2

Access the application

Open your browser and navigate to:
http://localhost:3000
(or the port you specified during installation)
3

View logs

Monitor application logs:
pnpm run logs
# or
yarn run logs

​
Available Scripts

After installation, these scripts are available:
package.json
{
  "scripts": {
    "dev": "node bin/loopar-cli.js dev && pm2 logs",
    "start": "node bin/loopar-cli.js start",
    "stop": "node bin/loopar-cli.js stop",
    "restart": "node bin/loopar-cli.js restart",
    "logs": "node bin/loopar-cli.js logs",
    "list": "node bin/loopar-cli.js list"
  }
}

dev

Start development server with hot reloading

start

Start production server

stop

Stop all running processes

restart

Restart all processes

logs

View application logs

list

List all running processes

​
Troubleshooting

If you see a port conflict error:
  1. Stop the process using that port
  2. Change the port in sites/dev/.env
  3. Restart the server
pnpm run stop
# Edit sites/dev/.env and change PORT
pnpm run dev
If you encounter permission errors:
  • Use sudo for the NPX installation
  • Check file permissions in the project directory
  • Ensure Node.js has proper access rights
If dependencies are missing:
# Clean install
rm -rf node_modules
pnpm install
If the setup wizard shows database errors:
  • Verify database server is running
  • Check connection credentials
  • Ensure database user has proper permissions
  • For development, SQLite requires no additional setup

​
Next Steps

Quick Start Guide

Now that Loopar is installed, follow the quick start guide to build your first application

Build docs developers (and LLMs) love

Get started for freeTalk to us