Public Access
FernandoJVideiraandClaude Fable 5.1
230037c5f5
Running `draft new monorepo` with the Vue client and then `docker compose build client` failed three separate ways, each found by actually doing it: - No Dockerfile: the Vue overlay never shipped one. The template now has an nginx-based image (project-template#4) and the client-vue sync job embeds it plus its nginx.conf.template, with the pnpm pin rewritten to the local version like the Nuxt overlay. - Stale root lockfile: the Vue scaffold wrote a pnpm-workspace.yaml into apps/client (to approve vue-demi's build script), which made it its own workspace, so the installs updated a nested lockfile and the root one kept describing the template's Nuxt client - pnpm install --frozen-lockfile then refused it. The file is only written when the client isn't already inside a workspace (standalone `draft new client`). - Missing component: the client-vue job listed components by name, so the AuthCard.vue that Login/Signup import was never embedded. It now embeds src/components/ as a whole. Co-Authored-By: Claude Fable 5.1 <[email protected]>
228 lines
6.7 KiB
Markdown
228 lines
6.7 KiB
Markdown
# Draft
|
|
|
|
A powerful CLI tool for bootstrapping Go APIs, frontend clients, and full-stack monorepos with best practices built-in. Draft helps you quickly scaffold production-ready projects — a standalone Go API, a standalone Nuxt/Vue client, or both wired together in a single monorepo.
|
|
|
|
## Features
|
|
|
|
- 🚀 **Quick Project Scaffolding** - Generate complete projects with a single command
|
|
- 🧩 **Three Project Shapes** - API only, client only, or a full-stack monorepo combining both
|
|
- 🔄 **Multiple API Types** - Support for both HTTP (REST) and gRPC architectures
|
|
- 🖼️ **Multiple Client Frameworks** - Nuxt or Vue, built on top of the official `nuxi`/`create-vue` tooling so the boilerplate always stays current
|
|
- 📦 **Service Generation** - Easily create new services with proper structure
|
|
- 🎯 **Handler Generation** - Generate HTTP or gRPC handlers on-demand
|
|
- 🔐 **Cryptographic Key Generator** - Built-in secure key generation
|
|
- 🛠️ **Pre-configured Tooling** - Automatic installation of essential Go tools
|
|
- 📝 **Template-based** - Consistent code generation using embedded templates
|
|
|
|
## Installation
|
|
|
|
### From Source
|
|
|
|
```bash
|
|
git clone [email protected]:FernandoJVideira/draft.git
|
|
cd draft
|
|
make build
|
|
```
|
|
|
|
### Build for Different Platforms
|
|
|
|
```bash
|
|
# macOS (ARM64)
|
|
make mac
|
|
|
|
# Linux (AMD64)
|
|
make linux
|
|
|
|
# Windows (AMD64)
|
|
make windows
|
|
|
|
# Windows (ARM64)
|
|
make win-arm
|
|
```
|
|
|
|
The compiled binary will be named `draft_<os>_<arch>` (e.g. `draft_darwin_arm64`, or `draft_windows_amd64.exe` on Windows).
|
|
|
|
## Usage
|
|
|
|
### Create a New Project
|
|
|
|
```bash
|
|
draft new
|
|
```
|
|
|
|
Prompts you to pick a project shape — **API**, **Client**, or **Full Stack** (monorepo) — then runs the matching flow below. Each shape is also available directly as its own subcommand if you already know what you want.
|
|
|
|
### Create a New API Project
|
|
|
|
```bash
|
|
draft new api
|
|
```
|
|
|
|
This interactive command will:
|
|
1. Prompt you for a project name (module name)
|
|
2. Ask you to select an API type (HTTP REST or gRPC)
|
|
3. Scaffold the complete project structure
|
|
4. Install required development tools
|
|
5. Run `go mod tidy` to organize dependencies
|
|
|
|
**Tools Automatically Installed:**
|
|
- `air` - Live reload for Go apps
|
|
- `golangci-lint` - Go linters aggregator
|
|
- `mockgen` - Mock generation for testing
|
|
- `sqlc` - SQL compiler for type-safe database code
|
|
- `migrate` - Database migration tool
|
|
- `swag` - Swagger documentation (HTTP only)
|
|
- `protoc-gen-*` - Protocol Buffer generators (gRPC only)
|
|
|
|
### Create a New Client Project
|
|
|
|
```bash
|
|
draft new client
|
|
```
|
|
|
|
1. Prompts for a project name
|
|
2. Prompts you to pick a framework — **Nuxt** or **Vue**
|
|
3. Scaffolds the base app via the official tooling (`nuxi init` for Nuxt, `create-vue` for Vue), so the generated boilerplate, dependency versions, and lockfile are always current rather than pinned by Draft
|
|
4. Layers a Draft-maintained overlay on top: an auth store (login/logout/register/token refresh), route guards, API composable, and pages for login/signup/profile/organizations/email verification/invites — all wired up to talk to a Draft-generated API out of the box
|
|
|
|
Both frameworks produce a comparable app: [`vue-ui-kit`](https://git.fernandovideira.com/FernandoJVideira/vue-ui-kit) (installed from its own Gitea npm registry - see its README for the one-time `.npmrc` token setup) + Tailwind, the same component library and theme tokens on either framework. Both clients ship with a Dockerfile that mounts that `~/.npmrc` as a build secret (wired up in the monorepo's `docker-compose.yml`), so container builds resolve the package without baking the token into the image - Nuxt runs its Nitro server, Vue is served by nginx with an SPA fallback and `/api/` proxied to the api container.
|
|
|
|
### Create a New Monorepo Project
|
|
|
|
```bash
|
|
draft new monorepo
|
|
```
|
|
|
|
Runs the API flow and the client flow together under one root, wired up as a single project:
|
|
- `apps/api` — the scaffolded Go API
|
|
- `apps/client` — the scaffolded Nuxt or Vue client
|
|
- Root-level `go.work`, `pnpm-workspace.yaml`, `docker-compose.yml`, and `Justfile` tying both together
|
|
|
|
### Generate a New Service
|
|
|
|
```bash
|
|
draft new service
|
|
```
|
|
|
|
Creates a new service file in `internal/service/` with:
|
|
- Service interface definition
|
|
- Service struct implementation
|
|
- Compile-time interface checks
|
|
|
|
### Generate a New Handler
|
|
|
|
```bash
|
|
draft new handler
|
|
```
|
|
|
|
Creates a new handler in the appropriate directory:
|
|
- HTTP handlers → `internal/handlers/http/`
|
|
- gRPC handlers → `internal/handlers/grpc/`
|
|
|
|
### Generate a Cryptographic Key
|
|
|
|
```bash
|
|
draft key
|
|
draft key --size 48
|
|
```
|
|
|
|
Generates a secure random key for use in your application (default and minimum size: 32 characters). Passing `--size` below 32 is rejected rather than silently substituted.
|
|
|
|
### Check Version
|
|
|
|
```bash
|
|
draft version
|
|
```
|
|
|
|
## Project Structure
|
|
|
|
### API
|
|
|
|
```
|
|
your-project/
|
|
├── cmd/
|
|
│ └── api/
|
|
│ └── main.go
|
|
├── internal/
|
|
│ ├── handlers/
|
|
│ │ ├── http/ (if HTTP selected)
|
|
│ │ └── grpc/ (if gRPC selected)
|
|
│ └── service/
|
|
├── proto/ (if gRPC selected)
|
|
├── pb/ (if gRPC selected)
|
|
└── go.mod
|
|
```
|
|
|
|
### Client
|
|
|
|
```
|
|
your-client/
|
|
├── app/ (Nuxt) or src/ (Vue)
|
|
│ ├── stores/auth.ts
|
|
│ ├── composables/useApi.ts
|
|
│ ├── pages/ or views/
|
|
│ └── ...
|
|
├── nuxt.config.ts (Nuxt) or vite.config.ts + components.json (Vue)
|
|
└── package.json
|
|
```
|
|
|
|
### Monorepo
|
|
|
|
```
|
|
your-project/
|
|
├── apps/
|
|
│ ├── api/ (Go API, its own go.mod)
|
|
│ └── client/ (Nuxt or Vue client)
|
|
├── go.work
|
|
├── pnpm-workspace.yaml
|
|
├── docker-compose.yml
|
|
└── Justfile
|
|
```
|
|
|
|
## Requirements
|
|
|
|
- Go 1.25.5 or higher
|
|
- Make (for building from source)
|
|
- `pnpm` and `npx` (Node.js) — required for client and monorepo scaffolding
|
|
- `protoc` — required only for gRPC API projects
|
|
|
|
## Dependencies
|
|
|
|
- [Cobra](https://github.com/spf13/cobra) - CLI framework
|
|
- [promptui](https://github.com/manifoldco/promptui) - Interactive prompts
|
|
- [golang.org/x/text](https://golang.org/x/text) - Text processing utilities
|
|
|
|
## Development
|
|
|
|
### Build
|
|
|
|
```bash
|
|
make build
|
|
```
|
|
|
|
### Run with Version Flag
|
|
|
|
```bash
|
|
make version
|
|
```
|
|
|
|
### Sync Templates
|
|
|
|
Draft's embedded API/client templates are synced from a reference monorepo checked out as a git submodule (`assets/testdata/template`). After updating that submodule, regenerate the embedded copies with:
|
|
|
|
```bash
|
|
go run tools/sync_templates.go
|
|
```
|
|
|
|
## Contributing
|
|
|
|
Contributions are welcome! Please feel free to submit a Pull Request.
|
|
|
|
## License
|
|
|
|
This project is licensed under the MIT License - see the LICENSE file for details.
|
|
|
|
## Author
|
|
|
|
Built by LKResuts for internal usage to bootstrap Go APIs.
|