gokart new notes --db sqlite --example
cd notes
gokart add redis --dry-runEverything in notes belongs to you. The manifest only records which generated files are safe for gokart add to rewrite.
| Path | Owner | Generator behavior |
|---|---|---|
cmd/main.go |
You | Created once; never rewritten by add |
internal/actions/** |
You | Put business behavior here |
command files except root.go |
You | Put commands and flags here |
internal/app/context.go |
Shared rewrite boundary | add may re-render it |
internal/commands/root.go |
Shared rewrite boundary | add may re-render it |
internal/app/config.go |
You | Generated for global config (stdlib only); not rewritten by add |
go.mod, go.sum |
Go tooling and you | add runs go get and go mod tidy |
.gokart-manifest.json |
Generator metadata | Records hashes and integration state; detach deletes it |
README.md, .gitignore |
You | Generated starting points |
New command, action, service, and repository files are safe extension seams. If you customize context.go or root.go, finish adding integrations first or stop using gokart add.
Managed scaffolds record SHA-256 hashes. Before replacing the two wiring files, gokart add compares them with their recorded hashes. A matching file is safe to rewrite; a changed or untracked rewrite target is a conflict.
--dry-runpreviews changes.--forcediscards conflicting edits in rewrite targets; copy or commit your edits first.--no-manifestsuppresses the manifest and therefore prevents latergokart adduse.
gokart add supports managed structured projects only. It re-renders the two wiring files, fetches dependencies, tidies the module, and updates the manifest. It does not regenerate the project.
Plain and global scaffolds default to flat and never write a manifest. Start with
gokart new <name> --structured --global when you want global configuration
plus later generator-managed integration updates.
Generated code imports upstream packages directly (modernc.org/sqlite, pgxpool, go-redis, the OpenAI SDK, and the standard library) and has no github.com/dotcommander/gokart/* runtime import. The application does not call the generator at runtime.
To stop using the generator, finish the desired integrations and delete .gokart-manifest.json. For a project generated by an older release that still imports gokart/sqlite, gokart/postgres, gokart/cache, or the root gokart module, run gokart detach (--dry-run to preview). It re-renders internal/app/context.go, internal/commands/root.go, and internal/app/config.go to upstream-direct code when they still import GoKart, refuses to overwrite files edited since generation unless --force, runs go mod tidy to drop the GoKart requires, and deletes the manifest. Flat projects have nothing to detach.
There is no gokart remove. To remove an integration, delete its fields, imports, config keys, initialization, cleanup, and consumers; run go mod tidy; delete the now-inaccurate manifest; then run go test ./....
Freshly generated projects are already upstream-direct, so this table applies to older generated code and to GoKart packages you adopted by hand.
| GoKart surface | Direct replacement |
|---|---|
| generated Kong command structs | Kong directly; the generated application already uses typed commands, Context.Run binding, and kong.Context writers |
sqlite |
database/sql with modernc.org/sqlite; own pragmas and transaction cleanup |
postgres |
pgxpool.NewWithConfig and pgx.BeginFunc or an explicit transaction |
cache.Cache |
redis.NewClient or redis.ParseURL; apply prefixes locally |
| generated OpenAI client | openai.NewClient from github.com/openai/openai-go/v3 |
logger.New |
slog.New with a text or JSON handler |
web |
net/http, chi, encoding/json, and validator directly |
migrate |
goose.Provider from pressly/goose/v3 |
| config/state helpers | Viper or encoding/json, os.UserConfigDir, and atomic writes |
Replace one boundary at a time. The recipes show the public escape hatches.