Claude Code Rules for Navios Repository

Package Manager & Task Runner

Use
yarn
instead of
```
npm
```
for all package management commands
Use
nx
for running most commands (build, test, lint, etc.)
- Example:
```
yarn nx run @navios/core:build
```
  ,
```
yarn nx test @navios/core
```

File Conventions

Use .mts
extension for all TypeScript files (ES module syntax)
Unit tests: *.spec.mts
Type tests: *.spec-d.mts

Code Style

No semicolons
Single quotes
Follow Prettier config
Run
```
yarn nx lint <project>
```
after making changes

DI System Testing Rules

Test File Structure

import { asyncInject, Container, inject, Injectable } from '@navios/di'

import { afterEach, beforeEach, describe, expect, it } from 'vitest'

describe('MyService', () => {
  let container: Container

  beforeEach(() => {
    container = new Container()
  })

  afterEach(async () => {
    await container.dispose()
  })

  it('should do something', async () => {
    @Injectable()
    class TestService {
      // ...
    }

    const service = await container.get(TestService)
    expect(service).toBeDefined()
  })
})

Key Patterns

Always create a fresh
Container
in
```
beforeEach
```
Always call container.dispose()
in
```
afterEach
```
Use custom
Registry
when isolating test services
Define @Injectable()
classes inside test blocks (not at module level) to avoid cross-test pollution
Use inject()
for synchronous property injection
Use asyncInject()
for async property injection
Test scope boundaries explicitly:
- Singleton: same instance (
```
expect(inst1).toBe(inst2)
```
  )
- Transient: different instances (
```
expect(inst1).not.toBe(inst2)
```
  )
Test lifecycle hooks (
```
onServiceInit
```
,
```
onServiceDestroy
```
) explicitly

Mocking Dependencies with TestContainer

import { InjectionToken } from '@navios/di'
import { TestContainer } from '@navios/di/testing'

const container = new TestContainer()

// Bind value
const TOKEN = InjectionToken.create<string>('token')
container.bind(TOKEN).toValue('mock-value')

// Bind class
container.bind(SomeToken).toClass(MockClass)

// Clear between tests
await container.clear()

Injection Patterns

@Injectable()
class MyService {
  // Synchronous injection - service must already be initialized
  private readonly userService = inject(UserService)

  // Async injection - can wait for initialization (useful for circular dependencies)
  private readonly apiService = asyncInject(ApiService)

  // Optional injection - returns null if service fails
  private readonly optionalService = optional(OptionalService)
}

DI System Testing Rules

import { asyncInject, Container, inject, Injectable } from '@navios/di'

import { afterEach, beforeEach, describe, expect, it } from 'vitest'

describe('MyService', () => {
  let container: Container

  beforeEach(() => {
    container = new Container()
  })

  afterEach(async () => {
    await container.dispose()
  })

  it('should do something', async () => {
    @Injectable()
    class TestService {
      // ...
    }

    const service = await container.get(TestService)
    expect(service).toBeDefined()
  })
})

Always create a fresh
Container
in

beforeEach

Always call container.dispose()
in

afterEach

Use custom
Registry
when isolating test services

Define @Injectable()
classes inside test blocks (not at module level) to avoid cross-test pollution

Use inject()
for synchronous property injection

Use asyncInject()
for async property injection

Test scope boundaries explicitly:

Singleton: same instance (
```
expect(inst1).toBe(inst2)
```
)
Transient: different instances (
```
expect(inst1).not.toBe(inst2)
```
)

Test lifecycle hooks (

onServiceInit

onServiceDestroy

) explicitly

import { InjectionToken } from '@navios/di'
import { TestContainer } from '@navios/di/testing'

const container = new TestContainer()

// Bind value
const TOKEN = InjectionToken.create<string>('token')
container.bind(TOKEN).toValue('mock-value')

// Bind class
container.bind(SomeToken).toClass(MockClass)

// Clear between tests
await container.clear()

@Injectable()
class MyService {
  // Synchronous injection - service must already be initialized
  private readonly userService = inject(UserService)

  // Async injection - can wait for initialization (useful for circular dependencies)
  private readonly apiService = asyncInject(ApiService)

  // Optional injection - returns null if service fails
  private readonly optionalService = optional(OptionalService)
}

Claude Code Rules for Navios Repository

Claude Code Rules for Navios Repository

Package Manager & Task Runner

File Conventions

Code Style

DI System Testing Rules

Test File Structure

Key Patterns

Mocking Dependencies with TestContainer

Injection Patterns

Related Skills

Nano Banana Pro

Markdown Converter

1password

Claude Code Rules for Navios Repository

Package Manager & Task Runner

File Conventions

Code Style

DI System Testing Rules

Test File Structure

Key Patterns

Mocking Dependencies with TestContainer

Injection Patterns