@lowdefy/docs-content 0.0.0-experimental-20260710073520

package/content/concepts/modules.md

@@ -0,0 +1,338 @@
+# Modules
+
+Blocks are the smallest reusable unit in Lowdefy; apps are the largest. Modules sit between them — they package the shape of a feature teams want to share, like a user-admin panel or an events timeline. A module bundles pages, connections, API endpoints, components, and menus into a single distributable unit. Instead of copying config between projects, you install a module and configure it with variables.
+
+A module is hosted in a GitHub repository or local directory. Each usage of a module in your app is called a **module entry** — identified by a user-chosen `id` that controls namespacing.
+
+## Using Modules
+
+Add modules to the `modules` array in your `lowdefy.yaml`:
+
+```yaml
+lowdefy: LOWDEFY_VERSION
+
+modules:
+  - id: notifications
+    source: "github:lowdefy/notifications@v1.0.0"
+    vars:
+      sender_email: support@myapp.com
+      badge_position: top-right
+
+  - id: team-users
+    source: "github:my-org/user-admin@v1.0.0"
+    vars:
+      roles:
+        _ref: config/team-roles.yaml
+      collection: team_users
+      components:
+        table_columns:
+          _ref: config/team-users/table-columns.yaml
+```
+
+Each module entry has:
+- `id: string` — **Required.** A unique identifier for this entry. Must not contain `/`. Controls the namespace for scoped IDs and page paths.
+- `source: string` — **Required.** Where to fetch the module. Supports GitHub repos and local paths.
+- `vars: object` — Values passed to the module, accessible via [`_module.var`](/_module). Consumer values override manifest defaults; any value you omit falls back to the module's declared default.
+- `connections: object` — Connection remapping. Maps module connection names to app connection IDs.
+- `dependencies: object` — Dependency wiring. Maps abstract dependency names to concrete module entry IDs. See [Cross-Module Dependencies](#cross-module-dependencies).
+
+The entry `id` becomes the URL prefix for every page the module contributes. A `user-admin` entry serves its pages at `/user-admin/all`, `/user-admin/invite`, `/user-admin/edit`; a `companies` entry serves `/companies/view`, `/companies/edit`, `/companies/create`.
+
+## Module Manifest
+
+Each module has a `module.lowdefy.yaml` manifest that declares its contents and interface:
+
+```yaml
+name: User Admin
+description: User administration — list, edit, invite users
+
+vars:
+  roles:
+    type: array
+    required: true
+    description: List of available user roles
+  collection:
+    type: string
+    default: users
+    description: MongoDB collection name
+
+connections:
+  - _ref: connections/users-db.yaml
+
+pages:
+  - _ref: pages/users-list.yaml
+  - _ref: pages/user-edit.yaml
+
+api:
+  - _ref: api/invite-user.yaml
+
+components:
+  - id: user-avatar
+    component:
+      _ref: components/user-avatar.yaml
+
+menus:
+  - _ref: menus.yaml
+
+# Default Lowdefy plugins do not need to be declared.
+plugins:
+  - name: "@lowdefy/blocks-aggrid"
+    version: "^4"
+
+secrets:
+  - name: MONGODB
+    description: MongoDB connection URI
+```
+
+The manifest schema:
+- `name: string` — Human-readable module name.
+- `description: string` — Module description.
+- `vars: object` — Variable declarations with `type`, `required`, `default`, and `description`.
+- `connections: object[]` — Connection definitions used by the module.
+- `pages: object[]` — Page definitions.
+- `api: object[]` — API endpoint definitions.
+- `dependencies: object[]` — Modules this module depends on. Each declares an abstract name (`id`) and `description`. The app wires these to concrete module entries. See [Cross-Module Dependencies](#cross-module-dependencies).
+- `exports: object` — Declares the module's public interface. Lists IDs per section type (`pages`, `components`, `menus`, `connections`, `api`). The build validates cross-module references against exports.
+- `components: object[]` — Named reusable config fragments exposed to the app.
+- `menus: object[]` — Menu definitions.
+- `plugins: object[]` — Required plugin dependencies with semver version constraints.
+- `secrets: object[]` — Allowlist of secrets the module may access.
+
+## Consuming Module Resources
+
+**Pages and APIs** are auto-included and auto-scoped — they appear in the app with the entry ID prefix.
+
+**Components** are reusable config fragments included via [`_ref`](/_ref) with the `module` and `component` arguments. You can pass `vars` to customize the component at the point of inclusion:
+
+```yaml
+blocks:
+  - _ref:
+      module: notifications
+      component: notification-badge
+      vars:
+        position: top-right
+```
+
+Components can export any config — not just UI blocks. Enum maps, config templates, and schema fragments all work:
+
+```yaml
+# Config template component
+updated:
+  _ref:
+    module: events
+    component: change_stamp
+
+# Enum map with key extraction
+icon:
+  _ref:
+    module: events
+    component: event_types
+    key: login.icon
+```
+
+**Menus** are included via `_ref` with the `module` and `menu` arguments. Use a `MenuGroup` to wrap each module's menu items:
+
+```yaml
+menus:
+  - id: default
+    links:
+      - id: companies
+        type: MenuGroup
+        properties:
+          title: Companies
+        links:
+          _ref:
+            module: companies
+            menu: default
+      - id: user-admin
+        type: MenuGroup
+        properties:
+          title: User Admin
+        links:
+          _ref:
+            module: user-admin
+            menu: default
+```
+
+## ID Scoping
+
+The build automatically scopes certain IDs using the module entry's `id`. Module authors write IDs without any prefix — the build adds it.
+
+| ID type         | Auto-scoped? | Module author writes | Becomes (in `team-users` entry) |
+| --------------- | ------------ | -------------------- | ------------------------------- |
+| Page ID         | Yes          | `users-list`         | `team-users/users-list`         |
+| Connection ID   | Yes          | `users-db`           | `team-users/users-db`           |
+| API endpoint ID | Yes          | `invite-user`        | `team-users/invite-user`        |
+| Menu item ID    | Yes          | `users`              | `team-users/users`              |
+| Block ID        | No           | `my-block`           | `my-block`                      |
+
+Block IDs and request IDs are not scoped — they inherit scope from their parent page.
+
+## Page Paths
+
+Module pages are served at `/{entryId}/{pageId}`:
+
+| Module Entry ID | Page ID      | URL Path                   |
+| --------------- | ------------ | -------------------------- |
+| `notifications` | `inbox`      | `/notifications/inbox`     |
+| `team-users`    | `users-list` | `/team-users/users-list`   |
+| `client-users`  | `users-list` | `/client-users/users-list` |
+
+From outside a module (app pages or other modules), reference scoped page IDs directly using the full path: `pageId: team-users/users-list`.
+
+## Connection Remapping
+
+Modules declare their own connections. By default, each entry gets namespaced connections (e.g., `team-users/users-db`). You can remap a module connection to use an existing app connection instead:
+
+```yaml
+modules:
+  - id: team-users
+    source: "github:lowdefy/user-admin@v1.0.0"
+    vars:
+      collection: team_users
+    connections:
+      users-db: my-app-mongodb
+```
+
+When remapped, the module's connection definition is skipped. References via `_module.connectionId: users-db` resolve to `my-app-mongodb` instead of `team-users/users-db`.
+
+## Multi-Instance Support
+
+Use the same module multiple times with different entry IDs:
+
+```yaml
+modules:
+  - id: team-users
+    source: "github:lowdefy/user-admin@v1.0.0"
+    vars:
+      collection: team_users
+
+  - id: client-users
+    source: "github:lowdefy/user-admin@v1.0.0"
+    vars:
+      collection: client_users
+```
+
+Each entry has its own namespace — pages, connections, and API endpoints do not collide.
+
+## Module Sources
+
+**GitHub:** `github:owner/repo@ref` or `github:owner/repo/path@ref`
+
+The `ref` can be a tag, branch, or commit SHA. For monorepos, the path after `owner/repo` specifies the subdirectory containing `module.lowdefy.yaml`.
+
+```yaml
+# Single-module repo
+source: "github:lowdefy/notifications@v1.0.0"
+
+# Monorepo — module in subdirectory
+source: "github:my-org/modules/user-admin@v1.0.0"
+```
+
+**Local:** `file:./relative/path`
+
+Local paths resolve relative to the project root. Useful for development and testing.
+
+```yaml
+source: "file:../my-module"
+```
+
+For private GitHub repositories, set the `GITHUB_TOKEN` environment variable. The CLI also checks `gh` CLI credentials and git credential helpers.
+
+## Plugin Dependency Validation
+
+Modules declare required plugins with semver version constraints. The build validates that:
+1. Every declared plugin exists in the app's `plugins` array.
+2. The app's installed plugin version satisfies the module's declared semver range.
+
+If validation fails, the build error includes remediation instructions.
+
+## Secret Allowlist
+
+Modules declare which secrets they access. Undeclared `_secret` references cause build errors.
+
+When a connection is remapped, the module's secret references for that connection are skipped — the app connection handles its own secrets. See [Secrets](/secrets) for more on secret management.
+
+## Cross-Module Dependencies
+
+Modules can reference each other — embed components, link to pages, call APIs, and use connections from other modules. Dependencies use injection: the module declares what it needs, you wire it to a concrete entry.
+
+### Auto-Wiring
+
+If a module declares a dependency and a module entry with the same `id` exists, the build wires them automatically. No configuration needed:
+
+```yaml
+modules:
+  - id: contacts
+    source: "github:my-org/crm/contacts@v1"
+    # Declares dependency "companies" — auto-wires to entry below
+  - id: companies
+    source: "github:my-org/crm/companies@v1"
+    # Declares dependency "contacts" — auto-wires to entry above
+```
+
+### Explicit Wiring
+
+When entry IDs don't match the dependency names, provide explicit `dependencies`:
+
+```yaml
+modules:
+  - id: app-layout
+    source: "github:my-org/crm/layout-sidebar@v2"
+
+  - id: contacts
+    source: "github:my-org/crm/contacts@v1"
+    dependencies:
+      layout: app-layout  # Module declares "layout", entry is "app-layout"
+```
+
+`dependencies` keys are the abstract names the module declares. Values are the entry IDs from your `modules` list. Explicit `dependencies` override auto-wiring.
+
+### Multi-Instance with Dependencies
+
+When the same module source has multiple entries, auto-wiring is ambiguous. Use explicit `dependencies` to wire each instance:
+
+```yaml
+modules:
+  - id: internal-contacts
+    source: "github:my-org/crm/contacts@v1"
+    dependencies:
+      companies: internal-companies
+    vars:
+      collection: internal_contacts
+
+  - id: external-contacts
+    source: "github:my-org/crm/contacts@v1"
+    dependencies:
+      companies: external-companies
+    vars:
+      collection: external_contacts
+
+  - id: internal-companies
+    source: "github:my-org/crm/companies@v1"
+    dependencies:
+      contacts: internal-contacts
+
+  - id: external-companies
+    source: "github:my-org/crm/companies@v1"
+    dependencies:
+      contacts: external-contacts
+```
+
+Each instance links to its own partner. The module code is identical — only the wiring differs.
+
+## Troubleshooting
+
+**"Module 'X' requires plugin 'Y' version 'Z'"** — Add the required plugin to your app's `plugins` array in `lowdefy.yaml`, or update the version if already installed.
+
+**"Module 'X' references undeclared secret 'Y'"** — The module author needs to declare this secret in `module.lowdefy.yaml`. If you're the module author, add it to the `secrets` array.
+
+**"Duplicate page ID 'X'"** — Two module entries produce the same scoped page ID. Use different entry IDs for each module instance.
+
+**Page not found at expected URL** — Module pages are served at `/{entryId}/{pageId}`, not `/{pageId}`. Check the entry ID in your `modules` config.
+
+**"Module 'X' declares dependency 'Y' but no mapping provided and no module entry 'Y' exists"** — The module needs another module that isn't in your app. Either add a module entry with `id: Y`, or add `dependencies: { Y: your-entry-id }` to the module entry.
+
+**"Module 'X' does not declare dependency 'Y'"** — You provided a `dependencies` key that the module doesn't expect. Check the module's `module.lowdefy.yaml` for declared dependencies.
+
+**"dependencies.contacts references 'my-contacts' but no module entry 'my-contacts' exists"** — The entry ID in your `dependencies` mapping doesn't match any `id` in the `modules` array. Check the entry ID spelling.

package/content/concepts/operators.md

@@ -0,0 +1,45 @@
+# Operators
+
+Operators are functions, that can be used to express logic. They are the reason why Lowdefy apps are not completely static, but can react to data and inputs. Operators can be used in `blocks`, `actions`, `requests`, and `connections`. See the specific documentation for more details.
+
+Each operators expects arguments with a specific structure. They can be the result of other operators, since operators are evaluated beginning with the most nested operators.
+
+If an operator errors while evaluating, it returns a `null` value, and logs the error to the console.
+
+## Client or server operators
+
+Some operators are only available on either the client or the server. For example, the [`_menu`](/_menu) operator is only useful on the client and is thus not included in server requests. Likewise, the [`_secret`](/_secret) operator is only available on the server for security reasons.
+
+If a operator has special environment considerations, it is indicated on the individual operator documentation page. If no indication is made, the operator can be used under both environments.
+
+##### Client only operators:
+- [_actions](/_actions)
+- [_api](/_api)
+- [_event](/_event)
+- [_global](/_global)
+- [_index](/_index)
+- [_input](/_input)
+- [_location](/_location)
+- [_media](/_media)
+- [_menu](/_menu)
+- [_request](/_request)
+- [_url_query](/_url_query)
+
+##### Server only operators:
+- [_hash](/_hash)
+- [_item](/_item)
+- [_payload](/_payload)
+- [_secret](/_secret)
+- [_step](/_step)
+
+Operators that are client side only cannot be used in `Requests` and `Connections`, and operators which are server side only cannot be used in `Blocks` and `Actions`.
+
+## Build time operators
+
+Besides the client and server environment, app build time is considered a third environment where special operator logic applies.
+
+The `_ref` and `_var` operators do not work like other operators. They are evaluated while an app is being built, and can thus be used anywhere in the app configuration. They are used to split an app into multiple files, and to reuse configuration. See [`_ref`](/_ref) for more details.
+
+Some operators can be evaluated at build time by using the [`_build`](/_build) operator. This is useful for once-off calculations when an app is built, for example looping over a list in a reference JSON file to calculate a value at build time instead of using normal operators which re-evaluate whenever the app state changes. It can also be used to read an environment variable.
+
+The [`_module`](/_module) operators provide access to module-scoped values during the build. See [Writing Modules](/module-authoring) for details.

package/content/concepts/overview.md

@@ -0,0 +1,19 @@
+# Overview
+
+A Lowdefy app is a [Hono](https://hono.dev) server with a [Vite](https://vite.dev)-built React client, that interprets / evaluates Lowdefy config. Lowdefy apps are written as YAML configuration files, which are easy to read, write and understand - and can be managed in source control. This makes Lowdefy quick to learn, maintain and pick up where others left off.
+
+Lowdefy can be considered as another level of abstraction on top of the web stack. The Lowdefy schema is designed to be a standardized, declarative and flexible expression of application parameters and logic. This allows developers to focus on translating the business problem into configuration.
+
+The Lowdefy schema abstracts app definitions into 5 categories:
+- [**Blocks**](/blocks): The building blocks of the UI, the client-side React component to render. Blocks are usually stateless since all app state is managed by the Lowdefy engine.
+- [**Operators**](/operators): The application logic is defined using operator functions, which can be used both server-side and client-side. These are synchronous methods, which are continuously evaluated every time the app state changes.
+- [**Actions**](/events-and-actions): Asynchronous client-side methods triggered by events, such as clicking a button or initializing the page state. These methods usually apply an action like setting state, using the [SetState](/SetState) action, or calling a request, using the [Request](/Request) action.
+- [**Connections and Requests**](/connections-and-requests): Server-side methods, which allow a Lowdefy app to make server requests to other services like APIs or databases. Requests are evoked by the [Request](/Request) action, and are only called after all user authentication and authorization checks have passed. Requests consume a payload from the client, and have access to server-side secrets like passwords and API keys.
+- [**Auth Providers and Adapters**](/users-introduction): Lowdefy implements [Auth.js](https://authjs.dev) for authentication. Auth.js allows for the configuration of a wide range of authentication providers and adapters, which can be configured in Lowdefy apps.
+
+The diagram below provides an overview of the Lowdefy app schematic:
+![Lowdefy App Diagram](/images/lowdefy_app_schema.png)
+
+Lowdefy offers a large number of default actions, blocks, operators, connections, and auth integrations - but also provides a [plugin interface](/plugins) for the extension of new types. All plugins are installed as [npm](https://www.npmjs.com/) modules, which means you can extend your Lowdefy application by any existing npm module - enabling developers to make use of anything that is available in the Javascript ecosystem.
+
+Since Lowdefy apps are self-hosted Node.js applications, they do not ship with a built in data store and typically connect to one or more APIs or databases. Server instances are also stateless, which simplifies deployment. You can deploy your app using Docker or any hosting provider that runs Node.js servers.

package/content/concepts/references-and-templates.md

@@ -0,0 +1,207 @@
+# References and Templates
+
+References and templates have the following use cases:
+- Splitting out the config for readability and code navigation.
+- Splitting out a piece of config in order to use the exact same config in multiple places.
+- Using a reference with variables to make use of a shared piece of config with dynamic variables.
+- Using a `.njk` file to create config files using the Nunjucks templating language.
+- Using resolver and transformer functions to create Lowdefy config using Javascript functions.
+
+## Using References to Improve Readability
+
+References are made using the [`_ref`](/_ref) operator. If the referenced file has a `.yaml` or `.json` extension, the contents of the file will be parsed, else the file content is included as a string (this is useful for `.md` or `.html` files). As an example of splitting an app into logically distinct files, references can be used to write each page as a separate file:
+
+###### lowdefy.yaml
+```yaml
+lowdefy: LOWDEFY_VERSION
+
+pages:
+  _ref: pages/page1.yaml # Path to the referenced file. Always from the root of the project.
+  _ref: pages/page1.yaml
+```
+
+## Using References as Templates for Improved Reusability
+
+The `_ref` operator can take an argument called `vars`. This can be any data, and is passed down to later be accessed with the [`_var`](/_var) operator. By using vars, the referenced file can become a template, using the given variables. For example, a standard page template might be used for multiple pages in an app:
+
+###### pages/page1.yaml
+```yaml
+_ref:
+  path: templates/text_page.yaml
+  vars:
+    id: page1
+    title: Page 1
+    content:
+      _ref: markdowns/content.md
+```
+
+###### markdowns/content.md
+```yaml
+Page content text.
+```
+
+###### templates/text_page.yaml
+```yaml
+id:
+  _var: id
+type: PageHeaderMenu
+properties:
+  title:
+    _var: title
+blocks:
+  - id: content_card
+    type: Card
+    blocks:
+      - id: title
+        type: Title
+        properties:
+          content:
+            _var: title
+      - id: content
+        type: Markdown
+        properties:
+          content:
+            _var: content
+```
+
+## Nunjucks Templating
+
+Templating can be taken further by referencing [Nunjucks](https://mozilla.github.io/nunjucks/) template files. If a file ends with the `.njk` file extension, the file will first be hydrated as a Nunjucks template, using the `vars` as template variables. If the file ends with `.yaml.njk` or `.json.njk`, the output of the template will then be parsed. Nunjucks templates are useful since the template file does not need to be valid yaml before it is hydrated, and features like for-loops and if-statements can be used.
+
+Templating is used extensively to create the Lowdefy docs (these docs are a Lowdefy app). You can look at how they are used [here](https://github.com/lowdefy/lowdefy/tree/main/packages/docs).
+
+We can modify the example above to make use of nunjucks templating to allow us to add subsections to our page. This can be done as follows:
+
+###### pages/page1.yaml
+```yaml
+_ref:
+  path: templates/text_page.yaml.njk
+  vars:
+    id: page1
+    title: Page 1
+    content:
+      _ref: markdowns/content.md
+    subsections:
+      - id: subsection1
+        title: Subsection 1
+        content: |
+          Subsection 1 content text.
+      - id: subsection2
+        title: Subsection 2
+        content: |
+          Subsection 2 content text.
+```
+
+###### markdowns/content.md
+```yaml
+Page content text.
+```
+
+###### templates/text_page.yaml.njk
+```yaml
+id:
+  _var: id
+type: PageHeaderMenu
+properties:
+  title:
+    _var: title
+blocks:
+  - id: content_card
+    type: Card
+    blocks:
+      - id: title
+        type: Title
+        properties:
+          content:
+            _var: title
+      - id: content
+        type: Markdown
+        properties:
+          content:
+            _var: content
+      {% if subsections %}
+      {% for subsection in subsections %}
+      - id: {{ subsection.id }}_title
+        type: Title
+        properties:
+          content: {{ subsection.title }}
+      - id: {{ subsection.id }}_content
+        type: Markdown
+        properties:
+          content: {{ subsection.content }}
+      {% endfor %}
+      {% endif %}
+```
+
+## Custom JavaScript Functions
+
+The `_ref` operator can also be extended with custom JavaScript functions. A `resolver` function can be specified, which can overwrite the default way configuration files are read from the filesystem. A `transformer` function can be used to transform the value returned by the `_ref` operator.
+
+### Resolver
+
+This resolver function will first look for the configuration file in the current working directory, but if the file is not found it will be read from an adjacent "shared" directory. This pattern can be used to build apps that mostly use a shared configuration, with a few components that are customised per app.
+
+###### resolvers/useLocalOrSharedConfig.js
+```js
+const fs = require('fs');
+const path = require('path');
+const { promisify } = require('util');
+
+const readFilePromise = promisify(fs.readFile);
+
+async function useLocalOrSharedConfig(refPath, vars, context) {
+  let fileContent
+  try {
+    fileContent =  await readFilePromise(path.resolve(refPath), 'utf8');
+    return fileContent;
+  } catch (error) {
+    if (error.code === 'ENOENT') {
+      fileContent = readFilePromise(path.resolve('../shared', refPath), 'utf8');
+      return fileContent;
+    }
+    throw error;
+  }
+
+
+}
+
+module.exports = useLocalOrSharedConfig;
+```
+
+###### lowdefy.yaml
+```yaml
+lowdefy: LOWDEFY_VERSION
+
+cli:
+  refResolver: resolvers/useLocalOrSharedConfig.js
+
+pages:
+  - _ref: pages/local-page.yaml
+  - _ref: pages/shared-page.yaml
+```
+
+### Transformer
+
+This transformer adds a standard footer to each page:
+
+###### transformers/addFooter.js
+```js
+function addFooter(page, vars) {
+  const footer = {
+    // ...
+  };
+  page.areas.footer = footer;
+  return page;
+}
+module.exports = addFooter;
+```
+
+###### lowdefy.yaml
+```yaml
+lowdefy: LOWDEFY_VERSION
+
+pages:
+  - _ref:
+      path: pages/page1.yaml
+      transformer: transformers/addFooter.js
+```

package/content/concepts/secrets.md

@@ -0,0 +1,24 @@
+# Secrets
+
+The `secrets` object is an object that can be used to securely store sensitive information such as passwords and API keys. Secrets can be accessed using the [`_secret`](/_secret) operator.
+
+The secrets object only exists on the backend server, and therefore the `_secret` operator can only be used in `connections` and `requests`.
+
+Secrets can be set by creating an environment variable prefixed with `LOWDEFY_SECRET_`. The secret will then be available in the secrets object with the remaining part of the name as key.
+
+For example, if the environment variable `LOWDEFY_SECRET_MY_SECRET` is set to `supersecret`, then `_secret: MY_SECRET` will return `supersecret`.
+
+To use secrets in the local development environment, environment variables can be set using a `.env` file. Create a file called `.env` at the root of the project directory, then set environment variables as follows:
+
+```
+# .env
+LOWDEFY_SECRET_MY_SECRET=supersecret
+```
+
+## Module Secret Allowlist
+
+Modules declare the secrets they require in their `module.lowdefy.yaml` manifest. Undeclared `_secret` references cause build errors.
+
+When a module connection is remapped to an app connection, the module's secret references for that connection are skipped — the app connection handles its own secrets.
+
+See [Modules](/modules) for full details.