Skip to content

registry.md

Latest commit

 

History

History
87 lines (64 loc) · 3.75 KB

registry.md

File metadata and controls

87 lines (64 loc) · 3.75 KB

Registry

StackFoundry modules are source-delivered capabilities. The public wedge is API SaaS: API keys, usage tracking, quotas, credits, billing, docs, and webhooks as editable source.

Each module has:

  • module.json
  • docs.md
  • skill/SKILL.md
  • tests/checklist.md
  • source files

Recipes live in registry/recipes/*.json and describe install order across modules. Presets install bundles; recipes explain the architecture. Modules remain the product.

Manifest Fields

  • name: stable module id
  • type: module, integration, or page
  • category: high-level grouping
  • dependencies: runtime packages
  • devDependencies: development packages
  • registryDependencies: other modules/items required first
  • env: required environment variables
  • files: files installed into the target app
  • drizzle: schema/migration metadata
  • maintenance: maintenance skill and review metadata
  • status: ready, planned, experimental, stable, or deprecated

Registry Model

StackFoundry follows a source registry pattern: source blocks are described by JSON, files are copied into the consumer app, and the consumer owns the result.

StackFoundry adapts that model for production SaaS systems instead of UI-only components. A block may include routes, server helpers, schema files, env examples, docs, tests/checklists, and maintenance skills.

Registry Principles

  • Modules install source code, not opaque package wrappers.
  • Recipes explain the path; presets only compose modules.
  • Provider modules adapt services into shared domain systems.
  • Recipes define complete workflow paths across modules.
  • Installers must produce enough metadata for safe diff/update workflows.
  • Public modules should avoid private assumptions about a single company or app.

Safety

Installers must not overwrite modified user files silently. The installer should track file hashes and support diff/update flows.

Local Prototype

pnpm registry:list
pnpm registry:presets
pnpm stackfoundry recipes
pnpm stackfoundry recipe api-saas-starter
pnpm registry:doctor
pnpm registry:build
pnpm stackfoundry add recipe api-saas-starter --target /path/to/app --dry-run
pnpm stackfoundry add recipe api-saas-starter --target /path/to/app
pnpm stackfoundry diff api-keys --target /path/to/app

Public Build Output

The build command generates registry-compatible JSON files under:

public/r/
  registry.json            # registry index
  drizzle-postgres.json
  api-keys.json
  stripe-billing.json
  provider-adapters.json     # installable aggregate preset block
  presets/
    next-saas.json         # StackFoundry preset manifest
  recipes/
    api-saas-starter.json  # human-readable recipe and install order

This mirrors the source-registry pattern: /r/registry.json is the registry index, while registry item JSON embeds file contents and target paths. Module metadata stays in registry/modules/<module>/module.json.

Generated public module and aggregate preset items are registry-compatible registry:block files using the shadcn registry item schema. Registry dependencies are emitted as absolute URLs so compatible registry clients can resolve StackFoundry dependencies.

Files under /r/presets/*.json are StackFoundry preset manifests for tooling and inspection. They are not installable registry item payloads; use /r/<preset>.json to install a preset bundle.

Files under /r/recipes/*.json are StackFoundry recipe manifests for human-readable architecture, outcomes, and staged install order. Recipes can also be installed through the StackFoundry command with stackfoundry add recipe <name>.

The build writes canonical generated output to public/r and mirrors it to apps/web/public/r. Vercel serves /r/*.json directly from the Next app as static JSON; no redirect is required.