3. Environment variables Actionhero reads NODE_ENV (defaults to development) and ACTIONHERO_CONFIG (optional path override). Set REDIS_URL or configure config/redis.ts to point at your Redis instance.

4. Redis — a running Redis server is required for clustering, tasks, and chat. For local dev redis-server on localhost:6379 is used by default.

5. Import from the barrel — always import from index.ts (or the npm package root) rather than deep paths to stay aligned with the public API:

import { Process, Action, Task, cache, chatRoom, task, api } from "./actionhero";

6. Build and start:

npx tsc
node dist/server.js

Public API

Process

class Process {
  registerProcessSignals(cb: (exitCode: number) => void): void;
  start(config?: Partial<ActionheroConfigInterface>): Promise<void>;
  stop(): Promise<void>;
  restart(): Promise<void>;
}

The main lifecycle controller. Instantiate once, call registerProcessSignals so Unix signals (SIGTERM, SIGINT) invoke a clean shutdown, then call start(). Pass a partial config object to override defaults programmatically without touching config files.

Action

abstract class Action {
  name: string;
  description: string;
  version: number;
  inputs: Inputs;
  middleware: string[];
  abstract run(params: ParamsFrom<this["inputs"]>, response: Record<string, unknown>): Promise<void>;
}

Base class for every API action. Extend it, declare inputs with validation rules, and implement run. Actionhero auto-discovers subclasses placed in actions/ and registers them with all transports.

cache

const cache: {
  save(key: string, value: unknown, expireTimeMS?: number): Promise<boolean>;
  load(key: string, options?: { expireTimeMS?: number }): Promise<{ value: unknown; expireAt: number | null }>;
  destroy(key: string): Promise<boolean>;
  keys(): Promise<string[]>;
  size(): Promise<number>;
};

Redis-backed key/value store accessible across all cluster nodes. Use it for shared session state, rate-limit counters, or anything that must survive a single-process restart.

task

const task: {
  enqueue(taskName: string, params: Record<string, unknown>, queue?: string): Promise<void>;
  enqueueAt(timestamp: number, taskName: string, params: Record<string, unknown>, queue?: string): Promise<void>;
  enqueueIn(delay: number, taskName: string, params: Record<string, unknown>, queue?: string): Promise<void>;
  del(queue: string, taskName: string, params: Record<string, unknown>, count?: number): Promise<number>;
  scheduledAt(queue: string, taskName: string, params: Record<string, unknown>): Promise<number[]>;
};

Enqueue background jobs by name. Tasks must be defined by extending Task and placed in tasks/. Use enqueueAt/enqueueIn for delayed execution.

chatRoom

const chatRoom: {
  create(room: string): Promise<void>;
  destroy(room: string): Promise<void>;
  exists(room: string): Promise<boolean>;
  list(): Promise<string[]>;
  addMember(connectionId: string, room: string): Promise<boolean>;
  removeMember(connectionId: string, room: string): Promise<boolean>;
  broadcast(connection: Connection | {}, room: string, message: Record<string, unknown>): Promise<void>;
};

Manage real-time pub-sub rooms backed by Redis. Connections join rooms; broadcast fans a message out to all members across every node.

Working examples

Scenario - Minimal server boot

Drop-in replacement for server.ts. Registers OS signal handlers and starts all configured transports.

import { Process } from "./actionhero";

async function main() {
  const app = new Process();

  app.registerProcessSignals((exitCode) => {
    process.exit(exitCode);
  });

  await app.start();
}

main().catch((err) => {
  console.error(err);
  process.exit(1);
});

Scenario - Defining a custom Action

Create src/actions/greet.ts. Actionhero picks it up automatically on next boot.

import { Action, ParamsFrom } from "./actionhero";

const inputs = {
  name: {
    required: true,
    validator: (p: string) => p.length <= 64 || "name too long",
  },
} as const;

export class Greet extends Action {
  name = "greet";
  description = "Returns a greeting for the supplied name";
  version = 1;
  inputs = inputs;

  async run(params: ParamsFrom<typeof inputs>, response: Record<string, unknown>) {
    response.message = `Hello, ${params.name}!`;
  }
}

Scenario - Defining and enqueuing a background Task

// src/tasks/sendWelcomeEmail.ts
import { Task } from "./actionhero";

export class SendWelcomeEmail extends Task {
  name = "sendWelcomeEmail";
  description = "Sends a welcome email to a new user";
  queue = "default";
  frequency = 0; // run once per enqueue, not on a schedule

  async run(params: { userId: string }) {
    // integrate your mailer here
    console.log(`Sending welcome email to user ${params.userId}`);
  }
}

// src/actions/register.ts
import { Action, task } from "./actionhero";

export class Register extends Action {
  name = "register";
  description = "Create account and queue welcome email";
  inputs = { userId: { required: true } } as const;

  async run(params: { userId: string }, response: Record<string, unknown>) {
    await task.enqueue("sendWelcomeEmail", { userId: params.userId }, "default");
    response.queued = true;
  }
}

Scenario - Using the cache and chatRoom APIs directly

import { cache, chatRoom, api } from "./actionhero";

async function demo() {
  // cache
  await cache.save("session:abc123", { role: "admin" }, 60_000);
  const { value } = await cache.load("session:abc123");
  console.log(value); // { role: 'admin' }

  // chat
  await chatRoom.create("announcements");
  const rooms = await chatRoom.list();
  console.log(rooms); // ['announcements']

  await chatRoom.broadcast(
    {},
    "announcements",
    { message: "Server is going down in 5 minutes" }
  );
}

File walkthrough

• index.ts - Central barrel; import everything from here. Bootstraps the global api singleton.
• server.ts - Thin production entry: creates a Process, registers signals, calls start().
• actions/ - Bundled example actions (status, cacheTest, swagger, etc.) — study or delete.
• bin/actionhero.ts - CLI root wired to commander; delegates to sub-commands under bin/methods/.
• bin/methods/ - Generators (generate action, generate task, etc.) and task enqueue helper.
• classes/action.ts - Abstract Action base with input validation scaffolding.
• classes/actionProcessor.ts - Runs an action through middleware, input coercion, and response building.
• classes/api.ts - The Api container holding references to connections, servers, tasks, initializers.
• classes/cli.ts - Abstract CLI base for adding custom CLI commands.
• classes/config.ts - ActionheroConfigInterface and PluginConfig types.
• classes/connection.ts - Represents a single client connection across any transport.
• classes/exceptionReporter.ts - Normalises uncaught exceptions into structured log events.
• classes/initializer.ts - Abstract Initializer base; implement initialize, start, stop.
• classes/initializers.ts - Registry that loads and orders all initializers.
• classes/input.ts / classes/inputs.ts - Input descriptor types and ParamsFrom utility type.
• classes/process.ts - Process lifecycle: discovers plugins, loads config, runs initializers.
• classes/server.ts - Abstract Server base for custom transports.
• classes/task.ts - Abstract Task base; implement run.
• classes/process/ - Static process metadata: env, id, pid, projectRoot, typescript, actionheroVersion.
• config/ - Default exported config factories consumed by Process at boot.
• initializers/ - Core framework boot logic (redis connect, resque workers, route loading, etc.).
• modules/cache.ts - cache object: Redis-backed KV store.
• modules/chatRoom.ts - chatRoom object: room create/destroy/broadcast.
• modules/action.ts - action object: middleware registration helpers.
• modules/utils/ - Shared utility functions (sleep, arrayUnique, etc.).
• servers/ - Built-in HTTP and WebSocket server implementations.
• tasks/ - Example task definitions.

Common pitfalls and fixes

• Redis not running — All cache, task, and chatRoom calls hang or throw. Fix: ensure redis-server is up and config/redis.ts points to the right host/port.
• globalThis.api conflicts in tests — Running multiple test files in the same process can share a stale api singleton. Fix: call api.stop() in afterAll and delete globalThis.api between suites, or use specHelper.
• TypeScript strict breaks input inference — ParamsFrom<typeof inputs> requires as const on the inputs object literal. Fix: always declare input objects with as const.
• ESM/CJS interop with ioredis or primus — Mixed module formats cause require is not defined. Fix: keep "module": "commonjs" in tsconfig.json; do not switch to "module": "ESNext" without a bundler.
• Action not discovered — Files in actions/ are only auto-loaded if they export a class that extends Action. Fix: ensure the class is a named export and the file is within the configured paths.actions glob.
• Config overrides ignored — Passing config to app.start(config) only deep-merges top-level keys. Fix: structure overrides to match the exact nested shape in ActionheroConfigInterface.

Vibe-coding prompt template

I have the Actionhero framework source (actionhero@29.3.4) copied into
src/actionhero/ and a USAGE.md guide at src/actionhero/USAGE.md.

Please help me integrate it into my existing Node.js/TypeScript project
step by step:

1. Read USAGE.md fully before making any changes.
2. Add the required dependencies from the "Required dependencies" section
   to my package.json and run npm install.
3. Update tsconfig.json as described in "Project setup".
4. Create a Process boot file at src/server.ts following the example in
   "Working examples - Minimal server boot".
5. Create a new Action in src/actions/ using the "Defining a custom Action"
   example as a template; adapt it to my domain logic.
6. If I need background jobs, create a Task in src/tasks/ following the
   "Defining and enqueuing a background Task" example.
7. Wire any environment variables (NODE_ENV, REDIS_URL) in my .env file.
8. Verify the build compiles with `npx tsc --noEmit`.

Only use symbols visible in USAGE.md and src/actionhero/index.ts.
Do not invent new APIs. Ask me before adding any dependency not listed
in USAGE.md.

License and credit

Actionhero is released under the Apache-2.0 license (see source/LICENSE if present in this block, or the upstream repository). Upstream package: actionhero on npm — source at github.com/actionhero/actionhero.

This product’s unique contribution is clean room implementation of valuable code block into AVCP compatible standard.

전체 설치 가이드와 연동 프롬프트는 구매 후 열람할 수 있습니다.

Total.js Full-Stack Node.js Web Framework

Automation, Utilities & Developer Tools

무료