Airframe Scala Development
Expert guidance for developing with the Airframe framework, a comprehensive library providing essential building blocks for Scala applications across JVM, Scala.js, and Scala Native platforms.
Tech Stack
**Primary Languages**: Scala, Scala.js, Scala Native**Scala Versions**: Prioritize Scala 2.13 syntax for broad compatibility. Scala 2.12 compatible syntax is also acceptable.**Scala 3**: Use Scala 3 specific syntax **only** within `src/{main,test}/scala3` directories.**Build Tool**: sbt (Scala Build Tool)**Testing Framework**: AirSpecProject Structure and Modules
This is a multi-module sbt project. Most modules are cross-built for JVM, JS, and Native platforms.
Platform-Specific Code Organization
**JVM**: `.jvm/src/main/scala`, `.jvm/src/test/scala`**JS**: `.js/src/main/scala`, `.js/src/test/scala`**Native**: `.native/src/main/scala`, `.native/src/test/scala`**Shared code**: Common to all platforms, resides in `src/main/scala` and `src/test/scala`Dependency Management
Core module `airframe-core` is designed for **minimal dependencies**. Avoid adding new library dependencies to `airframe-core` unless absolutely necessary.For other modules, carefully consider the impact of adding new dependencies.Check `libraryDependencies` in `build.sbt` for each module to understand its current dependencies.When adding a dependency:
Ensure it's available for all relevant platforms (JVM, JS, Native) if the module is cross-builtPrefer libraries already used in other modules if similar functionality is neededFor `airframe-core`, new dependencies are highly discouragedCoding Style
Formatting
Before committing changes, run `./sbt scalafmtAll` to properly format the Scala code according to project guidelines. This ensures consistent code style across the codebase.
For targeted formatting of specific modules:
```bash
./sbt "(moduleNameJVM)/scalafmtAll"
```
Replace `moduleNameJVM` with your target module.
Code Conventions
**Configuration case classes**: Should have `withXXX(...)` methods for all fields and `noXXX(...)` methods for all optional fields.**String interpolation**: Always enclose expressions with brackets `${...}` for consistency.**Error handling**: Returning `Try[A]` is generally discouraged as it forces a monadic style on the caller. Consider using plain exceptions for unrecoverable errors, or domain-specific error types.Testing with AirSpec
Running Tests
Use `./sbt` command to open sbt shell.
**Compile test code:**
JVM: `./sbt projectJVM/Test/compile`JS: `./sbt projectJS/Test/compile`Native: `./sbt projectNative/Test/compile`Replace `project` with the actual module name (e.g., `logJVM/Test/compile`).
**Run specific test class:**
```bash
./sbt '(moduleName)(JVM|JS|Native)/testOnly *TestClassName'
```
Examples:
JVM test in `airframe-log` module: `./sbt 'logJVM/testOnly *MyLogTest'`JS test in `airframe-codec` module: `./sbt 'codecJS/testOnly fully.qualified.TestClassName'`Test Writing Guidelines
Use **AirSpec** testing frameworkKey assertion syntaxes: `shouldBe`, `shouldNotBe`, `shouldMatch`Test names should be **concise and descriptive**, written in plain English**Avoid using mocks** as it increases maintenance costEnsure tests cover new functionality and bug fixes. Aim for good test coverageWhen a test fails, carefully analyze the stack trace and assertion failures from the sbt output. The output will indicate the exact line of failure.Git Workflow
Branch Naming
For creating a new feature branch:
```bash
git switch -c feature/$(date +"%Y%m%d_%H%M%S")-your-feature-description
```
The convention can be adapted for other types of changes:
`fix/$(date +"%Y%m%d_%H%M%S")-correct-off-by-one-error``doc/$(date +"%Y%m%d_%H%M%S")-update-readme``internal/$(date +"%Y%m%d_%H%M%S")-refactor-core`Commit Messages
Format: `type: description`
**Types:**
`feature:` — New features`fix:` — Bug fixes`internal:` — Non-user facing changes`doc:` — Documentation updates**Guidelines:**
Focus on the **why** of the change, not the what or howExample: `feature: Add XXX to improve user experience` is better than `feature: Add XXX class`Pull Requests
**Use gh command for GitHub operations.**
**Creating PRs:**
```bash
gh pr create
```
Provide a clear title and detailed bodyLink to any relevant issuesFollow `.github/pull_request_template.md` format for PR descriptions**Merging PRs:**
Prefer squashing commits via auto-merge to maintain a linear and clean history:
```bash
gh pr merge --squash --auto
```
Important Constraints
**Never** add dependencies to `airframe-core` without strong justification**Always** run `scalafmtAll` before committing**Always** ensure cross-platform compatibility when working on shared modules**Always** use Scala 2.13 syntax unless working in `scala3` directories**Never** use mocks in tests