@lowdefy/docs-content 0.0.0-experimental-20260710073520

package/content/plugins/plugins-actions.md

@@ -0,0 +1,80 @@
+# Action Plugins
+
+Actions are functions that are triggered by [events](https://docs.lowdefy.com/events-and-actions) in a Lowdefy app. Actions can be `async` functions. The response returned by the action can be read using the `_actions` operator. If a promise is returned, the promise will be awaited before the next action is run.
+
+The Lowdefy engine provides a context object to the action with the following parameters:
+
+- `globals: object`: Commonly used Javascript global objects. These are passed to the action for easier testing.
+  - `document: object`: The browser [`window.document`](https://developer.mozilla.org/en-US/docs/Web/API/Document/Document) global variable.
+  - `fetch: function`: The global [`fetch`](https://developer.mozilla.org/en-US/docs/Web/API/fetch) Javascript method.
+  - `window: object`: The browser [`window`](https://developer.mozilla.org/en-US/docs/Web/API/Window) global variable.
+- `methods: object`:
+  - `callMethod: function`: Call the CallMethod action.
+  - `displayMessage: function`: Call the DisplayMessage action.
+  - `getActions: function`: Get data from previous actions in the action chain.
+  - `getBlockId: function`: Get the blockId of the block that triggered the event.
+  - `getEvent: function`: Get event data from the event that triggered the action.
+  - `getGlobal: function`: Get data from the Lowdefy global object.
+  - `getInput: function`: Get data from the Lowdefy input object.
+  - `getLocale: function`: Return the active i18n locale code (or undefined when `config.i18n` is not configured).
+  - `getPageId: function`: Get the pageId of the block that the action is defined on.
+  - `getRequestDetails: function`: Get data from Lowdefy requests.
+  - `getState: function`: Get data from the Lowdefy state object.
+  - `getUrlQuery: function`: Get data from the Lowdefy urlQuery object.
+  - `getUser: function`: Get data from the Lowdefy user object.
+  - `link: function`: Call the Link action.
+  - `login: function`: Call the Login action.
+  - `logout: function`: Call the Logout action.
+  - `request: function`: Call the Request action.
+  - `reset: function`: Call the Reset action.
+  - `resetValidation: function`: Call the ResetValidation action.
+  - `setGlobal: function`: Call the SetGlobal action.
+  - `setState: function`: Call the SetState action.
+  - `translate: function`: Look up a translation key (`(key, values?) => string`) — same lookup chain as the [`_t`](/_t) operator. See [i18n](/i18n) for the plugin-author contract.
+  - `validate: function`: Call the Validate action.
+- `params: any`: The `params` defined by the user in the Lowdefy configuration. Operators are evaluated before the params are passed to the action. No validation is performed on this object.
+
+#### Examples
+
+###### The Lowdefy SetState action:
+```js
+function SetState({ methods: { setState }, params }) {
+  setState(params);
+}
+
+export default SetState;
+```
+
+###### The Lowdefy Fetch action:
+```js
+async function Fetch({ globals, params }) {
+  const { fetch } = globals;
+  const { url, options, responseFunction } = params;
+  const res = await fetch(url, options);
+  if (responseFunction) {
+    return res[responseFunction]();
+  }
+  return res;
+}
+
+export default Fetch;
+```
+
+###### An action that shows the user confetti using the js-confetti package:
+```js
+// Confetti.js
+import JSConfetti from 'js-confetti';
+
+async function Confetti({ params }) {
+  const jsConfetti = new JSConfetti();
+  const { emojis, confettiRadius = 3, confettiNumber = 50, emojiSize = 10 } = params;
+  jsConfetti.addConfetti({
+    emojis,
+    confettiRadius,
+    confettiNumber,
+    emojiSize,
+  });
+}
+
+export default Confetti;
+```

package/content/plugins/plugins-connections.md

@@ -0,0 +1,98 @@
+# Connection and Request Plugins
+
+Connections and requests are used to integrate with other services like API's or databases.
+
+Connections configure the settings to the external service, and often contain parameters like connection strings, urls and secrets like passwords or API keys. Lowdefy does not execute any code for the connection, it is merely a convenient object to hold configuration that is shared by multiple requests.
+
+Each connection type can include a number of request types. Requests are the functions that the Lowdefy server executes. The response returned by the request function will be serialised into JSON (with additional support for dates and Javascript errors) and used as the response value for the request by the client. If a promise is returned it wil be awaited.
+
+Request parameters:
+- `callApi: function`: Invoke another Lowdefy API endpoint in-process. See [Calling another endpoint](#calling-another-endpoint) below.
+- `connection: object`: The connection `properties` defined by the user in the Lowdefy configuration. Operators are evaluated before the properties are passed to the request.
+- `connectionId: string`: The connectionId used by the request and as set on the request.
+- `pageId: string`: The pageId from which the request was called.
+- `payload: object`: The payload data object passed to the request. Operators are evaluated on the client before the payload is passed to the server request function.
+- `request: object`: The request `properties` defined by the user in the Lowdefy configuration. Operators are evaluated before the properties are passed to the request.
+- `requestId: object`: The requestId of the request.
+
+#### Calling another endpoint
+
+Request resolvers can invoke a Lowdefy API endpoint from inside the resolver using the `callApi` function from the argument bag:
+
+```js
+const response = await callApi({ endpointId, payload });
+```
+
+- `endpointId: string`: __Required__ - The id of the target endpoint. Module endpoints use a `<module>/<endpoint>` id — `callApi` treats this as an opaque string and does not parse it.
+- `payload: object`: Optional payload passed to the target endpoint's routine as `_payload`. Already-evaluated by the caller.
+
+`callApi` returns the value returned by the target's `:return` step, or `null` if the target routine terminates without an explicit `:return`. The semantics match the routine [`CallApi`](/lowdefy-api#calling-other-endpoints) step:
+
+- The caller's user identity is used to authorize the target endpoint — no auth bypass.
+- The target runs in an isolated routine context: fresh `_payload`, fresh `_state`, fresh `_step` namespace.
+- The target inherits the caller's parser closure — `_user`, `_secret`, `_env` resolve to the same values as the caller.
+- [Internal API endpoints](/lowdefy-api#internal-api-endpoints) are reachable.
+- Endpoint calls share a per-chain depth cap of 10 with routine `:call_api` steps. Exceeding the cap throws an error.
+
+###### Errors
+
+`callApi` throws on failure. The thrown error preserves its underlying class so resolvers can branch on it:
+
+- `ConfigError` — unknown endpoint id, unauthorized against the target, or depth cap exceeded. Unauthorized collapses to the same "does not exist" message as a missing endpoint to avoid leaking endpoint existence.
+- `UserError` — the target routine terminated with [`:throw`](/:throw) or [`:reject`](/:reject). Catch this class to distinguish a deliberately-failed routine from a system fault.
+- Other Lowdefy error classes (`RequestError`, `ServiceError`) propagate unchanged from the target's failure site.
+
+###### Example
+
+A simplified resolver that looks up a user via another endpoint before running its own request:
+
+```js
+async function FetchOrderWithUser({ callApi, request, connection }) {
+  const user = await callApi({
+    endpointId: 'get_user',
+    payload: { id: request.userId },
+  });
+  const orders = await connection.db
+    .collection('orders')
+    .find({ user_id: user.id })
+    .toArray();
+  return { user, orders };
+}
+
+FetchOrderWithUser.meta = {
+  checkRead: true,
+  checkWrite: false,
+};
+
+export default FetchOrderWithUser;
+```
+
+#### Schema Validation
+
+A [JSON Schema](https://json-schema.org/) schema can be used to validate the connection and request properties before they are passed to the request function. The [ajv-errors](https://ajv.js.org/packages/ajv-errors.html) package is used to provide useful error messages if the schema validation fails. Attached the json-schema to the request function with property `schema`, to validate request input before the request function is called.
+
+#### Examples
+
+###### A simplified version of the AxiosHttp request:
+
+```js
+import axios from 'axios';
+import { mergeObjects } from '@lowdefy/helpers';
+
+import schema from '../schema.js';
+
+async function AxiosHttp({ request, connection }) {
+  const config = mergeObjects([connection, request]);
+  const res = await axios(config);
+  const { status, statusText, headers, method, path, data } = res;
+  return { status, statusText, headers, method, path, data };
+}
+
+AxiosHttp.schema = schema; // Attached json-schema used to validate request input before the request function is called.
+AxiosHttp.meta = {
+  checkRead: false,
+  checkWrite: false,
+};
+
+export default AxiosHttp;
+```

package/content/plugins/plugins-dev.md

@@ -0,0 +1,138 @@
+# Developing Plugins
+
+To develop plugins and publish plugins to npm or to use unpublished, project-specific plugins, we recommend using a pnpm monorepo with the plugin packages and a Lowdefy app, as demonstrated in [this example](https://github.com/lowdefy/lowdefy-example-plugins). The [Lowdefy default plugin packages](https://github.com/lowdefy/lowdefy/tree/main/packages/plugins) can also be used as examples.
+
+> In this documentation the collection of blocks, connections, actions, etc. will be referred to as _types_, not to be confused with Typescript types.
+
+> The Lowdefy plugin system is under active development and breaking changes might be made in a minor version update.
+
+A plugin package needs to include the following:
+
+- A `package.json` file which declares the package and exports the plugin types.
+- A `types.js` file which exports the plugin type names.
+- Files that export all the types as named exports.
+- The code for the types exposed by the plugin package.
+
+### package.json
+
+Lowdefy plugin packages should be an [ECMAScript module](https://nodejs.org/api/esm.html#modules-ecmascript-modules). To configure a package as an ECMAScript module, the `type` field in the `package.json` file should be set to `"module"`.
+
+Lowdefy uses the [`exports`](https://nodejs.org/api/packages.html#exports) package entry points to map to the `types.js` and plugin named export files.
+
+```json
+{
+  "name": "plugin-name",
+  "version": "1.0.0",
+  "type": "module",
+  "exports": {
+    "./actions": "./src/actions.js",
+    "./auth/callbacks": "./src/auth/callbacks.js",
+    "./auth/events": "./src/auth/events.js",
+    "./auth/providers": "./src/auth/providers.js",
+    "./blocks": "./src/blocks.js",
+    "./connections": "./src/connections.js",
+    "./metas": "./src/metas.js",
+    "./operators/client": "./src/operators/client.js",
+    "./operators/server": "./src/operators/server.js",
+    "./types": "./src/types.js"
+  },
+  "files": ["src/*"],
+  "dependencies": {}
+}
+```
+
+The `./types` entry point is required, and the other entry points are only required if the package exports the corresponding types. Block packages should also export `./metas` for build-time schema generation.
+
+You can change your folder structure in your package, but then you need to change the `exports` entry points in the `package.json` file to match your file structure.
+
+##### Compiling React for blocks
+
+To develop a block plugin, the React code needs to compiled before it can be used in the Lowdefy app. The [Lowdefy plugin example](https://github.com/lowdefy/lowdefy-example-plugins) has an example of this configured using SWC.
+
+### types.js
+
+The `types.js` file declares the different types provided by the plugin package. This is used by the Lowdefy build process to map plugin types used in the Lowdefy config to plugin packages.
+
+The file should export an object that contains the type names (the names used in the Lowdefy config) for all the different types provided by the package.
+
+###### Example with all types
+
+```js
+export default {
+  actions: ['Action'],
+  auth: {
+    callbacks: ['Callback'],
+    events: ['Event'],
+    provider: ['Provider'],
+  },
+  blocks: ['Block'],
+  connections: ['Connection'],
+  requests: ['Request'],
+  operators: {
+    build: ['_build_operator', '_shared_operator'],
+    client: ['_client_operator', '_shared_operator'],
+    server: ['_server_operator', '_shared_operator'],
+  },
+};
+```
+
+The type names do not need to be hard coded, and can be generated by importing the plugin types.
+
+###### Example `types.js` for connections
+
+```js
+import * as connections from './connections.js';
+
+export default {
+  connections: Object.keys(connections),
+  requests: Object.keys(connections)
+    .map((connection) => Object.keys(connections[connection].requests))
+    .flat(),
+};
+```
+
+###### Example `types.js` for blocks
+
+Block packages use `extractBlockTypes` from `@lowdefy/block-utils` to derive type information from block metadata files. Each block has a `meta.js` file containing its category, icons, events, CSS keys, and property schema. These are re-exported via a `metas.js` barrel file:
+
+```js
+// src/metas.js — re-export each block's metadata
+export { default as MyBlock } from './blocks/MyBlock/meta.js';
+export { default as MyOtherBlock } from './blocks/MyOtherBlock/meta.js';
+```
+
+```js
+// src/types.js — derive types from metas
+import { extractBlockTypes } from '@lowdefy/block-utils';
+import * as metas from './metas.js';
+
+export default extractBlockTypes(metas);
+```
+
+The `extractBlockTypes` function returns `{ blocks, icons, blockMetas }` which the build pipeline uses to resolve plugin types without loading React components or heavy dependencies.
+
+See the [default Lowdefy block packages](https://github.com/lowdefy/lowdefy/tree/main/packages/plugins/blocks) for full examples.
+
+### Named export files
+
+A file that exports the plugin types as named exports is needed for each kind of plugin-types. This is so that the Lowdefy server can import these directly to allow for tree shaking to reduce bundle size by excluding unused code. In the default configuration these file names correspond to the package entry point paths, for example, the files are named `actions.js`, `blocks.js`, and `operators/client.js`, but different file names and folder structures can be configured.
+
+###### Example `actions.js` file
+```js
+export { default as MyAction } from './actions/MyAction.js';
+```
+
+In the Lowdefy server, the types will be imported as:
+```js
+import { MyAction as MyAction } from 'my-plugin-package/actions';
+```
+
+### Plugin code
+
+Most types are written as standard Javascript functions, and blocks are written as React components. The function names should be in _CapitalCase_, except for operators which should be written in _snake_case_ and start with an underscore.
+
+Lowdefy uses object [destructuring](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Destructuring_assignment) to provide parameters to the type functions. These parameters include the parameters or properties defined by the user in the Lowdefy configuration. Any operators used in the configuration will be evaluated before it is passed to the type function. Other relevant metadata and helper functions are also passed to the plugin function.
+
+### Localizing plugin strings
+
+Plugins can ship locale-keyed default messages so consumers see translated strings out-of-the-box, and translate strings at runtime via `methods.translate(key, values)` in block / action code. See [i18n](/i18n) for the full plugin-author contract — `./messages` export shape, `package.json` `exports` registration, namespacing convention, and merge precedence.

package/content/plugins/plugins-introduction.md

@@ -0,0 +1,29 @@
+# Plugins
+
+Lowdefy plugins provides an interface to extend the platform functionality with custom javascript code. Plugins are installed into the Lowdefy app during the Lowdefy build process, and as a result are included as part of the Vite client build output. This enables plugin developers to use any npm packages when building Lowdefy plugins.
+
+Lowdefy plugins can be used to create custom blocks, connections, requests, action, operators and auth providers, adapters, callbacks and events. These plugins are written as standard [npm modules](https://docs.npmjs.com/about-packages-and-modules#about-modules), so community plugins can be published to npm, and the workspace and git protocols can be used for project specific or private plugins. Since plugins are npm packages most Javascript features and third-party npm packages can be used in plugins.
+
+## Using a plugin
+
+To use a plugin in an app, the plugin name and version should be specified in the `plugins` section of the Lowdefy config. Once the plugin is included, the types (blocks, connections, etc) defined in the plugin can be used anywhere in the app.
+
+If two plugins export types with the same type name, user defined plugins will override the default Lowdefy types, and user defined plugins will overwrite other plugins defined before them in the plugins array.
+
+The `typePrefix` property can be used to prevent plugins with the same name overwriting each other. If specified, the type names of all plugins in that package will have the prefix appended. For example, if a package contains a block with type `Button` and the typePrefix is set to `Other`, that block can be used with type name `OtherButton`, and the default Lowdefy `Button` block will still be available.
+
+###### Example
+
+```yaml
+plugins:
+  # plugins installed remotely from npm
+  - name: npm-plugin
+    version: 1.0.0
+    # local plugins in pnpm monorepo
+  - name: local-plugin
+    version: workspace:*
+  # Add a prefix to type names
+  - name: other-plugin
+    version: 1.0.0
+    typePrefix: Other
+```

package/content/plugins/plugins-operators.md

@@ -0,0 +1,71 @@
+# Operator Plugins
+
+Operators are synchronous functions that are used in Lowdefy to express logic. If you need to use asynchronous code, or promises, write an [action](/plugins-actions) instead.  Operator names should start with a single underscore, as this is used by the Lowdefy engine to identify and evaluate operators. By convention, operator functions are written in _snake_case_.
+
+Operators are used in both the web client and server runtimes. Some operators make sense in both environments, but other operators only work in one or the other. The `types.js` file declares the server and client operators exported by an app in the `operators.client` and `operators.server` fields. The operator named exports are exported under the `./operators/client` and `./operators/server` package entry points for client and server operators respectively. The same function can be exported for both the client and the server runtimes, or two different implementations can be exported in each file.
+
+Client parameters:
+- `actions: object`: The actions data object.
+- `args: array`: If the operator is used inside a `_function` operator, `args` is an array of arguments passed to the function.
+- `basePath: string`: The configured app URL basePath.
+- `event: object`: The event data object.
+- `globals: object`: Commonly used Javascript global objects. These are passed to the operator for easier testing.
+  - `document: object`: The browser [`window.document`](https://developer.mozilla.org/en-US/docs/Web/API/Document/Document) global variable.
+  - `window: object`: The browser [`window`](https://developer.mozilla.org/en-US/docs/Web/API/Window) global variable.
+- `home: object`:
+  - `configured: boolean`: True if the user configured a home pageId.
+  - `pageId: string`: The pageId of the home page. Either the user configured home pageId, or the pageId of the first page visible to the user in the default menu.
+- `input: object`: The input data object.
+- `lowdefyGlobal: `: The Lowdefy global data object.
+- `menus: array`: The app menus.
+- `methodName: string`: The name of the method if the operator is called with a method (as `_operator.methodName`).
+- `operators: object`: An object with all the operator functions used on the client.
+- `pageId: string`: The pageId of the page the operator is evaluated on.
+- `params: any`: The `params` defined by the user in the Lowdefy configuration. Operators are evaluated before the params are passed to the operator. No validation is performed on this object.
+- `requests: object`: The requests data object.
+- `runtime: string`: The runtime is set to the constant `"browser"`.
+- `state: object`: The state data object.
+- `user: object`: The user data object.
+
+
+Server parameters:
+- `args: array`: If the operator is used inside a `_function` operator, `args` is an array of arguments passed to the function.
+- `methodName: string`: The name of the method if the operator is called with a method (as `_operator.methodName`).
+- `operators: object`: An object with all the operator functions used on the server.
+- `params: any`: The `params` defined by the user in the Lowdefy configuration. Operators are evaluated before the params are passed to the operator. No validation is performed on this object.
+- `payload: object`: The payload object passed to a request. Operators are evaluated on the client before the payload is passed to the server request function.
+- `runtime: string`: The runtime is set to the constant `"node"`.
+- `secrets: object`: The secrets data object.
+- `user: object`: The user data object.
+
+### Pure Functions
+
+Operators in Lowdefy are usually pure functions - given a specific input they always give the same output. If a operator is used in blocks, they must be pure functions because operators are evaluated every time a page is re-rendered. Operators in block properties are evaluated recursively until the evaluated result matches the previous evaluated result.
+
+#### Examples
+
+###### An operator that multiplies a number by 11:
+```js
+function _times_eleven({ params }) {
+  return params.number * 11;
+}
+
+export default _times_eleven;
+```
+
+###### The _eq operator:
+```js
+import { type } from '@lowdefy/helpers';
+
+function _eq({ params }) {
+  if (!type.isArray(params)) {
+    throw new Error('_eq takes an array type as input.');
+  }
+  if (params.length !== 2) {
+    throw new Error('_eq takes an array of length 2 as input.');
+  }
+  return params[0] === params[1];
+}
+
+export default _eq;
+```

package/content/testing/e2e-auth.md

@@ -0,0 +1,108 @@
+# Testing Authentication
+
+When your app uses authentication, e2e tests need a way to set user sessions without going through a real login flow. The `@lowdefy/e2e-utils` package provides cookie-based user injection that works with Lowdefy's auth system.
+
+When you run e2e tests, a special e2e server is used instead of the production server. This server reads the test user from a browser cookie instead of using the Auth.js engine, so your tests can set any user object and have it work with Lowdefy's page protection and role-based access control.
+
+## Setting a default user
+
+Define a default test user in your `mocks.yaml` file. This user is applied to every test automatically:
+
+```yaml
+# e2e/mocks.yaml
+user:
+  name: Test User
+  email: test@example.com
+  roles:
+    - admin
+```
+
+The user object maps directly to `lowdefy.user` with no transforms. Whatever you set here is exactly what your app receives.
+
+> Your app must have <code>auth</code> configured in <code>lowdefy.yaml</code> for page protection to work. The e2e server respects the same <code>pages.public</code>, <code>pages.protected</code>, and <code>pages.roles</code> settings as the production server.
+
+## Setting users per test
+
+Use `ldf.user()` to set or change the user for a specific test:
+
+```javascript
+import { test } from './fixtures.js';
+
+test('admin can access dashboard', async ({ ldf }) => {
+  await ldf.user({ name: 'Admin', roles: ['admin'] });
+  await ldf.goto('/dashboard');
+  await ldf.url().expect.toBe('/dashboard');
+});
+```
+
+If you have a default user in `mocks.yaml`, calling `ldf.user()` overrides it for that test only. Other tests still use the default.
+
+## Testing without a user
+
+Clear the user with `ldf.user(null)` to test unauthenticated access:
+
+```javascript
+test('unauthenticated user is redirected to login', async ({ ldf }) => {
+  await ldf.user(null);
+  await ldf.goto('/dashboard');
+  await ldf.url().expect.toBe('/login');
+});
+
+test('public page loads without login', async ({ ldf }) => {
+  await ldf.user(null);
+  await ldf.goto('/login');
+  await ldf.url().expect.toBe('/login');
+});
+```
+
+When no user is set and the requested page is protected, the server redirects to the 404 page. If the 404 page has logic to redirect to a login page, the user will be redirected there.
+
+## Testing role-based access
+
+Set specific roles on the user to test role-based page protection:
+
+```javascript
+test('viewer cannot access admin page', async ({ ldf }) => {
+  await ldf.user({ name: 'Viewer', roles: ['viewer'] });
+  await ldf.goto('/admin-settings');
+  // Redirects because user lacks 'admin' role
+  await ldf.url().expect.toBe('/login');
+});
+
+test('admin can access admin page', async ({ ldf }) => {
+  await ldf.user({ name: 'Admin', roles: ['admin'] });
+  await ldf.goto('/admin-settings');
+  await ldf.url().expect.toBe('/admin-settings');
+});
+```
+
+## Complete example
+
+Here is a full test file that covers common authentication scenarios:
+
+```javascript
+import { test } from './fixtures.js';
+
+test('protected page loads with authenticated user', async ({ ldf }) => {
+  // Default user from mocks.yaml is used (has admin role)
+  await ldf.goto('/home');
+  await ldf.url().expect.toBe('/home');
+});
+
+test('public page loads without user', async ({ ldf }) => {
+  await ldf.user(null);
+  await ldf.goto('/login');
+  await ldf.url().expect.toBe('/login');
+});
+
+test('protected page redirects without user', async ({ ldf }) => {
+  await ldf.user(null);
+  await ldf.goto('/home');
+  await ldf.url().expect.toBe('/login');
+});
+```
+
+## Limitations
+
+- **Sign-in and sign-out are not supported.** If your app uses the Login or Logout actions, the e2e server will throw an error. Test login flows by setting the user directly with `ldf.user()` instead.
+- **No session callbacks.** The user object is passed through as-is. If your production app transforms the session via callbacks (for example, mapping `userFields`), those transforms do not run in e2e tests.

package/content/testing/e2e-configuration.md

@@ -0,0 +1,107 @@
+# Configuration
+
+The `playwright.config.js` file in your `e2e/` directory controls how tests are run. The `@lowdefy/e2e-utils/config` module provides helper functions that set up sensible defaults for Lowdefy apps.
+
+## Default configuration
+
+The simplest configuration uses all defaults:
+
+```javascript
+import { createConfig } from '@lowdefy/e2e-utils/config';
+
+export default createConfig();
+```
+
+This will:
+- Look for your Lowdefy app in the current directory
+- Build and start on port 3000
+- Run tests from the `e2e/` directory matching `**/*.spec.js`
+- Take screenshots only on failure
+
+## Configuration options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `appDir` | string | `'./'` | Path to your Lowdefy app root |
+| `buildDir` | string | `'.lowdefy/server/build'` | Build output directory (relative to appDir) |
+| `mocksFile` | string | `'e2e/mocks.yaml'` | Path to static mocks file (relative to appDir) |
+| `port` | number | `3000` | Port for the test server |
+| `testDir` | string | `'e2e'` | Directory containing test files |
+| `testMatch` | string | `'**/*.spec.js'` | Glob pattern for test files |
+| `timeout` | number | `180000` | Build + server start timeout in milliseconds (3 minutes) |
+| `screenshot` | string | `'only-on-failure'` | When to take screenshots: `'off'`, `'on'`, or `'only-on-failure'` |
+| `outputDir` | string | `'test-results'` | Directory for test artifacts |
+
+###### Custom port and timeout:
+```javascript
+import { createConfig } from '@lowdefy/e2e-utils/config';
+
+export default createConfig({
+  port: 3001,
+  timeout: 300000, // 5 minutes for slow builds
+});
+```
+
+## Multi-app configuration
+
+If your project has multiple Lowdefy apps (for example, in a monorepo), use `createMultiAppConfig`:
+
+```javascript
+import { createMultiAppConfig } from '@lowdefy/e2e-utils/config';
+
+export default createMultiAppConfig({
+  apps: [
+    { name: 'admin', appDir: './apps/admin', port: 3001 },
+    { name: 'customer', appDir: './apps/customer', port: 3002 },
+  ],
+});
+```
+
+Each app gets its own Playwright project and web server. Tests for each app should be placed in subdirectories matching the app name (for example, `e2e/admin/` and `e2e/customer/`).
+
+## Extending the configuration
+
+Since `createConfig` returns a standard Playwright configuration object, you can extend it with any Playwright options:
+
+```javascript
+import { createConfig } from '@lowdefy/e2e-utils/config';
+
+const base = createConfig({ port: 3000 });
+
+export default {
+  ...base,
+  retries: 2,
+  projects: [
+    ...base.projects,
+    {
+      name: 'firefox',
+      use: { browserName: 'firefox' },
+    },
+  ],
+};
+```
+
+## Environment variables
+
+The configuration sets these environment variables automatically:
+
+| Variable | Purpose |
+|----------|---------|
+| `LOWDEFY_BUILD_DIR` | Absolute path to build artifacts — used by test fixtures to generate the block manifest |
+| `LOWDEFY_E2E_MOCKS_FILE` | Absolute path to `mocks.yaml` — used by test fixtures to load static mocks |
+
+## Assertion timeouts
+
+Assertion methods accept an optional `{ timeout }` parameter. The defaults are:
+
+| Assertion type | Default timeout |
+|---------------|----------------|
+| Request assertions (`toFinish`, `toHaveResponse`, `toHavePayload`) | 30 seconds |
+| State assertions (`toBe`) | 5 seconds |
+| URL assertions (`toBe`, `toMatch`) | 5 seconds |
+| Validation assertions (`validationError`, etc.) | 5 seconds |
+
+```javascript
+// Override timeout for a slow request
+await ldf.request('generate_report').expect.toFinish({ timeout: 60000 });
+```