# How Superfile Embeds Default Configurations in Its Binary Using Go's embed Package

> Learn how Superfile embeds default configurations in its binary using Go's embed package. Discover how to access themes, icons, and config files directly from the executable at startup.

- Repository: [Yorukot/superfile](https://github.com/yorukot/superfile)
- Tags: internals
- Published: 2026-07-28

---

**Superfile bundles its default themes, icons, and configuration files directly into the compiled executable using Go's `embed` package, exposing them through an `embed.FS` variable that is traversed at startup to populate global configuration structs.**

The open-source terminal file manager **yorukot/superfile** ships with sensible defaults out of the box. To ensure these defaults are available without external file dependencies, the project embeds all default configuration assets directly into the binary. This allows the application to run immediately on any system while still permitting user customization through external config files.

## Declaring the Embedded Filesystem in [`main/main.go`](https://github.com/yorukot/superfile/blob/main/main/main.go)

The embedding process starts in [`main/main.go`](https://github.com/yorukot/superfile/blob/main/main/main.go) with a `//go:embed` directive that instructs the Go compiler to package the entire `src/superfile_config/` directory into the resulting binary.

```go
//go:embed src/superfile_config/*
var content embed.FS

```

This `content` variable implements the `embed.FS` interface, providing a read-only virtual filesystem. The variable is passed into the application's core logic—typically via a `Run(content)` invocation—ensuring the embedded data is available throughout the application lifecycle without requiring physical files on disk.

## Loading and Hydrating Configuration at Runtime

Once the binary starts, [`src/internal/common/load_config.go`](https://github.com/yorukot/superfile/blob/main/src/internal/common/load_config.go) orchestrates the extraction and application of these defaults through the `LoadAllDefaultConfig` function.

### Traversing the Virtual Filesystem with `fs.WalkDir`

Inside `LoadAllDefaultConfig`, Superfile uses `fs.WalkDir` to iterate recursively over every file within the embedded `src/superfile_config` path:

```go
func LoadAllDefaultConfig(content embed.FS) error {
    return fs.WalkDir(content, "src/superfile_config", func(path string, d fs.DirEntry, err error) error {
        if err != nil {
            return err
        }
        if d.IsDir() {
            return nil
        }
        // Process individual files below...
        return nil
    })
}

```

### Writing Themes and Parsing Structured Data

The loader distinguishes between binary assets (like themes) and structured configuration files. For theme files, it invokes `WriteThemeFiles` to extract the embedded bytes and write them to the user's local configuration directory. For JSON or YAML configuration files, the code reads the file content via `content.ReadFile(path)` and unmarshals the data directly into Go structs defined in [`src/internal/common/default_config.go`](https://github.com/yorukot/superfile/blob/main/src/internal/common/default_config.go) and [`src/internal/common/config_type.go`](https://github.com/yorukot/superfile/blob/main/src/internal/common/config_type.go).

```go
data, err := content.ReadFile(path)
if err != nil {
    return err
}

// Route based on file extension or path
switch filepath.Ext(path) {
case ".yaml", ".yml":
    // Unmarshal into theme or config structs
case ".json":
    // Parse icon definitions or fixed variables
}

```

## Global Access and User Override Behavior

After initialization completes, the rest of the application references these values through global variables—such as `cfg`, `iconConfig`, and others—defined in [`src/internal/common/default_config.go`](https://github.com/yorukot/superfile/blob/main/src/internal/common/default_config.go). If a user creates custom configuration files in their `$XDG_CONFIG_HOME/superfile/` directory (or the platform-specific equivalent), Superfile merges these user settings on top of the embedded defaults. This guarantees that every setting retains a sensible fallback value even if the user only customizes a subset of options.

## Summary

- **[`main/main.go`](https://github.com/yorukot/superfile/blob/main/main/main.go)** uses a `//go:embed src/superfile_config/*` directive to pack the entire default configuration directory into the binary as an `embed.FS`.
- **[`src/internal/common/load_config.go`](https://github.com/yorukot/superfile/blob/main/src/internal/common/load_config.go)** implements `LoadAllDefaultConfig`, which accepts the `embed.FS` and walks the virtual tree using `fs.WalkDir`.
- **Theme extraction** is handled by `WriteThemeFiles`, which writes embedded assets to the user's local config path.
- **Structured defaults** are unmarshaled from JSON/YAML into global Go structs defined in [`default_config.go`](https://github.com/yorukot/superfile/blob/main/default_config.go) and [`config_type.go`](https://github.com/yorukot/superfile/blob/main/config_type.go).
- The architecture ensures zero-dependency portability while allowing user overrides via standard configuration directories.

## Frequently Asked Questions

### What Go version is required for embedding files?

Go 1.16 or later is required to use the `embed` package and `//go:embed` directives. Superfile leverages this feature to bundle its themes and default settings directly into the compiled executable.

### Can I modify the embedded default configurations?

You cannot modify the files baked into the binary itself. However, you can override any default by placing a file with the same relative path in your user configuration directory (`$XDG_CONFIG_HOME/superfile/`). Superfile prioritizes user files over embedded defaults during the merge process.

### Where are the source files that get embedded located?

The source files reside in the `src/superfile_config/` directory at the repository root. This directory contains subdirectories for themes, icon definitions, and fixed variables, all of which are captured by the embed directive in [`main/main.go`](https://github.com/yorukot/superfile/blob/main/main/main.go).

### Does embedding configuration files increase the binary size?

Yes, the final binary includes the raw byte size of all embedded files. This increases the distributable size but eliminates external runtime dependencies, ensuring Superfile works immediately on fresh systems without requiring separate configuration file installation.