Setup a PURISTA project

In this quickstart step, you create a new project with the PURISTA CLI blueprint engine. The generator resolves a local project blueprint based on your runtime, event bridge, HTTP server, and linting choices, then writes an ESM project skeleton for that setup.

Create a new project

Run one of the following commands:

::: code-group

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

:::

You can also run the same flow directly through the main CLI:

purista init my-app

For CI, scripts, or agentic tooling, the same command also supports deterministic non-interactive usage:

purista init my-app \
  --runtime node \
  --event-bridge default \
  --webserver \
  --linter biome \
  --formatter biome \
  --package-manager npm \
  --non-interactive \
  --defaults \
  --no-install

The create wrapper and the main CLI use the same underlying command engine, so both entry points generate the same project shape.

::: tip Recommended for AI-assisted projects Generated projects include AGENTS.md, CLAUDE.md, .agents/IMPLEMENTATION.md, and local PURISTA skill links for coding agents by default. The skill links target node_modules/@purista/core/skills/purista, so updating @purista/core refreshes the project skill.

See Install the PURISTA AI Skill if you need to add the skill to an existing project or an assistant-specific mirror. :::

Choose the options that fit your runtime and deployment setup:

  • runtime: node or bun
  • event bridge: default, amqp, mqtt, nats, or dapr
  • webserver: add the bundled Hono-based HTTP surface when needed
  • linter: biome, eslint, or none
  • generated projects are ESM-only and always use "type": "module"

After setup, generate services and business artifacts through the project-local @purista/cli scripts:

  1. npm run add:service -- <name>
  2. npm run add:command -- <name>
  3. npm run add:subscription -- <name>
  4. npm run add:stream -- <name>
  5. npm run add:queue -- <name>
  6. npm run add:queue-worker -- <name>
  7. npm run add:agent -- <name>

Use the matching package manager for your project: npm run ..., pnpm run ..., yarn ..., or bun run ....

Recommended scaffold order for new projects:

  1. add:service and first add:command
  2. add:stream if you need push/live updates
  3. add:queue + add:queue-worker for background jobs
  4. install optional AI packages in the application when you need LLM-powered workloads

Rule of thumb:

  • commands = request/response entrypoints
  • streams = live outbound updates
  • queues/workers = durable async processing
  • agents = optional application-level AI workloads built outside the core runtime

See also:

AI agent packages

If your app uses AI agents with a model provider, add the provider package (AI agent support is built into @purista/core):

::: code-group

npm install @purista/harness-openai
pnpm add @purista/harness-openai
bun add @purista/harness-openai
yarn add @purista/harness-openai

:::

Project structure

The generated app shape is intentionally minimal. The initializer creates the runtime/bootstrap files, the project config, and an example ping service with one starter command. Follow-up CLI commands then extend that structure.

|-public/                     # only when --webserver is enabled
|-src/
| |-config/                   # bridge/http config files when required by the selected blueprints
| |-agents/
| |-service/
| |   |- serviceEvent.enum.ts
| |   |- ping/
| |       |- generalPingServiceInfo.ts
| |       |- v1/
| |           |- pingServiceConfig.ts
| |           |- pingV1ServiceBuilder.ts
| |           |- pingV1Service.ts
| |           |- pingV1Service.test.ts
| |           |- command/
| |               |- ping/
| |                   |- schema.ts
| |                   |- types.ts
| |                   |- pingCommandBuilder.ts
| |                   |- pingCommandBuilder.test.ts
| |-eventbridge.ts
| |-http.ts                   # only when --webserver is enabled
| |-index.ts
|- package.json
|- package-lock.json / bun.lockb / pnpm-lock.yaml / yarn.lock
|- tsconfig.json
|- purista.json
|- README.md
|- AGENTS.md
|- CLAUDE.md
|- .agents/
| |- IMPLEMENTATION.md
| |- skills/
|     |- purista -> node_modules/@purista/core/skills/purista
|- .claude/
| |- skills/
|     |- purista -> node_modules/@purista/core/skills/purista
|- .gitignore

Notes:

  • src/service and src/agents are the default CLI-managed roots.
  • AGENTS.md, CLAUDE.md, and .agents/IMPLEMENTATION.md guide coding agents toward PURISTA structure and CLI usage.
  • .agents/skills/purista and .claude/skills/purista are package-backed links to the PURISTA skill bundled with @purista/core.
  • The exact filenames follow the fileConvention and eventConvention from purista.json.
  • src/eventbridge.ts is generated from the chosen bridge blueprint.
  • src/http.ts and public/ are only created for the HTTP-enabled project variants.
  • Additional commands, subscriptions, streams, queues, queue workers, and agents are generated into this structure by the local add:* package scripts.

The CLI expects this structure for automated updates and type-safe wiring, so avoid moving the generated roots unless you also update purista.json.