App Templates and Contribution Workflow
Purpose and Scope
This page explains how Cal.diy contributors should use app templates when developing app-store integrations locally. In this context, a template is a reusable scaffold that the app-store CLI can offer to a developer, while an app integration is the finished provider package that appears in the app-store experience. The source evidence shows a practical but evolving workflow: the CLI README points contributors to the app-building guide, records several local-development TODOs, and explicitly connects app work to the app contribution guidelines. Sources: packages/app-store-cli/README.md
The most important workflow rule is that template readiness is not only about files existing on disk. A template becomes a selectable CLI option only when the utility can discover the directory, accept its name as an app name, read its configuration, and turn that metadata into a menu record. That makes the template folder, naming convention, and configuration metadata part of the contributor-facing contract. A template that looks plausible in the repository can still be invisible to the CLI if it fails one of those checks. Sources: packages/app-store-cli/src/utils/templates.ts
Relevant Source Files
- packages/app-store-cli/README.md — Provides the local app-building entrypoint, records known CLI workflow gaps, and links contributors to app contribution guidance.
- packages/app-store-cli/src/utils/templates.ts — Implements template discovery, name validation, configuration parsing, and the exported template option shape used by the CLI.
- packages/app-store/templates/_auth-based-app/README.md — Documents that the auth-based app template is still a TODO and needs an ideal existing app as a reference.
- packages/app-store/templates/_calendar/README.md — Documents that calendar app templates are not streamlined and still require substantial work.
Core Primitives
The template system has four core primitives. The first is the template directory under the app-store templates area. The second is the app-name check, which is applied to a directory name before it can be treated as a candidate. The third is the template configuration file, which is parsed as structured metadata. The fourth is the exported selection object, which contains a human-readable label, a value that points back to the directory, and a category derived from the configuration. Sources: packages/app-store-cli/src/utils/templates.ts
These primitives are useful because they separate experimentation from contribution. A contributor can create a local folder while exploring an integration, but the CLI does not automatically bless every folder as a supported scaffold. Discovery first filters for real directories and acceptable names, then tries to parse the configuration file. If parsing fails or the file is not present, the utility returns no option for that candidate. The resulting exported list is therefore a curated view of discoverable templates, not a raw listing of every folder. Sources: packages/app-store-cli/src/utils/templates.ts
Template Discovery Contract
The discovery contract is intentionally compact. The utility reads the configured templates path, keeps only entries that are directories, and requires the directory name to satisfy the app-name helper. For each remaining candidate, it reads a configuration file from that template folder and parses it as JSON. The display label is taken from the configuration description, the option value is the directory name, and the category is the first configured category. This keeps the CLI selector small while still giving contributors enough metadata to distinguish scaffold types. Sources: packages/app-store-cli/src/utils/templates.ts
| Template element | Source-backed behavior | Contributor implication |
|---|---|---|
| Directory | Must be a directory and pass the app-name check | Use a directory name that follows the expected app slug pattern |
| Configuration | Parsed from the template folder | Keep metadata valid before expecting the template to appear |
| Description | Becomes the selection label | Write a clear description for the scaffold |
| First category | Becomes the option category | Put the primary category first |
| Parse failure | Candidate becomes null and is filtered out | Treat visibility in the CLI as an acceptance check |
The quiet filtering behavior is an important edge case during review. A malformed configuration, a missing configuration file, or a name that does not satisfy the helper can all prevent a template from appearing, but the exported list simply omits that entry. That is convenient for incomplete folders, yet it can hide accidental mistakes. Contributors should confirm that a new or changed template is discoverable through the CLI path before documenting it as usable. A pull request should not rely only on the presence of a folder in the templates directory. Sources: packages/app-store-cli/src/utils/templates.ts
Local Contribution Flow
A practical contribution loop starts by choosing the closest template family, then replacing scaffold placeholders with provider-specific behavior, credentials, callbacks, assets, and user-facing documentation. The repository CLI README does not embed the full app-building tutorial; instead, it directs readers to the external app-building guide and the app contribution guidelines. Within this repository page, the actionable source-backed step is to make the local scaffold visible and honest: its name must be acceptable, its metadata must describe the intended integration type, and its category should help the next developer select it correctly. Sources: packages/app-store-cli/README.md, packages/app-store-cli/src/utils/templates.ts
After creating or modifying a scaffold, test the workflow from the perspective of a self-hosted administrator who will eventually configure the integration. The official documentation template for features emphasizes overview, how-to-use steps, configuration options, common use cases, and FAQ content. App integrations benefit from the same shape because users need to understand provider setup, secrets, redirect paths, and expected behavior before enabling an app. Treat the template as the beginning of both implementation work and documentation work, not just a way to copy files into a new directory.
The CLI README’s TODO list is also a guide to current workflow limitations. It notes that app-store watch and app-store commands should eventually be merged, that API validation should be skippable for testing so credentials can be created without a provider API, and that local editing from the Cal app itself, including asset uploads, is still desired. These TODOs matter because a contributor may need manual verification steps while developing locally. If a local workflow feels unfinished, check whether it matches one of these recorded limitations before assuming the integration itself is broken. Sources: packages/app-store-cli/README.md
Template Readiness by App Type
The auth-based app template should be treated as a placeholder rather than a complete recipe. Its README asks maintainers to identify an ideal existing auth-based app and add it as the model. That means contributors building OAuth-style or credential-based integrations should not assume this template captures all required screens, callbacks, credential handling, or documentation expectations. Use the folder as a signal that an auth scaffold is intended, but compare against a working integration pattern and document any assumptions until the reference model is established. Sources: packages/app-store/templates/_auth-based-app/README.md
The calendar template carries a similar caution but for a different reason. Its README states that calendar apps are not streamlined and that a useful template still needs a good amount of work. Calendar integrations often have provider-specific availability, sync, credential, callback, and permissions concerns, so a thin scaffold can be misleading if it suggests the category is uniform. When contributing calendar work, keep the template metadata conservative, document provider setup carefully, and avoid presenting the template as a complete implementation guide until the category has been streamlined. Sources: packages/app-store/templates/_calendar/README.md
Contribution Checklist
- Confirm the template directory is a real directory under the templates area.
- Confirm the directory name satisfies the same app-name check used by the CLI discovery utility.
- Add valid configuration metadata with a useful description and an appropriate first category.
- Verify the template appears in the CLI’s selectable template list before marking it supported.
- For auth-based templates, document the reference pattern because the current README is still a TODO.
- For calendar templates, expect extra design and validation work because the current README says the category is not streamlined.
- Review the app contribution guidance linked from the CLI README before preparing the final pull request.
Next Steps
Read the broader app-store CLI reference next if you need the command-level workflow around creating, editing, deleting, or generating app integrations. Then review provider-specific integration pages for examples of the operational details a useful app guide should include, such as credentials, redirect paths, environment variables, and admin setup steps. For template contributions, the concrete acceptance test is simple: the scaffold should be discoverable by the CLI, accurately described by its metadata, honest about unfinished areas, and clear enough that the next contributor does not need to reverse-engineer hidden assumptions. Sources: packages/app-store-cli/README.md, packages/app-store-cli/src/utils/templates.ts