Getting Started

Learn how to install Yama, create your first project, and run the development server.

Installation

Install the Yama CLI globally:

npm install -g @betagors/yama-cli
# or
pnpm add -g @betagors/yama-cli

Or use it directly with npx:

npx @betagors/yama-cli create my-app

Create a Project

Scaffold a new project with the interactive CLI:

yama create my-app

You can also specify options directly:

yama create my-app --database postgresql

This creates a project with the following structure:

my-app/
├── yama.yaml              # API configuration
├── package.json
├── src/
│   ├── handlers/          # Your business logic
│   └── generated/         # Auto-generated types (gitignored)
├── migrations/            # Database migrations
└── .env                   # Environment variables

Run the Development Server

Navigate to your project and start the dev server:

cd my-app
npm install
yama dev

The server starts at http://localhost:4000 with:

• Hot reload on file changes
• Auto-regeneration of types and SDK
• API documentation at /docs

Configure Your API

Edit yama.yaml to define your API:

name: my-app
version: 1.0.0

schemas:
  User:
    type: object
    properties:
      id:
        type: string
        format: uuid
      email:
        type: string
        format: email
      name:
        type: string

endpoints:
  /users:
    get:
      handler: handlers/listUsers
      response:
        type: array
        items:
          $ref: "#/schemas/User"
    post:
      handler: handlers/createUser
      request:
        $ref: "#/schemas/User"
      response:
        $ref: "#/schemas/User"

Write Handlers

Create handler files in src/handlers/:

// src/handlers/listUsers.ts
import { HandlerContext } from '@betagors/yama-core';

export async function listUsers(context: HandlerContext) {
  // Access database, services, etc. via context
  return context.db.query('SELECT * FROM users');
}

// src/handlers/createUser.ts
import { HandlerContext } from '@betagors/yama-core';

export async function createUser(context: HandlerContext) {
  const { email, name } = context.request.body;
  
  const user = await context.db.query(
    'INSERT INTO users (email, name) VALUES ($1, $2) RETURNING *',
    [email, name]
  );
  
  return user;
}

Generate Types and SDK

Generate TypeScript types and a client SDK:

yama generate

This creates:

• src/generated/types.ts — TypeScript types from your schemas
• src/generated/sdk.ts — Type-safe API client

Use the SDK in your frontend:

import { api } from './generated/sdk';

const users = await api.users.get();
const newUser = await api.users.post({ 
  email: 'user@example.com',
  name: 'John Doe'
});

Environment Variables

Create environment-specific configuration:

.env                    # Base configuration
.env.development        # Development overrides
.env.production         # Production overrides
.env.local              # Local overrides (gitignored)

Example .env:

DATABASE_URL=postgresql://user:password@localhost:5432/myapp
JWT_SECRET=your-secret-key
PORT=4000

Reference variables in yama.yaml:

database:
  url: ${DATABASE_URL}

auth:
  providers:
    - type: jwt
      secret: ${JWT_SECRET}

Next Steps

• Guides — Learn about migrations, authentication, and more
• CLI Reference — All available commands
• Examples — Full example projects