NPM Setup

The NPM distribution is perfect for developers who prefer npm package management and is especially well-suited for CI/CD pipelines and automated testing environments.

Overview

The NPM distribution provides:

Node.js package management: Install and manage Yaci CLI distribution through npm
Streamlined commands: Simplified up command that handles download and devnet creation
Yaci Viewer package: Separately installable web interface for blockchain exploration
Wallet SDK and MCP endpoint: Served by the Yaci CLI/admin service
CI/CD ready: Perfect for automated testing and continuous integration

Prerequisites

Supported Platforms

The NPM distribution is supported on:

Linux x86: Tested on Ubuntu 22.04 and later
macOS 15 (Arm64) or later

Requirements

Node.js: 20.8.0 or later
Available ports: Default ports should be free (3001, 8080, and 3000 if you run Yaci Viewer)

For Ogmios and Kupo, ensure ports 1337 and 1442 are also available if you plan to use these services.

Installation

Step 1: Install Yaci DevKit

For latest stable version:

npm i -g @bloxbean/yaci-devkit

For latest beta version:

npm i -g @bloxbean/yaci-devkit@beta

Step 2: Install Yaci Viewer (Optional)

For latest stable version:

npm install -g @bloxbean/yaci-viewer

For latest beta version:

npm install -g @bloxbean/yaci-viewer@beta

⚠️

Important: The NPM distribution uses different command names:

yaci-devkit: Starts the Yaci CLI and other components
yaci-viewer: Starts the Yaci Viewer web interface

Getting Started

Quick Start

The NPM distribution includes a convenient up command that handles both component download and devnet creation:

yaci-devkit up

This command:

Downloads the Cardano node (if not already downloaded)
Creates and starts a new devnet with 1-second block time
Sets up the basic development environment

By default, DevKit uses companion node mode: Yano bootstraps the network and then hands over to the Haskell node. See Node Modes.

Interactive Mode

To interact with the running devnet using the Yaci CLI prompt:

yaci-devkit up --interactive

This will:

Set up the devnet
Launch the interactive Yaci CLI interface
Allow you to run commands like topup, utxos, etc.

Customize Block Time (Optional)

Default Configuration: The standard up command creates a devnet with 1-second block time. You can customize this for faster development cycles.

The NPM distribution supports all devnet customization options, including sub-second block times:

# Sub-second block time (100ms) with 80-slot epochs and Yaci Store
yaci-devkit up --enable-yaci-store --block-time 0.1 --slot-length 0.1 --epoch-length 80
 
# Sub-second block time (200ms) in interactive mode
yaci-devkit up --interactive --block-time 0.2 --slot-length 0.2
 
# 5-second block time
yaci-devkit up --block-time 5 --slot-length 5

This command will:

Download Cardano node (if not already downloaded)
Download and enable Yaci Store (if specified)
Create a devnet with your custom configuration
Start the services with specified block time and epoch settings

Important considerations:

For sub-second block times, always set both --block-time and --slot-length
The slot length must be equal to or less than the block time
--epoch-length defines the number of slots per epoch (default: 600)
With 0.1s slots and 80-slot epochs, each epoch lasts 8 seconds

To see all supported options:

yaci-devkit up --help

Basic Usage

Essential Commands

1. Simple Devnet

yaci-devkit up

Basic devnet with Cardano node only.

2. Interactive Devnet

yaci-devkit up --interactive

Devnet with CLI access for manual testing.

3. Yaci Store Mode (Recommended for SDK Development)

yaci-devkit up --enable-yaci-store

Includes:

Cardano node
Yaci Store (Blockfrost-compatible APIs)
scalus transaction evaluation by default in v0.12.0+

Starting with Yaci DevKit v0.12.0, Yaci Store does not require Ogmios for transaction evaluation. If Ogmios is enabled and running, Yaci Store automatically switches to ogmios evaluation mode.

4. Kupomios Mode

yaci-devkit up --enable-kupomios

Includes:

Cardano node
Ogmios
Kupo

Advanced Configuration

You can pass the same arguments as the create-node command:

# Custom port
yaci-devkit up --port 3002 --interactive
 
# Custom slots per epoch
yaci-devkit up -e 30 --interactive

Configuration

The bundled configuration files are inside the NPM package and are replaced on every upgrade. Put your own settings, for example yaci.store.enabled=true or prometheus.port=12799, in $HOME/.yaci-cli/devkit.properties. See User Settings.

Yaci Viewer Setup

Starting Yaci Viewer

Once you have a devnet running with Yaci Store support:

yaci-viewer

Yaci Viewer runs at http://localhost:3000 (opens in a new tab). To use another port, set PORT, for example to match the Docker distribution's port 5173:

PORT=5173 yaci-viewer

You can also put PORT=5173 in the .env file described below.

By default, Yaci Viewer connects to:

Indexer API: http://localhost:8080/api/v1 (opens in a new tab)
WebSocket: ws://localhost:8080/ws/liveblocks

Configuration Options

Option 1: Using .env File

Create a .env file in your working directory:

PUBLIC_INDEXER_BASE_URL=http://localhost:8080/api/v1
PUBLIC_INDEXER_WS_URL=ws://localhost:8080/ws/liveblocks

Option 2: Command-Line Arguments

yaci-viewer --indexerBaseUrl http://new-url.com/api/v1 --indexerWsUrl ws://new-url.com/ws/liveblocks

Complete Workflow Example

For SDK Development

Start devnet with full services:

yaci-devkit up --enable-yaci-store --interactive

In another terminal, start Yaci Viewer:
```
yaci-viewer
```

Fund test addresses (in the interactive CLI):

devnet:default> topup addr_test1... 10000

For CI/CD Pipelines

# Start background devnet
yaci-devkit up --enable-yaci-store
 
# Run your tests
npm test
 
# DevKit will be available at localhost:8080 for your test suite

For detailed CI/CD integration examples and best practices, see the CI/CD Integration guide.

Service URLs

When services are enabled:

Cardano Node: localhost:3001
CLI/Admin Swagger UI: http://localhost:10000/swagger-ui.html (opens in a new tab)
Wallet page: http://localhost:10000/wallet (opens in a new tab)
Wallet SDK: http://localhost:10000/wallet-sdk.js (opens in a new tab)
MCP endpoint: http://localhost:10000/mcp (opens in a new tab)
Yaci Store (Blockfrost API): http://localhost:8080 (opens in a new tab)
Yaci Viewer: http://localhost:3000 (opens in a new tab) (yaci-viewer, or the port you set with PORT)
Ogmios (if enabled): ws://localhost:1337
Kupo (if enabled): http://localhost:1442 (opens in a new tab)

CLI Commands Reference

Once in interactive mode, you can use all standard Yaci CLI commands:

# Check devnet status
devnet:default> info
 
# Fund addresses
devnet:default> topup <address> <amount>
 
# Check UTXOs
devnet:default> utxos <address>
 
# Reset devnet
devnet:default> reset
 
# Stop devnet
devnet:default> stop

For a complete list, see Yaci CLI Commands.

Troubleshooting

Ensure Backend is Running

Before starting Yaci Viewer, make sure your devnet is running with Yaci Store:

yaci-devkit up --enable-yaci-store

Port Conflicts

If you encounter port conflicts, use custom ports:

yaci-devkit up --port 3002 --enable-yaci-store

If a cardano-node (for example a mainnet node) already runs on this machine, the devnet node cannot open its Prometheus port (12798). Use another one:

yaci-devkit up --prometheus-port 12799 --enable-yaci-store
 
# or for every run
PROMETHEUS_PORT=12799 yaci-devkit up --enable-yaci-store

See Known Issues.

Next Steps

Learn all commands: Check out Yaci CLI Commands
CI/CD integration: Set up automated testing
Compare options: Consider Docker Setup for local development, or Homebrew Setup to install without Node.js

Zip Setup Homebrew Setup