How to use
- Copy the installation command and review the source package before installing it in your own agent environment.
- Check the source document for required tools, credentials and supported hosts.
- Describe your input and desired deliverable; review the output against the source material.
npx skills add https://github.com/factorialco/factorial-code-skills --skill fcode-examplesBefore you start
- Installation does not include a model subscription, API allowance or permission to access your files.
- Repository stars and installation counts describe activity, not an independent quality or security test.
Rendered from the source repository. Headings, examples, code, tables, links, and referenced images are preserved.
Factorial Code — reference implementations
Worked, production-shaped examples of complete Factorial Code apps. Each reference in references/ walks through one real sample: its architecture, the key code, and how to adapt it. They complement the rule-focused skills (fcode-core-concepts, fcode-javascript/fcode-python, fcode-json-schema, fcode-forms, fcode-cli): those tell you how to write fcode code, this one shows what a finished app looks like.
Adapt, don't paste. These are patterns to rebuild for the user's actual vendor/requirements — rename slugs, variables, and mappings; drop what the use case doesn't need.
Which reference to read
| You are building… | Read |
|---|---|
| A marketplace integration that delivers Factorial data (payroll, leaves, …) to an external system | `references/integration-acme.md` |
| A custom app with install/uninstall lifecycle: setup form, webhooks, schedules | `references/custom-app-linear.md` |
| A one-shot automation: export/report generation, file processing | `references/utility-processes.md` |
| An app that connects a third-party account through OAuth from a form (no pasted API tokens) | `references/oauth-connect.md` |
Pattern index
Where to find a specific pattern, regardless of which app you build:
| Pattern | Reference |
|---|---|
Extending the outbound-sync base class (OutboundSync) | integration-acme |
| Per-item API push vs aggregate-to-file delivery | integration-acme |
Reporting per-item sync status (success / invalid / failed) | integration-acme |
| Webhook entry point authenticated by the platform, not in process code | integration-acme, custom-app-linear |
Activating webhook / form triggers in metadata.json, and protecting the webhook (webhook.authMode + the workspace webhookAuth, marketplace appRole) | integration-acme, custom-app-linear |
Multi-step setup form (nextProcessId chaining) | custom-app-linear |
Dynamic form dropdowns via preRenderProcess + #/variables | custom-app-linear |
OAuth connect button in a form (ui:widget: "oauth"): pre-render calls fcode.oauth.start(), the platform runs both redirect legs and invokes the completion process, which exchanges the code and 302s to the SDK callback page; onComplete: "reload" renders the connected state | oauth-connect |
| Creating webhooks + schedules at install, recording them for uninstall | custom-app-linear |
| Polling with a datastore cursor + idempotency (dedup map, or vendor upsert when available) | custom-app-linear |
| Best-effort uninstall / teardown | custom-app-linear |
Storage upload + signed download URL + email with fcode.sendMail | utility-processes |
| Reading a form-uploaded file from Storage | utility-processes |
Calling the Factorial API SDK (factorial-sdk module) | all three |
The base workspaces (always present — never recreate)
Every fcode App workspace inherits shared modules from the base apps. Import them with fcode.import(...) / fcode.import_module(...); do not reimplement them:
| Module | From | Provides |
|---|---|---|
factorial-sdk | base-app | createFactorialClient() — authenticated @factorialco/api-client / factorial-api-client instance |
factorial-utils | base-app | getCompanyId(), setupWebhook(), listWebhookSubscriptions(), deleteWebhookSubscription() |
fcode-forms | base-app | Form-schema builders: selectField(), toOptions(), … |
mail-helper | base-app | brandedHtml() for styled email bodies |
error-handler | base-app | Shared error handling |
outbound-sync | base-integration-app | OutboundSync base class for marketplace syncs |
Integration apps inherit base-integration-app (which inherits base-app); custom apps inherit base-app directly.
Note: the fcode-forms module above (form-schema builders you fcode.import) is unrelated to the fcode-forms skill, which documents embedding forms on webpages.
The references keep code compact and omit routine logging; real implementations should log verbosely through the shared fcode-logs module (see fcode-javascript / fcode-python).
Language variants
Every sample exists in JavaScript (Node.js v22) and Python (3.13) with identical structure and behavior. References show JavaScript; the Python variant differs only in idiom (main.py, fcode.import_module, fcode.send_mail, snake_case) — see fcode-python.
