Skip to main content

Dev Kit Overview

The @easy/dev-kit package provides tooling for local development of Easy.M applications with hot module replacement (HMR) support.

What is Dev Kit?​

Dev Kit is a CLI tool and Vite plugin that streamlines the local development workflow for Easy.M apps. It handles:

  • Process Management: Starts and manages backend, frontend, and shell processes
  • Authentication: Automatically authenticates with Kratos and grants OpenFGA permissions
  • App Registration: Registers your app with AppServer via GraphQL
  • HMR Support: Enables hot module replacement for frontend development
  • CSS Bundling: Solves cross-origin CSS loading issues in dev mode

Key Features​

CLI Tool (easy-dev)​

  • Start entire development environment with one command
  • Automatic health checks and service orchestration
  • Process lifecycle management with graceful shutdown
  • Status monitoring for all services

Vite Plugin (devCssBundle)​

  • Bundles CSS from all modules including Vue SFC styles
  • Serves CSS at predictable endpoint for cross-origin loading
  • Handles asset URL rewriting for embedded apps

Configuration System​

  • TypeScript configuration file (devkit.config.ts)
  • Support for Go and Node.js backends
  • Flexible environment variable injection
  • Sensible defaults with full customization

Prerequisites​

Before using Dev Kit, ensure you have:

  • Node.js 18+: Required runtime
  • Vite 5.0+: For frontend development (peer dependency)
  • Docker Infrastructure Running: The local Docker environment must be started first

Starting the Infrastructure​

Dev Kit requires the local Docker infrastructure to be running. This includes AppServer, Shell, Kratos, OpenFGA, PostgreSQL, and other services.

Start the infrastructure using:

# From the easy.appserver directory
./docker/scripts/start-local.sh

This script will:

  • Start all required Docker containers
  • Run database migrations
  • Set up OpenFGA authorization
  • Configure the Shell frontend

Wait for all services to be healthy before running easy-dev start.

Stop the Docker container for your app

If you want to develop an app locally (e.g., de.easy-m.statistics), you must stop its Docker container first so it can be replaced with your local dev instance:

docker stop local-statistics

This allows Dev Kit to register your local instance with AppServer instead of the containerized version.

See the Infrastructure documentation for more details.

Quick Start​

# 1. Install dev-kit
pnpm add -D @easy/dev-kit

# 2. Create devkit.config.ts (see Configuration)

# 3. Start development
easy-dev start

Architecture​

┌─────────────────────────────────────────────────────────────┐
│                    Development Environment                    │
│                                                               │
│  ┌──────────────┐    ┌──────────────┐    ┌──────────────┐   │
│  │    Shell     │◄───│   Browser    │───►│   Backend    │   │
│  │  (Docker)    │    │              │    │  (Local)     │   │
│  │  Port 3000   │    │              │    │  Port XXXX   │   │
│  └──────────────┘    └──────────────┘    └──────────────┘   │
│         │                   │                    │           │
│         │                   │                    │           │
│         ▼                   ▼                    ▼           │
│  ┌─────────────────────────────────────────────────────┐    │
│  │              Vite Dev Server (Port 5173)             │    │
│  │   • HMR for frontend code                           │    │
│  │   • CSS bundle at /__dev_styles.css                 │    │
│  │   • Asset serving with absolute URLs                │    │
│  └─────────────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────────────┘

Service URLs​

ServiceURLDescription
Shellhttp://localhost:3000Main entry point (Docker)
Frontendhttp://localhost:5173Vite dev server with HMR
Backendhttp://localhost:<port>Your app's backend API
CSS Bundlehttp://localhost:5173/__dev_styles.cssBundled CSS for dev mode

Next Steps​