Modules

A Module is a reusable capability — booking, payments, shared UI, and similar building blocks. It is not a mini app. Modules do not get their own customer-facing URL, icon, or launch identity. Those belong to Surfaces. Modules travel between apps in your organization. Surfaces present experiences inside one app. See One Product, One App for how they fit together.

​

Start from Modules

When creating a new app (with Alpha access):

1. Open New App.
2. Choose Start from Modules.
3. Select the Modules you want from the catalog.
4. Review the summary — required dependencies are included automatically.
5. Submit your first build request.

Starting from Modules and starting from a Blueprint are mutually exclusive.

​

Required dependencies

If a Module needs another Module to work, Stardeck includes those required dependencies in the composition for you. The creation summary shows what you picked and what was added automatically.

​

Setup progress, retry, and reconfirmation

After you submit, Stardeck installs the selected Modules before your first agent turn:

1. Each Module is installed in order.
2. Progress stays attached to the new project so you can see what finished and what didn’t.
3. If setup fails partway through, the project remains available with a retryable setup state. Use Retry setup to continue from the failure.
4. If a Module’s source changed since you selected it, retry may ask you to confirm the newer version before continuing.

The project agent starts only after setup reaches a ready state. It begins its first turn by connecting and testing the installed Modules, then continues with your original build request.

​

Install into an existing app

Open the app, go to Settings → Modules, and browse the catalog: Use Install on a catalog row to ask the project agent to install that Module into the current app. Home Modules can’t be installed again into the same app.

​

Installation vs connection

Module work has two steps:

1. Installation — Stardeck brings the reusable capability into the app, composes its declared routes, APIs, contributions, translations, and active optional integrations, then validates the result.
2. Connection — the project agent does the app-specific wiring: how the capability shows up in this product, how it fits your screens and data, and how to test that it works together.

Declared Module pages and API endpoints are mounted automatically during installation. Product-specific integration is still a separate step: navigation, permissions, app-level layouts and providers, and the way the capability fits your product remain owned by the app. Expect the agent to complete and test that connection work after install — whether you started from Modules or installed later from the Modules tab.

​

What Stardeck composes automatically

For the final set of installed Modules, Stardeck builds one deterministic composition:

• Pages and APIs — declared pages and endpoint handlers are connected to the app’s routes.
• Surface contributions — Module UI contributions are resolved only into declared slots; duplicate or unknown contributions block installation.
• Optional integrations — an enhancement participates only when both its owning Module and peer Module are installed.
• Translations — Module copy is combined with the app’s supported languages. Missing translated Module copy falls back to English and is reported as an installation note.
• Server initialization — active optional integrations initialize once before their endpoints handle requests.

These generated connections are maintained by Stardeck when Modules are installed or updated. The project agent should change the Module’s source or the app-owned extension points, not edit generated connections directly.

​

Validation and compatibility

Before a catalog Module is installable, Stardeck validates its manifest, portable structure, public import boundaries, and required checks. When you install or update Modules in an app, composition validation also checks that the selected set can work together. It catches incompatible dependency combinations and collisions in claimed API paths, app routes/mounts, and Surface contribution locations. Required automated workflows for the active composition must resolve and pass. These include Module-owned product workflows plus platform checks for endpoint declarations, Surface slot resolution, end-to-end test selection, and translation composition. Optional enhancements only participate when they are active for Modules already in that composition. If the target app has a locale the Module does not ship, Stardeck uses the Module’s English copy and surfaces the gap as an installation note — it does not refuse the install. Passing validation means the Module is structurally and compositionally compatible. It is not the same as finished product integration. The project agent must still connect the Module into this app and test that it works together.

​

What Modules are not for

• A distinct audience or device experience → create a Surface
• A complete starting product foundation → use a Blueprint
• A genuinely independent product with its own owners or release cadence → create a separate app