flora

README

Flora

Compile-time, reflection-free Dependency Injection for Go.
Spring-like developer experience, but with zero runtime overhead and absolute type safety.

Why Flora?

Flora acts as a "Convention over Configuration" layer for Go. It parses your source code's Abstract Syntax Tree (AST) to discover components natively and generates a strongly-typed DI container using Google Wire under the hood.

• Zero Runtime Overhead: The generated code is exactly as fast as manually written Go code.
• No Reflection: Everything is evaluated at compile-time. If your code compiles, your dependency graph is 100% safe.
• Auto-Discovery: Just embed a marker interface. Flora reads the constructors and wires them automatically.
• Native Go Idioms: Full support for error returns and cleanup func() routines in your constructors.

---

Installation

Flora consists of a CLI tool (to generate the container) and a core library (for the markers).

# 1. Install the CLI tool globally
go install [github.com/soner3/flora/cmd/flora@latest](https://github.com/soner3/flora/cmd/flora@latest)

# 2. Add the library to your project
go get [github.com/soner3/flora@latest](https://github.com/soner3/flora@latest)

---

Quick Start

Instead of maintaining huge initialization scripts, you define dependencies declaratively right where they belong.

package main

import "[github.com/soner3/flora](https://github.com/soner3/flora)"

// 1. Mark your struct as a component
type Greeter struct {
    flora.Component
}

// 2. Provide a standard constructor
func NewGreeter() *Greeter {
    return &Greeter{}
}

func (g *Greeter) Greet() string { return "Hello from Flora!" }

type App struct {
    flora.Component
    greeter *Greeter
}

// Flora automatically discovers the *Greeter dependency and injects it.
func NewApp(g *Greeter) *App {
    return &App{greeter: g}
}

Generate the container by running the CLI in your project root:

flora gen -i . -o .

---

Core Concepts & Markers

Flora uses two primary markers to understand your architecture. Knowing when to use which is the key to building clean applications.

1. flora.Component (For your Domain Logic)

Use this for structs that you own and write yourself (e.g., Services, Handlers, Repositories). By embedding flora.Component, you tell Flora to manage this struct.

Default Behaviors:

• Constructor: Flora automatically looks for an exported function named New<StructName> (e.g., NewUserService).
• Scope: singleton (one instance per application).
• Interfaces: If the struct implements any interfaces, Flora binds them automatically.

2. flora.Configuration (For Third-Party & Adapters)

Use this when you cannot (or should not) modify the target struct. This is strictly meant for Third-Party Integrations (like *sql.DB, *redis.Client) or functional paradigms (like HTTP Middlewares).

Instead of embedding a marker into the target struct, you create a config struct and use Magic Comments (// flora:...) above its provider methods.

package config

import (
    "database/sql"
    "[github.com/soner3/flora](https://github.com/soner3/flora)"
)

type DatabaseConfig struct {
    flora.Configuration
}

// flora:primary
func (c *DatabaseConfig) ProvidePostgres() (*sql.DB, func(), error) {
    db, err := sql.Open("postgres", "...")
    
    // Flora handles the cleanup function automatically during graceful shutdown!
    cleanup := func() { db.Close() }
    
    return db, cleanup, err 
}

Documentation

Overview

Copyright © 2026 Soner Astan astansoner@gmail.com

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Index

• type Component
• type Configuration

Types

type Component

type Component struct{}

Component is a marker struct that is embedded in components. It allows Flora to auto-discover and wire the struct using tags.

type Configuration

type Configuration struct{}

Configuration is a marker struct that is embedded in configuration classes. Flora will scan all methods of a Configuration struct and register them as providers. Methods can be configured using magic comments (e.g., // flora:primary).