---
url: https://repoctl.icebreaker.top/reference/templates.md
---
# Templates

repoctl templates are maintained by `@icebreakers/monorepo-templates`. The CLI, scaffolder, and docs share the same template metadata.

## Built-In Templates

| Key           | Category | Default target     | Use case                |
| ------------- | -------- | ------------------ | ----------------------- |
| `tsdown`      | library  | `packages/tsdown`  | TypeScript library      |
| `vue-lib`     | library  | `packages/vue-lib` | Vue 3 component library |
| `vue-hono`    | app      | `apps/client`      | Vue 3 + Hono app        |
| `hono-server` | service  | `apps/server`      | Hono API service        |
| `vitepress`   | docs     | `apps/website`     | VitePress docs site     |
| `cli`         | tool     | `apps/cli`         | TypeScript CLI          |

## Discover Templates

```bash
repo templates
repo templates tsdown
repo templates --category library
repo templates --json
repo templates --markdown --out docs/templates.md
```

## Create From A Template

```bash
repo new sdk --template tsdown
repo new ui --template vue-lib
repo new api --template hono-server
repo new website --template vitepress
repo new toolbox --template cli
```

Simple names are placed in the conventional target folder. Library templates go under `packages/`; app templates go under `apps/`. If you pass an explicit path such as `packages/shared-utils`, repoctl respects it.

## Choose By Goal

### Publish an npm library

```bash
repo new sdk --template tsdown
```

Check first:

* `package.json` `name`, `exports`, and `types`.
* Whether `tsdown.config.ts` matches the desired output format.
* Whether public types need `tsd` tests.

### Build reusable Vue components

```bash
repo new ui --template vue-lib
```

Check first:

* Component entry points only expose stable APIs.
* Styles pass Stylelint.
* A docs site or example app should be created alongside it if needed.

### Create an app or service

```bash
repo new web --template vue-hono
repo new api --template hono-server
```

Check first:

* Runtime environment variables and deployment constraints.
* `dev`, `build`, and `typecheck` scripts are part of root tasks.
* CI needs integration or E2E tests.

### Cloudflare Worker types

The `vue-hono` and `hono-server` templates generate `worker-configuration.d.ts` from the installed Wrangler version and `wrangler.jsonc` before `dev`, `build`, and `typecheck`. This generated file is ignored by Git and excluded from published templates. Dependency updates do not require committing regenerated declarations.

Run `pnpm cf-typegen` in the app workspace to refresh editor types after changing bindings or compatibility settings. `pnpm cf-typegen:check` is a read-only diagnostic: it reports missing or outdated declarations. Build and typecheck regenerate them automatically and still fail on invalid configuration or TypeScript errors.

For existing projects, update these scripts and the Turbo inputs/outputs, then remove `worker-configuration.d.ts` from the Git index with `git rm --cached worker-configuration.d.ts` and add it to `.gitignore`.

### Create a docs site

```bash
repo new docs --template vitepress
```

Check first:

* Nav and sidebar are organized around the product or package.
* A second locale is required.
* `repo templates --markdown` output should be written into docs.

### Create a CLI

```bash
repo new toolbox --template cli
```

Check first:

* The `bin` field matches the final command name.
* Argument parsing, exit codes, and help output are testable.
* README documents command usage.

## Preview Creation

```bash
repo new website --template vitepress --dry-run
repo new website --template vitepress --json
repo new website --template vitepress --json --out plans/website.json
```

`--dry-run` does not write files. It shows the template, source directory, target directory, package name, and output files.

`--json` emits the same plan as structured data and implies `--dry-run`.

`--out <file>` persists the preview and also implies `--dry-run`.

## Check Template Health

```bash
repo templates --check
repo templates --check --json
```

The check validates duplicate sources and targets, existing source directories, package metadata, categories, descriptions, and temporary files that would be filtered by the scaffolder.

## Keep Reading

* [Adopt an existing workspace](/tasks/adopt-existing)
* [Add checks to CI](/tasks/ci)
* [Configuration](./config.md)