PURISTA

Appearance

CLI ​

Create a new project ​

The easiest and fastest way to start with PURISTA is using your package manager's create command.
The scaffold is based on blueprint templates and guides you through runtime/event bridge/server choices.

In the project folder, simply execute:

bash
npm create purista@latest
bash
bun create purista@latest
bash
yarn create purista@latest
bash
pnpm create purista@latest

The CLI tool will guide you through all the necessary steps.

PURISTA CLI ​

PURISTA provides a command line interface (CLI) that allows you to create new services, and add commands or subscriptions to existing services.

You can either install the CLI globally, or run it with npx.

Global install:

bash
npm install -g @purista/cli
bash
bun add --global @purista/cli
bash
yarn global add @purista/cli
bash
pnpm add -g @purista/cli

In your project root run:

bash
purista add [service|command|subscription]

Or without global install:

bash
npx @purista/cli add [service|command|subscription]

Generated command and subscription schema stubs default to z.unknown() for payloads. This keeps generated code type-safe by default and avoids accidental any propagation.

Keep CLI-Managed Definition Lists

When the CLI generates or updates service files, keep commandDefinitions and subscriptionDefinitions as typed constants. Renaming or untyping these lists can break follow-up CLI updates and weaken inferred types.

PURISTA config file ​

Since version 1.12.0, the PURISTA CLI expects to find a purista.json file in the root of your project. This file contains basic information about your project. Especially the settings for file and event casing conventions are important.

Schema ​

This configuration file follows the JSON Schema specification.

json
{
  "$schema": "https://purista.dev/schemas/1.12.0/schema.json",
  "type": "object",
  "properties": { ... }
}

Configuration Options ​

$schema ​

  • Type: string
  • Description: A field for the JSON schema specification.
  • Default: https://purista.dev/schemas/1.12.0/schema.json

runtime ​

  • Type: string
  • Allowed Values: node, bun
  • Default: node
  • Description: Specifies the runtime environment for the project.

eventBridge ​

  • Type: string
  • Allowed Values: default, amqp, nats, mqtt, dapr
  • Default: default
  • Description: Defines the event bridge used in the project.

fileConvention ​

  • Type: string
  • Allowed Values: camel, snake, kebab, pascal, pascalSnake
  • Default: camel
  • Description: Determines the file naming convention used in the project.

eventConvention ​

  • Type: string
  • Allowed Values: camel, snake, kebab, pascal, pascalSnake, constantCase, dotCase, pathCase, trainCase
  • Default: camel
  • Description: Determines the naming convention for events in the project.

linter ​

  • Type: string
  • Allowed Values: biome, eslint, none
  • Default: none
  • Description: Specifies the linter used in the project.

formatter ​

  • Type: string
  • Allowed Values: biome, prettier, none
  • Default: none
  • Description: Specifies the formatter used in the project.

servicePath ​

  • Type: string
  • Default: src/service
  • Description: Defines the relative path where services are located in the project.

Example purista.json Configuration ​

json
{
  "$schema": "https://purista.dev/schemas/1.12.0/schema.json",
  "runtime": "node",
  "eventBridge": "nats",
  "fileConvention": "kebab",
  "eventConvention": "dotCase",
  "linter": "eslint",
  "formatter": "prettier",
  "servicePath": "src/services"
}