Eve library

IDE Configuration Guide

Guide

Revision 1

On this page

This guide covers recommended IDE setup for developing on the Lilith platform, with focus on VS Code.

Overview#

The Lilith platform uses:

  • TypeScript with ESM modules
  • ESLint for linting
  • Prettier for formatting
  • EditorConfig for consistent editor settings

VS Code Setup#

Install these extensions for the best development experience:

Essential#

Extension ID Purpose
ESLint dbaeumer.vscode-eslint JavaScript/TypeScript linting
Prettier esbenp.prettier-vscode Code formatting
EditorConfig editorconfig.editorconfig Editor settings sync
TypeScript Built-in TypeScript support
Extension ID Purpose
GitLens eamodio.gitlens Git history and blame
Docker ms-azuretools.vscode-docker Docker integration
YAML redhat.vscode-yaml YAML support
OpenAPI Editor 42crunch.vscode-openapi API spec editing
Thunder Client rangav.vscode-thunder-client API testing
Jest Runner firsttris.vscode-jest-runner Run Jest tests
Playwright ms-playwright.playwright E2E test runner

Optional#

Extension ID Purpose
GitHub Copilot github.copilot AI assistance
Error Lens usernamehw.errorlens Inline error display
Todo Tree gruntfuggly.todo-tree TODO tracking
Import Cost wix.vscode-import-cost Bundle size display
Path Intellisense christian-kohler.path-intellisense Path autocomplete

Quick Install#

Copy and run in VS Code Command Palette (Ctrl+Shift+P → "Install Extensions"):

text
dbaeumer.vscode-eslint
esbenp.prettier-vscode
editorconfig.editorconfig
eamodio.gitlens
ms-azuretools.vscode-docker
redhat.vscode-yaml
42crunch.vscode-openapi

VS Code Settings#

Create or update .vscode/settings.json in the project root:

json
{
  // Editor settings
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": "explicit"
  },
  "editor.tabSize": 2,
  "editor.insertSpaces": true,
  "editor.rulers": [100],
  "editor.wordWrap": "off",

  // File settings
  "files.encoding": "utf8",
  "files.eol": "\n",
  "files.trimTrailingWhitespace": true,
  "files.insertFinalNewline": true,
  "files.exclude": {
    "**/node_modules": true,
    "**/dist": true,
    "**/coverage": true,
    "**/.nyc_output": true
  },

  // TypeScript settings
  "typescript.preferences.importModuleSpecifier": "relative",
  "typescript.suggest.autoImports": true,
  "typescript.updateImportsOnFileMove.enabled": "always",
  "typescript.preferences.quoteStyle": "single",

  // ESLint settings
  "eslint.enable": true,
  "eslint.validate": [
    "javascript",
    "javascriptreact",
    "typescript",
    "typescriptreact"
  ],
  "eslint.workingDirectories": [
    { "directory": "services/*", "changeProcessCWD": true }
  ],

  // Prettier settings
  "prettier.requireConfig": true,
  "prettier.singleQuote": true,
  "prettier.trailingComma": "none",

  // Language-specific formatters
  "[javascript]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  },
  "[typescript]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  },
  "[json]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  },
  "[yaml]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  },
  "[markdown]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode",
    "editor.wordWrap": "on"
  },

  // Search exclusions
  "search.exclude": {
    "**/node_modules": true,
    "**/dist": true,
    "**/coverage": true,
    "**/playwright-report": true,
    "**/test-results": true
  },

  // Terminal settings
  "terminal.integrated.defaultProfile.linux": "bash",
  "terminal.integrated.cwd": "${workspaceFolder}"
}

Debug Configurations#

Create .vscode/launch.json for debugging:

json
{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Debug Current Service",
      "type": "node",
      "request": "launch",
      "runtimeExecutable": "npm",
      "runtimeArgs": ["start"],
      "cwd": "${fileDirname}/..",
      "console": "integratedTerminal",
      "env": {
        "NODE_ENV": "development",
        "PORT": "8080"
      }
    },
    {
      "name": "Debug BFF Service",
      "type": "node",
      "request": "launch",
      "program": "${workspaceFolder}/services/bff/src/server.js",
      "cwd": "${workspaceFolder}/services/bff",
      "console": "integratedTerminal",
      "env": {
        "NODE_ENV": "development",
        "PORT": "3000"
      }
    },
    {
      "name": "Debug Auth Service",
      "type": "node",
      "request": "launch",
      "program": "${workspaceFolder}/services/auth/src/server.ts",
      "cwd": "${workspaceFolder}/services/auth",
      "runtimeArgs": ["--loader", "ts-node/esm"],
      "console": "integratedTerminal",
      "env": {
        "NODE_ENV": "development",
        "PORT": "3003"
      }
    },
    {
      "name": "Debug Jest Tests",
      "type": "node",
      "request": "launch",
      "runtimeExecutable": "npm",
      "runtimeArgs": ["test", "--", "--runInBand"],
      "cwd": "${fileDirname}/..",
      "console": "integratedTerminal"
    },
    {
      "name": "Debug Current Jest Test File",
      "type": "node",
      "request": "launch",
      "runtimeExecutable": "npm",
      "runtimeArgs": ["test", "--", "--runInBand", "${relativeFile}"],
      "cwd": "${fileDirname}/..",
      "console": "integratedTerminal"
    },
    {
      "name": "Debug Playwright Tests",
      "type": "node",
      "request": "launch",
      "program": "${workspaceFolder}/node_modules/.bin/playwright",
      "args": ["test", "--headed"],
      "cwd": "${workspaceFolder}",
      "console": "integratedTerminal"
    },
    {
      "name": "Attach to Running Service",
      "type": "node",
      "request": "attach",
      "port": 9229,
      "restart": true,
      "skipFiles": ["<node_internals>/**"]
    }
  ],
  "compounds": [
    {
      "name": "Debug Core Services",
      "configurations": ["Debug BFF Service", "Debug Auth Service"]
    }
  ]
}

Using Debug Configurations#

  1. Debug Current Service: Open any file in a service, then run this config
  2. Debug BFF/Auth: Start specific core services with debugging
  3. Debug Jest Tests: Run tests with debugger attached
  4. Attach to Running: Connect to a service started with --inspect

To start a service with debug port:

bash
node --inspect=9229 src/server.js

Tasks Configuration#

Create .vscode/tasks.json for common tasks:

json
{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "Install Dependencies",
      "type": "shell",
      "command": "npm install",
      "group": "build",
      "problemMatcher": []
    },
    {
      "label": "Lint",
      "type": "shell",
      "command": "npm run lint",
      "group": "build",
      "problemMatcher": ["$eslint-stylish"]
    },
    {
      "label": "Type Check",
      "type": "shell",
      "command": "npm run typecheck",
      "group": "build",
      "problemMatcher": ["$tsc"]
    },
    {
      "label": "Run Tests",
      "type": "shell",
      "command": "npm test",
      "group": "test",
      "problemMatcher": []
    },
    {
      "label": "Start Docker Stack",
      "type": "shell",
      "command": "npm run deploy",
      "group": "build",
      "problemMatcher": []
    },
    {
      "label": "Stop Docker Stack",
      "type": "shell",
      "command": "npm run deploy:stop",
      "group": "build",
      "problemMatcher": []
    },
    {
      "label": "Health Check",
      "type": "shell",
      "command": "npm run health",
      "group": "test",
      "problemMatcher": []
    },
    {
      "label": "Current Service - Start",
      "type": "shell",
      "command": "npm start",
      "options": {
        "cwd": "${fileDirname}/.."
      },
      "group": "build",
      "problemMatcher": []
    },
    {
      "label": "Current Service - Test",
      "type": "shell",
      "command": "npm test",
      "options": {
        "cwd": "${fileDirname}/.."
      },
      "group": "test",
      "problemMatcher": []
    }
  ]
}

Running Tasks#

  • Ctrl+Shift+B → Select task to run
  • Ctrl+Shift+P → "Tasks: Run Task"

EditorConfig#

The project includes .editorconfig for consistent settings across editors:

ini
root = true

[*]
charset = utf-8
end_of_line = lf
insert_final_newline = true
trim_trailing_whitespace = true
indent_style = space
indent_size = 2

[*.{js,jsx,ts,tsx,json,yml,yaml}]
indent_size = 2

[*.md]
trim_trailing_whitespace = false

[*.sql]
indent_size = 4

[Dockerfile*]
indent_size = 4

[Makefile]
indent_style = tab

Most editors automatically respect these settings with the EditorConfig plugin.


Linting & Formatting Setup#

ESLint#

The project uses ESLint with these key rules:

Rule Setting Description
quotes 'single' Single quotes
indent 2 2-space indentation
no-console warn Avoid console.log
prefer-const error Use const when possible
no-var error No var declarations
eqeqeq error Strict equality

Prettier#

Prettier configuration (.prettierrc):

json
{
  "semi": true,
  "trailingComma": "none",
  "singleQuote": true,
  "printWidth": 100,
  "tabWidth": 2,
  "arrowParens": "avoid",
  "endOfLine": "lf"
}

Format on Save#

With the recommended settings, files auto-format on save:

  1. Prettier formats the code
  2. ESLint auto-fixes issues
  3. EditorConfig ensures consistent line endings

Workspace Setup#

For monorepo development, create lilith.code-workspace:

json
{
  "folders": [
    { "path": ".", "name": "Root" },
    { "path": "services/bff", "name": "BFF" },
    { "path": "services/auth", "name": "Auth" },
    { "path": "services/conversation", "name": "Conversation" },
    { "path": "services/content", "name": "Content" },
    { "path": "services/ai", "name": "AI" },
    { "path": "sdk/typescript", "name": "SDK" },
    { "path": "docs", "name": "Docs" }
  ],
  "settings": {
    "files.exclude": {
      "**/node_modules": true,
      "**/dist": true
    }
  }
}

Open with: File → Open Workspace from File


Keyboard Shortcuts#

Recommended custom shortcuts (add to keybindings.json):

json
[
  {
    "key": "ctrl+shift+t",
    "command": "workbench.action.tasks.runTask",
    "args": "Run Tests"
  },
  {
    "key": "ctrl+shift+l",
    "command": "workbench.action.tasks.runTask",
    "args": "Lint"
  },
  {
    "key": "ctrl+shift+d",
    "command": "workbench.action.tasks.runTask",
    "args": "Start Docker Stack"
  }
]

Other IDEs#

JetBrains (WebStorm, IntelliJ)#

  1. Install TypeScript, ESLint, Prettier plugins
  2. Settings → Languages → TypeScript → Enable ESLint
  3. Settings → Tools → File Watchers → Add Prettier
  4. EditorConfig is supported natively

Vim/Neovim#

lua
-- Install via plugin manager
-- coc.nvim for TypeScript
-- ALE or null-ls for linting
-- vim-prettier for formatting

Sublime Text#

  1. Install Package Control
  2. Install: LSP, LSP-typescript, SublimeLinter-eslint
  3. Configure EditorConfig package

Troubleshooting#

ESLint Not Working#

bash
# Verify ESLint is installed
npm ls eslint

# Run ESLint manually
npm run lint

# Check VS Code output
View → Output → ESLint

Prettier Not Formatting#

  1. Check .prettierrc exists in root
  2. Verify Prettier extension is enabled
  3. Check "Default Formatter" setting
  4. Try Format Document manually: Shift+Alt+F

TypeScript Errors Not Showing#

  1. Restart TypeScript server: Ctrl+Shift+P → "TypeScript: Restart TS Server"
  2. Check tsconfig.json is valid
  3. Ensure dependencies are installed

Slow Performance#

  1. Exclude node_modules from watch
  2. Disable unnecessary extensions
  3. Increase TypeScript memory: "typescript.tsserver.maxTsServerMemory": 4096