@warlock.js/ai Tools

Warlock.js

The full-stack TypeScript framework for server-rendered React, typed HTTP and data, and production-ready AI agents — in one application.

Documentation · Getting started · Packages · Contributing · Changelog

Why Warlock.js

Most Node.js stacks make you assemble a server, an ORM, a validator, a queue, an SSR layer and an AI SDK yourself — and then keep them in step forever. Warlock.js ships them as one family of packages, released together at one version, designed to share a lifecycle, a configuration model and a type system.

• One application, every surface. Server-rendered React pages, a typed HTTP API and AI agents live in the same codebase and boot in the same lifecycle.
• Typed end to end. Models, request schemas, resources, page loaders and agent tools are all TypeScript-first, and the whole family typechecks under strict with noUncheckedIndexedAccess.
• Batteries included, never forced. Heavy integrations (S3, SES, sharp, socket.io, provider SDKs) are optional peer dependencies — install one only when you use the feature that needs it.
• Lockstep releases. Every package is published at the same version after the whole family passes its typecheck, its tests, a local-registry install and an end-to-end application check.
• AI that is part of the app. Provider-agnostic agents, tools, teams, workflows, RAG, memory and guardrails, with adapters for every major model provider.

Getting started

Create a new application with the scaffolder:

npx create-warlock@latest my-app
cd my-app
npm run dev

The wizard asks what you are building (full-stack web or API only), which database driver to use and which optional features to include — SSR pages, authorization, mail, storage, queues, notifications, AI providers and more — then generates a typed, ready-to-run project. Read the getting-started guide for a full walkthrough.

A taste

// src/app/products/routes.ts — an HTTP API
import { router } from "@warlock.js/core";
import { createProduct, listProducts, showProduct } from "./controllers";

router.get("/api/products", listProducts);
router.post("/api/products", createProduct);
router.get("/api/products/:id", showProduct);

// src/web/products/index.page.tsx — a server-rendered React page
import type { PageLoader, PageProps } from "@warlock.js/web";
import { catalog } from "app/products/catalog";
import ProductGrid from "./product-grid";

export const loader = (async () => ({
  products: await catalog.list(),
})) satisfies PageLoader;

export default function Products({ data }: PageProps<typeof loader>) {
  return <ProductGrid items={data.products} />;
}

// src/app/support/agents/triage.ts — an AI agent
import { ai } from "@warlock.js/ai";
import { openai } from "./providers";

export const supportAgent = ai.agent({
  model: openai.model({ name: "gpt-4o-mini" }),
  systemPrompt: "Help customers choose a product.",
});

Packages

All packages live in packages/ and are published to npm at the same version.

Foundation

Application services

AI

Model providers: ai-openai · ai-anthropic · ai-google · ai-bedrock · ai-mistral · ai-groq · ai-deepseek · ai-xai · ai-ollama

Repository layout

framework/
├── packages/            every published package, one directory each
│   ├── core/
│   ├── web/
│   ├── cascade/
│   └── …
├── docs/                the documentation site (Astro + Starlight) → warlock.js.org
├── tools/release/       the release runner: gate, publish and confirm the family
├── scripts/             workspace-wide checks (spec coverage, CI package selection)
├── skills/              agent playbooks for working in this repository
└── .github/workflows/   CI, docs deployment, create-warlock and release pipelines

Each package keeps its own README.md, CHANGELOG.md, tests and agent skills. The full history of every package was carried over from its original repository, so git log and git blame work across the move.

Development

Requirements: Node.js 22.15 or newer (CI uses Node 24) and pnpm 11.24.0. With Corepack enabled, the right pnpm is picked up from packageManager automatically:

corepack enable
git clone https://github.com/warlockjs/framework.git
cd framework
pnpm install

Packages resolve each other from this repository, never from npm, so a change in core is immediately visible to auth, web and every other dependent.

Common tasks

Some suites need services: queue and notifications expect Redis on port 6390, and parts of cascade and auth start databases through Testcontainers, which needs Docker.

docker run -d --name warlock-redis -p 6390:6379 redis:7

Continuous integration

The shared Oxlint check fails on correctness errors; warnings remain advisory. Unused locals and unsafe optional access stay errors. Override parameters, intentionally ignored catches, object-rest omissions, snapshot spreads, numeric array allocation and typed createElement children follow the repository's existing conventions. Exceptions to safety checks belong on the specific line with a reason; do not disable a safety rule to conceal a failing check.

Releasing

The family is released in lockstep from GitHub Actions, never from a developer machine. Every package shares one version, so a release starts by moving all of them at once:

pnpm release:version 5.30.0   # every package, the exact family pins and the lockfile

Date each package's ## 5.30.0 CHANGELOG heading, commit, push, then dispatch the release workflow with that version:

1. Gate — strictness, every package's typecheck and tests, build, pack, and an install of the tarballs from a local registry.
2. Application check — a real application is built and exercised on the release tarballs.
3. Publish — only with publish: true, and only after the gate passes.
4. Confirm — the published versions are installed back from npm and checked, then v<version> is tagged.

See tools/release for the details.

Contributing

Contributions are welcome. Before opening a pull request:

1. Branch from main and keep the change focused on one concern.
2. Add or update tests next to the code you changed; a fix starts with a failing test.
3. Update the package's docs and its CHANGELOG.md in the same change.
4. Run pnpm --filter <package> typecheck and pnpm --filter <package> test for each package you touched.

CI must pass before a change is merged. Report security issues privately to the maintainers rather than in a public issue.

License

MIT © Hassan Zohdy

Repository formatting uses the pinned Oxfmt tool and one root .oxfmtrc.json: run pnpm format to write changes and pnpm format:check to check them. CI checks the same configuration. Generated references, locks, build output and archived material are excluded; regenerate their source projections instead. Scaffolder source uses this root formatter even in its standalone test job. Generated app templates retain their own toolchain checks.

Oxlint/Oxfmt are the only supported lint and format tools in 5.34.0. Repository import sorting stays disabled; generated apps use Oxfmt's built-in import sorting. Migrate legacy apps with npx warlock upgrade --from 5.33 --to 5.34.0.