$detect Markers

Opt-in auto-detection for configuration values.

Overview

$detect markers let Genbox automatically detect values from your project. This combines the convenience of auto-detection with the transparency of explicit configuration.


apps:
  web:
    path: ./web
    type: frontend            # Explicit - you know this
    port: $detect             # Auto-detect from package.json
    framework: $detect        # Auto-detect from dependencies

How It Works

At gb init: Scans project, creates .genbox/detected.yaml
At resolution: Replaces $detect with values from detected.yaml
At validation: Reports if detection fails

Detectable Fields

Field	Detection Source
`apps.*.type`	Dependencies in package.json
`apps.*.port`	Scripts in package.json, config files
`apps.*.framework`	Dependencies and config files
`apps.*.commands.install`	Package manager lockfile
`apps.*.commands.dev`	package.json scripts.dev
`apps.*.commands.build`	package.json scripts.build
`apps.*.commands.start`	package.json scripts.start
`project.structure`	Workspace files, directory structure

Detection Sources

Port Detection

Genbox looks for ports in:


// package.json scripts
"scripts": {
  "dev": "next dev --port 3000",      // --port flag
  "start": "PORT=3050 node server.js"  // PORT= prefix
}


// Framework configs
// next.config.js
module.exports = {
  serverRuntimeConfig: {
    port: 3000
  }
}
 
// vite.config.js
export default {
  server: {
    port: 5173
  }
}

Framework Detection

Detected from dependencies:

Package	Framework
`next`	Next.js
`nuxt`	Nuxt
`@angular/core`	Angular
`vue`	Vue
`@nestjs/core`	NestJS
`express`	Express
`fastify`	Fastify

Type Detection

Based on dependencies:

Indicator	Type
`react`, `vue`, `angular`	frontend
`@nestjs/core`, `express`	backend
`bull`, `agenda`	worker

Detection Output

After running gb init or gb scan:

.genbox/detected.yaml:


_meta:
  generated_at: 2024-12-24T10:30:00Z
  genbox_version: 4.0.0
 
apps:
  web:
    path: ./web
    type: frontend
    type_reason: has next dependency
    port: 3000
    port_source: next.js default
    framework: nextjs
    framework_source: next.config.js exists
 
  api:
    path: ./api
    type: backend
    type_reason: has @nestjs/core dependency
    port: 3050
    port_source: package.json scripts.dev "--port 3050"
    framework: nestjs
    framework_source: nest-cli.json exists

Using $detect

Basic Usage


apps:
  web:
    path: ./web
    type: frontend
    port: $detect              # Will become 3000
    framework: $detect         # Will become nextjs

Mixed Explicit and Detect


apps:
  api:
    path: ./api
    type: backend              # I know this
    port: 3050                 # I know this too
    framework: $detect         # Let Genbox figure this out
    commands:
      install: pnpm install    # Explicit
      dev: $detect             # Auto-detect
      build: $detect           # Auto-detect

Resolution Order

When resolving $detect:

CLI flags (highest priority)
Profile overrides
Explicit values in genbox.yaml
$detect → value from detected.yaml
Schema defaults (lowest priority)

Viewing Resolution

See where values come from:


gb config show --explain


apps.web.port: 3000
  ├─ CLI flag: (not set)
  ├─ Profile 'quick': (not set)
  ├─ genbox.yaml: $detect
  │   └─ detected.yaml: 3000
  │       └─ source: package.json scripts.dev "--port 3000"
  └─ schema default: (none)
  ✓ Final value: 3000

Detection Failures

If detection fails:


gb validate


$detect resolution:
  ✓ apps.web.port → 3000
  ✗ apps.admin.port: could not detect

    Tried: package.json scripts.dev (no --port flag found)

    Suggestions:
    • Add explicit value: port: 3001
    • Add --port flag to scripts.dev in admin/package.json

Fixing Failures

Option 1: Add explicit value


apps:
  admin:
    port: 3001               # Replace $detect with explicit

Option 2: Add detection hint


// package.json
"scripts": {
  "dev": "vite --port 3001"  // Now detectable
}

Refreshing Detection

Re-scan your project:


gb scan

This updates .genbox/detected.yaml with current values.

Best Practices

Use for convenience: $detect reduces boilerplate
Verify detected values: Run gb config show
Replace if wrong: Use explicit values if detection is incorrect
Commit genbox.yaml: But gitignore detected.yaml
Re-scan on changes: Run gb scan after project changes