@lowdefy/docs-content 6.0.0 → 7.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +1 -0
- package/content/actions/downloadcsv.md +1 -1
- package/content/actions/emailotpsend.md +58 -0
- package/content/actions/emailotpverify.md +79 -0
- package/content/actions/getlocalstorage.md +43 -0
- package/content/actions/link.md +47 -1
- package/content/actions/login.md +25 -5
- package/content/actions/logout.md +7 -5
- package/content/actions/magiclinkverify.md +117 -0
- package/content/actions/pdfmake.md +2 -2
- package/content/actions/posthogalias.md +29 -0
- package/content/actions/posthogcapture.md +49 -0
- package/content/actions/posthogcapturepageleave.md +38 -0
- package/content/actions/posthogfeatureflag.md +50 -0
- package/content/actions/posthoggroup.md +37 -0
- package/content/actions/posthogidentify.md +54 -0
- package/content/actions/posthoginit.md +96 -0
- package/content/actions/posthogoptin.md +29 -0
- package/content/actions/posthogoptout.md +29 -0
- package/content/actions/posthogpageview.md +37 -0
- package/content/actions/posthogreloadfeatureflags.md +47 -0
- package/content/actions/posthogreset.md +28 -0
- package/content/actions/posthogsetpersonproperties.md +36 -0
- package/content/actions/removelocalstorage.md +28 -0
- package/content/actions/resetvalidation.md +5 -3
- package/content/actions/setdarkmode.md +3 -3
- package/content/actions/setglobal.md +2 -0
- package/content/actions/setlocale.md +1 -1
- package/content/actions/setlocalstorage.md +34 -0
- package/content/actions/setstate.md +2 -0
- package/content/actions/validate.md +7 -4
- package/content/adapter-reference/mongodbauthadapter.md +46 -0
- package/content/agents/agent-endpoint-tools.md +24 -0
- package/content/agents/agent-properties.md +13 -3
- package/content/agents/agent-server-hooks.md +1 -1
- package/content/agents/agentchat.md +41 -4
- package/content/agents/agentconversations.md +42 -8
- package/content/agents/agents-introduction.md +107 -0
- package/content/callback-reference/auth0logoutcallback.md +54 -0
- package/content/concepts/ai-agent-docs.md +455 -106
- package/content/concepts/blocks.md +150 -0
- package/content/concepts/connections-and-requests.md +402 -0
- package/content/concepts/custom-html.md +42 -0
- package/content/concepts/custom-styling.md +50 -5
- package/content/concepts/dynamic-page-content.md +309 -0
- package/content/concepts/events-and-actions.md +185 -2
- package/content/concepts/four-primitives.md +31 -0
- package/content/concepts/html-attributes.md +293 -0
- package/content/concepts/i18n.md +12 -3
- package/content/concepts/keyboard-shortcuts.md +2 -2
- package/content/concepts/layout-overview.md +1 -1
- package/content/concepts/logger.md +99 -0
- package/content/concepts/lowdefy-api.md +1319 -0
- package/content/concepts/lowdefy-schema.md +144 -3
- package/content/concepts/menus.md +8 -7
- package/content/concepts/module-authoring.md +76 -5
- package/content/concepts/modules.md +3 -1
- package/content/concepts/notifications.md +180 -0
- package/content/concepts/operators.md +7 -0
- package/content/concepts/page-and-app-state.md +252 -0
- package/content/concepts/page-paths.md +209 -0
- package/content/concepts/theming.md +582 -0
- package/content/connections/aigateway.md +375 -0
- package/content/connections/anthropic.md +169 -2
- package/content/connections/awss3.md +178 -2
- package/content/connections/axioshttp.md +181 -0
- package/content/connections/google.md +169 -2
- package/content/connections/mongodb.md +1014 -3
- package/content/connections/openai-connection.md +169 -2
- package/content/connections/sendgridmail.md +3 -0
- package/content/connections/smtp.md +16 -0
- package/content/connections/treg.md +329 -0
- package/content/container-blocks/affix.md +47 -7
- package/content/container-blocks/alert.md +76 -24
- package/content/container-blocks/badge.md +100 -24
- package/content/container-blocks/box.md +9 -9
- package/content/container-blocks/card.md +132 -27
- package/content/container-blocks/carousel.md +60 -7
- package/content/container-blocks/collapse.md +153 -9
- package/content/container-blocks/configprovider.md +35 -13
- package/content/container-blocks/confirmmodal.md +69 -23
- package/content/container-blocks/content.md +62 -98
- package/content/container-blocks/descriptions.md +45 -4
- package/content/container-blocks/drawer.md +139 -28
- package/content/container-blocks/dropdownmenu.md +119 -31
- package/content/container-blocks/flex.md +40 -62
- package/content/container-blocks/footer.md +15 -11
- package/content/container-blocks/googlemapsheatmap.md +1 -1
- package/content/container-blocks/googlemapsscript.md +2 -2
- package/content/container-blocks/header.md +71 -36
- package/content/container-blocks/label.md +34 -7
- package/content/container-blocks/layout.md +52 -34
- package/content/container-blocks/masonry.md +17 -71
- package/content/container-blocks/mobilemenu.md +131 -88
- package/content/container-blocks/modal.md +161 -26
- package/content/container-blocks/pageheadermenu.md +138 -31
- package/content/container-blocks/pagesidebarlayout.md +230 -27
- package/content/container-blocks/pagesidermenu.md +153 -43
- package/content/container-blocks/popover.md +34 -31
- package/content/container-blocks/result.md +32 -21
- package/content/container-blocks/sider.md +85 -122
- package/content/container-blocks/span.md +7 -7
- package/content/container-blocks/spinner.md +3 -3
- package/content/container-blocks/splitter.md +150 -68
- package/content/container-blocks/tabs.md +64 -12
- package/content/container-blocks/tooltip.md +22 -46
- package/content/container-blocks/watermark.md +22 -4
- package/content/controls/parallel_for.md +21 -2
- package/content/controls/reject.md +26 -3
- package/content/controls/return.md +17 -1
- package/content/controls/throw.md +30 -2
- package/content/controls/try.md +24 -2
- package/content/controls/while.md +46 -0
- package/content/deployment/deployment-environments.md +146 -0
- package/content/deployment/docker.md +23 -7
- package/content/deployment/node-server.md +4 -0
- package/content/deployment/vercel.md +25 -19
- package/content/display-blocks/aggrid.md +33 -16
- package/content/display-blocks/anchor.md +16 -15
- package/content/display-blocks/avatar.md +57 -37
- package/content/display-blocks/breadcrumb.md +70 -21
- package/content/display-blocks/button.md +93 -19
- package/content/display-blocks/calendar.md +12 -0
- package/content/display-blocks/clickablehtml.md +239 -0
- package/content/display-blocks/dangeroushtml.md +1 -1
- package/content/display-blocks/difflist.md +1 -1
- package/content/display-blocks/difftimeline.md +1 -1
- package/content/display-blocks/divider.md +64 -3
- package/content/display-blocks/dropdownbutton.md +81 -30
- package/content/display-blocks/echart.md +35 -1
- package/content/display-blocks/eventlog.md +363 -0
- package/content/display-blocks/floatbutton.md +129 -42
- package/content/display-blocks/html.md +61 -1
- package/content/display-blocks/icon.md +250 -67
- package/content/display-blocks/img.md +2 -2
- package/content/display-blocks/menu.md +146 -73
- package/content/display-blocks/message.md +38 -124
- package/content/display-blocks/notification.md +94 -222
- package/content/display-blocks/paragraph.md +59 -9
- package/content/display-blocks/pollingtimer.md +263 -0
- package/content/display-blocks/progress.md +96 -17
- package/content/display-blocks/qrcode.md +19 -4
- package/content/display-blocks/s3download.md +1 -1
- package/content/display-blocks/search.md +19 -9
- package/content/display-blocks/skeletonbutton.md +1 -0
- package/content/display-blocks/skeletoninput.md +1 -0
- package/content/display-blocks/statistic.md +75 -17
- package/content/display-blocks/steps.md +58 -25
- package/content/display-blocks/table.md +2527 -0
- package/content/display-blocks/tablelight.md +621 -0
- package/content/display-blocks/tag.md +102 -17
- package/content/display-blocks/title.md +50 -11
- package/content/display-blocks/tour.md +33 -23
- package/content/input-blocks/autocomplete.md +81 -9
- package/content/input-blocks/buttonselector.md +45 -8
- package/content/input-blocks/captcha.md +40 -0
- package/content/input-blocks/checkboxselector.md +97 -7
- package/content/input-blocks/checkboxswitch.md +33 -3
- package/content/input-blocks/colorselector.md +63 -14
- package/content/input-blocks/daterangeselector.md +165 -45
- package/content/input-blocks/dateselector.md +139 -41
- package/content/input-blocks/datetimeselector.md +158 -49
- package/content/input-blocks/inputgallery.md +3 -3
- package/content/input-blocks/intentinput.md +207 -0
- package/content/input-blocks/monthselector.md +120 -52
- package/content/input-blocks/multipleselector.md +150 -39
- package/content/input-blocks/numberinput.md +98 -12
- package/content/input-blocks/pagination.md +70 -14
- package/content/input-blocks/paragraphinput.md +51 -37
- package/content/input-blocks/passwordinput.md +60 -6
- package/content/input-blocks/phonenumberinput.md +59 -26
- package/content/input-blocks/placesautocomplete.md +319 -0
- package/content/input-blocks/radioselector.md +83 -7
- package/content/input-blocks/ratingslider.md +57 -26
- package/content/input-blocks/s3uploadbutton.md +24 -24
- package/content/input-blocks/s3uploaddragger.md +3 -3
- package/content/input-blocks/s3uploadphoto.md +5 -5
- package/content/input-blocks/segmentedselector.md +72 -32
- package/content/input-blocks/selector.md +109 -21
- package/content/input-blocks/switch.md +65 -17
- package/content/input-blocks/tableinput.md +445 -0
- package/content/input-blocks/tagmultipleselector.md +114 -0
- package/content/input-blocks/tagselector.md +114 -0
- package/content/input-blocks/textarea.md +32 -3
- package/content/input-blocks/textinput.md +70 -29
- package/content/input-blocks/tiptapinput.md +1 -1
- package/content/input-blocks/tiptapmentioninput.md +2 -2
- package/content/input-blocks/titleinput.md +39 -12
- package/content/input-blocks/treeinput.md +49 -25
- package/content/input-blocks/treemultipleselector.md +127 -10
- package/content/input-blocks/treeselector.md +97 -9
- package/content/input-blocks/upload.md +64 -15
- package/content/input-blocks/uploaddragger.md +17 -1
- package/content/input-blocks/uploadphoto.md +18 -1
- package/content/input-blocks/weekselector.md +120 -55
- package/content/learn/introduction.md +27 -0
- package/content/learn/quickstart.md +53 -0
- package/content/learn/showcase.md +8 -0
- package/content/list-blocks/controlledlist.md +24 -15
- package/content/list-blocks/list.md +11 -11
- package/content/list-blocks/masonrylist.md +7 -34
- package/content/migration/auth-upgrade.md +337 -0
- package/content/migration/upgrade-guide.md +1 -0
- package/content/migration/v3-to-v4.md +417 -0
- package/content/migration/v6-to-v7.md +620 -0
- package/content/operators/_agent.md +155 -0
- package/content/operators/_app.md +2 -1
- package/content/operators/_array.md +122 -1
- package/content/operators/_build.md +1 -0
- package/content/operators/_credential.md +57 -0
- package/content/operators/_cron.md +292 -0
- package/content/operators/_date.md +2 -0
- package/content/operators/_error.md +196 -0
- package/content/operators/_get.md +6 -6
- package/content/operators/_hmac.md +78 -0
- package/content/operators/_js.md +2 -1
- package/content/operators/_location.md +1 -1
- package/content/operators/_media.md +13 -0
- package/content/operators/_module.md +56 -2
- package/content/operators/_operator.md +17 -3
- package/content/operators/_path_params.md +82 -0
- package/content/operators/_ref.md +258 -0
- package/content/operators/_request.md +1 -1
- package/content/operators/_request_details.md +6 -0
- package/content/operators/_type.md +14 -3
- package/content/operators/_url_query.md +2 -0
- package/content/operators/_user.md +3 -3
- package/content/plugins/plugins-actions.md +10 -0
- package/content/plugins/plugins-connections.md +25 -0
- package/content/plugins/plugins-dev.md +66 -0
- package/content/plugins/plugins-icon-sets.md +267 -0
- package/content/plugins/plugins-introduction.md +27 -1
- package/content/plugins/plugins.md +19 -0
- package/content/plugins/posthog.md +359 -0
- package/content/provider-reference/auth-js-providers.md +107 -0
- package/content/provider-reference/openidconnectprovider.md +44 -0
- package/content/recipes/recipes.md +16 -0
- package/content/reference/actions-reference.md +31 -0
- package/content/reference/blocks-reference.md +35 -0
- package/content/reference/cli.md +403 -0
- package/content/reference/connections-reference.md +23 -0
- package/content/reference/operators-reference.md +47 -0
- package/content/reference/reference.md +16 -0
- package/content/reference/schema-reference.md +12 -0
- package/content/testing/config-tests.md +677 -0
- package/content/testing/e2e-configuration.md +31 -1
- package/content/testing/e2e-getting-started.md +1 -1
- package/content/testing/e2e-introduction.md +1 -1
- package/content/testing/e2e-writing-tests.md +12 -1
- package/content/testing/explore-pull-request.md +136 -0
- package/content/testing/journey-data-sets.md +326 -0
- package/content/tutorial/tutorial-actions-operators.md +2 -2
- package/content/tutorial/tutorial-add-blocks.md +2 -2
- package/content/tutorial/tutorial-create-page.md +48 -2
- package/content/tutorial/tutorial-display-data-page.md +3 -3
- package/content/tutorial/tutorial-requests-api.md +155 -0
- package/content/tutorial/tutorial-requests-sql.md +153 -0
- package/content/tutorial/tutorial-start.md +66 -1
- package/content/user-authentication/auth-configuration.md +267 -0
- package/content/user-authentication/auth-providers.md +24 -0
- package/content/user-authentication/auth-steps.md +141 -0
- package/content/user-authentication/login-and-logout.md +160 -8
- package/content/user-authentication/mcp-oauth.md +424 -0
- package/content/user-authentication/organizations.md +246 -0
- package/content/user-authentication/protected-pages-apis.md +97 -0
- package/content/user-authentication/roles.md +49 -0
- package/content/user-authentication/two-factor.md +229 -0
- package/content/user-authentication/user-object.md +58 -0
- package/content/user-authentication/users-introduction.md +8 -0
- package/content/websockets/websocket-publish.md +105 -0
- package/content/websockets/websocket-subscriptions.md +136 -0
- package/content/websockets/websockets-introduction.md +101 -0
- package/hazards.json +56 -0
- package/index.json +3472 -14
- package/package.json +10 -1
- package/scripts/extractAgentDocs.js +41 -30
- package/scripts/hashDocSources.js +38 -0
- package/scripts/isRedirectPage.js +26 -0
- package/scripts/recordSourceHashes.js +97 -0
- package/scripts/resolvePageSections.js +42 -0
- package/scripts/sectionKind.js +27 -0
- package/content/concepts/cli.md +0 -223
- package/content/other/introduction.md +0 -39
- package/content/other/next-auth-providers.md +0 -3
- /package/content/{other → actions}/updatesession.md +0 -0
|
@@ -0,0 +1,146 @@
|
|
|
1
|
+
# Deployment environments
|
|
2
|
+
|
|
3
|
+
Most apps run as more than one deployment: production, a staging copy, a developer's machine. Everything that differs between them is declared once, under `config.environments`, and each deployment says which environment it is with the `LOWDEFY_ENVIRONMENT` environment variable. Lowdefy then takes every environment-specific default from the **current environment** — the app URL, crons, the email delivery filter, Sentry, PostHog, and the feature switches — so none of them needs its own variable or operator chain.
|
|
4
|
+
|
|
5
|
+
```yaml
|
|
6
|
+
# lowdefy.yaml
|
|
7
|
+
config:
|
|
8
|
+
environments:
|
|
9
|
+
local:
|
|
10
|
+
email:
|
|
11
|
+
filter:
|
|
12
|
+
replaceAddress: team+local@example.com
|
|
13
|
+
staging:
|
|
14
|
+
url: https://staging.example.com
|
|
15
|
+
cron:
|
|
16
|
+
secret: STAGING_CRON_SECRET
|
|
17
|
+
email:
|
|
18
|
+
filter:
|
|
19
|
+
replaceAddress: team+staging@example.com
|
|
20
|
+
prod:
|
|
21
|
+
url: https://app.example.com
|
|
22
|
+
guards:
|
|
23
|
+
secrets:
|
|
24
|
+
MONGODB_URI: 'acme-prod\.a1b2c\.mongodb\.net'
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
Then set `LOWDEFY_ENVIRONMENT=prod` on the production deployment, `LOWDEFY_ENVIRONMENT=staging` on staging, and `LOWDEFY_ENVIRONMENT=local` in your local `.env`.
|
|
28
|
+
|
|
29
|
+
## The current environment
|
|
30
|
+
|
|
31
|
+
`LOWDEFY_ENVIRONMENT` is read **at build time**, so set it wherever the app is built (on Vercel, as an Environment Variable of each Vercel environment). `config.environment` can name the current environment in config instead, for a deployment that sets no `LOWDEFY_ENVIRONMENT`; the variable always wins, so a literal committed to config never forces every deployment into one environment.
|
|
32
|
+
|
|
33
|
+
- With `config.environments` declared, the current environment must be one of its names — a typo fails the build.
|
|
34
|
+
- With `config.environments` declared, a production build (`lowdefy build`) fails when no current environment is set: no environment setting would apply — no email filter, no forwarded crons, no guards. The dev server warns and runs with no environment setting.
|
|
35
|
+
- Environment names may contain `A-Z`, `a-z`, `0-9`, `-` and `_`. `default` is reserved.
|
|
36
|
+
|
|
37
|
+
## Environment settings
|
|
38
|
+
|
|
39
|
+
Every setting is optional, and every feature is **on by default**: only an explicit `enabled: false` switches one off.
|
|
40
|
+
|
|
41
|
+
| Setting | Default | What it does |
|
|
42
|
+
| --- | --- | --- |
|
|
43
|
+
| `url` | none | The deployment origin, e.g. `https://staging.example.com`. |
|
|
44
|
+
| `cron.secret` | none | The name of the Lowdefy secret holding this environment's `CRON_SECRET`; makes this environment a cron forwarding target. |
|
|
45
|
+
| `cron.enabled` | `true` | `false`: no cron jobs registered or forwarded for this environment. |
|
|
46
|
+
| `email.filter` | none | Delivery filter (`replaceAddress`, `allowlist`, `regex`) for mail requests. |
|
|
47
|
+
| `email.enabled` | `true` | `false`: mail requests send nothing. |
|
|
48
|
+
| `sentry.enabled` | `true` | `false`: Sentry off, server and client. |
|
|
49
|
+
| `posthog.enabled` | `true` | `false`: PostHog off — `PostHogInit` behaves as `enabled: false`. |
|
|
50
|
+
| `guards.secrets`, `guards.env` | none | Regular expressions the named secrets and environment variables must match, or the build fails. |
|
|
51
|
+
|
|
52
|
+
## URL
|
|
53
|
+
|
|
54
|
+
The current environment's `url` is the default for:
|
|
55
|
+
|
|
56
|
+
- the auth canonical URL (`BETTER_AUTH_URL`) — password-reset, magic-link and verification links, the CSRF origin allowlist, and the MCP resource URIs;
|
|
57
|
+
- the `serverUrl` of `RenderNotification` steps — the links and logo in notification emails;
|
|
58
|
+
- where crons are forwarded to, when another environment forwards to this one.
|
|
59
|
+
|
|
60
|
+
An explicit `BETTER_AUTH_URL` or `serverUrl` still wins. The dev server (`lowdefy dev`) never uses the current environment's `url`: notification and auth links use the request origin, the local app, even when your local `.env` names a deployed environment. On the dev server, a `BETTER_AUTH_URL` on `localhost`, `127.0.0.1` or `[::1]` follows the port the dev server runs on: the port it names is usually the one you ran on before, while `lowdefy dev` skips a busy port and the dev hub allocates its own. Any other origin, such as a tunnel, is used as set. Production never uses the request origin, since a spoofed `Host` header would then steer the links in outgoing mail. A production server with `auth.email` configured refuses to start when neither `BETTER_AUTH_URL` nor the current environment's `url` is set.
|
|
61
|
+
|
|
62
|
+
Every deployment that names an environment is taken to be served at its `url`. Preview deployments that should not sign users in on the staging host need their own environment, e.g. a `preview` environment with no `url` and the same `email.filter` and guards as staging.
|
|
63
|
+
|
|
64
|
+
## Crons
|
|
65
|
+
|
|
66
|
+
Vercel fires cron jobs only on the **production** deployment, so the schedules of other environments are registered there too and forwarded:
|
|
67
|
+
|
|
68
|
+
- The current environment registers its own schedules as `/api/cron/<endpointId>` jobs.
|
|
69
|
+
- An environment with a `cron.secret` is a **forwarding target**. The environment without one (production) also registers the target's schedules as `/api/cron-forward/<environment>/<endpointId>` jobs; when one fires, it pings the target's own `/api/cron/<endpointId>` at its `url` with the target's `CRON_SECRET` and answers immediately.
|
|
70
|
+
- `cron.secret` is the **name** of a Lowdefy secret — a plain string such as `STAGING_CRON_SECRET`, not a `_secret` operator (environment settings are resolved at build time, where `_secret` is not evaluated). Production reads the value at runtime from `LOWDEFY_SECRET_STAGING_CRON_SECRET`, so set that variable on the production deployment to staging's `CRON_SECRET`.
|
|
71
|
+
- `cron.enabled: false` registers nothing for that environment, and production does not forward to it.
|
|
72
|
+
|
|
73
|
+
Endpoint `schedules` can be keyed by environment name, with a `default` for the rest and `[]` to turn an endpoint off in one environment — see [Schedules per environment](/lowdefy-api). The Vercel side (securing the routes, plan limits) is covered in [Deploy with Vercel](/vercel).
|
|
74
|
+
|
|
75
|
+
## Email
|
|
76
|
+
|
|
77
|
+
- **`email.filter`** is applied to every `SMTPMailSend` and `SendGridMailSend` request whose connection sets no `filter` of its own, or a filter whose fields all resolve to `null` (a `_secret` that is not set on this deployment, say). Put a catch-all `replaceAddress` on every non-production environment and no environment can email real users by accident.
|
|
78
|
+
- A connection's own `filter` wins when it sets at least one field, and **`filter: false`** on a connection turns filtering off entirely, the environment's too — for mail that must reach its real recipient everywhere, such as an invite.
|
|
79
|
+
- Addresses on the reserved `.invalid` domain are always dropped before any filter, in every environment and for auth emails too. So test users with addresses such as `user@audit.invalid` never reach a `replaceAddress` catch-all. Use `.invalid` for test users that must never receive mail, and `example.com` or `.test` for journey users whose mail a journey reads.
|
|
80
|
+
- **`email.enabled: false`** sends nothing: each message reports `{ messageId: null, to: null, disabled: true }`.
|
|
81
|
+
- Auth emails (magic links, verification, invitations sent by the auth engine) never go through a mail request, so neither setting affects them — sign-in keeps working in every environment. The `auth.email` connection's own `filter` still applies to them, so set one there to catch auth emails outside production.
|
|
82
|
+
|
|
83
|
+
See the [SMTP](/SMTP) and [SendGridMail](/SendGridMail) connections for the filter fields.
|
|
84
|
+
|
|
85
|
+
## Logs, Sentry and PostHog
|
|
86
|
+
|
|
87
|
+
- Every server log line carries `environment` next to `app_name`, `app_version` and `git_sha`, so one log drain can hold every environment. Logging cannot be switched off.
|
|
88
|
+
- Sentry reports under the environment name unless `logger.sentry.environment` is set, and `sentry.enabled: false` turns it off on the server and in the browser.
|
|
89
|
+
- `PostHogInit` registers the environment name as the `environment` super property, so every PostHog event carries it. `posthog.enabled: false` switches PostHog off in that environment: `PostHogInit` behaves as `enabled: false` whatever its params say, needs no `apiKey`, and every other PostHog action is a no-op.
|
|
90
|
+
|
|
91
|
+
## Guards
|
|
92
|
+
|
|
93
|
+
Guards pin an environment's secrets and environment variables to a pattern kept in config — a second factor for deploy-time configuration. In the current environment the build fails before anything deploys unless every guarded value matches its regular expression; an unset value fails too. The production server checks the same guards again when it starts, against the variables it runs with, and refuses to start on a mismatch — an image built once can be started with different variables. Changing the production database then takes both a new variable value **and** a reviewed config change.
|
|
94
|
+
|
|
95
|
+
```yaml
|
|
96
|
+
config:
|
|
97
|
+
environments:
|
|
98
|
+
prod:
|
|
99
|
+
url: https://app.example.com
|
|
100
|
+
guards:
|
|
101
|
+
secrets: # Lowdefy secrets, by name (LOWDEFY_SECRET_<name>)
|
|
102
|
+
MONGODB_URI: 'acme-prod\.a1b2c\.mongodb\.net'
|
|
103
|
+
env: # any environment variable
|
|
104
|
+
BETTER_AUTH_URL: '^https://app\.example\.com$'
|
|
105
|
+
```
|
|
106
|
+
|
|
107
|
+
- Patterns match anywhere in the value, so a distinctive substring is enough; add `^` and `$` to pin the whole value. A pattern is committed with your config, so never put the sensitive part of a secret in it — a host name or database name is enough.
|
|
108
|
+
- Only the current environment's guards are checked. Every environment's patterns are validated, so a broken pattern fails the build that introduces it. `secrets` and `env` are the only guard kinds; any other key (a `secret:` typo, say) fails the build.
|
|
109
|
+
- A failure names the variable and never prints its value.
|
|
110
|
+
- Guards need the real values at build time and at startup. On Vercel, Environment Variables are available to both; a container build that only injects secrets when the container starts sees them as unset and fails.
|
|
111
|
+
|
|
112
|
+
## What reaches the browser
|
|
113
|
+
|
|
114
|
+
Environment settings stay on the server. The browser only learns the current environment's **name** and the list of features it switches off, through the app metadata:
|
|
115
|
+
|
|
116
|
+
- `_app: environment` — the current environment's name.
|
|
117
|
+
- `_app: disabled` — the switched-off features, e.g. `[email, posthog]`.
|
|
118
|
+
|
|
119
|
+
Other environments' settings, URLs, secret names, email filters and guards never reach the client bundle. Only the current environment's guards are kept in the build output, in the server-only `config.json`, for the startup check.
|
|
120
|
+
|
|
121
|
+
## Upgrading from `config.cron`
|
|
122
|
+
|
|
123
|
+
Lowdefy 6.0 declared cron environments under `config.cron.environments`. That key is replaced, and a build that still has it fails with the migration:
|
|
124
|
+
|
|
125
|
+
```yaml
|
|
126
|
+
# Before
|
|
127
|
+
config:
|
|
128
|
+
cron:
|
|
129
|
+
environments:
|
|
130
|
+
production: {}
|
|
131
|
+
staging:
|
|
132
|
+
url: https://staging.example.com
|
|
133
|
+
secret: STAGING_CRON_SECRET
|
|
134
|
+
|
|
135
|
+
# After
|
|
136
|
+
config:
|
|
137
|
+
environments:
|
|
138
|
+
production:
|
|
139
|
+
url: https://app.example.com
|
|
140
|
+
staging:
|
|
141
|
+
url: https://staging.example.com
|
|
142
|
+
cron:
|
|
143
|
+
secret: STAGING_CRON_SECRET
|
|
144
|
+
```
|
|
145
|
+
|
|
146
|
+
Move each `secret` to `cron.secret` and `enabled` to `cron.enabled`, give production its `url`, and set `LOWDEFY_ENVIRONMENT` on each deployment.
|
|
@@ -15,7 +15,7 @@ The generated Dockerfile:
|
|
|
15
15
|
```text
|
|
16
16
|
# syntax=docker/dockerfile:1
|
|
17
17
|
|
|
18
|
-
FROM node:
|
|
18
|
+
FROM node:24-slim AS builder
|
|
19
19
|
|
|
20
20
|
WORKDIR /lowdefy
|
|
21
21
|
|
|
@@ -41,7 +41,7 @@ RUN --mount=type=cache,id=pnpm,target=/pnpm/store \
|
|
|
41
41
|
&& npx lowdefy@"$LOWDEFY_VERSION" build \
|
|
42
42
|
&& npx lowdefy@"$LOWDEFY_VERSION" docker-output
|
|
43
43
|
|
|
44
|
-
FROM node:
|
|
44
|
+
FROM node:24-slim AS runner
|
|
45
45
|
|
|
46
46
|
ENV NODE_ENV=production
|
|
47
47
|
ENV PORT=3000
|
|
@@ -93,7 +93,7 @@ Key properties of this setup:
|
|
|
93
93
|
- **Fast rebuilds**: the pnpm store is kept in a BuildKit cache mount, so changing app config only re-downloads dependencies that actually changed.
|
|
94
94
|
- **Small runtime image**: `docker-output` traces the server's real import graph and copies only what the server loads at runtime — a fraction of the installed `node_modules`, since the client-side block packages are already compiled into `dist/client` and never imported by the server.
|
|
95
95
|
- **Non-root**: the server runs as the `node` user built into the official Node.js images.
|
|
96
|
-
- For stronger supply-chain guarantees, pin the base images by digest (`node:
|
|
96
|
+
- For stronger supply-chain guarantees, pin the base images by digest (`node:24-slim@sha256:...`) and let a bot like Renovate or Dependabot keep the digest updated.
|
|
97
97
|
|
|
98
98
|
### Health checks
|
|
99
99
|
|
|
@@ -123,7 +123,8 @@ The server is configured entirely through environment variables at runtime — t
|
|
|
123
123
|
| `PORT` | Port the server listens on (default `3000`). |
|
|
124
124
|
| `LOWDEFY_SECRET_*` | App secrets, accessed with the [`_secret`](/_secret) operator. |
|
|
125
125
|
| `AUTH_SECRET` | Required when using [Lowdefy Auth](/users-introduction). |
|
|
126
|
-
| `
|
|
126
|
+
| `LOWDEFY_ENVIRONMENT` | Read at build time: the environment this image is built for, one of `config.environments`. |
|
|
127
|
+
| `BETTER_AUTH_URL` | The app's canonical origin for auth links and the MCP resource URIs. Defaults to the `url` of the current environment in `config.environments`. The server refuses to start without one of the two when `auth.email` is configured. Set it when a proxy terminates TLS in front of the container: without it, auth trusts only the origin the request reached the server on (`http://…`), and refuses sign-in from the `https://` page. |
|
|
127
128
|
| `CRON_SECRET` | Bearer token protecting `/api/cron/*` and `/api/detached/*` endpoints. |
|
|
128
129
|
| `LOWDEFY_LOG_LEVEL` | Server log level: `debug`, `info` (default), `warn`, `error`. |
|
|
129
130
|
| `SENTRY_DSN` | Enables Sentry error reporting when set. |
|
|
@@ -147,6 +148,21 @@ RUN --mount=type=secret,id=sentry,env=SENTRY_AUTH_TOKEN \
|
|
|
147
148
|
npx lowdefy@"$LOWDEFY_VERSION" build
|
|
148
149
|
```
|
|
149
150
|
|
|
151
|
+
### Behind a reverse proxy
|
|
152
|
+
|
|
153
|
+
The server takes each request's client address from its connection. Auth rate limits count attempts per client address (for example 3 sign-in attempts per 10 seconds), sessions record it, and the request log writes it as `client_address`. `X-Forwarded-For` is not read by default, because any client can send it.
|
|
154
|
+
|
|
155
|
+
Behind a reverse proxy, load balancer or ingress, every connection comes from the proxy, so every client would share its address and its rate limits. List the proxy addresses, or CIDR ranges, in `config.trustedProxies`:
|
|
156
|
+
|
|
157
|
+
```yaml
|
|
158
|
+
config:
|
|
159
|
+
trustedProxies:
|
|
160
|
+
- 10.0.0.0/8
|
|
161
|
+
- 172.16.0.0/12
|
|
162
|
+
```
|
|
163
|
+
|
|
164
|
+
When a request's connection comes from a trusted proxy, the server reads `X-Forwarded-For` from the right, skips every trusted hop, and takes the first address that is not trusted. Entries further left were written by the client and are ignored. Do not list `0.0.0.0/0` or `::/0`: they trust every address, so any client could choose its own, and the build warns about them. The proxy must append to `X-Forwarded-For` (nginx: `proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;`). The server logs a warning the first time a request carries `X-Forwarded-For` while `trustedProxies` is not set.
|
|
165
|
+
|
|
150
166
|
### Logging
|
|
151
167
|
|
|
152
168
|
The server writes structured JSON logs (one JSON object per line, via [pino](https://getpino.io)) to stdout — the format container platforms and log collectors (CloudWatch, Loki, Datadog, etc.) expect. Nothing is written to files inside the container.
|
|
@@ -187,7 +203,7 @@ The container inherits the Dockerfile `HEALTHCHECK`, so `docker compose ps` repo
|
|
|
187
203
|
docker compose up --build
|
|
188
204
|
```
|
|
189
205
|
|
|
190
|
-
If you set a container memory limit, Node.js
|
|
206
|
+
If you set a container memory limit, Node.js 24+ sizes its heap from the container's cgroup limit automatically. To control it explicitly, set `NODE_OPTIONS=--max-old-space-size=<MiB>` a comfortable margin below the container limit.
|
|
191
207
|
|
|
192
208
|
### Config files or plugins outside the config directory
|
|
193
209
|
|
|
@@ -198,7 +214,7 @@ Sometimes files outside of the config directory need to be accessed by the Lowde
|
|
|
198
214
|
```text
|
|
199
215
|
# syntax=docker/dockerfile:1
|
|
200
216
|
|
|
201
|
-
FROM node:
|
|
217
|
+
FROM node:24-slim AS builder
|
|
202
218
|
|
|
203
219
|
WORKDIR /lowdefy
|
|
204
220
|
|
|
@@ -216,7 +232,7 @@ RUN --mount=type=cache,id=pnpm,target=/pnpm/store \
|
|
|
216
232
|
&& npx lowdefy@"$LOWDEFY_VERSION" build --config-directory ./app \
|
|
217
233
|
&& npx lowdefy@"$LOWDEFY_VERSION" docker-output --config-directory ./app
|
|
218
234
|
|
|
219
|
-
FROM node:
|
|
235
|
+
FROM node:24-slim AS runner
|
|
220
236
|
|
|
221
237
|
ENV NODE_ENV=production
|
|
222
238
|
ENV PORT=3000
|
|
@@ -22,6 +22,10 @@ from inside the folder, or `pnpm start`. The server listens on `PORT` (default 3
|
|
|
22
22
|
|
|
23
23
|
Always run the build before restarting the server — the server reads the client asset manifest once at startup.
|
|
24
24
|
|
|
25
|
+
With `auth.email` configured, the server needs the app's canonical origin — `BETTER_AUTH_URL`, or the `url` of the current environment in `config.environments` — or it refuses to start, so emailed auth links cannot take their host from a request. To test the production server locally, set `BETTER_AUTH_URL=http://localhost:3000`.
|
|
26
|
+
|
|
27
|
+
Behind a reverse proxy or load balancer, list its addresses in `config.trustedProxies` so auth rate limits count each client, not the proxy. See [Behind a reverse proxy](/docker#behind-a-reverse-proxy).
|
|
28
|
+
|
|
25
29
|
### Alternative
|
|
26
30
|
|
|
27
31
|
An alternative option would be to make use of [Docker](./docker) to deploy the app. Docker has a few advantages, including scalability, application portability, version control and deployment speed, amoung others.
|
|
@@ -27,14 +27,17 @@ In the Vercel project:
|
|
|
27
27
|
- Eg: if `lowdefy.yaml` is at the top level of the repository, set the root directory to `deploy`; if it is in `apps/app_name`, set it to `apps/app_name/deploy`.
|
|
28
28
|
- **Install Command:** `bash vercel.install.sh`. Leave the **Build Command** to `vercel.json` (do not override it in the dashboard). There is no **Output Directory** setting — the build emits `.vercel/output`, which Vercel detects automatically.
|
|
29
29
|
- Enable **"Include files outside the root directory in the Build Step"** — the Lowdefy config usually lives in the parent of `deploy/`.
|
|
30
|
+
- **Node.js Version:** `24.x` or newer. The install and build steps run the Lowdefy CLI, which requires Node.js 24; the function itself runs on the `nodejs24.x` runtime set in the generated Build Output.
|
|
30
31
|
|
|
31
32
|
###### Public files
|
|
32
33
|
|
|
33
|
-
Files in your app's `public/` directory (favicon, icons, images, `manifest.webmanifest`, etc.) are copied into `dist/client` by Vite during the build, placed in `.vercel/output/static`, and served by the Vercel CDN — no extra configuration needed.
|
|
34
|
+
Files in your app's `public/` directory (favicon, icons, images, `manifest.webmanifest`, etc.) are copied into `dist/client` by Vite during the build, placed in `.vercel/output/static`, and served by the Vercel CDN — no extra configuration needed. With `config.basePath` set, they are placed and served under the base path, as are the generated cron paths below.
|
|
34
35
|
|
|
35
36
|
###### Secrets and environment variables
|
|
36
37
|
|
|
37
|
-
Secrets can be set in the Environment Variables settings section by creating environment variables prefixed with `LOWDEFY_SECRET_`.
|
|
38
|
+
Secrets can be set in the Environment Variables settings section by creating environment variables prefixed with `LOWDEFY_SECRET_`. Pin the auth canonical URL with the current environment's `url` (see [Deployment environments](/deployment-environments)) or `BETTER_AUTH_URL`; with `auth.email` configured the app refuses to start without it. Different secrets can be set for production and preview deployments.
|
|
39
|
+
|
|
40
|
+
On Vercel the client address used by auth rate limits, sessions and request logs comes from the platform (`x-real-ip`), which Vercel sets on every request. `config.trustedProxies` is not used.
|
|
38
41
|
|
|
39
42
|
###### Function settings
|
|
40
43
|
|
|
@@ -80,41 +83,44 @@ Each schedule becomes a cron job pointing at `/api/cron/<endpointId>`. When it f
|
|
|
80
83
|
- **Plan limits:** Vercel **Hobby** only allows daily crons (a sub-daily expression fails the deployment); **Pro**/**Enterprise** allow per-minute. Up to 100 cron jobs per project.
|
|
81
84
|
- **Idempotency:** Vercel does not retry failed runs and delivery is best-effort (a run can be missed or delivered more than once). Design scheduled routines to be idempotent.
|
|
82
85
|
|
|
83
|
-
######
|
|
86
|
+
###### Deployment environments
|
|
84
87
|
|
|
85
|
-
|
|
88
|
+
Declare the app's environments once under `config.environments` and name the current one with the `LOWDEFY_ENVIRONMENT` Environment Variable — see [Deployment environments](/deployment-environments) for every setting (URL, crons, email, Sentry, PostHog, feature switches, guards). On Vercel, add `LOWDEFY_ENVIRONMENT` to each Vercel environment (for example `prod` on Production and `staging` on the staging branch's Preview environment). Vercel Environment Variables are available at build time, which is when Lowdefy reads it and checks guards.
|
|
86
89
|
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
environments:
|
|
91
|
-
production: {} # no url: the deployment Vercel fires crons on
|
|
92
|
-
staging:
|
|
93
|
-
url: https://staging.example.com
|
|
94
|
-
secret: STAGING_CRON_SECRET
|
|
95
|
-
```
|
|
90
|
+
###### Sentry
|
|
91
|
+
|
|
92
|
+
With `SENTRY_DSN` set, the function reports server errors to Sentry but does not trace requests, unless `logger.sentry.serverTracing` is `true`: tracing adds to every cold start, and the function stays billed after each response while a sampled transaction uploads. A request that captures no error ends as soon as its response is sent. See [Logger](/logger).
|
|
96
93
|
|
|
97
|
-
|
|
94
|
+
###### Crons for staging and other environments
|
|
95
|
+
|
|
96
|
+
Vercel fires cron jobs only on the **production** deployment — a staging or preview deployment never runs its schedules on its own. Give an environment a `cron.secret` and the environment Vercel fires crons on registers that environment's schedules too; when one fires, production forwards it to that environment's own `/api/cron/<endpointId>` at its `url` (under `config.basePath` when one is set) and answers Vercel immediately (the ping is fire-and-forget, kept alive via the request context and bounded by `maxDuration`; its outcome is logged as `forward_scheduled_endpoint_done` / `_failed`).
|
|
97
|
+
|
|
98
|
+
- **Forwarded environments:** an environment with a `cron.secret` is forwarded to, so it must have a `url`. `cron.secret` is the **name** of the Lowdefy secret holding that environment's own `CRON_SECRET` — a plain string such as `STAGING_CRON_SECRET`, not `{ _secret: ... }`: environment settings are resolved at build time, and the forward route reads the value at runtime from `LOWDEFY_SECRET_<name>`. Set `cron.enabled: false` on an environment to register no crons for it.
|
|
98
99
|
- **Secrets on production:** for each forwarded environment add an Environment Variable `LOWDEFY_SECRET_<secret name>` (for example `LOWDEFY_SECRET_STAGING_CRON_SECRET`) to the production deployment, with that environment's `CRON_SECRET` as value. The forward route `/api/cron-forward/*` itself is secured by production's own `CRON_SECRET` like every cron route, and fails closed when the environment's secret is missing.
|
|
99
|
-
- **Per-environment schedules:** key an endpoint's `schedules` by environment name with an optional `default` (`staging: []` turns them off) — see [Schedules per environment](/api). The generated crons are `/api/cron/<endpointId>` for the
|
|
100
|
+
- **Per-environment schedules:** key an endpoint's `schedules` by environment name with an optional `default` (`staging: []` turns them off) — see [Schedules per environment](/lowdefy-api). The generated crons are `/api/cron/<endpointId>` for the current environment and `/api/cron-forward/<environment>/<endpointId>` for the forwarded ones; all of them count toward the project's cron limit.
|
|
100
101
|
- **Plan limits still apply per project:** a per-minute staging schedule needs the same Pro plan as a per-minute production one.
|
|
102
|
+
- **Upgrading from 6.0:** `config.cron.environments` is replaced by `config.environments`; see [Upgrading from `config.cron`](/deployment-environments).
|
|
101
103
|
|
|
102
104
|
###### Background work: async endpoints and detached calls
|
|
103
105
|
|
|
104
|
-
Two [API endpoint](/api) controls exist for work that should not hold up a response — they behave differently on Vercel:
|
|
106
|
+
Two [API endpoint](/lowdefy-api) controls exist for work that should not hold up a response — they behave differently on Vercel:
|
|
105
107
|
|
|
106
108
|
- **`async: true` endpoints** respond `{ accepted: true }` immediately and run the routine in the background. On Vercel the invocation is kept alive via the platform request context (Fluid compute) until the routine settles — but it is still the *same* invocation, so the background work remains bounded by `maxDuration`. Raise `config.vercel.maxDuration` to cover your longest async routine.
|
|
107
109
|
- **`detached: true` on `CallApi` steps** fire-and-forget the target endpoint through a `POST` to the deployment's own `/api/detached/<endpointId>` route, so the target runs in its **own** invocation with a fresh `maxDuration` budget. The route is secured by `CRON_SECRET` (same secret as cron, fail closed), and detached steps fail with a config error if it is not set. Delivery is at-most-once with no retry; targets run as system context (`_user` is `undefined`) and must be idempotent.
|
|
108
110
|
|
|
109
|
-
See [Async Endpoints](/api) and [Detached Endpoint Calls](/api) in the API docs for full semantics.
|
|
111
|
+
See [Async Endpoints](/lowdefy-api) and [Detached Endpoint Calls](/lowdefy-api) in the API docs for full semantics.
|
|
110
112
|
|
|
111
113
|
###### Cost protection
|
|
112
114
|
|
|
113
115
|
Vercel Fluid bills by execution duration, so a request that hangs (a stuck database, SMTP or external API call) is a real cost risk. Two guardrails apply:
|
|
114
116
|
|
|
115
|
-
- **`config.requestTimeout`** (in `lowdefy.yaml`, default `30000` ms) — the server returns a timeout instead of letting a request run on. Set to `0` to disable. Agent streaming routes are exempt.
|
|
117
|
+
- **`config.requestTimeout`** (in `lowdefy.yaml`, default `30000` ms) — the server returns a timeout instead of letting a request run on, and cancels the AI model calls the request was waiting on. Set to `0` to disable. Agent streaming routes are exempt.
|
|
116
118
|
- **`config.vercel.maxDuration`** (default `60`) — a hard platform cap; Vercel stops the function at this many seconds. See Function settings above.
|
|
117
119
|
|
|
118
|
-
|
|
120
|
+
Keep `config.requestTimeout` below `maxDuration`: when it is not, Vercel stops the function before the request timeout answers, so the upstream calls the request left running are not cancelled and the request ends without a logged timeout. The build warns when `config.requestTimeout` is not shorter than `maxDuration` (or than the 60-second default, when it runs on Vercel).
|
|
121
|
+
|
|
122
|
+
On Vercel, only the request timeout cancels an AI model call a request is waiting on. A client that disconnects does not: the call runs until it finishes, reaches its own `timeout`, or hits the request timeout. On the Node server a disconnect cancels it too.
|
|
123
|
+
|
|
124
|
+
> The function runs on Vercel's Node.js runtime. Streaming agent responses (`/api/agent/*`) are exempt from `config.requestTimeout` and are bounded only by `maxDuration` — for heavy streaming or agent workloads, a long-lived Node host (Docker, Fly.io, Railway, Render) may suit better. An agent run keeps running to the end when its client disconnects, so its work completes; a `GET` stream (such as an MCP client's notification stream) stops when its client goes, instead of holding the function until `maxDuration`.
|
|
119
125
|
|
|
120
126
|
All other Vercel configuration like domain names, preview deploy branches, serverless regions and redirects can be configured as desired.
|
|
@@ -410,7 +410,7 @@ Migrate the column-level checkbox flags in the same edit — `checkboxSelection`
|
|
|
410
410
|
assignee: Diana
|
|
411
411
|
priority: Low
|
|
412
412
|
status: To Do
|
|
413
|
-
- task: Code review PR
|
|
413
|
+
- task: "Code review PR #42"
|
|
414
414
|
assignee: Erik
|
|
415
415
|
priority: Medium
|
|
416
416
|
status: In Progress
|
|
@@ -1064,20 +1064,25 @@ Migrate the column-level checkbox flags in the same edit — `checkboxSelection`
|
|
|
1064
1064
|
Archived: default
|
|
1065
1065
|
- headerName: Actions
|
|
1066
1066
|
field: _id
|
|
1067
|
-
width:
|
|
1067
|
+
width: 300
|
|
1068
1068
|
cell:
|
|
1069
1069
|
type: buttons
|
|
1070
1070
|
buttons:
|
|
1071
1071
|
- eventName: onEditClick
|
|
1072
1072
|
title: Edit
|
|
1073
|
-
icon:
|
|
1073
|
+
icon: edit
|
|
1074
1074
|
type: primary
|
|
1075
1075
|
- eventName: onDeleteClick
|
|
1076
1076
|
title: Delete
|
|
1077
|
-
icon:
|
|
1077
|
+
icon: delete
|
|
1078
1078
|
danger: true
|
|
1079
1079
|
disabledField: locked
|
|
1080
1080
|
hiddenField: archived
|
|
1081
|
+
- eventName: onOpenClick
|
|
1082
|
+
title: Open
|
|
1083
|
+
icon: arrow-right
|
|
1084
|
+
iconPlacement: end
|
|
1085
|
+
type: link
|
|
1081
1086
|
rowData:
|
|
1082
1087
|
- _id: TSK-001
|
|
1083
1088
|
name: Wire main switchboard
|
|
@@ -1112,6 +1117,14 @@ Migrate the column-level checkbox flags in the same edit — `checkboxSelection`
|
|
|
1112
1117
|
_string.concat:
|
|
1113
1118
|
- "Delete "
|
|
1114
1119
|
- _event: row.name
|
|
1120
|
+
onOpenClick:
|
|
1121
|
+
- id: open_msg
|
|
1122
|
+
type: DisplayMessage
|
|
1123
|
+
params:
|
|
1124
|
+
content:
|
|
1125
|
+
_string.concat:
|
|
1126
|
+
- "Open "
|
|
1127
|
+
- _event: row._id
|
|
1115
1128
|
```
|
|
1116
1129
|
|
|
1117
1130
|
```yaml
|
|
@@ -1307,6 +1320,7 @@ Migrate the column-level checkbox flags in the same edit — `checkboxSelection`
|
|
|
1307
1320
|
| `themeParams` | object | - | AG Grid Theming API parameters merged onto this block's theme, for per-grid overrides. Keys are AG Grid param names, e.g. `headerBackgroundColor`, `rowHoverColor`, `borderColor`. Values are CSS strings and may reference antd tokens, e.g. `var(--ant-color-primary)`. An unrecognised param name has no effect — neither Lowdefy nor AG Grid validates the names — so check spelling against AG Grid's theming parameter reference. |
|
|
1308
1321
|
| `height` | number \| string | `"auto"` | Specify table height explicitly, in pixel. |
|
|
1309
1322
|
| `rowData` | array | - | The list of data to display on the table. |
|
|
1323
|
+
| `quickFilterValue` | string | - | Show only rows with a cell containing this text. Bind it to state to drive a search box; the `setQuickFilter` method does the same imperatively. |
|
|
1310
1324
|
| `rowId` | string | - | The data field to use in `getRowId` which results in Row Selection being maintained across Row Data changes (assuming the Row exists in both sets). See Ag Grid docs for more details (https://www.ag-grid.com/react-data-grid/data-update-row-data/). |
|
|
1311
1325
|
| `enableBrowserTooltips` | boolean | `false` | Set to `true` to use the browser native `title` attribute tooltips instead of AG Grid's styled tooltip component. |
|
|
1312
1326
|
| `suppressCellFocus` | boolean | `true` | When `true` (default), clicking a cell does not draw the AG Grid cell-focus border. Set to `false` to enable spreadsheet-style cell focus and keyboard navigation. |
|
|
@@ -1320,14 +1334,14 @@ Migrate the column-level checkbox flags in the same edit — `checkboxSelection`
|
|
|
1320
1334
|
| `columnDefs.$.sortable` | boolean | `false` | Set to true to allow sorting on this column. |
|
|
1321
1335
|
| `columnDefs.$.resizable` | boolean | `false` | Set to true to allow this column should be resized. |
|
|
1322
1336
|
| `columnDefs.$.width` | number | - | Initial width in pixels for the cell. |
|
|
1323
|
-
| `columnDefs.$.cellStyle` |
|
|
1337
|
+
| `columnDefs.$.cellStyle` | object | - | An object of css values returning an object of css values for a particular cell. |
|
|
1324
1338
|
| `columnDefs.$.cellRenderer` | object | - | Provide your own cell Renderer function (using the `_function` operator) for this column's cells. |
|
|
1325
1339
|
| `columnDefs.$.valueFormatter` | object \| string | - | A function (using the `_function` operator) or expression to format a value, should return a string. Not used for CSV export or copy to clipboard, only for UI cell rendering. |
|
|
1326
1340
|
| `columnDefs.$.tooltipField` | string | - | The field of the row object to read the tooltip value from. When set, hovering a cell shows a tooltip with that value using the grid's default tooltip component. |
|
|
1327
1341
|
| `columnDefs.$.tooltipValueGetter` | object | - | Provide a function (using the `_function` operator) that returns the tooltip value for a cell. Overrides `tooltipField`. |
|
|
1328
1342
|
| `columnDefs.$.tooltipComponent` | object | - | Provide a custom tooltip component. See AG Grid tooltip component docs (https://www.ag-grid.com/react-data-grid/component-tooltip/). |
|
|
1329
1343
|
| `columnDefs.$.ellipsis` | number | - | Line-clamp count for long text. Automatically enables `wrapText` and `autoHeight` and applies the `.lf-ellipsis-N` class (1–6). |
|
|
1330
|
-
| `columnDefs.$.cell` | object | - | Built-in cell renderer. Takes precedence over `cellRenderer` when `type` is set. Field-valued keys (e.g. `nameField`, `srcField`, `urlQuery.*`) are row-data paths. |
|
|
1344
|
+
| `columnDefs.$.cell` | object | - | Built-in cell renderer. Takes precedence over `cellRenderer` when `type` is set. Field-valued keys (e.g. `nameField`, `srcField`, `urlQuery.*`, `pathParams.*`) are row-data paths. |
|
|
1331
1345
|
| `columnDefs.$.cell.type` | string | - | The built-in renderer to use. Enum: `tag`, `avatar`, `link`, `date`, `boolean`, `progress`, `number`, `buttons`, `menu`, `selector`, `multipleSelector`, `switch`, `textInput`, `paragraphInput`. |
|
|
1332
1346
|
| `columnDefs.$.cell.colorMap` | object | - | Tag: map of cell value → color (antd tag color name or hex). Used when `cell.type: tag`. The cell value may be a single string or an array of strings; arrays render one tag per item. If neither `colorMap`, `colorFrom`, nor `default` is set, tag values are auto-coloured from a stable hash for consistency across rows. |
|
|
1333
1347
|
| `columnDefs.$.cell.colorFrom` | string | - | Tag: row-data path to a color value. Takes precedence over `colorMap`. |
|
|
@@ -1336,13 +1350,14 @@ Migrate the column-level checkbox flags in the same edit — `checkboxSelection`
|
|
|
1336
1350
|
| `columnDefs.$.cell.srcField` | string | - | Avatar: row-data path for the image src (optional). |
|
|
1337
1351
|
| `columnDefs.$.cell.idField` | string | - | Avatar: row-data path for an id used to seed initials colour. |
|
|
1338
1352
|
| `columnDefs.$.cell.shape` | string | - | Avatar shape. Defaults to `circle`. Enum: `circle`, `square`. |
|
|
1339
|
-
| `columnDefs.$.cell.link` | object | - | Avatar/Link: navigation config. Emits `onCellLink` on click. `pageId`/`href`/`back`/`home`/`newTab` are literal; `urlQuery` values are row-data paths. |
|
|
1353
|
+
| `columnDefs.$.cell.link` | object | - | Avatar/Link: navigation config. Emits `onCellLink` on click. `pageId`/`href`/`back`/`home`/`newTab` are literal; `urlQuery` and `pathParams` values are row-data paths. |
|
|
1340
1354
|
| `columnDefs.$.cell.pageId` | string | - | Link: target page id (literal). |
|
|
1341
1355
|
| `columnDefs.$.cell.href` | string | - | Link: literal href (overrides `pageId`). |
|
|
1342
1356
|
| `columnDefs.$.cell.back` | boolean | - | Link: navigate back. |
|
|
1343
1357
|
| `columnDefs.$.cell.home` | boolean | - | Link: navigate home. |
|
|
1344
1358
|
| `columnDefs.$.cell.newTab` | boolean | - | Link: open in a new tab. |
|
|
1345
1359
|
| `columnDefs.$.cell.urlQuery` | object | - | Link: query params. Each value is a row-data path. |
|
|
1360
|
+
| `columnDefs.$.cell.pathParams` | object | - | Link: values for the page path's placeholders. Each value is a row-data path. |
|
|
1346
1361
|
| `columnDefs.$.cell.labelField` | string | - | Link: row-data path for the visible label (falls back to cell value). |
|
|
1347
1362
|
| `columnDefs.$.cell.format` | string | - | Number: `number` (default), `currency`, `percent`, or `compact` (K/M/B). Date: dayjs format string (default `YYYY-MM-DD HH:mm`). |
|
|
1348
1363
|
| `columnDefs.$.cell.relative` | boolean | - | Date: render as relative time (e.g. "3 hours ago"). |
|
|
@@ -1365,7 +1380,7 @@ Migrate the column-level checkbox flags in the same edit — `checkboxSelection`
|
|
|
1365
1380
|
| `columnDefs.$.cell.negative` | string | `"minus"` | Number: how to render negative numbers — `minus` (default) or `parentheses` for accounting. Enum: `minus`, `parentheses`. |
|
|
1366
1381
|
| `columnDefs.$.cell.signColor` | boolean | `false` | Number: when true, positives use `positiveColor` (default success token), negatives use `negativeColor` (default error token). |
|
|
1367
1382
|
| `columnDefs.$.cell.positiveColor` | string | - | Number: CSS colour when value > 0 (requires `signColor: true`). |
|
|
1368
|
-
| `columnDefs.$.cell.negativeColor` | string | - | Number: CSS colour when value
|
|
1383
|
+
| `columnDefs.$.cell.negativeColor` | string | - | Number: CSS colour when value < 0 (requires `signColor: true`). |
|
|
1369
1384
|
| `columnDefs.$.cell.zeroColor` | string | - | Number: CSS colour when value === 0 (requires `signColor: true`). |
|
|
1370
1385
|
| `columnDefs.$.cell.color` | string | - | Number: CSS colour applied to all values (overridden by `signColor`). |
|
|
1371
1386
|
| `columnDefs.$.cell.prefix` | string | - | Number: literal prefix (e.g. `Δ `, `~`). |
|
|
@@ -1374,8 +1389,9 @@ Migrate the column-level checkbox flags in the same edit — `checkboxSelection`
|
|
|
1374
1389
|
| `columnDefs.$.cell.buttons.$.eventName` | string | - | Block-level event name to trigger on click. |
|
|
1375
1390
|
| `columnDefs.$.cell.buttons.$.title` | string | - | Title text on the button - supports html. |
|
|
1376
1391
|
| `columnDefs.$.cell.buttons.$.titleField` | string | - | Row-data path for the title. |
|
|
1377
|
-
| `columnDefs.$.cell.buttons.$.icon` | string \| object | - |
|
|
1392
|
+
| `columnDefs.$.cell.buttons.$.icon` | string \| object | - | Icon name (a semantic name like `edit`, a Lucide icon name like `Pencil`, or a set-qualified name like `tabler:Pencil`) or Icon block config. |
|
|
1378
1393
|
| `columnDefs.$.cell.buttons.$.iconField` | string | - | Row-data path for the icon name or config. |
|
|
1394
|
+
| `columnDefs.$.cell.buttons.$.iconPlacement` | string | `"start"` | Place the icon before (start) or after (end) the title. Enum: `start`, `end`. |
|
|
1379
1395
|
| `columnDefs.$.cell.buttons.$.type` | string | - | antd Button type. Enum: `primary`, `default`, `dashed`, `link`, `text`. |
|
|
1380
1396
|
| `columnDefs.$.cell.buttons.$.variant` | string | - | antd Button variant. Takes precedence over `type` when set. Enum: `solid`, `outlined`, `dashed`, `filled`, `text`, `link`. |
|
|
1381
1397
|
| `columnDefs.$.cell.buttons.$.color` | string | - | Button color (antd preset or hex). |
|
|
@@ -1384,6 +1400,7 @@ Migrate the column-level checkbox flags in the same edit — `checkboxSelection`
|
|
|
1384
1400
|
| `columnDefs.$.cell.buttons.$.danger` | boolean | `false` | |
|
|
1385
1401
|
| `columnDefs.$.cell.buttons.$.ghost` | boolean | `false` | |
|
|
1386
1402
|
| `columnDefs.$.cell.buttons.$.hideTitle` | boolean | `false` | Hide the button's title (icon-only). |
|
|
1403
|
+
| `columnDefs.$.cell.buttons.$.tooltip` | string | - | Hover text for the button. An icon-only button (`hideTitle: true`) shows its `title` as the tooltip when this is not set. |
|
|
1387
1404
|
| `columnDefs.$.cell.buttons.$.disabled` | boolean | `false` | |
|
|
1388
1405
|
| `columnDefs.$.cell.buttons.$.disabledField` | string | - | Row-data path → boolean. |
|
|
1389
1406
|
| `columnDefs.$.cell.buttons.$.hidden` | boolean | `false` | Hide the button entirely. |
|
|
@@ -1392,15 +1409,15 @@ Migrate the column-level checkbox flags in the same edit — `checkboxSelection`
|
|
|
1392
1409
|
| `columnDefs.$.cell.items.$.eventName` | string | - | Block-level event name to trigger on click. Event payload is `{ row, value, item: { eventName, title }, itemIndex }`. |
|
|
1393
1410
|
| `columnDefs.$.cell.items.$.title` | string | - | Item label - supports html. |
|
|
1394
1411
|
| `columnDefs.$.cell.items.$.titleField` | string | - | Row-data path for the label. |
|
|
1395
|
-
| `columnDefs.$.cell.items.$.icon` | string \| object | - |
|
|
1412
|
+
| `columnDefs.$.cell.items.$.icon` | string \| object | - | Icon name (a semantic name like `edit`, a Lucide icon name like `Pencil`, or a set-qualified name like `tabler:Pencil`) or Icon block config. |
|
|
1396
1413
|
| `columnDefs.$.cell.items.$.iconField` | string | - | Row-data path for the icon name or config. |
|
|
1397
1414
|
| `columnDefs.$.cell.items.$.danger` | boolean | `false` | Render the item in the danger colour. |
|
|
1398
1415
|
| `columnDefs.$.cell.items.$.disabled` | boolean | `false` | |
|
|
1399
1416
|
| `columnDefs.$.cell.items.$.disabledField` | string | - | Row-data path → boolean. |
|
|
1400
1417
|
| `columnDefs.$.cell.items.$.hidden` | boolean | `false` | Hide the item entirely. |
|
|
1401
1418
|
| `columnDefs.$.cell.items.$.hiddenField` | string | - | Row-data path → boolean. |
|
|
1402
|
-
| `columnDefs.$.cell.icon` | string \| object | `"
|
|
1403
|
-
| `columnDefs.$.cell.placement` | string | `"bottomRight"` | Menu cell: where the dropdown opens relative to its trigger. Enum: `bottomLeft`, `bottom`, `bottomRight`, `topLeft`, `top`, `topRight`. |
|
|
1419
|
+
| `columnDefs.$.cell.icon` | string \| object | `"more-vertical"` | Menu cell: the trigger icon. Icon name (a semantic name like `edit`, a Lucide icon name like `Pencil`, or a set-qualified name like `tabler:Pencil`) or Icon block config. The trigger is icon-only. |
|
|
1420
|
+
| `columnDefs.$.cell.placement` | string | `"bottomRight"` | Menu cell: where the dropdown opens relative to its trigger. Enum: `bottomLeft`, `bottom`, `bottomRight`, `topLeft`, `top`, `topRight`, `left`, `leftTop`, `leftBottom`, `right`, `rightTop`, `rightBottom`. |
|
|
1404
1421
|
| `columnDefs.$.cell.options` | array | - | Selector / Multiple selector cell: dropdown options. An array of primitives, or objects mirroring the `Selector` block options: `{ label, value, disabled, color, filterString, style }`. `label` supports html. |
|
|
1405
1422
|
| `columnDefs.$.cell.valueKey` | string | - | Selector / Multiple selector: field on each option object to use as its value. Defaults to `value`. |
|
|
1406
1423
|
| `columnDefs.$.cell.primaryKey` | string | - | Selector / Multiple selector: field used to match the cell value to an option (identity key for object values). |
|
|
@@ -1418,8 +1435,8 @@ Migrate the column-level checkbox flags in the same edit — `checkboxSelection`
|
|
|
1418
1435
|
| `columnDefs.$.cell.autoClearSearchValue` | boolean | - | Multiple selector: clear the search box after each selection. |
|
|
1419
1436
|
| `columnDefs.$.cell.checkedText` | string | - | Switch: label shown inside the switch when on. |
|
|
1420
1437
|
| `columnDefs.$.cell.uncheckedText` | string | - | Switch: label shown inside the switch when off. |
|
|
1421
|
-
| `columnDefs.$.cell.checkedIcon` | string \| object | - | Switch: icon shown when on (
|
|
1422
|
-
| `columnDefs.$.cell.uncheckedIcon` | string \| object | - | Switch: icon shown when off (
|
|
1438
|
+
| `columnDefs.$.cell.checkedIcon` | string \| object | - | Switch: icon shown when on (icon name like `edit`, `Pencil` or `tabler:Pencil`, or Icon block config). |
|
|
1439
|
+
| `columnDefs.$.cell.uncheckedIcon` | string \| object | - | Switch: icon shown when off (icon name like `edit`, `Pencil` or `tabler:Pencil`, or Icon block config). |
|
|
1423
1440
|
| `columnDefs.$.cell.inputType` | string | - | Text input: the HTML input type (e.g. `text`, `email`, `number`, `password`). Named `inputType` to avoid clashing with `cell.type`. |
|
|
1424
1441
|
| `columnDefs.$.cell.maxLength` | number | - | Text input / Paragraph input: maximum number of characters. |
|
|
1425
1442
|
| `columnDefs.$.cell.showCount` | boolean | - | Text input: show the character count. |
|
|
@@ -1438,9 +1455,9 @@ Migrate the column-level checkbox flags in the same edit — `checkboxSelection`
|
|
|
1438
1455
|
|
|
1439
1456
|
| Event | Event Data | Description |
|
|
1440
1457
|
| --- | --- | --- |
|
|
1441
|
-
| `onCellClick` | `{ cell, colId, row, rowIndex, selected }` | Trigger event when a cell is clicked. |
|
|
1458
|
+
| `onCellClick` | `{ cell, colId, row, rowIndex, selected }` | Trigger event when a cell is clicked. Clicks on a button, link, menu, input or checkbox in the cell do not trigger it. |
|
|
1442
1459
|
| `onFilterChanged` | `{ rows, filter }` | Trigger event when the filter changes. |
|
|
1443
|
-
| `onRowClick` | `{ row, selected, rowIndex }` | Trigger event when a row is clicked. |
|
|
1460
|
+
| `onRowClick` | `{ row, selected, rowIndex }` | Trigger event when a row is clicked. Clicks on a button, link, menu, input or checkbox in a cell do not trigger it. |
|
|
1444
1461
|
| `onRowSelected` | `{ row, rowIndex, selected }` | Trigger event when a row is selected. |
|
|
1445
1462
|
| `onSelectionChanged` | `{ selected }` | Triggered when the selected rows are changed. |
|
|
1446
1463
|
| `onSortChanged` | `{ rows, sort }` | Trigger event when the sort changes. |
|