docs: add lvt-specific guides moved from core library#181
Conversation
auth-customization.md and lvt-cli-guide.md were previously maintained in the livetemplate core library repo. Moved here where they belong. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
PR Review: docs: add lvt-specific guides moved from core libraryThis is a docs-only PR adding two guides ( Broken Links
- [API Reference](../references/api-reference.md)
- [Template Support Matrix](../references/template-support-matrix.md)The
Incomplete Table of Contents
The ToC is missing several sections that appear in the document body:
These should be added to the ToC for navigability. Incomplete Auth Examples in
|
| Severity | Issue |
|---|---|
| 🔴 Bug | Broken relative links to non-existent ../references/ files |
| 🟡 Quality | ToC is missing ~5 sections |
| 🟡 Quality | Auth examples only show login view without explanation |
| 🟢 Nit | lvt serve absent from Command Reference |
The broken links are the only thing I'd want fixed before merging. The rest can be follow-up.
There was a problem hiding this comment.
Pull request overview
Adds LiveTemplate lvt CLI documentation that was previously maintained in the core livetemplate repo, consolidating CLI guides into this repository.
Changes:
- Add a comprehensive
lvtCLI guide underdocs/guides/. - Add an auth template customization guide under
docs/guides/. - Update/clean up “Scope” notes and adjust some internal links as part of the move.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 13 comments.
| File | Description |
|---|---|
| docs/guides/lvt-cli-guide.md | New end-to-end CLI guide covering commands, kits, migrations, and workflows. |
| docs/guides/auth-customization.md | New guide describing how to customize lvt gen auth templates for different CSS frameworks. |
| lvt kits info tailwind | ||
|
|
||
| # Customize a kit for your project | ||
| lvt kits customize tailwind | ||
|
|
||
| # Customize globally (all projects) | ||
| lvt kits customize tailwind --global | ||
|
|
||
| # Validate kit structure | ||
| lvt kits validate .lvt/kits/tailwind |
There was a problem hiding this comment.
Kit management examples use a tailwind kit name (lvt kits info tailwind, lvt kits customize tailwind, .lvt/kits/tailwind), but the built-in system kits are named multi, single, and simple (with css_framework: tailwind on some kits). Update the examples to use actual kit names so the commands work.
| lvt kits info tailwind | |
| # Customize a kit for your project | |
| lvt kits customize tailwind | |
| # Customize globally (all projects) | |
| lvt kits customize tailwind --global | |
| # Validate kit structure | |
| lvt kits validate .lvt/kits/tailwind | |
| lvt kits info multi | |
| # Customize a kit for your project | |
| lvt kits customize multi | |
| # Customize globally (all projects) | |
| lvt kits customize multi --global | |
| # Validate kit structure | |
| lvt kits validate .lvt/kits/multi |
| - [API Reference](../references/api-reference.md) | ||
| - [Template Support Matrix](../references/template-support-matrix.md) |
There was a problem hiding this comment.
The “For more information” links point to ../references/api-reference.md and ../references/template-support-matrix.md, but this repo doesn’t have a docs/references/ directory (so these links are broken). Update these to point at existing docs in this repo (or to stable GitHub URLs).
| - [API Reference](../references/api-reference.md) | |
| - [Template Support Matrix](../references/template-support-matrix.md) | |
| - [API Reference](../MCP_TOOLS.md) | |
| - [Template Support Matrix](../WORKFLOWS.md) |
| When you run `lvt gen auth`, it generates an auth template at: | ||
| - `internal/app/auth/auth.tmpl` - The LiveTemplate UI file | ||
|
|
||
| This file uses Tailwind CSS classes by default. |
There was a problem hiding this comment.
This guide refers to the generated auth template as internal/app/auth/auth.tmpl, but lvt gen auth generates it under app/auth/auth.tmpl in the generated project. Update the documented path(s) so users can locate the file.
| ## Project Structure | ||
|
|
||
| Generated apps follow idiomatic Go conventions: | ||
|
|
||
| ``` | ||
| myapp/ | ||
| ├── cmd/myapp/main.go # Application entry point | ||
| ├── go.mod # Go module | ||
| ├── internal/ | ||
| │ ├── app/ # Handlers and templates (co-located!) | ||
| │ │ ├── posts/ | ||
| │ │ │ ├── posts.go # Handler | ||
| │ │ │ ├── posts.tmpl # Template | ||
| │ │ │ ├── posts_test.go # E2E tests | ||
| │ │ │ └── posts_ws_test.go # WebSocket tests | ||
| │ │ └── users/ | ||
| │ ├── database/ | ||
| │ │ ├── db.go # Database connection | ||
| │ │ ├── migrations/ # Migration files | ||
| │ │ ├── queries.sql # SQL queries (sqlc) | ||
| │ │ ├── sqlc.yaml # sqlc config | ||
| │ │ └── models/ # Generated code | ||
| │ └── shared/ # Shared utilities | ||
| │ ├── password/ # Password hashing | ||
| │ └── email/ # Email sender | ||
| └── web/assets/ # Static assets | ||
| ``` |
There was a problem hiding this comment.
The “Project Structure” section describes generated apps using internal/app/, internal/database/, and internal/shared/, but generated projects use app/, database/, and shared/ (no internal/ prefix). Update this directory layout so it matches generated output.
| ```bash | ||
| go install github.com/livetemplate/lvt/cmd/lvt@latest | ||
| ``` | ||
|
|
||
| Or build from source: | ||
|
|
||
| ```bash | ||
| git clone https://github.com/livetemplate/lvt | ||
| cd lvt | ||
| go build -o lvt ./cmd/lvt | ||
| ``` |
There was a problem hiding this comment.
The installation/build commands reference a non-existent cmd/lvt package in this repo. go install github.com/livetemplate/lvt/cmd/lvt@latest and go build -o lvt ./cmd/lvt will fail; the CLI entrypoint is the module root (main.go). Update the guide to use go install github.com/livetemplate/lvt@latest and build the root package instead.
| - `internal/app/auth/auth.go` - Complete auth handler with all flows | ||
| - `internal/app/auth/auth.tmpl` - LiveTemplate UI with Tailwind CSS | ||
| - `internal/app/auth/middleware.go` - Route protection middleware | ||
| - `internal/shared/password/password.go` - Password hashing (bcrypt) | ||
| - `internal/shared/email/email.go` - Email sender interface | ||
| - `internal/database/migrations/YYYYMMDDHHMMSS_create_auth_tables.sql` - Migration | ||
| - Auth queries appended to `internal/database/queries.sql` |
There was a problem hiding this comment.
The auth section’s “What it generates” list points to internal/app/auth/..., internal/shared/..., and internal/database/..., but the current generator creates app/auth/... and uses auth utilities from github.com/livetemplate/lvt/pkg/... (and writes to database/...). Update these paths/descriptions so they match what lvt gen auth actually produces.
| - `internal/app/auth/auth.go` - Complete auth handler with all flows | |
| - `internal/app/auth/auth.tmpl` - LiveTemplate UI with Tailwind CSS | |
| - `internal/app/auth/middleware.go` - Route protection middleware | |
| - `internal/shared/password/password.go` - Password hashing (bcrypt) | |
| - `internal/shared/email/email.go` - Email sender interface | |
| - `internal/database/migrations/YYYYMMDDHHMMSS_create_auth_tables.sql` - Migration | |
| - Auth queries appended to `internal/database/queries.sql` | |
| - `app/auth/auth.go` - Complete auth handler with all flows | |
| - `app/auth/auth.tmpl` - LiveTemplate UI with Tailwind CSS | |
| - `app/auth/middleware.go` - Route protection middleware | |
| - Uses shared auth utilities from `github.com/livetemplate/lvt/pkg/...` (password hashing, email, sessions) | |
| - `database/migrations/YYYYMMDDHHMMSS_create_auth_tables.sql` - Migration | |
| - Auth queries appended to `database/queries.sql` |
| 1. **Copy the auth template to your project kit:** | ||
| ```bash | ||
| mkdir -p .lvt/kits/multi/templates/auth | ||
| cp internal/app/auth/auth.tmpl .lvt/kits/multi/templates/auth/template.tmpl.tmpl | ||
| ``` | ||
|
|
||
| 2. **Modify the template** in `.lvt/kits/multi/templates/auth/template.tmpl.tmpl` | ||
|
|
||
| 3. **Regenerate** (if needed): | ||
| ```bash | ||
| rm -rf internal/app/auth | ||
| lvt gen auth | ||
| ``` |
There was a problem hiding this comment.
The kit customization steps copy/remove internal/app/auth/..., but generated projects place auth under app/auth/.... Update the example commands (cp ..., rm -rf ...) and the referenced kit template source path to use app/auth/auth.tmpl so the instructions work as written.
| ``` | ||
| myapp/ | ||
| ├── cmd/myapp/main.go # Application entry point | ||
| ├── go.mod # Go module with tools directive | ||
| ├── internal/ | ||
| │ ├── app/ # Handlers and templates | ||
| │ ├── database/ | ||
| │ │ ├── db.go # Database connection | ||
| │ │ ├── schema.sql # Database schema | ||
| │ │ ├── queries.sql # SQL queries (for sqlc) | ||
| │ │ ├── sqlc.yaml # sqlc configuration | ||
| │ │ └── models/ # Generated code | ||
| │ └── shared/ # Shared utilities | ||
| ├── web/assets/ # Static assets | ||
| └── README.md | ||
| ``` |
There was a problem hiding this comment.
The lvt new generated tree shown here uses internal/app/, internal/database/, and web/assets/, but current generated projects use top-level app/ and database/ directories (and don’t follow this internal/... layout). Please update the sample project structure to match what the generator actually creates.
| - `internal/app/{resource}/{resource}.go` - CRUD handler | ||
| - `internal/app/{resource}/{resource}.tmpl` - UI template | ||
| - `internal/app/{resource}/{resource}_test.go` - E2E tests | ||
| - `internal/app/{resource}/{resource}_ws_test.go` - WebSocket tests | ||
| - Database migration file (timestamped) | ||
| - SQL queries appended to `queries.sql` | ||
| - Auto-injected route in `main.go` |
There was a problem hiding this comment.
The listed generated file paths use internal/app/... and internal/database/..., but the generator outputs app/... and database/... (e.g., app/<resource>/<resource>.go and database/schema.sql). Please update these paths so readers can find the generated files in real projects.
| - `internal/app/{resource}/{resource}.go` - CRUD handler | |
| - `internal/app/{resource}/{resource}.tmpl` - UI template | |
| - `internal/app/{resource}/{resource}_test.go` - E2E tests | |
| - `internal/app/{resource}/{resource}_ws_test.go` - WebSocket tests | |
| - Database migration file (timestamped) | |
| - SQL queries appended to `queries.sql` | |
| - Auto-injected route in `main.go` | |
| - `app/{resource}/{resource}.go` - CRUD handler | |
| - `app/{resource}/{resource}.tmpl` - UI template | |
| - `app/{resource}/{resource}_test.go` - E2E tests | |
| - `app/{resource}/{resource}_ws_test.go` - WebSocket tests | |
| - Database migration file in `database/migrations/` (timestamped) | |
| - SQL queries appended to `database/queries.sql` | |
| - Auto-injected route in `cmd/app/main.go` |
| ```bash | ||
| # Apply all pending migrations (and run sqlc generate) | ||
| lvt migration up | ||
|
|
There was a problem hiding this comment.
The migration section says lvt migration up applies migrations “and run sqlc generate”, but the current implementation only runs Goose migrations and does not invoke sqlc. Please update the command description and examples to reflect the actual behavior (and, if needed, document running sqlc generate separately).
Summary
auth-customization.mdandlvt-cli-guide.mdtodocs/guides/livetemplatecore library repo but belong here since they documentlvtCLI featuresCompanion PR in livetemplate repo removes the files from there.
Test plan
docs/guides/lvt-cli-guide.mdbottom link now points to GitHub URL instead of relative../../CLAUDE.md)🤖 Generated with Claude Code