Author hosting integrations in TypeScript
Dette indhold er ikke tilgængeligt i dit sprog endnu.
You can write a hosting integration in TypeScript instead of C#. The integration exports methods, such as addNuxtApp, that appear in the generated SDK of a consuming AppHost, just like the methods of a C# integration. Under the hood, Aspire runs your integration in its own Node.js process and routes each call to it, so your code configures the same resource model as a C# integration.
To make a C# integration available to TypeScript AppHosts instead, see Multi-language integrations.
Choose a library or an exported integration
Section titled “Choose a library or an exported integration”You can share TypeScript AppHost code in two ways:
- Plain library: An npm package that exports ordinary functions, such as
addKafka(builder, ...). A TypeScript AppHost imports and calls them directly. No opt-in is required, but the functions aren’t added to the builder and AppHosts in other languages can’t use them. - Exported integration: A package that marks its functions with
AspireExportand runs as an integration host. Consuming AppHosts get fluent builder methods, such asbuilder.addNuxtApp(...), in their generated SDK. This page describes this option.
Author an integration
Section titled “Author an integration”An integration is a library package, not an app. It has its own aspire.config.json so that aspire restore can generate the typed Aspire SDK that your code builds on, and an entry point that starts the integration host.
-
Create a package with an aspire.config.json file that declares the TypeScript language and the hosting packages your integration uses. Don’t set an AppHost path:
aspire.config.json {"appHost": {"language": "typescript/nodejs"},"packages": {"Aspire.Hosting.JavaScript": ""}} -
Add a package.json file. Aspire starts the integration host with
node --import tsx, so includetsxas a dependency:package.json {"name": "@contoso/aspire-nuxt","version": "0.1.0","type": "module","dependencies": {"tsx": "^4.21.0","vscode-jsonrpc": "8.2.1"}} -
Run
aspire restorein the package directory. It generates the SDK in .aspire/modules/, including theAspireExport,defineIntegration, andrunIntegrationHosthelpers. -
Write your integration. Wrap each method with
AspireExportand use the generated builder APIs to configure resources. Theprojectiondescribes the method’s target, parameters, and return type so that consuming AppHosts can generate a typed method for it. ThetypeIdof each Aspire type matches the handle types in the generated .aspire/modules/aspire.mts file. Finally, group the methods withdefineIntegration:src/integration.ts import type {DistributedApplicationBuilder,JavaScriptAppResource,} from '../.aspire/modules/aspire.mjs';import {AspireExport,defineIntegration,type AspireTypeRef,} from '../.aspire/modules/base.mjs';const builderType: AspireTypeRef = {typeId: 'Aspire.Hosting/Aspire.Hosting.IDistributedApplicationBuilder',category: 'Handle',isInterface: true,};const appType: AspireTypeRef = {typeId: 'Aspire.Hosting.JavaScript/Aspire.Hosting.JavaScript.JavaScriptAppResource',category: 'Handle',};const stringType: AspireTypeRef = { typeId: 'string', category: 'Primitive' };interface AddNuxtAppArgs {builder: DistributedApplicationBuilder;name: string;appDirectory: string;}export const addNuxtApp = AspireExport<AddNuxtAppArgs, JavaScriptAppResource>({id: '@contoso/aspire-nuxt/addNuxtApp',method: 'addNuxtApp',description: 'Adds a Nuxt application.',projection: {capabilityKind: 'Method',targetTypeId: builderType.typeId,targetType: builderType,targetParameterName: 'builder',returnsBuilder: true,returnType: appType,parameters: [{ name: 'name', type: stringType },{ name: 'appDirectory', type: stringType },],},},async ({ builder, name, appDirectory }) => {return await builder.addJavaScriptApp(name, appDirectory, { runScriptName: 'dev' }).withHttpEndpoint({ env: 'PORT' }).withEnvironment('HOST', '0.0.0.0');},);export default defineIntegration({name: 'NuxtIntegration',capabilities: [addNuxtApp],});Give each method a unique
id. Consuming AppHosts call the method by itsmethodname. -
Add an entry point that starts the integration host:
src/host.ts import nuxtIntegration from './integration.js';import { runIntegrationHost } from '../.aspire/modules/integration-host.mjs';await runIntegrationHost({packageName: '@contoso/aspire-nuxt',integrations: [nuxtIntegration],});runIntegrationHosthandles the connection to the AppHost, registration, and dispatching calls to your methods.
To distribute the integration, compile it and publish or pack it as an npm package. Include the compiled output and the generated .aspire/modules/ SDK, as the preview @aspire/nuxt package does.
Consume an integration
Section titled “Consume an integration”-
Enable the feature in the AppHost directory:
Aspire CLI aspire config set features.experimentalHostingIntegrations trueWithout this setting, the CLI rejects AppHosts that reference npm hosting integrations and shows the command to enable them. Running the command adds the
featuressetting shown in the next step to aspire.config.json. -
Install the integration package, and then add it to the
packagessection of the AppHost’s aspire.config.json file. Setsourcetonpmandpathto the integration’s host entry point, relative to aspire.config.json:aspire.config.json {"appHost": {"path": "apphost.mts","language": "typescript/nodejs"},"features": {"experimentalHostingIntegrations": true},"packages": {"Aspire.Hosting.JavaScript": "","@contoso/aspire-nuxt": {"source": "npm","path": "./node_modules/@contoso/aspire-nuxt/dist/src/host.js"}}}During development,
pathcan also point to a TypeScript entry point in a local folder, such as./nuxt-integration/src/host.ts. -
Run
aspire restore. The CLI installs the integration’s dependencies, starts its host, and adds its methods to the generated SDK. -
Call the methods from your AppHost like any other builder method:
apphost.mts import { createBuilder } from './.aspire/modules/aspire.mjs';const builder = await createBuilder();const api = await builder.addJavaScriptApp('api', './api', { runScriptName: 'start' }).withHttpEndpoint({ env: 'PORT' });await builder.addNuxtApp('web', './web').withReference(api).waitFor(api);await builder.build().run();
Current limitations
Section titled “Current limitations”- TypeScript is the only supported language for authoring these integrations.
- You write the
projectionmetadata for each method by hand. aspire adddoesn’t find npm integrations. Add them to aspire.config.json manually.- The preview
@aspire/nuxtintegration isn’t published to npm. To try it, build and pack it from the Aspire repository. - If an integration host that registered callbacks stops unexpectedly, the AppHost stops and you need to start it again.
See also
Section titled “See also”- Multi-language integrations: Export C# hosting integrations to TypeScript AppHosts.
- TypeScript AppHost: Build an AppHost in TypeScript.
- Custom resources: Create custom resource types.