⚡ qwykz ⚡

Quick & Ready Boilerplate Builder

A lightning-fast CLI tool built with Bun to scaffold organized Backend, Frontend, and Fullstack starter applications for beginners and AI-assisted development.

Features • Installation • Usage • Wiki / Docs • Contributing

The problem qwykz is trying to solve

Starting a project should feel exciting, but the first hour often disappears into the same chores: creating folders, choosing packages, wiring authentication, configuring a database, fixing environment files, and explaining the structure to an AI assistant all over again. Experienced developers have rebuilt this foundation too many times. New learners can get stuck before they reach the part they actually wanted to learn. And the proudly “lazy” developer—usually the one looking for the simplest repeatable path—should not have to trade speed for clarity.

qwykz turns those repeated decisions into an inspectable scaffold. You choose the stack; qwykz generates the project, explains every package, records the choices in a manifest, and leaves an AGENTS.md guide for humans and AI tools. Use --dry-run when you want to see the exact files first, --strict when you want a package audit, and the public capability matrix when you need an honest answer about what is supported today.

It is for working developers who want momentum, learners who need a reliable example, teams that want consistent starting points, and anyone in tech who would rather spend their energy building the product than rebuilding setup scripts.

Features

• Multi-Stack Scaffolding: Generate exact boilerplate architectures in Backend (Express, Hono, Elysia, Laravel, Python FastAPI, Go Fiber, Rust Axum), Frontend (React, Vue), or Fullstack (Next.js) environments.
• Enterprise-Inspired Architecture: Organizes generated projects around clear service, controller, model, middleware, route, database, and configuration layers.
• Frontend Powerhouses:
  • React & Vue apps are generated using high-speed Vite.
  • Zero-config UI: Tailwind CSS v4 is automatically injected and configured.
  • Auth choices with honest maturity labels: Local authentication scaffolds include Login, Register, and Dashboard flows. Supabase and Clerk scaffolds are available behind --experimental while their production auth contracts are completed.
  • Strict Validation: Zod schemas are automatically wired up to the frontend authentication forms.
  • Deterministic installs: framework/runtime packages are always included for the selected stack, while optional packages stay opt-in and visible in the prompts.
  • Universal Fullstack Alignment: Frontends automatically map their VITE_API_URL exactly to match the chosen backend framework (3000 for Go/Node, 8000 for Python/Laravel, 8080 for Rust). All backends expose identical routing topologies (/api/auth, /api/users, etc.) for seamless, plug-and-play cross-stack compatibility.
• Database Orchestration: Intelligent, automated setup for your PostgreSQL environment:
  • Local Installation
  • Fully Dockerized (automatically assigns ports, boots containers, and waits for health checks)
  • Supabase Cloud & Neon Serverless Postgres (automatically formats connections and skips local migrations)
• Out-of-the-Box API Security:
  • Express/Hono/Elysia: Prisma ORM, JWT authentication, Argon2 hashing, Helmet, CORS, and Zod validation with Role-Based Access Control.
  • Laravel: Silent Sanctum installation, automatic User model traits, and built-in Auth endpoints.
  • Python/Go/Rust: Native ORMs (SQLModel, Gorm, SQLx) natively wired with Bcrypt/Argon2 hashing and JWT Role-Based Access Control.
• Non-Interactive Mode: Fully scriptable via CLI flags for CI/CD or automated testing setups.
• Inspectable By Default: Every scaffold includes a manifest and AI context guide; dry-run and strict policy modes make files and dependencies reviewable before setup.

Installation

Run without installing (Recommended)

You can run qwykz directly using bunx:

bunx qwykz@latest
# or
bunx qwykz

Global Install

If you prefer to install it globally:

bun install -g qwykz

Usage

Interactive Mode

Simply run the command and follow the beautiful CLI prompts:

qwykz

You will be prompted to:

1. Name your project
2. Select your Stack (Express, Hono, Elysia, Laravel, Python, Go, Rust, Next.js, React, or Vue)
3. Select your Database Target (Local, Docker, Supabase, Neon) or Frontend Auth (Clerk, Supabase)
4. Opt-in to extra features (Zod, Helmet, CORS) [JS/TS Backends only]

Non-Interactive Mode (Automated)

Perfect for scripts or CI/CD pipelines! Use the --yes or -y flag combined with options:

qwykz --yes \
  --name my-awesome-api \
  --framework laravel \
  --db docker

Available flags:

• --yes or -y: Skip all prompts and use defaults/flags
• --name <string>: Name of your project directory
• --framework <express|hono|elysia|laravel|python|go|rust|nextjs|react|vue>: Choose your stack
• --db <supabase|neon|local|docker>: Select database environment
• --zod, --helmet, --cors: Include extra middlewares
• --dry-run: Preview the generated tree, packages, manifest, and file diffs without creating the target project
• --show-diff: Show every generated file diff during a dry run
• --strict: Print the reason and category for every generated dependency
• --record-prompts: Store the resolved scaffold answers in .qwykz-manifest.json
• --no-ai-context: Skip generated AGENTS.md
• --experimental: Explicitly allow a combination marked experimental
• --plugins-dir <path>: Load plugins from an explicit directory
• --deploy <plugin-target>: Apply a deployment target registered by a plugin

Capability matrix

See the generated public capability matrix for the current framework, database, authentication, cache, and Dockerfile contract. Unsupported combinations are rejected before project files are written; experimental combinations require --experimental.

Managed credential smoke tests

Managed provider checks are opt-in and read credentials from environment variables only. Do not commit .env files or paste real provider tokens into test scripts.

SUPABASE_URL="..." \
SUPABASE_ANON_KEY="..." \
CLERK_SECRET_KEY="..." \
UPSTASH_REDIS_REST_URL="..." \
UPSTASH_REDIS_REST_TOKEN="..." \
bun run test:managed

Laravel uses Laravel-style split database variables and Predis Redis settings, so helper scripts derive DB_HOST, DB_PORT, DB_DATABASE, DB_USERNAME, and DB_PASSWORD from SUPABASE_DB_URL. For Laravel + Upstash Redis, provide Redis protocol credentials too:

UPSTASH_REDIS_HOST="..." \
UPSTASH_REDIS_PASSWORD="..." \
UPSTASH_REDIS_PORT="6379"

Missing provider env vars skip only that provider's live check. The default safety checks still verify that generated scaffolds keep managed credentials as placeholders and that helper scripts do not contain committed provider credentials.

Docker resource and data lifecycle

Generated Docker services use development-sized memory/CPU limits and bounded log files. PostgreSQL data is stored in a named volume so ordinary docker compose down preserves the database. Redis is generated as an ephemeral, memory-bounded cache and does not create a data volume.

When a generated project is disposable, remove its containers and PostgreSQL volume from inside that project directory:

docker compose down -v

-v permanently deletes that project's local database. Omit it when the data must survive. qwykz-managed PostgreSQL volumes carry the io.qwykz.managed=true label so unused generator data can be inventoried and cleaned deliberately instead of using an unscoped system-wide prune.

Documentation

Check out the Wiki Guides for deep dives into:

• Architecture Overview
• The Template Engine
• Dependency Resolution
• Adding New Features
• Writing Plugins
• Roadmap

Roadmap

The trust-and-predictability foundation is now in place:

• --dry-run, file diffs, manifests, strict package audits, AI context packs, and capability gating ship as part of normal generation.
• Community plugins can add frameworks, auth providers, and deployment targets through validated manifests and templates.
• Template validation and generated-project smoke workflows guard the scaffold surface in CI.

The largest remaining milestone is production-ready Supabase Auth and Clerk fullstack support, delivered through provider/backend contract tests rather than SDK presence alone. See the detailed roadmap for current status and sequencing.

Contributing

Contributions are welcome and appreciated.

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request