X-Go Gen-code

Modify an Existing App

Gen-X is a regenerative system: every time you run the Depicter, it rewrites the files it owns from scratch. This means that custom code you add to a generated file will be overwritten on the next generation run — unless you explicitly mark the file as protected. The |@@| file header annotation is the mechanism that tells Gen-X which files to overwrite and which to leave untouched. Understanding this system is the foundation of all sustainable work in a Gen-X project.

Table of Contents

File headers

Every generated file begins with a |@@| annotation on its first line - under the package declaration. Gen-X reads this annotation before each generation run to decide whether the file should be overwritten.

  • // |@@| C (Legacy: // |@@| F)

    • Means the file will be regenerated when the depicter is ran (second terminal tab).
    • Means the file content have been generated

  • // |@@| W (Legacy: // |@@| O)

    • Means the file content has been modified
    • Means the file won’t be regenerated when depicter is ran
    • If the header isn’t W, all modifications will not remain after depicter is ran.

⚠️ Warning: If you modify a file and forget to update its header, all of your changes will be silently lost the next time the Depicter runs. There is no warning or diff — Gen-X simply overwrites the file. Always update the header before committing custom changes.

To protect a file, change its first line from the generated annotation to the write-protected annotation:

// Before (file will be overwritten by the Depicter):
// |@@| C

// After (file is protected from regeneration):
// |@@| W

Only the first line needs to change. All other file content remains exactly as-is.

After modifying Gen-X

Important: Gen-X generates itself; it means that file headers described in the above section will have the same behavior as in any other generated app.

  • Run tdd
  • Accept changes with Windows + X
  • Rerun tdd
  • Run ./bin/tests/check.sh
  • Open the URL and Accept the changes (Submit)
  • Commit and push

After modifying KitCla

📝 Note: KitCla is not an app generated by Gen-X. It is an independent stateless UI component library with its own release cycle and versioning scheme. The |@@| file header system does not apply to KitCla. After making changes to KitCla, follow KitCla’s own documentation and then update its version pin in Gen-X as described below.

  • Run ./bin/run-code-checks.sh
  • Commit & push
  • Tag new version ./bin/tag-version.sh (auto increment - supports flags --patch, --minor, --major)
  • Update kitcla’s dependency with new tag in Gen-X :
// go.mod
require (
	// ...
	gitlab.com/blue-lila/kitcla vX.X.X // <=== New Tag
	// ...
)

// src/srv/appliers/project-create-applier.go
func (this *ProjectCreateApplier) addDependencies(ctx context.Context, config *mdl.ProjectConfig) {
	// ....
    this.DependencyHandler.MustCreate(ctx, &mdl.Dependency{
      Name:      "gitlab.com/blue-lila/kitcla",
      Version:   "vX.X.X", // <=== New Tag
      ProjectId: config.ProjectId,
    }, nil)
}

Next Steps

Creating A New App
File Header Reference