@helyx/module-example

@helyx/module-example is a publishable, standalone starter for one independent Helyx module outcome. Its default runtime is deliberately small; optional capability examples remain unregistered until an author deliberately adopts their contracts.

Availability and deployment

The package is a Testing authoring template and supports Hosted and Self-Hosted deployments without credentials. Installing or copying it does not enable a module for any server, promote a release, or make optional examples active.

Use Node.js 24–26 and npm 11. Copy the package to a new module directory, remove generated dist/ output, then follow the template checklist. Replace the package name, manifest identity, descriptions, versions, repository metadata and feature behavior before release.

What it does

The active starter demonstrates a parsed manifest, a small composition root, canonical constants/contracts/configuration/presentation boundaries, one dashboard setting and one enabled-server command with a unique permission identity.

Optional examples live below src/optional/ and are not exported or composed by src/index.ts:

src/
|-- index.ts                 composition only
|-- commands.ts              command metadata and delegation
|-- configuration.ts         canonical setting validation
|-- constants.ts             stable identity and bounds
|-- contracts.ts             default permission catalogue
|-- presentation.ts          adapter-safe response construction
`-- optional/                capabilities to adopt only when required
    |-- event.ts
    |-- lifecycle.ts
    |-- managed-resource.ts
    |-- migrations/0001_create_example_notes.sql
    |-- privacy.ts
    |-- records.ts
    |-- safe-errors.ts
    `-- scheduled-task.ts

Do not combine unrelated customer outcomes to reuse this structure. A real module adds only the capability files its own outcome needs.

Commands and interactions

/example replies privately with the configured greeting and an optional normalized name. It uses registrationPolicy: "enabled-guild", the unique permission ID example.run, an explicit public default policy and a bounded per-user rate limit.

The starter has no buttons, selects or modals. Add them only when the feature needs them; use stable namespaced IDs, expiry/replay protection and matching manifest/adapter tests.

Dashboard configuration

The active dashboard contract contains one greeting string setting with the same 1–80 character limits enforced by the runtime validator. Browser input remains untrusted.

Dashboard appearance is inherited from shared core rendering: an unboxed header, standard surface panel and soft inset field groups. Do not add a module-owned stylesheet. Review all six dashboard themes at narrow and wide widths, including information snippets, keyboard focus, Permissions and save/error states. Specialised workspaces must preserve that visual language without removing their task-specific controls.

The optional managed-resource example demonstrates bounded listing, optimistic revisions, safe error mapping and labelled resource details. It is intentionally absent from the active manifest and module definition. Before enabling it, add the resource declaration to the manifest, compose the implementation, add a real record-service repository and move the reviewed SQL file into the module’s root migrations/ directory.

Discord requirements

The active command requires only a guild installation and no Discord permission or privileged intent. It does not post publicly and explicitly disables user mentions in its response.

Optional events or Discord writes require a fresh capability review. Declare only the exact manifest permissions, gateway events, intents and deployment prerequisites the adopted behavior uses.

Data, privacy and retention

The active starter stores no module records or personal data. Its manifest declares containsPersonalData: false, an empty collection list and provider version 1; therefore no executable privacy provider is registered by default.

The optional record, migration and privacy examples show where data contracts belong. If a real module retains Discord identities or identifying content, update the manifest declaration, register the provider at the same version, cover disabled-module records, and document export, erasure, retention and Discord-artifact behavior before release.

Operations and failure behavior

The active starter supplies the framework-required no-op start and stop hooks and needs no health hook because it owns no runtime state or dependency. The optional lifecycle example demonstrates retained repeatable state and dependency-aware health; the optional scheduled task demonstrates validated versioned payloads, bounded retries and cancellation-aware execution.

Run the standalone gates before packaging:

npm install
npm run typecheck
npm test
npm pack --dry-run

Tests do not connect to Discord, PostgreSQL or production Helyx services. A real release still needs applicable packed lifecycle, database, adapter and controlled Discord evidence.

Documentation and support

Use the packaged template checklist for the copy/build review. The Helyx SDK and manifest packages are the public integration boundary; never import private applications, discord.js, database drivers, shard internals or another module’s private source.

Report template defects through the Helyx issue tracker. Public operator documentation is available from Helyx Docs.