cratis extension new: create an extension package that builds and verifies
cratis extension new creates an extension package in one command. What it creates already has a
contract.play with its manifest,
builds, and passes cratis extension verify without edits. See
Manage extension packages for the other cratis extension commands.
cratis extension new [-n <NAME>] [--kind extension|package] [--backend csharp|kotlin|go|typescript|none] [--frontend react|mount|screenplay|none] [--component react|mount] [--display-name <TEXT>] [--description <TEXT>] [--publisher <NAME>] [-o <PATH>] [--template-path <PATH>] [--package <ID>] [--version <VERSION>] [--dry-run] [--force] [--no-prompts] [--format table|json]Two kinds of package
Section titled “Two kinds of package”| Kind | Published as | Choices |
|---|---|---|
extension (the default) |
An OCI artifact: the contract, an optional backend and an optional frontend, at fixed paths. | --backend is csharp, kotlin, go, typescript or none. --frontend is react, mount, screenplay (a Screenplay-authored component) or none. |
package |
An npm package with frontend components only. | --component is react or mount, and is required. A frontend-only package has no backend. |
Every combination is valid, including an extension with no backend and no frontend that only declares abilities.
What every package contains
Section titled “What every package contains”contract.playwith its manifest: display name, description, icon, marketplace images and requirements.- A placeholder icon and image.
- For each frontend component, a static HTML placeholder with no scripts and no external files, which is what
cratis extension verifyrequires of every placeholder. - A sample ability or component, with specifications.
- A README and the build and publish scripts.
The wizard and the flags
Section titled “The wizard and the flags”Run the command with no arguments in a terminal and it asks only what the flags did not answer: the name, the kind, the backend and frontend (or the component), the display name, the description and the publisher. A flag skips its question, so a partly answered command line asks the rest.
The wizard and the flags build the same request and check it with the same rules, so they create the same package:
cratis extension new -n Stripe --backend go --frontend react --publisher acmecreates what answering Stripe, extension, go, react and acme in the wizard creates. --no-prompts never asks,
and neither does a run with redirected input or output or inside an AI agent: it uses the flags and the defaults
(a full extension, no backend, no frontend, the display name spelled out from the name).
| Option | Meaning |
|---|---|
-n, --name |
The package name, a PascalCase identifier such as Stripe or OrderTracking. |
--kind |
extension (default) or package. |
--backend, --frontend |
The parts of a full extension. Default none. |
--component |
The component kind of a frontend-only package. |
--display-name, --description |
The manifest text. Default: the name spelled out, and The <name> extension. |
--publisher |
The OCI namespace or npm scope. Default example. |
-o, --output |
The folder to create. Default: a folder named after the package. |
--template-path |
Use the templates in a local folder instead of the template package. |
--package, --version |
Use another template package, or a version of it. Default: Cratis.Templates.Extensions, latest. |
--dry-run, --force |
List the files without writing them; write into a folder that is not empty. |
--format |
table (default) or json: the kind, name, output folder and created files. |
Exit codes
Section titled “Exit codes”| Code | Meaning |
|---|---|
0 |
The package was created (or listed, with --dry-run). |
1 |
Creation failed after the template was found. |
2 |
The request is invalid, or the template package or template could not be found or does not offer a choice. |
The template interface
Section titled “The template interface”The CLI does not generate files itself. It instantiates templates from the
Cratis/Templates package Cratis.Templates.Extensions through the same templating engine
as cratis new, so dotnet new can use them too. The agreement between the two:
| Full extension | Frontend-only package | |
|---|---|---|
| Template short name | cratis-extension |
cratis-extension-package |
| Name | The template’s sourceName, replaced by the package name. |
The same. |
| Choice symbols | Backend (csharp, kotlin, go, typescript, none), Frontend (react, mount, screenplay, none). |
Component (react, mount). |
| Text symbols | DisplayName, Description, Publisher. |
The same. |
The package folder also holds a .extensionignore that names what the build does not ship (sources, specifications, scripts), so that
cratis extension verify can tell them from what is shipped.
The CLI passes every symbol for the kind, always, and fails with exit code 2 when a template does not declare one or does
not offer a value, so a template and the CLI cannot drift apart silently. The contract and manifest are at the root of the
created folder, and the container build puts them at /extension/contract.play as the
contract requires.
The templates README lists them.
Related
Section titled “Related”cratis extension verify: check what was created.- Manage extension packages: restore, update and vendor the packages a model references.
- Extension contracts: what
contract.playdeclares. - Extension packages in Stage: how a package is admitted when it is loaded.