feat: add background job queue system using River#261
Conversation
Add `lvt gen queue` and `lvt gen job <name>` commands that scaffold background job processing using River (https://riverqueue.com), the de facto Go job queue library with 4.8k stars. River handles all queue/worker internals: worker pool, retry with exponential backoff, scheduled jobs, dead letter queue, unique jobs, graceful shutdown, and supports both SQLite and PostgreSQL. Our code is purely the generation layer: - Kit templates for migration, worker init, and job handler scaffolds - Generator functions (GenerateQueue, GenerateJob) with main.go injection - CLI commands with help text Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
There was a problem hiding this comment.
Pull request overview
Adds first-class background job scaffolding to LiveTemplate via River, wiring new generation commands into the CLI and providing kit templates for queue schema/migrations, worker registration, and job handler scaffolds.
Changes:
- Add
lvt gen queueto generate River queue DB artifacts and attempt to inject worker startup into appmain.go. - Add
lvt gen job <name>to scaffold a River worker + args type and register it inapp/jobs/worker.go. - Add generator + tests plus CLI routing/help text for the new subcommands.
Reviewed changes
Copilot reviewed 12 out of 12 changed files in this pull request and generated 8 comments.
Show a summary per file
| File | Description |
|---|---|
| internal/kits/system/single/templates/jobs/worker_init.go.tmpl | Template for app/jobs/worker.go worker registry (single kit). |
| internal/kits/system/single/templates/jobs/schema.sql.tmpl | River schema appended into database/schema.sql (single kit). |
| internal/kits/system/single/templates/jobs/migration.sql.tmpl | Goose migration template for River tables (single kit). |
| internal/kits/system/single/templates/jobs/handler.go.tmpl | Scaffold for per-job River worker/args (single kit). |
| internal/kits/system/multi/templates/jobs/worker_init.go.tmpl | Template for app/jobs/worker.go worker registry (multi kit). |
| internal/kits/system/multi/templates/jobs/schema.sql.tmpl | River schema appended into database/schema.sql (multi kit). |
| internal/kits/system/multi/templates/jobs/migration.sql.tmpl | Goose migration template for River tables (multi kit). |
| internal/kits/system/multi/templates/jobs/handler.go.tmpl | Scaffold for per-job River worker/args (multi kit). |
| internal/generator/jobs.go | Implements GenerateQueue/GenerateJob + string-based main.go/worker registration injection. |
| internal/generator/jobs_test.go | Unit tests for queue/job generation behaviors. |
| commands/jobs.go | CLI entrypoints for lvt gen queue / lvt gen job. |
| commands/gen.go | Routes new queue/job subcommands and updates interactive help text. |
| riverSetup := []string{ | ||
| "", | ||
| "\t// Background job processing (River)", | ||
| "\triverDB, err := sql.Open(\"sqlite\", dbPath+\"?_pragma=journal_mode(WAL)\")", | ||
| "\tif err != nil {", | ||
| "\t\tslog.Error(\"Failed to open River database\", \"error\", err)", | ||
| "\t\tos.Exit(1)", | ||
| "\t}", | ||
| "\triverDB.SetMaxOpenConns(1)", | ||
| "\tdefer riverDB.Close()", | ||
| "", | ||
| "\tjobWorkers := jobs.SetupWorkers()", | ||
| "\triverClient, err := river.NewClient(riversqlite.New(riverDB), &river.Config{", | ||
| "\t\tQueues: map[string]river.QueueConfig{", | ||
| "\t\t\triver.QueueDefault: {MaxWorkers: 100},", | ||
| "\t\t},", | ||
| "\t\tWorkers: jobWorkers,", | ||
| "\t})", | ||
| "\tif err != nil {", | ||
| "\t\tslog.Error(\"Failed to create River client\", \"error\", err)", | ||
| "\t\tos.Exit(1)", | ||
| "\t}", | ||
| "\tif err := riverClient.Start(appCtx); err != nil {", | ||
| "\t\tslog.Error(\"Failed to start job workers\", \"error\", err)", | ||
| "\t\tos.Exit(1)", | ||
| "\t}", | ||
| "\tdefer riverClient.Stop(appCtx)", | ||
| "\t_ = riverClient // Available for enqueueing jobs in handlers", | ||
| } | ||
| result = append(result, riverSetup...) | ||
| injected = true | ||
| } | ||
| } | ||
|
|
||
| if !injected { | ||
| return fmt.Errorf("could not find injection point in main.go (expected 'defer database.CloseDB()')") | ||
| } | ||
|
|
||
| // Inject imports | ||
| resultStr := strings.Join(result, "\n") | ||
|
|
||
| // Add River imports | ||
| riverImports := fmt.Sprintf("\t\"%s/app/jobs\"\n", moduleName) + | ||
| "\t\"github.com/riverqueue/river\"\n" + | ||
| "\t\"github.com/riverqueue/river/riverdriver/riversqlite\"" | ||
|
|
||
| // Find the import block and add our imports | ||
| if idx := strings.Index(resultStr, "\"database/sql\""); idx != -1 { | ||
| // Insert after "database/sql" import | ||
| insertPos := idx + len("\"database/sql\"") | ||
| resultStr = resultStr[:insertPos] + "\n" + riverImports + resultStr[insertPos:] |
There was a problem hiding this comment.
injectJobWorker inserts River setup code that calls sql.Open(...), but the import injection only adds app/jobs, river, and riversqlite imports. Since the generated main.go templates don’t import database/sql, the injected code won’t compile unless database/sql is also added to the import block (or the code avoids using sql.Open).
| // Find injection point: after database.InitDB call, before route registrations | ||
| // Look for the database init line | ||
| lines := strings.Split(mainStr, "\n") | ||
| var result []string | ||
| injected := false | ||
|
|
||
| for _, line := range lines { | ||
| result = append(result, line) | ||
|
|
||
| // Inject after the database initialization block | ||
| // Look for the line that closes the database error check (the closing brace after InitDB) | ||
| if !injected && strings.Contains(line, "defer database.CloseDB()") { | ||
| // Insert River setup after this line | ||
| riverSetup := []string{ | ||
| "", | ||
| "\t// Background job processing (River)", | ||
| "\triverDB, err := sql.Open(\"sqlite\", dbPath+\"?_pragma=journal_mode(WAL)\")", | ||
| "\tif err != nil {", | ||
| "\t\tslog.Error(\"Failed to open River database\", \"error\", err)", | ||
| "\t\tos.Exit(1)", | ||
| "\t}", | ||
| "\triverDB.SetMaxOpenConns(1)", | ||
| "\tdefer riverDB.Close()", | ||
| "", | ||
| "\tjobWorkers := jobs.SetupWorkers()", | ||
| "\triverClient, err := river.NewClient(riversqlite.New(riverDB), &river.Config{", | ||
| "\t\tQueues: map[string]river.QueueConfig{", | ||
| "\t\t\triver.QueueDefault: {MaxWorkers: 100},", | ||
| "\t\t},", | ||
| "\t\tWorkers: jobWorkers,", | ||
| "\t})", | ||
| "\tif err != nil {", | ||
| "\t\tslog.Error(\"Failed to create River client\", \"error\", err)", | ||
| "\t\tos.Exit(1)", | ||
| "\t}", | ||
| "\tif err := riverClient.Start(appCtx); err != nil {", | ||
| "\t\tslog.Error(\"Failed to start job workers\", \"error\", err)", | ||
| "\t\tos.Exit(1)", | ||
| "\t}", | ||
| "\tdefer riverClient.Stop(appCtx)", | ||
| "\t_ = riverClient // Available for enqueueing jobs in handlers", | ||
| } | ||
| result = append(result, riverSetup...) | ||
| injected = true | ||
| } |
There was a problem hiding this comment.
The injected River setup references appCtx (riverClient.Start(appCtx) / Stop(appCtx)), but injectJobWorker injects immediately after defer database.CloseDB(). In the multi-kit main.go template, appCtx is created later (after route setup), and in the single-kit main.go template there is no appCtx at all. As a result, generated apps will not compile. The injection needs to either (a) inject after appCtx is created (and add an appCtx block for kits that don’t have one), or (b) use a locally-created context for River startup/shutdown.
| // 5. Inject River client setup into main.go | ||
| mainGoPath := findMainGo(projectRoot) | ||
| if mainGoPath != "" { | ||
| if err := injectJobWorker(mainGoPath, moduleName); err != nil { | ||
| return fmt.Errorf("failed to inject job worker into main.go: %w", err) | ||
| } | ||
| } |
There was a problem hiding this comment.
GenerateQueue’s main.go injection path isn’t exercised by these tests: setupTestProject doesn’t create a cmd/*/main.go, so findMainGo() returns "" and injectJobWorker() is skipped. This leaves the most fragile/critical part (string-based injection + import edits) untested; adding a test fixture main.go matching the kit templates would catch compile-breaking issues like missing imports / undefined identifiers.
| // Create lvt.yaml (project config) | ||
| lvtConfig := `kit: multi | ||
| module: testmodule | ||
| ` | ||
| if err := os.WriteFile(filepath.Join(dir, "lvt.yaml"), []byte(lvtConfig), 0644); err != nil { | ||
| t.Fatalf("Failed to create lvt.yaml: %v", err) |
There was a problem hiding this comment.
The test writes lvt.yaml as the "project config", but config.LoadProjectConfig reads .lvtrc (and returns defaults if it doesn’t exist). This means the tests aren’t actually validating config loading behavior (e.g., kit selection/module name), and could mask bugs. Update the fixture to write a .lvtrc file with kit= / module= entries (or adjust to whatever config format is actually used).
| // Create lvt.yaml (project config) | |
| lvtConfig := `kit: multi | |
| module: testmodule | |
| ` | |
| if err := os.WriteFile(filepath.Join(dir, "lvt.yaml"), []byte(lvtConfig), 0644); err != nil { | |
| t.Fatalf("Failed to create lvt.yaml: %v", err) | |
| // Create .lvtrc (project config) | |
| lvtConfig := `kit=multi | |
| module=testmodule | |
| ` | |
| if err := os.WriteFile(filepath.Join(dir, ".lvtrc"), []byte(lvtConfig), 0644); err != nil { | |
| t.Fatalf("Failed to create .lvtrc: %v", err) |
| ); | ||
|
|
||
| CREATE INDEX IF NOT EXISTS river_job_kind ON river_job (kind); | ||
| CREATE INDEX IF NOT EXISTS river_job_prioritized_fetching_index ON river_job (state, queue, priority, scheduled_at, id); |
There was a problem hiding this comment.
database/schema.sql is executed directly at app startup in the generated kits, so it should create the full River schema. This template is missing important indexes/constraints that are present in the generated migration (notably river_job_state_and_finalized_at_index and the partial unique index on unique_key/unique_states used for unique jobs). Consider keeping schema.sql.tmpl in sync with the migration’s Up DDL so River features/performance match expectations.
| CREATE INDEX IF NOT EXISTS river_job_prioritized_fetching_index ON river_job (state, queue, priority, scheduled_at, id); | |
| CREATE INDEX IF NOT EXISTS river_job_prioritized_fetching_index ON river_job (state, queue, priority, scheduled_at, id); | |
| CREATE INDEX IF NOT EXISTS river_job_state_and_finalized_at_index ON river_job (state, finalized_at); | |
| CREATE UNIQUE INDEX IF NOT EXISTS river_job_unique_key_and_unique_states_index ON river_job (unique_key, unique_states) WHERE unique_key IS NOT NULL AND unique_states IS NOT NULL; |
| ); | ||
|
|
||
| CREATE INDEX IF NOT EXISTS river_job_kind ON river_job (kind); | ||
| CREATE INDEX IF NOT EXISTS river_job_prioritized_fetching_index ON river_job (state, queue, priority, scheduled_at, id); |
There was a problem hiding this comment.
database/schema.sql is executed directly at app startup in the generated kits, so it should create the full River schema. This template is missing important indexes/constraints that are present in the generated migration (notably river_job_state_and_finalized_at_index and the partial unique index on unique_key/unique_states used for unique jobs). Consider keeping schema.sql.tmpl in sync with the migration’s Up DDL so River features/performance match expectations.
| CREATE INDEX IF NOT EXISTS river_job_prioritized_fetching_index ON river_job (state, queue, priority, scheduled_at, id); | |
| CREATE INDEX IF NOT EXISTS river_job_prioritized_fetching_index ON river_job (state, queue, priority, scheduled_at, id); | |
| CREATE INDEX IF NOT EXISTS river_job_state_and_finalized_at_index ON river_job (state, finalized_at); | |
| CREATE UNIQUE INDEX IF NOT EXISTS river_job_unique_key_unique_states_partial_idx ON river_job (unique_key, unique_states) WHERE unique_key IS NOT NULL; |
| fmt.Println(" app/jobs/worker.go Job worker registration") | ||
| fmt.Println(" database/migrations/..._river.sql River queue tables") |
There was a problem hiding this comment.
The “Generated files” output for the queue migration doesn’t match the filename pattern produced by GenerateQueue (which creates *_setup_river_queue.sql). Printing database/migrations/..._river.sql is misleading for users trying to locate the file; consider updating the message to reflect the actual naming convention.
| fmt.Println(" app/jobs/worker.go Job worker registration") | |
| fmt.Println(" database/migrations/..._river.sql River queue tables") | |
| fmt.Println(" app/jobs/worker.go Job worker registration") | |
| fmt.Println(" database/migrations/..._setup_river_queue.sql River queue tables") |
| // Convert snake_case to CamelCase for display | ||
| parts := strings.Split(jobName, "_") | ||
| for i, p := range parts { | ||
| if len(p) > 0 { | ||
| parts[i] = strings.ToUpper(p[:1]) + p[1:] | ||
| } | ||
| } | ||
| camelName := strings.Join(parts, "") | ||
| fmt.Printf(" riverClient.Insert(ctx, jobs.%sArgs{...}, nil)\n", camelName) | ||
|
|
||
| return nil |
There was a problem hiding this comment.
GenJob builds the displayed jobs.<Camel>Args name using a local snake_case→CamelCase conversion that doesn’t preserve Go initialisms (e.g. sync_api becomes SyncApiArgs here, but generator.toCamelCase would generate SyncAPIArgs). This can lead to incorrect/misleading CLI instructions compared to the generated type names. Consider reusing the same CamelCase helper as the generator (e.g., export a shared helper) to keep the output consistent.
| // Convert snake_case to CamelCase for display | |
| parts := strings.Split(jobName, "_") | |
| for i, p := range parts { | |
| if len(p) > 0 { | |
| parts[i] = strings.ToUpper(p[:1]) + p[1:] | |
| } | |
| } | |
| camelName := strings.Join(parts, "") | |
| fmt.Printf(" riverClient.Insert(ctx, jobs.%sArgs{...}, nil)\n", camelName) | |
| return nil | |
| // Convert snake_case to CamelCase for display, preserving Go initialisms | |
| camelName := snakeToCamelPreserveInitialisms(jobName) | |
| fmt.Printf(" riverClient.Insert(ctx, jobs.%sArgs{...}, nil)\n", camelName) | |
| return nil | |
| } | |
| // snakeToCamelPreserveInitialisms converts a snake_case identifier to CamelCase, | |
| // preserving common Go initialisms (e.g., "sync_api" -> "SyncAPI"). | |
| func snakeToCamelPreserveInitialisms(s string) string { | |
| if s == "" { | |
| return "" | |
| } | |
| parts := strings.Split(s, "_") | |
| for i, p := range parts { | |
| if p == "" { | |
| continue | |
| } | |
| upper := strings.ToUpper(p) | |
| switch upper { | |
| case "API", "ASCII", "CPU", "CSS", "DNS", "EOF", | |
| "GUID", "HTML", "HTTP", "HTTPS", "ID", "IP", | |
| "JSON", "LHS", "QPS", "RAM", "RHS", "RPC", | |
| "SLA", "SMTP", "SQL", "SSH", "TCP", "TLS", | |
| "TTL", "UDP", "UI", "UID", "UUID", "URI", | |
| "URL", "UTF8", "VM", "XML", "XMPP", "XSRF", "XSS": | |
| parts[i] = upper | |
| default: | |
| parts[i] = strings.ToUpper(p[:1]) + strings.ToLower(p[1:]) | |
| } | |
| } | |
| return strings.Join(parts, "") |
Code Review: feat: add background job queue system using RiverGreat feature addition! River is a solid choice for Go job queues. The generator pattern is clean and happy-path test coverage is good. Here are my observations: Bugs / Correctness Issues1. After all the River setup in 2. The injected code references 3. Import injection does not check for duplicates
4. Partial file left on disk if template execution fails in
5.
Architecture Concerns6. PostgreSQL apps get broken generated code The injection always hardcodes the SQLite driver and 7. Template duplication between All five files in Quality Issues8. Schema drift between migration and schema.sql templates
9. Migration version numbers are hardcoded When River releases v0.27+ and adds migration 7, generated migrations will be stale. Worth adding a comment warning, and pinning River to the specific version the templates target. 10. Two runs on the same day could pull different versions. Pin to 11. Inconsistent template delimiters
Test Coverage Gaps12.
13. No test for error paths (partial file cleanup in 14. No compilation test for generated code -- the handler template could have a syntax error that only surfaces at runtime. Minor
Summary: Two blockers: (1) |
- Move injection point from defer database.CloseDB() to after appCtx creation (appCtx must exist before River client Start/Stop) - Add missing "database/sql" import for sql.Open in injected code - Use existing injectImport() helper instead of manual import injection - Buffer template output in bytes.Buffer before writing files to prevent partial files on template execution failure - Export ToCamelCase for use by CLI commands (consistent initialism handling for display output) - Sync schema.sql.tmpl with full migration.sql.tmpl (was missing constraints and indexes) Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
- Fix riverClient.Stop using cancelled appCtx: now uses fresh background context with 30s timeout for graceful drain - Make riverClient accessible to handlers via jobs.SetClient/Client() so jobs can actually be enqueued from HTTP handlers - Fix CLI output: migration filename now matches actual generated name - Fix test config: use .lvtrc format (key=value) not lvt.yaml - Add TestInjectJobWorker: tests main.go injection with real fixture, verifying imports, River setup code, and idempotency Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
|
test |
|
placeholder to test approval |
|
module github.com/livetemplate/lvt go 1.26.0 require github.com/livetemplate/livetemplate v0.8.4 replace github.com/livetemplate/lvt/components => ./components require ( require ( |
|
test without repo flag |
|
0.1.0 |
Code Review: feat: add background job queue system using RiverSolid PR overall — the architecture is clean, test coverage is good, and following the generator pattern is the right call. A few issues worth addressing before merge: Bug: Wrong type parameter for river.Client The template declares var client but river.Client is generic over the transaction type. |
|
test simple |
LiveTemplate CLI Generator (
|
| AI Assistant | Installation | Best For |
|---|---|---|
| Claude Code | lvt install-agent --llm claude |
Full workflows with 20+ skills |
| GitHub Copilot | lvt install-agent --llm copilot |
In-editor suggestions |
| Cursor | lvt install-agent --llm cursor |
Rule-based development |
| Aider | lvt install-agent --llm aider |
CLI-driven development |
| Generic/Other | lvt install-agent --llm generic |
Custom LLMs via CLI |
Claude Code (Recommended)
Full-featured agent with skills and workflows:
# Install
lvt install-agent --llm claude
# Upgrade
lvt install-agent --upgrade
# Start Claude Code
claudeFeatures:
- 20+ skills for lvt commands
- Project management agent
- Guided workflows
- Best practices enforcement
Try asking:
- "Add a posts resource with title and content"
- "Generate authentication system"
- "Create a quickstart blog app"
GitHub Copilot
Instructions-based integration:
# Install
lvt install-agent --llm copilot
# Open in VS Code - Copilot automatically understands LiveTemplateCursor
Rule-based development patterns:
# Install
lvt install-agent --llm cursor
# Open project in Cursor - rules apply to *.go files automaticallyAider
CLI configuration:
# Install
lvt install-agent --llm aider
# Start Aider - configuration loads automatically
aiderUpgrading Agents
# Upgrade any agent type
lvt install-agent --llm <type> --upgradeThis preserves your custom settings while updating the agent files.
Complete Setup Guide
For detailed setup instructions for each AI assistant, see:
- docs/AGENT_SETUP.md - Complete setup guide for all AI assistants
- docs/WORKFLOWS.md - Common development workflows
- docs/AGENT_USAGE_GUIDE.md - Claude Code usage examples
Quick Start
You can use lvt in two modes: Interactive (TUI wizards) or Direct (CLI arguments).
Important: Create apps outside of existing Go module directories. If you create an app inside another Go module (e.g., for testing), you'll need to use GOWORK=off when running commands:
GOWORK=off go run cmd/myapp/main.goInteractive Mode (Recommended for New Users)
# Launch interactive app creator
lvt new
# Launch interactive resource builder
lvt gen
# Launch interactive view creator
lvt gen viewDirect Mode
1. Create a New App
lvt new myapp
cd myappThis generates:
- Complete Go project structure
- Database layer with sqlc integration
- go.mod with Go 1.24+ tools directive
- README with next steps
2. Generate a CRUD Resource
# With explicit types
lvt gen users name:string email:string age:int
# With inferred types (NEW!)
lvt gen products name price quantity enabled created_at
# → Infers: name:string price:float quantity:int enabled:bool created_at:timeThis generates:
app/users/users.go- Full CRUD handlerapp/users/users.tmpl- Tailwind CSS UIapp/users/users_ws_test.go- WebSocket testsapp/users/users_test.go- Chromedp E2E tests- Database schema and queries (appended)
3. Run Migrations
lvt migration up # Runs pending migrations and auto-generates database codeThis automatically:
- Applies pending database migrations
- Runs
sqlc generateto create Go database code - Updates your query interfaces
4. Wire Up Routes
Add to cmd/myapp/main.go:
import "myapp/app/users"
// In main():
http.Handle("/users", users.Handler(queries))5. Run the App
go run cmd/myapp/main.goOpen http://localhost:8080/users
Tutorial: Building a Blog System
Let's build a complete blog system with posts, comments, and categories to demonstrate lvt's capabilities.
Step 1: Create the Blog App
lvt new myblog
cd myblogThis creates your project structure with database setup, main.go, and configuration. Dependencies are automatically installed via go get ./....
Step 2: Generate Resources
lvt gen posts title content:string published:bool
lvt gen categories name description
lvt gen comments post_id:references:posts author textThis generates for each resource:
- ✅
app/{resource}/{resource}.go- CRUD handler with LiveTemplate integration - ✅
app/{resource}/{resource}.tmpl- Component-based template with Tailwind CSS - ✅
app/{resource}/{resource}_test.go- E2E tests with chromedp - ✅ Database migration file with unique timestamps
- ✅ SQL queries appended to
database/queries.sql
For the comments resource with post_id:references:posts:
- ✅ Creates
post_idfield as TEXT (matching posts.id type) - ✅ Adds foreign key constraint:
FOREIGN KEY (post_id) REFERENCES posts(id) ON DELETE CASCADE - ✅ Creates index on
post_idfor query performance - ✅ No manual migration needed!
Step 3: Run Migrations
lvt migration upThis command:
- ✅ Runs all pending database migrations
- ✅ Automatically generates Go database code with sqlc
- ✅ Creates type-safe query interfaces
You'll see output like:
Running pending migrations...
OK 20240315120000_create_posts.sql
OK 20240315120001_create_categories.sql
OK 20240315120002_create_comments.sql
Generating database code with sqlc...
✅ Database code generated successfully!
✅ Migrations complete!
Step 4: Resolve Dependencies
go mod tidyThis resolves all internal package imports created by the generated code. Required before running the app.
Step 5: Wire Up Routes
The routes are auto-injected, but verify in cmd/myblog/main.go:
import (
"myblog/app/posts"
"myblog/app/categories"
"myblog/app/comments"
)
func main() {
// ... database setup ...
// Routes (auto-injected)
http.Handle("/posts", posts.Handler(queries))
http.Handle("/categories", categories.Handler(queries))
http.Handle("/comments", comments.Handler(queries))
// Start server
http.ListenAndServe(":8080", nil)
}Step 6: Run the Blog
go run cmd/myblog/main.goVisit:
- http://localhost:8080/posts - Create and manage blog posts
- http://localhost:8080/categories - Organize posts by category
- http://localhost:8080/comments - View all comments
Note: Visiting http://localhost:8080/ will show a 404 since no root handler exists. You can add a homepage next.
Step 7: Add a Custom View for the Homepage (Optional)
lvt gen view home
go mod tidy
go run cmd/myblog/main.goThis creates a view-only handler (no database operations). Edit app/home/home.tmpl to create your landing page, then visit http://localhost:8080/home.
Step 8: Test the Application
# Run all tests (E2E + WebSocket)
go test ./...
# Run specific resource tests
go test ./app/posts -vCustomization Ideas
1. Generate resources (CSS framework determined by kit):
# Resources use the CSS framework from your chosen kit
# Multi and single kits use Tailwind CSS
# Simple kit uses no CSS framework (semantic HTML)
lvt gen tags name
# To use a different CSS framework, create your app with a different kit
lvt new myapp --kit simple # Uses no CSS (semantic HTML)
cd myapp
lvt gen authors name bio # Will use semantic HTML2. Use Type Inference:
# Field types are inferred from names
lvt gen articles title content published_at author email price
# Infers: title=string, content=string, published_at=time,
# author=string, email=string, price=float3. Create Custom Templates:
# Copy templates to customize
lvt template copy all
# Edit templates in .lvt/templates/
# Your customizations apply to all new resources4. Define Relationships with references:
# Basic reference (ON DELETE CASCADE - default)
lvt gen comments post_id:references:posts author text
# Custom ON DELETE behavior
lvt gen audit_logs user_id:references:users:set_null action:string
# Makes user_id nullable, sets NULL when user deleted
# Multiple references
lvt gen likes user_id:references:users post_id:references:posts
# Restrict deletion (prevent deleting parent if children exist)
lvt gen invoices customer_id:references:customers:restrict amount:float5. Add More Features:
# Tags for posts
lvt gen tags name color:string
# Post-tag relationship (many-to-many with references)
lvt gen post_tags post_id:references:posts tag_id:references:tags
# User accounts
lvt gen users username email password_hash:string
# Post reactions with proper relationships
lvt gen reactions post_id:references:posts user_id:references:users type:stringProject Structure
After completing the tutorial, your project looks like:
myblog/
├── cmd/myblog/main.go
├── internal/
│ ├── app/
│ │ ├── posts/
│ │ │ ├── posts.go
│ │ │ ├── posts.tmpl
│ │ │ ├── posts_test.go
│ │ │ └── posts_ws_test.go
│ │ ├── categories/
│ │ ├── comments/
│ │ └── home/
│ └── database/
│ ├── db.go
│ ├── migrations/
│ │ ├── 20240315120000_create_posts.sql
│ │ ├── 20240315120001_create_categories.sql
│ │ └── ...
│ ├── queries.sql
│ └── models/ # Generated by sqlc
│ ├── db.go
│ ├── models.go
│ └── queries.sql.go
└── go.mod
Next Steps
- Add Authentication - Integrate session management
- Rich Text Editor - Add markdown or WYSIWYG editor to post content
- Image Uploads - Add image upload functionality
- Search - Implement full-text search across posts
- RSS Feed - Generate RSS feed from posts
- Admin Dashboard - Create
lvt gen view admin - API Endpoints - Add JSON API alongside HTML views
Tips
- Start simple - Begin with core resources, add features incrementally
- Use migrations - Always use
lvt migration createfor schema changes - Test continuously - Run
go test ./...after each change - Customize templates - Copy and modify templates to match your design
- Component mode - Use
--mode singlefor SPA-style applications
Commands
lvt new <app-name>
Creates a new LiveTemplate application with:
myapp/
├── cmd/myapp/main.go # Application entry point
├── go.mod # With //go:tool directive
├── internal/
│ ├── app/ # Handlers and templates
│ ├── database/
│ │ ├── db.go # Connection & migrations
│ │ ├── schema.sql # Database schema
│ │ ├── queries.sql # SQL queries (sqlc)
│ │ ├── sqlc.yaml # sqlc configuration
│ │ └── models/ # Generated code
│ └── shared/ # Shared utilities
├── web/assets/ # Static assets
└── README.md
lvt gen <resource> <field:type>...
Generates a full CRUD resource with database integration.
Example:
lvt gen posts title:string content:string published:bool views:intGenerated Files:
- Handler with State struct, Change() method, Init() method
- Bulma CSS template with:
- Create form with validation
- List view with search, sort, pagination
- Delete functionality
- Real-time WebSocket updates
- WebSocket unit tests
- Chromedp E2E tests
- Database schema and queries
Features:
- ✅ CRUD operations (Create, Read, Update, Delete)
- ✅ Search across string fields
- ✅ Sorting by fields
- ✅ Pagination
- ✅ Real-time updates via WebSocket
- ✅ Form validation
- ✅ Statistics/counts
- ✅ Bulma CSS styling
- ✅ Comprehensive tests
- ✅ Auto-injected routes - Automatically adds route and import to
main.go
lvt gen view <name>
Generates a view-only handler without database integration (like the counter example).
Example:
lvt gen view dashboardGenerates:
app/dashboard/dashboard.go- View handler with state managementapp/dashboard/dashboard.tmpl- Bulma CSS templateapp/dashboard/dashboard_ws_test.go- WebSocket testsapp/dashboard/dashboard_test.go- Chromedp E2E tests
Features:
- ✅ State management
- ✅ Real-time updates via WebSocket
- ✅ Bulma CSS styling
- ✅ Comprehensive tests
- ✅ No database dependencies
- ✅ Auto-injected routes - Automatically adds route and import to
main.go
lvt gen auth
Generates a complete authentication system similar to Phoenix's mix phx.gen.auth.
Example:
# Generate with default settings (password + magic-link auth)
lvt gen auth
# Generate with only password authentication
lvt gen auth --no-magic-link
# Generate with only magic-link authentication
lvt gen auth --no-password
# Disable email confirmation
lvt gen auth --no-email-confirm
# Disable CSRF protection
lvt gen auth --no-csrfFlags:
--no-password- Disable password authentication--no-magic-link- Disable magic-link authentication--no-email-confirm- Disable email confirmation flow--no-password-reset- Disable password reset functionality--no-sessions-ui- Disable session management UI--no-csrf- Disable CSRF protection middleware
Note: At least one authentication method (password or magic-link) must be enabled.
Generates:
shared/password/password.go- Password hashing utilities (bcrypt)shared/email/email.go- Email sender interface with console loggerdatabase/migrations/YYYYMMDDHHMMSS_create_auth_tables.sql- Auth tables migration- Auth queries appended to
database/queries.sql
Features:
- ✅ Password authentication with bcrypt hashing
- ✅ Magic-link email authentication
- ✅ Email confirmation flow
- ✅ Password reset functionality
- ✅ Session management
- ✅ CSRF protection with gorilla/csrf
- ✅ Auto-updates
go.moddependencies - ✅ EmailSender interface (console logger + SMTP/Mailgun examples)
- ✅ Case-insensitive email matching
- ✅ Configurable features via flags
Database Tables:
users- User accounts with email and optional hashed passworduser_tokens- Tokens for magic links, email confirmation, password reset
Next Steps After Generation:
# 1. Run migrations
lvt migration up
# 2. Generate sqlc code
sqlc generate
# 3. Update main.go to register auth handler
# (Implementation in Phase 2)Router Auto-Update
When you generate a resource or view, lvt automatically:
-
Adds the import to your
cmd/*/main.go:import ( "yourapp/app/users" // ← Auto-added )
-
Injects the route after the TODO comment:
// TODO: Add routes here http.Handle("/users", users.Handler(queries)) // ← Auto-added
-
Maintains idempotency - Running the same command twice won't duplicate routes
This eliminates the manual step of wiring up routes, making the development workflow smoother. Routes are inserted in the order you generate them, right after the TODO marker.
Type Mappings
| CLI Type | Go Type | SQL Type |
|---|---|---|
| string | string | TEXT |
| int | int64 | INTEGER |
| bool | bool | BOOLEAN |
| float | float64 | REAL |
| time | time.Time | DATETIME |
Aliases:
str,text→stringinteger→intboolean→boolfloat64,decimal→floatdatetime,timestamp→time
Smart Type Inference (🆕 Phase 1)
The CLI includes an intelligent type inference system that automatically suggests types based on field names:
How It Works
When using the type inference system, you can omit explicit types and let the system infer them:
// In ui.InferType("email") → returns "string"
// In ui.InferType("age") → returns "int"
// In ui.InferType("price") → returns "float"
// In ui.InferType("enabled") → returns "bool"
// In ui.InferType("created_at") → returns "time"Inference Rules
String fields (default for unknown):
- Exact:
name,title,description,email,username,url,slug,address, etc. - Contains:
*email*,*url*
Integer fields:
- Exact:
age,count,quantity,views,likes,score,rank,year - Suffix:
*_count,*_number,*_index
Float fields:
- Exact:
price,amount,rating,latitude,longitude - Suffix/Contains:
*_price,*_amount,*_rate,*price*,*amount*
Boolean fields:
- Exact:
enabled,active,published,verified,approved,deleted - Prefix:
is_*,has_*,can_*
Time fields:
- Exact:
created_at,updated_at,deleted_at,published_at - Suffix:
*_at,*_date,*_time
Usage
The inference system is available via the ui package:
import "github.com/livetemplate/lvt/internal/ui"
// Infer type from field name
fieldType := ui.InferType("email") // → "string"
// Parse field input (with or without type)
name, typ := ui.ParseFieldInput("email") // → "email", "string" (inferred)
name, typ := ui.ParseFieldInput("age:float") // → "age", "float" (explicit override)Future Enhancement
In upcoming phases, this will power:
- Interactive field builders that suggest types as you type
- Direct mode support:
lvt gen users name email age(without explicit types) - Smart defaults that reduce typing
Project Layout
The generated app follows idiomatic Go conventions:
cmd/- Application entry pointsapp/- Handlers and templates (co-located!)database/- Database layer with sqlcshared/- Shared utilitiesweb/assets/- Static assets
Key Design Decision: Templates live next to their handlers for easy discovery.
Generated Handler Structure
package users
type State struct {
Queries *models.Queries
Users []User
SearchQuery string
SortBy string
CurrentPage int
PageSize int
TotalPages int
// ...
}
// Action methods - automatically dispatched based on action name
func (s *State) Add(ctx *livetemplate.ActionContext) error {
// Create user
return nil
}
func (s *State) Update(ctx *livetemplate.ActionContext) error {
// Update user
return nil
}
func (s *State) Delete(ctx *livetemplate.ActionContext) error {
// Delete user
return nil
}
func (s *State) Search(ctx *livetemplate.ActionContext) error {
// Search users
return nil
}
func (s *State) Init() error {
// Load initial data
return nil
}
func Handler(queries *models.Queries) http.Handler {
tmpl := livetemplate.New("users")
state := &State{Queries: queries, PageSize: 10}
return tmpl.Handle(state)
}Testing
The project includes comprehensive testing infrastructure at multiple levels.
Make Targets (Recommended)
Use these convenient make targets for different testing workflows:
make test-fast # Unit tests only (~30s)
make test-commit # Before committing (~3-4min)
make test-all # Full suite (~5-6min)
make test-clean # Clean Docker resourcesSee Testing Guide for detailed documentation on test optimization and architecture.
Quick Start
# Run all tests (fast mode - skips deployment tests)
go test ./... -short
# Run all tests (including slower e2e tests)
go test ./...
# Run specific package tests
go test ./internal/generator -v
# Run tests with coverage
go test ./... -coverTest Types
1. Unit Tests
Fast tests for individual packages and functions:
# Internal packages
go test ./internal/config ./internal/generator ./internal/parser -v
# Commands package
go test ./commands -vDuration: <5 seconds
2. WebSocket Tests (*_ws_test.go)
Fast unit tests for WebSocket protocol and state changes in generated resources:
go test ./app/users -run WebSocketFeatures:
- Test server startup with dynamic ports
- WebSocket connection testing
- CRUD action testing
- Server log capture for debugging
Duration: 2-5 seconds per resource
3. E2E Browser Tests (*_test.go)
Full browser testing with real user interactions for generated resources:
go test ./app/users -run E2EFeatures:
- Docker Chrome container
- Real browser interactions (clicks, typing, forms)
- Visual verification
- Screenshot capture
- Console log access
Duration: 20-60 seconds per resource
4. Deployment Tests (Advanced)
Comprehensive deployment testing infrastructure for testing real deployments:
# Mock deployment tests (fast, no credentials needed)
go test ./e2e -run TestDeploymentInfrastructure_Mock -v
# Docker deployment tests (requires Docker)
RUN_DOCKER_DEPLOYMENT_TESTS=true go test ./e2e -run TestDockerDeployment -v
# Fly.io deployment tests (requires credentials)
export FLY_API_TOKEN="your_token"
RUN_FLY_DEPLOYMENT_TESTS=true go test ./e2e -run TestRealFlyDeployment -vFeatures:
- Mock, Docker, and Fly.io deployment testing
- Automatic cleanup and resource management
- Smoke tests (HTTP, health, WebSocket, templates)
- Credential-based access control
Duration: 2 minutes (mock) to 15 minutes (real deployments)
Test Environment Variables
| Variable | Purpose | Default |
|---|---|---|
RUN_DOCKER_DEPLOYMENT_TESTS |
Enable Docker deployment tests | false |
RUN_FLY_DEPLOYMENT_TESTS |
Enable Fly.io deployment tests | false |
FLY_API_TOKEN |
Fly.io API token for real deployments | - |
Continuous Integration
Tests run automatically on every pull request via GitHub Actions:
- ✅ Code formatting validation
- ✅ Unit tests (all internal packages)
- ✅ Commands tests
- ✅ E2E tests (short mode)
- ✅ Mock deployment tests
On-demand/scheduled deployment testing available via manual workflow dispatch or weekly schedule.
For detailed CI/CD documentation, see:
Skip Slow Tests
Use -short flag to skip slow tests (deployment tests, long-running e2e tests):
go test -short ./...Test Documentation
For comprehensive testing documentation, see:
- Deployment Testing - Complete deployment testing guide
- CI/CD Testing - CI/CD workflows and setup
- Deployment Plan - Implementation progress and status
Go 1.24+ Tools Support
Generated go.mod includes:
//go:tool github.com/sqlc-dev/sqlc/cmd/sqlcRun migrations (automatically runs sqlc):
lvt migration upCSS Framework
All generated templates use Bulma CSS by default:
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/bulma@1.0.4/css/bulma.min.css">Components used:
.section,.container- Layout.box- Content containers.table- Data tables.button,.input,.select- Form controls.pagination- Pagination controls
Development Workflow
- Create app:
lvt new myapp - Generate resources:
lvt gen users name:string email:string - Run migrations:
lvt migration up(auto-generates DB code) - Wire routes in
main.go - Run tests:
go test ./... - Run app:
go run cmd/myapp/main.go
Examples
Blog App
lvt new myblog
cd myblog
# Generate posts resource
lvt gen posts title:string content:string published:bool
# Generate comments resource
lvt gen comments post_id:string author:string text:string
# Run migrations (auto-generates DB code)
lvt migration up
# Run
go run cmd/myblog/main.goE-commerce
lvt new mystore
cd mystore
lvt gen products name:string price:float stock:int
lvt gen customers name:string email:string
lvt gen orders customer_id:string total:float
lvt migration up # Runs migrations and generates DB code
go run cmd/mystore/main.goArchitecture
Template System
The generator uses custom delimiters ([[, ]]) to avoid conflicts with Go template syntax:
- Generator templates:
[[.ResourceName]]- Replaced during generation - Output templates:
{{.Title}}- Used at runtime by LiveTemplate
Embedded Templates
All templates are embedded using embed.FS for easy distribution.
Code Generation Strategy
- Parse field definitions (
name:type) - Map types to Go and SQL types
- Render templates with resource data
- Generate handler, template, tests
- Append to database files
Testing the Generator
Run All Tests
go test ./cmd/lvt -vTest Layers
-
Parser Tests (
cmd/lvt/internal/parser/fields_test.go)- Field parsing and validation
- Type mapping correctness
- 13 comprehensive tests
-
Golden File Tests (
cmd/lvt/golden_test.go)- Regression testing for generated code
- Validates handler and template output
- Update with:
UPDATE_GOLDEN=1 go test ./cmd/lvt -run Golden
-
Integration Tests (
cmd/lvt/integration_test.go)- Go syntax validation
- File structure validation
- Generation pipeline testing
-
Smoke Test (
scripts/test_cli_smoke.sh)- End-to-end CLI workflow
- App creation and resource generation
- File structure verification
Roadmap
-
lvt gen view- View-only handlers -
Router auto-update✅ Complete -
Bubbletea interactive UI✅ Complete (Phase 1-3)- Dependencies & infrastructure
- Smart type inference system (50+ patterns)
- UI styling framework (Lipgloss)
- Interactive app creation wizard
- Interactive resource builder
- Interactive view builder
- Mode detection (auto-switch based on args)
- Type inference in direct mode
-
Enhanced validation & help system (Phase 4)✅ Complete- Real-time Go identifier validation
- SQL reserved word warnings (25+ keywords)
- Help overlay with
?key in all wizards - Color-coded feedback (✓✗⚠)
- All 3 wizards enhanced
-
Migration commands✅ Complete- Goose integration with minimal wrapper (~410 lines)
- Auto-generate migrations from
lvt gen resource - Commands:
up,down,status,create <name> - Timestamped migration files with Up/Down sections
- Schema versioning and rollback support
-
Custom template support✅ Complete- Cascading template lookup (project → user → embedded)
-
lvt template copycommand for easy customization - Project templates in
.lvt/templates/(version-controlled) - User-wide templates in
~/.config/lvt/templates/ - Selective override (only customize what you need)
- Zero breaking changes (~250 lines total)
-
Multiple CSS frameworks✅ Complete- Tailwind CSS v4 (default)
- Bulma 1.0.4
- Pico CSS v2
- None (pure HTML)
- CSS framework determined by kit (multi/single use Tailwind, simple uses Pico)
- 57 CSS helper functions for framework abstraction
- Conditional template rendering (single source of truth)
- Semantic HTML support for Pico CSS (, )
- Zero breaking changes (~550 lines total)
-
lvt gen auth- Authentication system- Password authentication (bcrypt)
- Magic-link email authentication
- Email confirmation flow
- Password reset functionality
- Session management tables
- CSRF protection (gorilla/csrf)
- Auto-dependency updates (go.mod)
- EmailSender interface with examples
- Configurable via flags
- Auth handlers (Phase 2)
- Custom authenticator (Phase 3)
- Middleware templates (Phase 4)
- GraphQL support
Contributing
See the main LiveTemplate CLAUDE.md for development guidelines.
License
Same as LiveTemplate project.
|
[core] |
Summary
lvt gen queuecommand to set up background job infrastructure (River queue tables, worker registration, main.go injection)lvt gen job <name>command to scaffold individual job handlers with River worker patternArchitecture
Following the pattern of every major framework (Rails -> Solid Queue, Phoenix -> Oban, Django -> Celery), we wrap an existing battle-tested library rather than building from scratch. Our code is purely the generation layer:
internal/kits/system/{multi,single}/templates/jobs/internal/generator/jobs.go) withGenerateQueue()andGenerateJob()functionscommands/jobs.go) with help text and validationUsage
Test plan
TestGenerateQueue— verifies migration, schema.sql, worker.go creationTestGenerateQueueIdempotent— second call errors with "already set up"TestGenerateJob— verifies handler file, worker registration injectionTestGenerateJobWithoutQueue— errors with "Run lvt gen queue first"TestGenerateJobDuplicate— errors with "already exists"TestGenerateMultipleJobs— 3 jobs all registered correctlygo test ./...green🤖 Generated with Claude Code