CLI Reference¶

wilco provides a command-line interface for development and production workflows.

wilco <command> [options]

If no command is specified, serve is used by default.

wilco serve¶

Start a development server with live component bundling.

wilco serve [--components-dir DIR]

Options¶

--components-dir DIR: Path to the components directory. Defaults to ./components if it exists, otherwise falls back to the built-in example components.

The server starts on http://0.0.0.0:8000 with auto-reload enabled. It uses FastAPI with uvicorn and exposes the standard API endpoints:

GET /api/bundles — list available components
GET /api/bundles/{name}.js — get bundled JavaScript
GET /api/bundles/{name}/metadata — get component metadata

CORS is configured to allow requests from http://localhost:5173 (Vite dev server) by default.

wilco build¶

Pre-compile component bundles for production deployment.

wilco build --output DIR [options]

Options¶

--output DIR (required): Output directory for pre-built bundles and manifest.
--components-dir DIR: Path to the components directory. Defaults to ./components if it exists, otherwise falls back to the built-in example components.
--prefix PREFIX: Prefix for component names (e.g., store). Components will be registered as store:component_name instead of component_name.
--no-minify: Disable JavaScript minification. Useful for debugging production bundles.
--sourcemap: Include source maps in the output. Disabled by default.

Output structure¶

dist/wilco/
├── manifest.json
└── bundles/
    ├── component_name.a1b2c3d4.js
    ├── store--product.e5f6g7h8.js
    └── ...

The manifest.json maps component names to their hashed bundle files:

{
  "component_name": {
    "file": "bundles/component_name.a1b2c3d4.js",
    "hash": "a1b2c3d4"
  },
  "store:product": {
    "file": "bundles/store--product.e5f6g7h8.js",
    "hash": "e5f6g7h8"
  }
}

Component names containing colons are sanitized for filenames: : becomes -- (e.g., store:product → store--product.{hash}.js).

Examples¶

# Basic build
wilco build --output dist/wilco/

# Build with prefix and source maps
wilco build --output dist/wilco/ --prefix store --sourcemap

# Build from a specific directory without minification
wilco build --output dist/wilco/ --components-dir ./my_components --no-minify

Environment variables¶

WILCO_BUILD_DIR

Path to the pre-built bundles directory. Used by bridges and the Django integration to locate the manifest. When set to an empty string, pre-built bundles are explicitly disabled.

export WILCO_BUILD_DIR=dist/wilco

This can also be resolved programmatically:

from pathlib import Path
from wilco.manifest import resolve_build_dir

# Checks WILCO_BUILD_DIR env var first, then falls back to default path
build_dir = resolve_build_dir(Path("./dist/wilco"))

Django management command¶

The Django bridge provides an equivalent management command:

python manage.py wilco_build [--output DIR]

When --output is not specified, it uses the WILCO_BUILD_DIR setting. See Django Integration for details.