Configuration

Complete reference for the devkit.config.ts configuration file.

Configuration File

Create a devkit.config.ts file in your app's root directory:

import { defineDevKitConfig } from '@easy/dev-kit/config'

export default defineDevKitConfig({
  // Your configuration here
})

The dev-kit automatically searches for configuration files in this order:

1. devkit.config.ts
2. devkit.config.js
3. devkit.config.mjs

It searches from the current directory and walks up parent directories until found.

Configuration Schema

interface DevKitConfig {
  // Required: App identifier (must match AppServer registration)
  appName: string

  // Required: Backend configuration
  backend: {
    type: 'go' | 'node'           // Backend language
    port: number                   // Port to listen on
    command?: string               // Custom start command
    cwd?: string                   // Working directory (default: '.')
    env?: Record<string, string>   // Environment variables
    healthEndpoint?: string        // Health check path (default: '/health')
    skipHealthCheck?: boolean      // Skip HTTP health check
  }

  // Required: Frontend configuration
  frontend: {
    path: string                   // Path relative to config file
    port: number                   // Vite dev server port
    command?: string               // Custom start command
  }

  // Optional: Shell configuration
  shell?: {
    path?: string                  // Path to shell package
    port?: number                  // Shell port (default: 3000)
    projectRoot?: string           // Project root for Docker
  }

  // Optional: Infrastructure URLs
  infrastructure?: {
    appServerUrl?: string          // Default: http://localhost:8080
    appServerGrpcUrl?: string      // Default: localhost:9091
    kratosPublicUrl?: string       // Default: http://localhost:4433
    kratosAdminUrl?: string        // Default: http://localhost:4434
    openfgaUrl?: string            // Default: http://localhost:8090
    openfgaStoreId?: string        // OpenFGA store ID
  }

  // Optional: Authentication credentials
  auth?: {
    email?: string                 // Default: cli@easy-m.de
    password?: string              // Default: cli-password
  }
}

Configuration Options

appName (required)

The application identifier. Must match the name used when registering the app with AppServer.

appName: 'de.easy-m.statistics'

backend (required)

Backend process configuration.

Option	Type	Default	Description
type	'go' | 'node'	-	Backend language (required)
port	number	-	Port to listen on (required)
command	string	auto	Custom start command
cwd	string	'.'	Working directory
env	object	{}	Environment variables
healthEndpoint	string	'/health'	Health check endpoint
skipHealthCheck	boolean	false	Skip health verification

Default commands by type:

• go: go run cmd/app/main.go
• node: node dist/index.js

frontend (required)

Frontend Vite configuration.

Option	Type	Default	Description
path	string	-	Path to frontend package (required)
port	number	-	Vite dev server port (required)
command	string	pnpm dev	Custom start command

shell (optional)

Shell configuration for Docker integration.

Option	Type	Default	Description
path	string	'web/v2/packages/shell'	Path to shell package
port	number	3000	Shell port
projectRoot	string	auto	Project root for Docker compose

infrastructure (optional)

Service URLs. All have sensible defaults for local development.

Option	Default	Environment Variable
appServerUrl	http://localhost:8080	APPSERVER_URL
appServerGrpcUrl	localhost:9091	APPSERVER_GRPC_URL
kratosPublicUrl	http://localhost:4433	KRATOS_PUBLIC_URL
kratosAdminUrl	http://localhost:4434	KRATOS_ADMIN_URL
openfgaUrl	http://localhost:8090	OPENFGA_URL
openfgaStoreId	''	OPENFGA_STORE_ID

auth (optional)

Authentication credentials for Kratos.

Option	Default	Environment Variable
email	cli@easy-m.de	CLI_EMAIL
password	cli-password	CLI_PASSWORD

Example Configurations

Go Backend App

import { defineDevKitConfig } from '@easy/dev-kit/config'

export default defineDevKitConfig({
  appName: 'de.easy-m.statistics',

  backend: {
    type: 'go',
    port: 1338,
    command: 'go run cmd/app/main.go',
    cwd: '.',
    healthEndpoint: '/health',
    env: {
      APP_ENV: 'development',
      APPSERVER_GRAPHQL_HTTP: 'http://localhost:8080/graphql',
      OTEL_ENABLED: 'false',
      DB_HOST: 'localhost',
      DB_PORT: '5432',
      DB_NAME: 'partner',
      DB_USER: 'partner',
      DB_PASSWORD: 'partner',
      DB_SSL_MODE: 'disable',
    },
  },

  frontend: {
    path: 'web/packages/statistic-app',
    port: 5173,
  },
})

Node.js Frontend-Only App

import { defineDevKitConfig } from '@easy/dev-kit/config'

export default defineDevKitConfig({
  appName: 'de.easy-m.tagmanagement',

  backend: {
    type: 'node',
    port: 9000,
    cwd: '.',
    skipHealthCheck: true,  // No backend server
    env: {
      APP_ENV: 'development',
    },
  },

  frontend: {
    path: 'web/packages/tagmanagement-app',
    port: 5173,
  },

  shell: {
    path: '../web/v2/packages/shell',
    port: 3000,
  },
})

Custom Infrastructure URLs

import { defineDevKitConfig } from '@easy/dev-kit/config'

export default defineDevKitConfig({
  appName: 'de.easy-m.myapp',

  backend: {
    type: 'node',
    port: 9000,
    skipHealthCheck: true,
  },

  frontend: {
    path: 'web/packages/myapp',
    port: 5173,
  },

  infrastructure: {
    appServerUrl: 'http://appserver.local:8080',
    kratosPublicUrl: 'http://kratos.local:4433',
  },

  auth: {
    email: 'developer@example.com',
    password: 'dev-password',
  },
})

Environment Variables

Configuration values can be overridden via environment variables:

# Infrastructure
export APPSERVER_URL=http://localhost:8080
export KRATOS_PUBLIC_URL=http://localhost:4433
export OPENFGA_URL=http://localhost:8090

# Authentication
export CLI_EMAIL=dev@example.com
export CLI_PASSWORD=mypassword

Next Steps

• CLI Commands - Use the configuration with CLI commands
• Vite Plugin - Configure the Vite plugin