# Project Templates

`kanject new` scaffolds a deploy-ready .NET service from a template — the solution, `manifest.json`, stage files, an optional test project, and Lambda defaults all wired. The free templates ship **inside the CLI** (no NuGet feed access needed); a paid catalog adds more.

**You'll learn**

- Scaffold a service with `kanject new <template> --name`
- Choose between the three free templates — `webapi`, `minimal-api`, `tasks`
- Tune the scaffold with `--framework`, `--auth-provider`, and `--include-tests`
- Understand the free vs paid template catalogs

## Scaffold a service

`kanject new [template] [--name <Name>]` installs or refreshes the bundled template pack, runs `dotnet new`, then runs `kanject init`. In a terminal, omitted inputs are progressive: choose the template first, then enter the project name. CI and redirected input must supply both.

```bash
# Scaffold a deploy-ready service from a template
kanject new webapi --name Acme.Analytics

# Or choose a template, then enter the project name interactively
kanject new

# Tune the scaffold with template options
kanject new webapi --name Acme.Api \
  --framework net10.0 --auth-provider none --include-tests false
```

## The free templates

Three templates ship with the CLI itself:

- **webapi** — A REST API with ASP.NET Core (MVC + controllers) on AWS Lambda. JWT bearer auth is scaffolded by default.
- **minimal-api** — A lean ASP.NET Core Minimal API on AWS Lambda — the same host, fewer files.
- **tasks** — Background workers using AWS Lambda Annotations and Kanject Core — for queue and event handlers, not HTTP.

## Options

- `--framework` — `net8.0` *(default)*, `net9.0`, or `net10.0`.
- `--auth-provider` — `jwt` *(default)* or `none`. Applies to `webapi`.
- `--include-tests` — `true` *(default)* / `false`; scaffolds a wired xUnit project.
- `--name` / `--output` — the service name and where it lands.
- `--non-interactive` — never prompt; requires complete inputs and either `--skip-init` or `--yes`.
- `--yes` — explicitly accept onboarding defaults and any required confirmation; it is not just a synonym for non-interactive mode.

## Free vs paid catalogs

The three above are **free** and bundled in the CLI — nothing to authenticate, and they update when the CLI does. A **paid** catalog (`--paid`, requires a Kanject subscription feed) adds richer starters: a notification hub, an instant-messaging API, a file-server API, and a source-generator project. `--paid` is sticky once the pack is installed; `--free` forces the bundled set.

```bash
# Pull from the paid catalog (requires a Kanject subscription feed)
kanject new notification-hub --name Acme.Notifications --paid
```

> **Some paid templates are also license-gated:** Beyond needing the subscription feed, a template like notification-hub is gated behind a feature key (pro.aws.template.notification-hub) — it appears with a lock and an upgrade hint until your license enables it.

## Keeping templates current

The free pack is versioned with the CLI, so `kanject update` (or `kanject update --templates-only`) refreshes it; `kanject new` also auto-refreshes before scaffolding. The paid pack flows through your subscription feed, and `new` runs a background update check before it creates the project.

## Add another function

Inside an existing service, bare `kanject add function` shows the available function-capable templates, then asks for the function name. Supply only the template to skip the picker and answer the name prompt; automation must pass both, for example `kanject add function tasks --name Acme.Worker --non-interactive`.

## Guidelines

- **Pick by shape:** `webapi` for a controller-based REST API, `minimal-api` for a lean API surface, `tasks` for queue / event workers with no HTTP.
- **Keep `--include-tests true`.** The xUnit project is already wired — cheap to keep, costly to bolt on later.
- **Pin `--framework` to your team's target** rather than drifting on the `net8.0` default.
- **Use `--auth-provider none`** when auth is terminated at the edge (an API Gateway authorizer) rather than in the app.
- **Make CI intent explicit:** pass the template and name, add `--non-interactive`, and use `--yes` only when the workflow intends to approve initialization or template installation.

**Recap**

- `kanject new <template> --name` scaffolds a deploy-ready service: solution, manifest, stages, tests, Lambda defaults.
- Three free templates ship in the CLI — `webapi`, `minimal-api`, `tasks` — with no feed access required.
- `--framework`, `--auth-provider`, and `--include-tests` tune the scaffold.
- A paid catalog (`--paid`) adds notification-hub, instant-messaging, file-server, and source-generator starters.

---
_Source: https://www.kanject.com/docs/cli-templates/ · Kanject Docs_