From c5962fc3818000534a3a252876d2e0e24e9df656 Mon Sep 17 00:00:00 2001 From: itowlson Date: Wed, 4 Feb 2026 13:21:43 +1300 Subject: [PATCH] Target environment docs Signed-off-by: itowlson --- content/v3/api-guides-overview.md | 18 ++++++++++++++++++ content/v3/manifest-reference.md | 2 ++ 2 files changed, 20 insertions(+) diff --git a/content/v3/api-guides-overview.md b/content/v3/api-guides-overview.md index 2734fb5d..86d08386 100644 --- a/content/v3/api-guides-overview.md +++ b/content/v3/api-guides-overview.md @@ -5,6 +5,7 @@ date = "2023-11-04T00:00:01Z" url = "https://github.com/spinframework/spin-docs/blob/main/content/v3/api-guides-overview.md" --- +- [Targeting a Deployment Environment](#targeting-a-deployment-environment) The following table shows the status of the interfaces Spin provides to applications. @@ -24,3 +25,20 @@ The following table shows the status of the interfaces Spin provides to applicat | [MQTT Messaging](./mqtt-outbound) | Experimental | For more information about what is possible in the programming language of your choice, please see our [Language Support Overview](./language-support-overview). + +## Targeting a Deployment Environment + +Some Spin runtimes may support a different set of APIs from those listed above, or may support only older versions. For example, some runtimes might not support SQLite, or Serverless AI; or the Spin 3.2 runtime does not support the most recent PostgreSQL API introduced in Spin 3.4. This is an important consideration when writing a Spin application that will run in a different environment from your development environment: you do not want to depend on SQLite if you will have to deploy to an environment without it. + +You can tell the Spin CLI about the environment (or environments) that you plan to deploy into using the `application.targets` field in `spin.toml`. If you do this, `spin build` verifies the set of APIs used by your components against each listed environment. If a component uses APIs that wouldn't be supported, `spin build` will warn you. + +For example, here is how to specify that you want your application to be compatible with `spin up` version 3.2: + +```toml +# spin.toml + +[application] +targets = ["spin-up:3.2"] +``` + +For the other runtime environments such as SpinKube or commercial clouds, see the documentation for those projects for their environment IDs. diff --git a/content/v3/manifest-reference.md b/content/v3/manifest-reference.md index ca0d69f8..6f8dd7f3 100644 --- a/content/v3/manifest-reference.md +++ b/content/v3/manifest-reference.md @@ -84,6 +84,7 @@ The only variables permitted in manifest expressions are application variables. | `version` | Optional | String | The version of the application. The must be a string of the form `major.minor.patch`, where each element is a number. | `"1.0.5"` | | `description` | Optional | String | A human-readable description of the application. | `"The best app for all your world-greeting needs"` | | `authors` | Optional | Array of strings | The authors of the applications. If present, this must ba an array, even if it has only one entry. | `["Jane Q Hacker ()"]` | +| `targets` | Optional | Array of strings | The environments that the application is expected to be compatible with. | ["spin-up:3.2"] | | `trigger` | Optional | Table | Application-global trigger settings. See [The `application.trigger` Table](#the-applicationtrigger-table) below. | `[application.trigger.redis]`
`address = "redis.example.com"` | ## The `application.trigger` Table @@ -183,6 +184,7 @@ The value of each key is a table with the following fields. | `environment` | Optional | Table | Environment variables to be set for the Wasm module. This is a table. The table keys are user-defined; the values must be strings. | `{ DB_URL = "mysql://spin:spin@localhost/dev" }` | | `build` | Optional | Table | The command that `spin build` uses to build this component. See [The `component.(id).build` Table](#the-componentidbuild-table) below. | `[component.cart.build]`
`command = "npm run build"` | | `variables` | Optional | Table | Application configuration values to be made available to this component. The table keys are user-defined; the values must be strings, and may use template notation as described under [Application Variables](variables#adding-variables-to-your-applications). | `[component.cart.variables]`
`api_base_url = "https://{{ api_host }}/v1"` | +| `targets` | Optional | Array of strings | The environments that the component is expected to be compatible with. The default is the application `targets`. | ["spin-up:3.2"] | | `dependencies_inherit_configuration` | Optional | Boolean | If true, dependencies can invoke Spin APIs with the same permissions as the main component. If false, dependencies have no permissions (e.g. network, key-value stores, SQLite databases). The default is false. | `false` | | `dependencies` | Optional | Table | Specifies how to satisfy Wasm Component Model imports of this component. See [Using Component Dependencies](writing-apps.md#using-component-dependencies). | `[component.cart.dependencies]`
`"example:calculator/adder" = { registry = "example.com", package = "example:adding-calculator", version = "1.0.0" }` |