Skip to content

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.

Terminal window
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]
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.

  • contract.play with 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 verify requires of every placeholder.
  • A sample ability or component, with specifications.
  • A README and the build and publish scripts.

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:

Terminal window
cratis extension new -n Stripe --backend go --frontend react --publisher acme

creates 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.
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 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.