Contributing to Restura

This guide covers everything you need to set up your local development environment and start contributing to Restura.

Prerequisites

Before you begin, ensure you have the following installed:

• Node.js 18+
• pnpm 8+
• Docker Compose (required for PostgreSQL and running tests)
• PostgreSQL client (psql) for database setup

Quick Start

Clone the repository:

HTTPS

git clone https://github.com/redsky-engineering/restura.git

SSH

git clone git@github.com:redsky-engineering/restura.git

Navigate to the restura-ui directory and run the following command to start the Restura UI:

npm

cd restura
cd apps/restura-ui
npm install

pnpm

cd restura
cd apps/restura-ui
pnpm install

yarn

cd restura
cd apps/restura-ui
yarn install

bun

cd restura
cd apps/restura-ui
bun install

Repository Structure

• Directorypackages

  • Directorycore # @restura/core - Restura Engine

    • Directorysrc

      • …
    • package.json
    • tsconfig.json
  • Directoryinternal # @restura/internal - Shared utilities

    • Directorysrc

      • …
    • package.json
    • tsconfig.json
• Directoryapps

  • Directoryrestura-express # Test application that loads the Restura Engine

    • Directorymigrations

      • schema.sql # SQL schema file needed for tests
      • data.sql # SQL data file needed for tests
    • Directorysrc

      • …
    • docker-compose.local.yaml
    • package.json
    • tsconfig.json
  • Directoryrestura-ui # Visual editor

    • Directorysrc

      • …
    • package.json
    • tsconfig.json
• Directorydocs # Documentation website

  • Directorysrc

    • …
  • package.json
  • tsconfig.json

Database Setup

The example Express app uses a PostgreSQL database running in Docker on port 5488.

1. Start the PostgreSQL Container

# From the project root
cd apps/restura-express

# Start the database container
pnpm run startDevDockerDb

This starts a PostgreSQL 16.1 container with:

• Port: 5488 (mapped to container’s 5432)
• User: postgres
• Password: postgres

2. Create the Database Schema

Apply the schema migration to set up all tables, indexes, and triggers:

# From apps/restura-express directory
psql -h localhost -p 5488 -U postgres -f ./migrations/schema.sql

When prompted, enter the password: postgres

3. Load Initial Data

Populate the database with sample data for development:

psql -h localhost -p 5488 -U postgres -f ./migrations/data.sql

Running the Express App

Once the database is set up, you can run the example Express application:

# From the project root
pnpm express:dev

This command:

1. Rebuilds all workspace packages
2. Compiles the Express app TypeScript
3. Starts the development server

Alternatively, use tsx for faster iteration (skips compilation):

cd apps/restura-express
pnpm run devTsx

Development Workflow

Editing Restura Core

When contributing to @restura/core (packages/core/):

1. Make your changes in packages/core/src/

2. Restart the Express app to test your changes:

   pnpm express:dev

Editing the UI

To work on the visual editor (apps/restura-ui/):

# Start the Vite dev server
pnpm ui:start

Running Tests

Caution

Docker must be running for tests to work, as they require PostgreSQL.

Run All Tests

pnpm test

Run Tests for a Specific Package

# Core package tests
cd packages/core
pnpm test

Run Linting

# Lint all packages
pnpm lint

# Lint a specific package
cd packages/core
pnpm lint

Adding Tests

When adding new features or fixing bugs, please include tests.

Core Package Tests

Tests in @restura/core use Mocha and Chai:

// packages/core/src/yourModule.test.ts
import { expect } from 'chai';
import { yourFunction } from './yourModule.js';

describe('yourFunction', () => {
  it('should do something', () => {
    const result = yourFunction('input');
    expect(result).to.equal('expected output');
  });
});

Run tests with:

cd packages/core
pnpm test

Code Style

This project uses:

• ESLint for code linting
• Prettier for code formatting
• Husky with lint-staged for pre-commit hooks

Prettier runs automatically on staged files when you commit. To manually format:

pnpm exec prettier --write .

Pull Request Guidelines

1. Fork the repository and create a feature branch
2. Write tests for new functionality
3. Ensure all tests pass: pnpm test
4. Lint your code: pnpm lint
5. Submit a PR with a clear description of changes