ZED IDE Setup for OBP-API Development

September 2, 2025 · View on GitHub

Complete ZED IDE integration for the Open Bank Project API

This folder contains everything needed to set up ZED IDE with full Scala language server support, automated build tasks, and streamlined development workflows for OBP-API.

🚀 Quick Setup (5 minutes)

Prerequisites

Java 17+ (OpenJDK recommended)
Maven 3.6+
ZED IDE (latest version)

Single Setup Script

cd OBP-API
./zed/setup-zed-ide.sh

This unified script automatically:

✅ Installs missing dependencies (Coursier, Bloop)
✅ Compiles the project and resolves dependencies
✅ Generates dynamic Bloop configurations
✅ Sets up Metals language server
✅ Copies ZED configuration files to .zed/ folder
✅ Configures build and run tasks
✅ Sets up manual-only code formatting

📁 What's Included

zed/
├── README.md                   # This comprehensive guide
├── setup-zed-ide.sh           # Single unified setup script
├── generate-bloop-config.sh    # Dynamic Bloop config generator
├── settings.json               # ZED IDE settings template
├── tasks.json                  # Pre-configured build/run tasks
├── .metals-config.json         # Metals language server config
└── setup-zed.bat              # Windows setup script

⌨️ Essential Keyboard Shortcuts

Action	Linux	macOS/Windows	Purpose
Command Palette	`Ctrl+Shift+P`	`Cmd+Shift+P`	Access all tasks
Go to Definition	`F12`	`F12`	Navigate to symbol definition
Find References	`Shift+F12`	`Shift+F12`	Find all symbol usages
Quick Open File	`Ctrl+P`	`Cmd+P`	Fast file navigation
Format Code	`Ctrl+Shift+I`	`Cmd+Shift+I`	Auto-format Scala code
Symbol Search	`Ctrl+T`	`Cmd+T`	Search symbols project-wide

🛠️ Available Development Tasks

Access via Command Palette (Ctrl+Shift+P on Linux, Cmd+Shift+P on macOS/Windows) → "task: spawn" (Linux) or "Tasks: Spawn" (macOS/Windows):

Core Development Tasks

Task	Purpose	Duration	When to Use
Quick Build Dependencies	Build only dependencies	1-3 min	First step, after dependency changes
[1] Run OBP-API Server	Start development server	3-5 min	Daily development
🔨 Build OBP-API	Full project build	2-5 min	After code changes
Run Tests	Execute test suite	5-15 min	Before commits
[3] Compile Only	Quick syntax check	30s-1 min	During development

Utility Tasks

Task	Purpose
[4] Clean Target Folders	Remove build artifacts
🔄 Continuous Compile (Scala)	Auto-recompile on changes
[2] Test API Root Endpoint	Verify server status
🔧 Kill Server on Port 8080	Stop stuck processes
🔍 Check Dependencies	Verify Maven dependencies

🏗️ Development Workflow

Daily Development

Start Development Session
- Linux: Ctrl+Shift+P → "task: spawn" → "Quick Build Dependencies"
- macOS: Cmd+Shift+P → "Tasks: Spawn" → "Quick Build Dependencies"
Start API Server
- Use task "[1] Run OBP-API Server"
- Server runs on: http://localhost:8080
- Test endpoint: http://localhost:8080/obp/v5.1.0/root
Code Development
- Edit Scala files in obp-api/src/main/scala/
- Use F12 for Go to Definition
- Auto-completion with Ctrl+Space
- Real-time error highlighting
- Format code with Ctrl+Shift+I
Testing & Validation
- Quick compile: "[3] Compile Only" task
- Run tests: "Run Tests" task
- API testing: "[2] Test API Root Endpoint" task

🔧 Configuration Details

ZED IDE Settings (`settings.json`)

Format on Save: DISABLED (manual formatting only - use Ctrl+Shift+I)
Scala LSP: Optimized Metals configuration
Maven Integration: Proper MAVEN_OPTS for Java 17+
UI Preferences: One Dark theme, consistent layout
Inlay Hints: Enabled for better code understanding

Build Tasks (`tasks.json`)

All tasks include proper environment variables:

MAVEN_OPTS="-Xss128m --add-opens=java.base/java.util.jar=ALL-UNNAMED --add-opens=java.base/java.lang=ALL-UNNAMED --add-opens=java.base/java.lang.reflect=ALL-UNNAMED"

Metals LSP (`.metals-config.json`)

Build Tool: Maven
Bloop Integration: Dynamic configuration generation
Scala Version: 2.12.20
Java Target: Java 11 (compatible with Java 17)

🚨 Troubleshooting

Common Issues

Problem	Symptom	Solution
Language Server Not Working	No go-to-definition, no autocomplete	Restart ZED, wait for Metals initialization
Compilation Errors	Red squiggly lines, build failures	Check Problems panel, run "Clean Target Folders"
Server Won't Start	Port 8080 busy	Run "Kill Server on Port 8080" task
Out of Memory	Build fails with heap space error	Already configured in tasks
Missing Dependencies	Import errors	Run "Check Dependencies" task

Recovery Procedures

Full Reset:

./zed/setup-zed-ide.sh  # Re-run complete setup

Regenerate Bloop Configurations:

./zed/generate-bloop-config.sh  # Regenerate configs

Clean Restart:
- Clean build with "Clean Target Folders" task
- Restart ZED IDE
- Wait for Metals to reinitialize (2-3 minutes)

Platform-Specific Notes

Linux Users

Use "task: spawn" in command palette (not "Tasks: Spawn")
Ensure proper Java permissions for Maven

macOS/Windows Users

Use "Tasks: Spawn" in command palette
Windows users can also use setup-zed.bat

🌐 API Development

Project Structure

OBP-API/
├── obp-api/                    # Main API application
│   └── src/main/scala/         # Scala source code
│       └── code/api/           # API endpoint definitions
│           ├── v5_1_0/         # Latest API version
│           ├── v4_0_0/         # Previous versions
│           └── util/           # Utility functions
├── obp-commons/                # Shared utilities and models
│   └── src/main/scala/         # Common Scala code
└── .zed/                       # ZED IDE configuration (generated)

Adding New API Endpoints

Navigate to obp-api/src/main/scala/code/api/v5_1_0/
Find appropriate API trait (e.g., OBPAPI5_1_0.scala)
Follow existing endpoint patterns
Use F12 to navigate to helper functions
Test with API test task

Testing Endpoints

# Root API information
curl http://localhost:8080/obp/v5.1.0/root

# Health check
curl http://localhost:8080/obp/v5.1.0/config

# Banks list (requires proper setup)
curl http://localhost:8080/obp/v5.1.0/banks

🎯 Pro Tips

Quick file access: Ctrl+P then type filename
Symbol search: Ctrl+T then type function/class name
Project-wide text search: Ctrl+Shift+F

Efficiency Shortcuts

Ctrl+/ - Toggle line comment
Ctrl+D - Select next occurrence
Ctrl+Shift+L - Select all occurrences
F2 - Rename symbol
Alt+←/→ - Navigate back/forward

Performance Optimization

Close unused files to reduce memory usage
Use "Continuous Compile" for faster feedback
Limit test runs to specific modules during development

📚 Additional Resources

Documentation

OBP-API Project: https://github.com/OpenBankProject/OBP-API
API Documentation: https://apiexplorer.openbankproject.com
Community Forums: https://openbankproject.com

Learning Resources

Scala: https://docs.scala-lang.org/
Lift Framework: https://liftweb.net/
Maven: https://maven.apache.org/guides/
ZED IDE: https://zed.dev/docs

🆘 Getting Help

Diagnostic Commands

# Check Java version
java -version

# Check Maven
mvn -version

# Check Bloop status
bloop projects

# Test compilation
bloop compile obp-commons obp-api

# Check ZED configuration
ls -la .zed/

Common Error Messages

Error	Cause	Solution
"Java module system" errors	Java 17+ module restrictions	Already handled in MAVEN_OPTS
"Port 8080 already in use"	Previous server still running	Use "Kill Server" task
"Metals not responding"	Language server crashed	Restart ZED IDE
"Compilation failed"	Dependency issues	Run "Check Dependencies"

🎉 Getting Started Checklist

Welcome to productive OBP-API development with ZED IDE! 🚀

This setup provides a complete, optimized development environment for the Open Bank Project API using ZED IDE with full Scala language server support.