Skip to main content

Quick Start Guide

This guide will walk you through creating your first Stack9 application in under 30 minutes. You'll build a simple Customer Management system with CRUD operations, a data grid, and basic business logic.

Prerequisites​

Before you begin, make sure you have:

Step 1: Clone the Stack9 Monorepo​

git clone https://github.com/april9au/stack9-monorepo.git
cd stack9-monorepo

Step 2: Install Dependencies​

yarn install

Step 3: Create Your Stack9 Instance​

A Stack9 instance is a separate package that uses Stack9 as its foundation:

# Create a new instance directory
mkdir -p ../my-stack9-app/packages/my-stack9-stack
cd ../my-stack9-app/packages/my-stack9-stack

# Initialize package.json
npm init -y

Step 4: Install Stack9 Dependencies​

yarn add @april9/stack9-core-module @april9/stack9-sdk
yarn add -D typescript tsup @april9/eslint-config

Create tsconfig.json:

{
  "extends": "@april9/tsconfig/base.json",
  "compilerOptions": {
    "outDir": "./dist",
    "rootDir": "./src"
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"]
}

Step 5: Create Your Project Structure​

mkdir -p src/{entities/custom,screens,query-library,entity-hooks,automations,connectors}

Your structure should look like:

my-stack9-stack/
├── package.json
├── tsconfig.json
└── src/
    ├── entities/
    │   └── custom/
    ├── screens/
    ├── query-library/
    ├── entity-hooks/
    ├── automations/
    ├── connectors/
    └── index.ts

Step 6: Define Your First Entity​

Create src/entities/custom/customer.json:

{
  "head": {
    "name": "Customer",
    "key": "customer",
    "pluralisedName": "Customers",
    "icon": "UserIcon",
    "allowComments": true,
    "allowTasks": true,
    "allowAttachments": true
  },
  "fields": [
    {
      "label": "First Name",
      "key": "first_name",
      "type": "TextField",
      "validateRules": {
        "required": true
      }
    },
    {
      "label": "Last Name",
      "key": "last_name",
      "type": "TextField",
      "validateRules": {
        "required": true
      }
    },
    {
      "label": "Email",
      "key": "email",
      "type": "TextField",
      "typeOptions": {
        "format": "email"
      },
      "validateRules": {
        "required": true
      }
    },
    {
      "label": "Phone",
      "key": "phone",
      "type": "TextField",
      "typeOptions": {
        "format": "phone"
      }
    },
    {
      "label": "Active",
      "key": "is_active",
      "type": "Checkbox",
      "defaultValue": true
    }
  ],
  "hooks": []
}

That's it! Stack9 will automatically:

  • Create a customers database table
  • Generate REST APIs: GET, POST, PUT, DELETE, Search
  • Handle validation
  • Create audit logs

Step 7: Create a List Screen​

Create src/screens/customer-list.json:

{
  "head": {
    "title": "Customers",
    "key": "customer_list",
    "route": "customers",
    "app": "main",
    "icon": "UsersIcon"
  },
  "screenType": "listView",
  "entityKey": "customer",
  "columnsConfiguration": [
    {
      "field": "first_name",
      "headerName": "First Name",
      "width": 150
    },
    {
      "field": "last_name",
      "headerName": "Last Name",
      "width": 150
    },
    {
      "field": "email",
      "headerName": "Email",
      "width": 200
    },
    {
      "field": "phone",
      "headerName": "Phone",
      "width": 150
    },
    {
      "field": "is_active",
      "headerName": "Active",
      "width": 100,
      "type": "boolean"
    }
  ],
  "defaultFilters": {
    "is_active": true
  },
  "allowCreate": true,
  "allowEdit": true,
  "allowDelete": true,
  "allowExport": true
}

Step 8: Create App Configuration​

Create src/app.json:

{
  "name": "My Stack9 App",
  "key": "main",
  "description": "Customer Management System",
  "navigation": [
    {
      "label": "Customers",
      "route": "customers",
      "icon": "UsersIcon"
    }
  ]
}

Step 9: Configure Your Instance​

Create src/index.ts:

import { defineStack9Instance } from '@april9/stack9-core-module';
import * as customerEntity from './entities/custom/customer.json';
import * as customerListScreen from './screens/customer-list.json';
import * as appConfig from './app.json';

export default defineStack9Instance({
  entities: [customerEntity],
  screens: [customerListScreen],
  apps: [appConfig],
  queryLibrary: [],
  automations: [],
  connectors: [],
});

Step 10: Set Up Environment Variables​

Create .env.local:

# packages/stack9-server/.env.local

# Secret key for environment variables encryption
ENVVARS_SECRET_HEX=<ENVVARS_SECRET_HEX>

# SendGrid API key for email functionality
SEND_GRID_API_KEY=<SEND_GRID_API_KEY>

# Authentication configuration (Azure AD)
AUTH_SECRETS='{
   "AUTH_ENVVARS_SECRET_HEX":"<ENVVARS_SECRET_HEX>",
   "AUTH_TENANT_ID":"<TENANT_ID>",
   "AUTH_CLIENT_ID":"<CLIENT_ID>",
   "AUTH_CLIENT_SECRET":"<CLIENT_SECRET>"
}'

Step 11: Run Your Application​

# Development mode
yarn dev

# Your app will start at:
# Application: http://localhost:3333
# Admin Panel: http://localhost:3334

Step 12: Test Your APIs​

Stack9 automatically generated these endpoints:

# Get all customers
GET http://localhost:3333/api/customer/search

# Create a customer
POST http://localhost:3333/api/customer
{
  "first_name": "John",
  "last_name": "Doe",
  "email": "john@example.com",
  "phone": "+1234567890",
  "is_active": true
}

# Get customer by ID
GET http://localhost:3333/api/customer/1

# Update customer
PUT http://localhost:3333/api/customer/1
{
  "phone": "+0987654321"
}

# Delete customer
DELETE http://localhost:3333/api/customer/1

What Just Happened?​

With just 3 JSON files (entity, screen, app), you created:

✅ REST API with 7+ endpoints per entity ✅ PostgreSQL database table with proper indexes ✅ Admin UI with data grid, forms, and validation ✅ Search & filtering capabilities ✅ Pagination support ✅ Audit logs for all changes ✅ Role-based access control ✅ File attachments support ✅ Comments & tasks features

Next Steps​

Now that you have a working Stack9 app, learn how to:

  1. Add Relationships - Connect customers to orders
  2. Create Custom Queries - Build complex data queries
  3. Add Business Logic - Use hooks for validation
  4. Create Workflows - Add approval processes
  5. Build Automations - Trigger actions on events

Common Issues​

Database Connection Errors​

Make sure PostgreSQL is running and your DATABASE_URL is correct:

psql $DATABASE_URL -c "SELECT 1;"

Port Already in Use​

Change the port in your configuration:

PORT=3335 yarn dev

License Key Missing​

Contact your Stack9 administrator or visit stack9.cloud to obtain a license key.

Getting Help​

Summary​

In this guide, you learned:

  • How to create a Stack9 instance
  • How to define entities using JSON
  • How to create screens for your UI
  • How the auto-generated APIs work
  • How to run and test your application

Continue to the Core Concepts section to learn more about Stack9's powerful features!