Hello World Workflow

Create a minimal workflow to verify your Loopstack setup is working.

Step 1: Create a Workflow

Create src/hello/hello.ui.yaml — this configures the workflow’s title, description, and input form in Studio:


title: Hello World
description: A simple workflow that greets you by name.
 
ui:
  form:
    properties:
      name:
        title: 'What is your name?'
        default: 'World'

Create src/hello/hello.workflow.ts:


import { z } from 'zod';
import { BaseWorkflow, Final, Initial, MessageDocument, Transition, Workflow } from '@loopstack/common';
 
@Workflow({
  uiConfig: __dirname + '/hello.ui.yaml',
  schema: z.object({
    name: z.string().default('World'),
  }),
})
export class HelloWorkflow extends BaseWorkflow<{ name: string }> {
  private name: string;
 
  @Initial({ to: 'ready' })
  async start(args: { name: string }) {
    this.name = args.name;
  }
 
  @Transition({ from: 'ready', to: 'done' })
  async greet() {
    await this.repository.save(MessageDocument, {
      role: 'assistant',
      content: `Hello, ${this.name}!`,
    });
  }
 
  @Final({ from: 'done' })
  async finish() {
    console.log('Workflow finished');
  }
}

The @Workflow() decorator links the YAML config and defines the input schema with Zod. The schema tells Studio what form to render, and the YAML form.properties customizes how each field appears. The @Initial method receives the validated input as args. State is stored on the class instance and persists across transitions.

Step 2: Create a Workspace

Inject the Workflow so it can be discovered and executed.


import { Injectable } from '@nestjs/common';
import { InjectWorkflow, Workspace } from '@loopstack/common';
import { HelloWorkflow } from './hello.workflow';
 
@Injectable()
@Workspace({
  uiConfig: {
    title: 'Hello World',
  },
})
export class HelloWorkspace {
  @InjectWorkflow() hello: HelloWorkflow;
}

Step 3: Create a Module (optional)

Wrap the workflow and workspace in a NestJS module. Create src/hello/hello.module.ts:


import { Module } from '@nestjs/common';
import { HelloWorkflow } from './hello.workflow';
import { HelloWorkspace } from './hello.workspace';
 
@Module({
  providers: [HelloWorkflow, HelloWorkspace],
})
export class HelloModule {}

or add them as providers to the app.module.ts directly.

Step 4: Register in AppModule

Add HelloModule to your src/app.module.ts:


import { Module } from '@nestjs/common';
import { LoopstackModule } from '@loopstack/loopstack-module';
import { HelloModule } from './hello/hello.module';
 
@Module({
  imports: [LoopstackModule.forRoot(), HelloModule],
})
export class AppModule {}

Step 5: Run and Verify

Start your app:


npm run start:dev

Open Studio at http://localhost:5173 . You should be able to create the Hello World workspace. Create and select the workspace, then start a new run — enter your name in the form and the workflow will greet you.

What’s Next

Core Concepts — Deeper look at workflows, tools, and documents
Your First Workflow — Build a real workflow with AI, structured output, and human-in-the-loop