Nile Js

TypeScript-first, service and actions oriented backend framework for building modern, fast, safe and AI-ready backends with simplest developer experience possible.

You define actions, group them into services, and get a predictable API with validation, error handling, and schema export, no route definitions, no controllers, no middleware chains and rest api conventions to care about, just your business logic.

And it's all AI agent-ready out of the box, progressively discoverable and tool calling ready with validation.

Get Started View on GitHub

Installation

npx @nilejs/cli new my-app

How It Works

1. Define an Action

// services/tasks/create.ts
import { Ok } from "slang-ts";
import { createAction, type ActionHandler } from "@nilejs/nile";
import { z } from "zod";

const createTaskSchema = z.object({
  title: z.string().min(1),
  status: z.enum(["pending", "in-progress", "done"]).default("pending"),
});

type CreateTaskPayload = z.infer<typeof createTaskSchema>;

const handler: ActionHandler<CreateTaskPayload> = (data) => {
  const task = { id: crypto.randomUUID(), ...data };
  return Ok({ task });
};

export const createTask = createAction({
  name: "create",
  description: "Create a new task",
  handler,
  validation: createTaskSchema,
});

2. Group into a Service

// services/tasks.ts
import { createService } from "@nilejs/nile";
import { createTask } from "./tasks/create";

export const tasksService = createService({
  name: "tasks",
  description: "Task management operations",
  actions: [createTask],
});

3. Start the Server

// server.ts
import { createNileServer } from "@nilejs/nile";
import { tasksService } from "./services/tasks";

const server = await createNileServer({
  serverName: "my-app",
  services: [tasksService],
  rest: {
    baseUrl: "/api",
    port: 8000,
    allowedOrigins: ["http://localhost:8000"],
  },
});

if (server.rest) {
  const { fetch } = server.rest.app;
  Bun.serve({ fetch, port: 8000 });
}

4. Invoke the Action

curl -X POST http://localhost:8000/api/services \
  -H "Content-Type: application/json" \
  -d '{
    "intent": "execute",
    "service": "tasks",
    "action": "create",
    "payload": { "title": "Ship Nile", "status": "in-progress" }
  }'

Why You Should Care

Service-Action Model

Define operations as actions, group them into services by domain. No route definitions, no controllers, no middleware chains. Just business logic with a consistent interface.

Built for Speed

Highly optimized with first-class Bun support. A single endpoint with fast action lookups and caching for frequently accessed operations. Deploys anywhere Node.js or Bun can run.

AI Agent Ready

Every action exports its schema as JSON Schema. AI agents can discover available operations, understand their parameters, and invoke them through the same endpoint your frontend uses.

Result Pattern

Every handler returns Ok or Err. No unhandled exceptions. Every response follows the same shape: status, message, and data.

Composable Pipelines

Chain actions together with hooks. Before hooks validate or gate. After hooks log or notify. Critical hooks stop the pipeline on failure, non-critical ones log and continue.

Built-In Auth

JWT authentication configured once at the server level, enforced per action. Global hooks handle authorization, RBAC, and API keys without per-route middleware.

First-Class File Uploads

Multipart form-data support with MIME detection, file size limits, and extension validation. No external libraries needed.

Structured Logging

Built-in logger with chunking support. Every request, hook execution, and error is logged with context for debugging.

Robust Error Handling

Every handler and hook is wrapped in error handling. Crashes become graceful failures. Traceable log IDs make production debugging straightforward.

Type Safety

Payload types are preserved through generics. The schema intent serves types over the wire for client code generation without monorepo coupling.

Predictable and Simple

One endpoint. One request shape. One response shape. Every action follows the same pattern. Low mental overhead means less context switching and fewer decisions about how to structure code.

Ecosystem

Join the community chat for discussions, help, and updates.