Use an extension in a Screenplay model
This guide adds an extension package to a model, uses what it provides and keeps it current. For what the pieces are, read the extensions overview first.
The examples use a payment package. Replace the name with the package you use.
1. Add a system that references the package
Section titled “1. Add a system that references the package”A system names the business system. Its extension line names the package:
secret StripeSecretKey description "The key the payment provider issues"
system Payments description "The card payment provider" extension "cratis/stripe" version 2 setting secretKey from secret StripeSecretKey setting statementDescriptor = "Acme Shop" activation on demand idle after 10 minutes- With no
version, the reference means the latest release.version 2means the latest 2.x,version 2.3.1exactly that release. All forms are listed in Referencing a package. - A system that names an extension declares no abilities of its own. Declaring one is
PLAY1106. - The reference is a catalog short name (
"cratis/stripe"), a full OCI reference ("ghcr.io/acme/extension-ledger") or annpm:package for a frontend-only package.
2. Restore it
Section titled “2. Restore it”The compiler never fetches a package. It reads each contract from screenplay.lock and a digest-keyed cache, so pin and restore first:
cratis extension restoreA reference the lock does not have yet is resolved to the newest release in its range, checked, stored in the cache and written to screenplay.lock. Commit the lock. Until you restore, the compiler reports PLAY1107 (not in the lock) or PLAY1108 (not restored). The language server and MCP server only warn and restore for you when SCREENPLAY_EXTENSION_SOURCE names a package source.
In CI, use cratis extension restore --locked. It never changes the lock and fails for a reference the lock does not pin or pins for another range. For a model folder without network access, screenplay restore reads packages from a directory; see Restore extensions. The CLI reference is cratis extension restore.
Naming a package is not trusting it. Restore refuses a package whose publisher is not on the allow-list in .cratis/extensions.json; in an interactive terminal it asks once. The rules are in the CLI’s trust section.
3. Configure settings and secrets
Section titled “3. Configure settings and secrets”Each setting the contract declares is mapped in the model to a literal (for settings that are not secret) or to a named secret. A setting the model does not mention is read from configuration under systems.<System>.<setting>. The model never holds a secret’s value. See System settings and named secrets.
Give the values to the environment, then list what is missing:
cratis config --requires ./modelcratis config set secrets.StripeSecretKeycratis config set reads the secret from standard input or a prompt. The CLI documents environments in Environments.
4. Invoke abilities
Section titled “4. Invoke abilities”The abilities of the package are now abilities of Payments. Invoke one from a reaction, a workflow action or a state’s entering line, and handle each way it can end:
reaction TakePayment runs as system when OrderPlaced orderId total invokes Payments.CreatePaymentIntent amount = total orderId = orderId on returned produces PaymentRequested clientSecret = $result.clientSecret on failed produces PaymentFailed reason = $failure.reasonEvery input the ability declares is mapped once, and on <Outcome> handles an outcome the contract declares. The rules and diagnostics are in Invoke an ability. The effect class of the ability decides retries: a once ability is never retried after an attempt that may have reached the provider. See Choose the effect class.
A contract can also declare triggers. They become triggers of the system, so a reaction can start with when Payments.PaymentSucceeded.
5. Place components on screens
Section titled “5. Place components on screens”A screen places a component by naming the system and the component, never the package, and handles the signals the contract says it raises:
component Payments.PaymentForm payment property amount = "10" on succeeded execute ConfirmPayment with paymentIntentId from signal.paymentIntentId on failed notify warning "The payment failed"The component, its properties, the signals handled with on and the values read as signal.<value> are checked against the contract. See Extension components.
6. Specify it
Section titled “6. Specify it”A reaction specification scripts what an ability answers while the reaction runs, so nothing external is called. The lines are given <System>.<Ability> followed by returns, answers <Outcome> or fails "<reason>":
given Carrier.BookPickup returns trackingNumber = "TRK-1"given Carrier.BookPickup answers NoCapacitygiven Carrier.BookPickup fails "carrier unavailable"Each line is checked against the system’s declared ability, outcomes and returned fields (PLAY1017). then invokes <System>.<Ability> asserts the call. See Ability answers.
7. Run it
Section titled “7. Run it”cratis run ./model -e developmentBefore Docker starts, cratis run checks that every extension line is pinned in the lock, that the publisher is allowed, that the contracts are in the cache and that the environment holds every setting and secret. Nothing starts when one is refused. Stage then fetches each package itself from the lock, verifies it again, and starts each backend in its tier when it is first needed. See cratis run and Stage’s Extension packages.
8. Update it later
Section titled “8. Update it later”cratis extension update --dry-runcratis extension updateupdate moves each reference to the newest release in its range and shows how the contract changes: what it adds, what it no longer offers and every use in your model that the new contract does not offer. When a use would break, the lock is left alone unless you pass --allow-incompatible. To update one extension, name its system: cratis extension update Payments. See cratis extension update and Provider compatibility.
To work offline or from a private mirror, copy the locked packages with cratis extension vendor; the vendored extensions folder beside the lock is read before the user cache.
- Building an extension creates a package of your own.
- Systems and abilities and Extension contracts are the references.