App Setup Guide

Step-by-step guide to configure your app for local development with @easy/dev-kit.

Prerequisites

Before starting, ensure:

Docker infrastructure is running (./docker/scripts/start-local.sh)
Node.js 18+ is installed
Your app has a Vite-based frontend

Setup Steps

Step 1: Install Dev Kit

Add @easy/dev-kit as a dev dependency in your frontend package:

cd web/packages/your-app
pnpm add -D @easy/dev-kit

Step 2: Create Configuration File

Create devkit.config.ts in your app's root directory (not the frontend package):

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

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

  backend: {
    type: 'go',  // or 'node'
    port: 9000,
    // Add your backend configuration
  },

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

Step 3: Configure Vite Plugin

Update your vite.config.ts to include the CSS bundle plugin:

import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import { devCssBundle } from '@easy/dev-kit/vite-plugin'

export default defineConfig({
  plugins: [
    vue(),
    devCssBundle(),  // Add this
  ],

  // REQUIRED: Server configuration for Docker access
  server: {
    host: '0.0.0.0',
    allowedHosts: ['host.docker.internal'],
  },
})

Step 4: Start Development

From your app's root directory:

easy-dev start

Or via pnpm:

pnpm easy-dev start

Complete Examples

Go Backend App (de.easy-m.statistics)

Directory Structure:

de.easy-m.statistics/
├── devkit.config.ts          # Dev kit config
├── cmd/
│   └── app/
│       └── main.go           # Go entry point
└── web/
    └── packages/
        └── statistic-app/
            ├── package.json  # Has @easy/dev-kit
            ├── vite.config.ts
            └── src/

devkit.config.ts:

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: '.',
    skipHealthCheck: false,
    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,
  },
})

vite.config.ts:

import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import VueI18nPlugin from '@intlify/unplugin-vue-i18n/vite'
import { devCssBundle } from '@easy/dev-kit/vite-plugin'
import { fileURLToPath, URL } from 'node:url'
import { resolve } from 'path'

export default defineConfig({
  plugins: [
    vue({
      template: {
        compilerOptions: {
          isCustomElement: (tag) => tag !== 'ez-icon' && tag.startsWith('ez-'),
        },
      },
    }),
    VueI18nPlugin({ include: resolve(__dirname, './src/locales/**') }),
    devCssBundle(),
  ],

  server: {
    host: '0.0.0.0',
    allowedHosts: ['host.docker.internal'],
  },

  resolve: {
    alias: {
      '@': fileURLToPath(new URL('./src', import.meta.url)),
    },
  },
})

Node.js Frontend-Only App (de.easy-m.tagmanagement)

Directory Structure:

de.easy-m.tagmanagement/
├── devkit.config.ts
├── package.json
└── web/
    └── packages/
        └── tagmanagement-app/
            ├── package.json
            ├── vite.config.ts
            └── src/

devkit.config.ts:

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 to check
    env: {
      APP_ENV: 'development',
    },
  },

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

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

vite.config.ts:

import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import VueI18nPlugin from '@intlify/unplugin-vue-i18n/vite'
import { devCssBundle } from '@easy/dev-kit/vite-plugin'
import { resolve } from 'path'

export default defineConfig({
  plugins: [
    vue(),
    VueI18nPlugin({ include: resolve(__dirname, './src/locales/**') }),
    devCssBundle(),
  ],

  server: {
    host: '0.0.0.0',
    allowedHosts: ['host.docker.internal'],
    port: 5173,
    cors: true,
  },
})

Verification Checklist

After setup, verify everything works:

1. Start Development Environment

easy-dev start

Expected output:

✓ Configuration loaded from devkit.config.ts
✓ Infrastructure health check passed
✓ Authenticated with Kratos
✓ Backend running on port 1338
✓ App installed via GraphQL
✓ Frontend running on port 5173
✓ Shell container restarted with dev mode

Development environment is ready!

  Services:
    Shell:    http://localhost:3000 (Docker)
    Frontend: http://localhost:5173 (Vite HMR)
    Backend:  http://localhost:1338

2. Check CSS Loading

Open browser DevTools → Network tab:

/__dev_styles.css should return 200
CSS should contain your component styles

3. Check HMR

Open http://localhost:3000/admin/your-app.do
Edit a Vue component
Changes should apply without page refresh

4. Check Assets

Images should load correctly
No 404 errors in Network tab

Troubleshooting

"Configuration file not found"

Ensure devkit.config.ts exists in your app's root directory (where you run easy-dev start).

"Backend health check failed"

Check backend is starting correctly
Verify healthEndpoint matches your backend's health route
Use skipHealthCheck: true if no health endpoint exists

"CSS not loading"

Verify devCssBundle() is in your Vite plugins
Check server.host is '0.0.0.0'
Check server.allowedHosts includes 'host.docker.internal'

"Assets return 404"

The shell proxies /src/* requests to Vite. If assets still fail:

Verify Vite is running on the expected port
Check the asset path is correct
Rebuild shell if proxy route was recently added

"Vite blocked request from host.docker.internal"

Add to vite.config.ts:

server: {
  allowedHosts: ['host.docker.internal'],
}

Tips

Speed Up Restarts

Skip authentication if you have a valid session:

easy-dev start --skip-auth

Verbose Output

Debug issues with verbose mode:

easy-dev start -v

Check Service Status

easy-dev status

Next Steps

CLI Commands - Full CLI reference
Configuration - All configuration options
Vite Plugin - Plugin details

Prerequisites​

Setup Steps​

Step 1: Install Dev Kit​

Step 2: Create Configuration File​

Step 3: Configure Vite Plugin​

Step 4: Start Development​

Complete Examples​

Go Backend App (de.easy-m.statistics)​

Node.js Frontend-Only App (de.easy-m.tagmanagement)​

Verification Checklist​

1. Start Development Environment​

2. Check CSS Loading​

3. Check HMR​

4. Check Assets​

Troubleshooting​

"Configuration file not found"​

"Backend health check failed"​

"CSS not loading"​

"Assets return 404"​

"Vite blocked request from host.docker.internal"​

Tips​

Speed Up Restarts​

Verbose Output​

Check Service Status​

Next Steps​