Getting Started

Welcome to the Krewire Getting Started Guide.

This chapter is your complete onboarding manual for the Krewire ecosystem. It walks you through setting up your environment, understanding the developer toolchain, scaffolding and running your first project, and organizing your codebase according to battle-tested Go architectural standards.

Whether you are authoring a lightweight static documentation portal, developing an interactive terminal utility, building a fullstack web monolith, or operating high-throughput microservices, this guide equips you with the foundational workflows to build and ship software with zero toolchain fatigue.

1. Prerequisites & System Verification

Before building with Krewire, ensure your local development machine meets the baseline requirements. Krewire requires no Node.js, no npm, no bundlers, and no external runtimes—only standard Go and a Unix-compatible shell or Windows terminal.

System Requirements Matrix

Run Environment Check

Run the following one-liner in your terminal to verify your development environment readiness:

printf "Go:      %s\nGit:     %s\nOS/Arch: %s/%s\n" \
  "$(go version 2>/dev/null || echo 'NOT INSTALLED')" \
  "$(git --version 2>/dev/null || echo 'NOT INSTALLED')" \
  "$(uname -s 2>/dev/null || echo 'Unknown')" \
  "$(uname -m 2>/dev/null || echo 'Unknown')"

[!NOTE] If Go is not installed or your version is older than 1.22, download the official installer from golang.org/dl before continuing.

2. The Krewire Development Lifecycle

Traditional fullstack development often requires juggling multiple disjointed build tools: package managers (npm, pnpm), bundlers (vite, webpack), process supervisors, CSS processors, and deployment CLIs.

Krewire replaces this cognitive overhead with a unified, circular development lifecycle orchestrated entirely through a single binary (kiw) and a single configuration (krewire.yaml):

┌──────────────┐     ┌──────────────┐     ┌──────────────┐
│  1. Scaffold │ ──> │ 2. Configure │ ──> │  3. Develop  │
│   kiw new    │     │ krewire.yaml │     │   kiw dev    │
└──────────────┘     └──────────────┘     └──────┬───────┘
                                                 │ (Hot Reload)
┌──────────────┐     ┌──────────────┐     ┌──────▼───────┐
│   6. Ship    │ <── │   5. Build   │ <── │   4. Verify  │
│  kiw deploy  │     │  kiw build   │     │   kiw test   │
└──────────────┘     └──────────────┘     └──────────────┘

Lifecycle Stages:

1. Scaffold (kiw new): Generate a clean, idiomatic project structure tailored to your chosen workload archetype (--site, --app, --cli, --book).
2. Configure (krewire.yaml): Declare build outputs, dev server ports, asset directories, and task runner scripts in a single declarative file.
3. Develop (kiw dev): Launch a local development server with integrated hot reloading, instant template compilation, and live browser refresh.
4. Verify (kiw test & kiw vet): Validate code correctness with native Go tests, static analysis, and workload contract audits.
5. Build (kiw build): Compile optimized, zero-dependency release artifacts—either static HTML/CSS/WASM assets or a self-contained Go binary with embedded static files.
6. Ship (kiw deploy): Package deployment containers or stage distribution bundles into dist/.

3. Hands-On 5-Minute Quickstart

Follow this end-to-end tutorial to install kiw, scaffold a project, experience hot reloading, and generate a production build.

Step 1: Install the kiw CLI

On Linux or macOS, run the automated installation script:

curl -fsSL https://krewire.com/scripts/install.sh | sh

For Windows or Go-centric workflows, install directly via go install:

go install github.com/krewire/kiw/cmd/kiw@latest

Verify that the CLI is accessible in your system PATH:

kiw version

Expected output:

kiw v0.1.0 (linux/amd64) built with go1.22

Step 2: Scaffold a New Project

Create a new static site project named my-krewire-app:

kiw new my-krewire-app --site --title "My Krewire App"
cd my-krewire-app

The kiw new command creates a clean, minimal project structure:

my-krewire-app/
├── krewire.yaml          # Project devtool configuration
├── go.mod                # Go module definition
├── layouts/
│   └── Base.kiw          # Root HTML document wrapper
├── pages/
│   ├── index.kiw         # Home page component
│   └── 404.html          # Custom 404 page
├── components/           # Reusable UI components
├── public/               # Static assets (images, icons)
│   ├── favicon.svg
│   └── robots.txt
└── assets/
    └── style.css         # Global stylesheet

Step 3: Start the Development Server

Launch the local development server with file watching and live reloading:

kiw dev

Terminal output:

2026/09/29 20:00:00 INFO krewire dev server listening at http://localhost:8080
2026/09/29 20:00:00 INFO watching: pages/, layouts/, components/, public/, assets/

Open http://localhost:8080 in your web browser. You will see the default Krewire welcome page rendered instantly.

Step 4: Make a Live Edit

Open pages/index.kiw in your favorite code editor and modify the content:

---
title: "Welcome to Krewire"
layout: Base
---

<section class="hero">
  <h1>Building with Krewire is Fast.</h1>
  <p>Zero JavaScript overhead, compiled Go speed, and instant hot reload.</p>
  <button class="btn" onclick="alert('Hello from Go!')">Click Me</button>
</section>

<style>
.hero {
  padding: 4rem 1rem;
  text-align: center;
}
h1 {
  color: var(--primary, #39D353);
  font-size: 2.5rem;
}
.btn {
  padding: 0.75rem 1.5rem;
  font-weight: bold;
  border-radius: 8px;
  cursor: pointer;
}
</style>

Save the file. Observe your terminal and browser: the development server detects the file change, recompiles the template in < 10ms, and hot-reloads your browser without resetting client state.

Step 5: Build for Production

When you are ready to prepare your application for deployment, run:

kiw build

Terminal output:

2026/09/29 20:01:00 INFO building SSG site from file layout root=. output=.krewire/build
created index.html
created 404.html
created assets/style.css
created favicon.svg
created robots.txt
2026/09/29 20:01:00 INFO build complete: 5 files generated in 12ms

To preview your production build locally exactly as it will run on a web server:

kiw serve --port 3000

Visit http://localhost:3000 to verify your optimized production artifact.

4. Workload Archetype Selection Guide

Krewire supports eight first-class workload archetypes. When bootstrapping a new project, select the archetype that matches your architectural objective:

[!TIP] Progressive Growth: You can start with --site and later evolve your codebase into an --app or extract parts into a --service without rewriting your component files or folder layouts.

5. What is in this Chapter?

This Getting Started chapter is divided into five focused, in-depth subchapters designed to give you complete mastery over the Krewire toolchain:

6. Primary CLI Commands Cheat Sheet

Keep these everyday kiw commands at your fingertips during development:

7. Common Beginner Pitfalls & Solutions

1. kiw: command not found after Installation

Cause: The directory where kiw was installed is not included in your shell's PATH environment variable.

Resolution:

• If installed via the shell installer as non-root, add ~/.local/bin to your shell profile (~/.bashrc, ~/.zshrc):

  export PATH="$HOME/.local/bin:$PATH"
  

• If installed via go install, ensure Go's binary path is in your PATH:

  export PATH="$(go env GOPATH)/bin:$PATH"
  

• Reload your profile: source ~/.bashrc or source ~/.zshrc.

2. Port Collision (address already in use: 8080)

Cause: Another service (e.g. Tomcat, Docker, or another dev server) is occupying port 8080.

Resolution:

• Specify a custom port in krewire.yaml:

  dev:
    port: "3000"
  

• Or override on the command line using environment variables:

  KIW_PORT=3000 kiw dev
  

3. Outdated Go Version (requires go >= 1.22)

Cause: Your system has an older Go distribution (e.g. Go 1.18 or 1.20) installed via standard OS package managers (such as older Ubuntu apt).

Resolution:

• Check your current Go binary: go version.
• Remove the stale system package and install the official upstream distribution from golang.org/dl.

Next Steps

Now that you understand the big picture and development workflow, dive deep into the implementation details:

• Proceed to 2.1 Installation → to install and configure kiw for your specific operating system.
• Or explore the architectural foundation in 1. Overview →.