Get Started

Folder Structure

Here's how your Antelopejs project is organized - we'll explain the main files and folders so you can find your way around easily.

Antelopejs Project Structure

Your Antelopejs project is made up of config files and modules that work together. Let's take a tour of the important files and folders you'll see.

Overview

A typical project looks like this:

my-antelope-project/
├── .antelope/             # Where interface definitions are stored
├── node_modules/          # Your dependencies
├── src/                   # Your app's source code
│   ├── index.ts           # Main entry point
│   ├── implementations/   # Where you implement interfaces
│   └── interfaces/        # Interfaces you export
├── dist/                  # Your compiled code
├── antelope.json          # Main project settings
├── package.json           # NPM settings
└── tsconfig.json          # TypeScript settings

Configuration Files

antelope.json

This is the heart of your project. It defines which modules to load and how they should be set up.

{
  "name": "my-project",
  "version": "1.0.0",
  "description": "My Antelopejs project",
  "author": "Your Name",
  "modules": {
    "app": {
      "source": {
        "type": "local",
        "path": "."
      },
      "config": {
        "port": 3000
      }
    },
    "database": {
      "source": "[email protected]",
      "config": {
        "url": "mongodb://localhost:27017"
      }
    }
  },
  "environments": {
    "production": {
      "modules": {
        "database": {
          "config": {
            "url": "mongodb://prod-server:27017"
          }
        }
      }
    }
  }
}

Main sections:

Basic Info: Name, version, description, author
Modules: Settings for each module and where to find it
Environments: Different settings for different environments (dev, prod, etc.)

package.json

This has your NPM settings and handy scripts:

{
  "name": "my-project",
  "version": "1.0.0",
  "scripts": {
    "dev": "ajs project run --watch",
    "build": "tsc",
    "start": "ajs project run"
  },
  "devDependencies": {
    "antelopejs": "^1.0.0",
    "typescript": "^4.5.0"
  }
}

tsconfig.json

Controls how TypeScript compiles your code:

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "CommonJS",
    "moduleResolution": "node",
    "esModuleInterop": true,
    "outDir": "./dist",
    "rootDir": "./src",
    "baseUrl": "./src",
    "paths": {
      "@/*": ["*"]
    }
  },
  "include": ["src/**/*"]
}

Module Source Types

You can add modules to your project in several ways:

Get a module from NPM:

"api": {
  "source": "[email protected]",
  "config": {
    "port": 3000
  }
}

Grab a module from Git:

"auth": {
  "source": {
    "type": "git",
    "remote": "https://github.com/organization/auth-module.git",
    "branch": "main",
    "installCommand": ["npm install", "npm run build"]
  },
  "config": {
    "secretKey": "abc123"
  }
}

Use code from your local folder:

"app": {
  "source": {
    "type": "local",
    "path": ".",
    "installCommand": "npm run build"
  },
  "config": {
    "debug": true
  }
}

Load multiple modules from a folder:

"plugins": {
  "source": {
    "type": "dir",
    "path": "./plugins",
    "installCommand": "npm run build-all"
  },
  "config": {
    "enableAll": true
  }
}

Module Structure

Each module follows this pattern:

module-name/
├── src/
│   ├── index.ts           # Main entry point
│   ├── interfaces/        # Interfaces it offers
│   │   └── example/       # Interface namespace
│   │       └── 1/         # Version 1
│   │           └── index.ts
│   └── implementations/   # How it uses other modules
├── dist/                  # Compiled code
├── package.json           # Module settings
└── tsconfig.json          # TypeScript settings

Let's look at the key files:

src/index.ts

This is where it all starts. It exports these important functions:

export function construct(config: any): void {
  // Set things up
}

export function start(): void {
  // Start doing work
}

export function stop(): void {
  // Pause operation
}

export function destroy(): void {
  // Clean up
}

src/interfaces/

This is where you put the interfaces your module offers to others:

interfaces/
└── payment/           # Interface name
    ├── 1/             # Version 1
    │   └── index.ts   # Interface code
    └── 2/             # Version 2
        └── index.ts   # Updated interface code

src/implementations/

This is where you implement interfaces from other modules:

implementations/
└── database/          # Interface name
    └── dev/           # Version
        └── index.ts   # Your implementation

Each module has its own settings:

package.json

This tells Antelopejs about your module:

{
  "name": "payment-module",
  "version": "1.0.0",
  "main": "dist/index.js",
  "antelopeJs": {
    "imports": ["database@dev", "logger@1"],
    "exportsPath": "dist/interfaces",
    "baseUrl": "dist",
    "paths": {
      "@/*": ["*"]
    }
  }
}

The antelopeJs section defines:

imports: Interfaces your module needs
exportsPath: Where your interfaces live
baseUrl and paths: Where to find your code

tsconfig.json

TypeScript settings for just this module.

Environment Configuration

You can use environment variables to change settings on the fly:

"envOverrides": {
  "DATABASE_URL": "modules.database.config.url",
  "API_PORT": "modules.api.config.port"
}

When you set DATABASE_URL in your environment, it will update the database URL in your config.

Have different settings for dev, production, etc:

"environments": {
  "development": {
    "modules": {
      "database": {
        "config": {
          "url": "mongodb://localhost:27017"
        }
      }
    }
  },
  "production": {
    "modules": {
      "database": {
        "config": {
          "url": "mongodb://prod-server:27017"
        }
      }
    }
  }
}

Run with a specific environment like this:

ajs project run --env production

Module

Modules are the building blocks of your Antelopejs app. They talk to each other through interfaces - exporting features others can use, and importing features they need.

Export Interfaces

Learn how to create and share interfaces between your modules. We'll cover how to organize, version, and implement them properly.