Lakutata

An IoC application framework for Node.js and TypeScript

Website · Getting started · Examples · API reference · 中文

Lakutata gives web services, command line tools, desktop (Electron) applications and embedded devices one programming model. An application is a tree of objects (components, providers, controllers) that a container creates; DTOs validate the options of the objects and the input of the actions; and transports expose the controllers over HTTP (Express, Fastify), the command line (Commander), service calls (HTTP, Socket.IO, JSON-RPC 2.0, gRPC, NATS, Electron IPC), MCP, D-Bus, schedules and message queues. One controller method can serve several of them at once.

Quick start

npx @lakutata/cli create --name my-app
cd my-app
npm run dev
# in another terminal
curl 'http://localhost:8080/example?name=you'     # {"message":"Hello, you!"}

Lakutata needs Node.js ^22.13.0 || >=24.11.0. The templates of lakutata create give you a web service, a command line tool, an HTTP API with a React, Vue, Next.js or Nuxt interface, or an Electron application. An application written by hand looks like this:

import {Application, DTO} from 'lakutata'
import {buildEntrypoints, Controller} from 'lakutata/com/entrypoint'
import {GET, ServiceAction} from 'lakutata/decorator/ctrl'
import {Expect} from 'lakutata/decorator/dto'
import {expressHTTPEntrypoint} from 'lakutata/adapter/express'

class GreetDTO extends DTO {
    @Expect(DTO.String().optional().default('world'))
    public name: string
}

class GreetController extends Controller {
    //GET /greet?name=you, and the service action {cmd: 'greet', name: 'you'}
    @GET('/greet', GreetDTO)
    @ServiceAction({cmd: 'greet'}, GreetDTO)
    public async greet(input: GreetDTO): Promise<{ message: string }> {
        return {message: `Hello, ${input.name}!`}
    }
}

Application.run(() => ({
    id: 'com.example.greeter',
    name: 'Greeter',
    components: {
        entrypoint: buildEntrypoints({
            controllers: [GreetController],
            http: expressHTTPEntrypoint({port: 8080})
        })
    },
    bootstrap: ['entrypoint']
}))

Packages

lakutata is the framework: it re-exports most of the packages below under its subpaths (lakutata/com/database, lakutata/adapter/express…), so an application usually installs it alone, plus the drivers and adapters it uses.

The templates of lakutata create are the @lakutata/template-* packages, listed by @lakutata/templates.

Documentation

• lakutata.com: the guides and the examples, in English and Chinese, and the API reference. Their sources are packages/lakutata/doc (en, zh, and their examples) and the type declarations of the packages.
• Each package has a README with its options, API and errors.
• plugins/lakutata: the Agent Skill of the framework, for AI coding assistants. Any assistant: npx skills add lakutata/lakutata; Claude Code: /plugin install lakutata --marketplace lakutata/lakutata; the others, and how the skill works: its page.

Development

npm install
npm run build        # compiles every package, in the order of their dependencies
npm run test:unit    # the unit tests of the packages
npm run lint         # ESLint, and the check of the documentation of the public API

cd website && npm ci && npm run dev    # the website, once the packages are built

The repository holds the packages and the templates (packages/), the website (website/) and the build and documentation-check scripts (scripts/). CONTRIBUTING.md gives the naming rules and how the public API is documented.

Lakutata 2.x

Lakutata 3 brought the framework and its packages into this repository. The 2.x releases of lakutata are tagged here (2.0.x). The 2.x versions of @lakutata/cli, @lakutata/dbus and @lakutata/nats come from lakutata-packages, and the 2.x templates from the lakutata-template-* repositories. To bring a 2.x project to 3.x, see Upgrading from Lakutata 2.x; a project on Lakutata 1.x (@lakutata/core 1.x and the @lakutata-module/* and @lakutata-component/* packages) follows Upgrading from Lakutata 1.x instead.

License

MIT